1 DEFRAGMENT Invokes the Disk File Optimizer. This utility is a layered product that restores file contiguity while the target volume remains on line and accessible. The Disk File Optimizer is compatible with any Files-11 structure levels 2 or 5 (ODS-2, ODS-5) formatted volume including single volumes, bound volume sets, stripe sets or shadow sets. Format DEFRAGMENT [ /INTERFACE ] 2 Qualifiers /INTERFACE /INTERFACE=CHARACTER_CELL(default) /INTERFACE=DECWINDOWS The /INTERFACE qualifier allows you to start up the Disk File Optimizer with either the character cell terminal interface or the DECwindows interface. 2 ABORT The ABORT subcommand terminates the execution of the script or scripts specified in the command line. Format DEFRAGMENT ABORT { script-name[,...] } [ /QUALIFIERS ] 3 Parameters script-name The script-name parameter is the name of the script to be aborted. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. 3 Restrictions o You cannot use the script-name parameter with the /ALL qualifier. 3 Qualifiers /AFTER /AFTER={time} /NOAFTER (default) The /AFTER qualifier keeps the script from being aborted until after the specified time. You can specify time as either an absolute time or as a combination of absolute and delta times. For complete information on specifying time values, see the VMS DCL Concepts Manual. /ALL /ALL /NOALL (default) The /ALL qualifier aborts all currently executing scripts across the system. This qualifier is functionally equivalent to using an asterisk (*) for the script-name parameter. 3 Examples The following examples show how the ABORT command functions. 1. $ DEFRAGMENT ABORT MY_SCRIPT/AFTER=16:30 This command aborts MY_SCRIPT after 16:30 on the day this command is submitted. 2. $ DEFRAGMENT ABORT/ALL This command immediately aborts all currently executing scripts in the entire system. 2 ATTACH The ATTACH subcommand transfers control from your current process (which then hibernates) to the specified process. Format DEFRAGMENT ATTACH { process-name } [ /QUALIFIERS ] 3 Parameters process-name The process-name specifies the name of a process to which control passes. The process must already exist, be part of your current job, and share the same input stream as your current process. However, the process cannot be your current process or a subprocess created with the /NOWAIT qualifier. Process names can contain from 1 to 15 alphanumeric characters. If a connection to the specified process cannot be made, an error message is displayed. 3 Restrictions o The ATTACH command cannot be used if your terminal has an associated mailbox. o You cannot use the process-name parameter with the /IDENTIFICATION qualifier. o You must supply either a process name or a PID for this command. 3 Qualifiers /IDENTIFICATION /IDENTIFICATION=pid /IDENTIFICATION lets you specify the process identification (PID) of the process to which terminal control will be transferred. Leading zeros can be omitted. 3 Examples The following examples show how you can use the ATTACH command. 1. $ DEFRAGMENT ATTACH JONES_2 This ATTACH command transfers the terminal's control to the subprocess named JONES_2. 2. $ DEFRAGMENT ATTACH /IDENTIFICATION=2A401A1B This ATTACH command switches control from the current process to the process whose PID is 2A401A1B. 2 CANCEL The CANCEL subcommand skips the next scheduled execution of the scripts specified in the command line. Format DEFRAGMENT CANCEL { script-name } [ /QUALIFIERS ] 3 Parameters script-name The script-name parameter is the name of the scripts to be canceled. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. 3 Restrictions o The script-name parameter is not allowed if the /ALL qualifier is used. 3 Qualifiers /ALL /ALL /NOALL (default) The /ALL qualifier cancels the next scheduled execution of all scripts in the scheduling and parameter database. 3 Example The following example shows how to use the CANCEL command. 1. $ DEFRAGMENT CANCEL MY_SCRIPT, YOUR_SCRIPT In this example, the next scheduled execution of MY_SCRIPT and YOUR_SCRIPT are canceled. Afterwards, both scripts resume their normal schedule. 2 DISABLE The DISABLE subcommand makes the specified script ineligible for execution. Currently executing scripts are not affected. Use the ABORT subcommand to stop currently executing scripts. Format DEFRAGMENT DISABLE { script-name } [ /QUALIFIERS ] 3 Parameters script-name The script-name parameter specifies the scripts to be disabled. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. 3 Restrictions o The script-name parameter is not allowed if the /ALL qualifier is used. 3 Qualifiers /ALL /ALL /NOALL (default) The /ALL qualifier indicates that all scripts in the scheduling and parameter database should be disabled. 3 Example The following example shows how to disable a script. 1. $ DEFRAGMENT DISABLE MY_SCRIPT In this example, script MY_SCRIPT is disabled. 2 ENABLE The ENABLE subcommand reactivates scripts that have been disabled. Format DEFRAGMENT ENABLE { script-name } [ /QUALIFIERS ] 3 Parameters script-name The script-name specifies the name of the scripts to be enabled. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. 3 Restrictions o The script-name parameter is not allowed if the /ALL qualifier is used. 3 Qualifiers /ALL /ALL /NOALL (default) The /ALL qualifier indicates that all disabled scripts in the scheduling and parameter database should be enabled. 3 Examples The following examples show how to use the ENABLE command. 1. $ DEFRAGMENT ENABLE/ALL In this example, all previously deactivated scripts are enabled. The enabled script executes according to its previously set schedule. Enabled predecessor or successor scripts resume executing according to their link dependencies. 2. $ DEFRAGMENT ENABLE MY_SCRIPT In this example, MY_SCRIPT is enabled. MY_SCRIPT starts executing according to the parameters and qualifiers assigned to it. 2 EXIT The EXIT subcommand exits the user from the Disk File Optimizer utility. Format DEFRAGMENT EXIT 3 Parameters None. 3 Restrictions None. 3 Qualifiers None. 3 Example The following example shows how to use the EXIT command. 1. DFO> EXIT $ This command exits the user from the Disk File Optimizer utility and returns to DCL. 2 FILE The DEFRAGMENT FILE command defragments the files given as a parameter on the command line according to the DEFRAGMENT command line qualifiers. Use this command to defragment a small number of files. To defragment a large number of files, use the DEFRAGMENT VOLUME command. Format DEFRAGMENT FILE { file-spec[,...] } [ /QUALIFIERS ] 3 Parameters file-spec[,...] The file-spec parameter identifies the file or files to be defragmented. You can use wildcards for the file specification. 3 Restrictions o A script that has the /CONTINUOUS qualifier may not be named as the predecessor of another script. o If you specify the /INTERVAL qualifier, the /PREDECESSOR qualifier is not allowed. o If /LEVEL=5 is selected, the /LOG qualifier is required. o Do not use /BRIEF and /FULL concurrently. 3 Qualifiers /AFTER /AFTER={time} /AFTER={current_time} (default) /NOAFTER The /AFTER qualifier keeps the script from executing until after the specified time. You can specify time as either an absolute time or as a combination of absolute and delta times. For complete information on specifying time values, see the VMS DCL Concepts Manual. The /AFTER qualifier has three states. It can be specified with a valid time, it can be omitted from the command line, or it can be negated (/NOAFTER). If /AFTER is specified with a valid time, the script is scheduled to execute after that time. If the /AFTER qualifier is omitted, the defragmentation software processes the command as if the /AFTER qualifier were specified with the current time. If /NOAFTER is specified, no starting time is associated with the script being defined. The /NOAFTER qualifier allows you to define a script without scheduling it to execute. To subsequently start the script, use the START subcommand. /BRIEF /BRIEF (default) /NOBRIEF The /BRIEF qualifier has meaning only when the /LOG qualifier is also present. The /BRIEF qualifier requests a brief log of all actions taken by the defragmentation process. This log includes beginning and ending file status information. The /BRIEF and /FULL qualifiers are mutually exclusive, and /NOBRIEF produces the same result as /FULL. The /BRIEF qualifier is the default. /CONSOLIDATE_FREESPACE /CONSOLIDATE_FREESPACE /NOCONSOLIDATE_FREESPACE (default) The /CONSOLIDATE_FREESPACE qualifier tells the Disk File Optimizer to use its free space consolidation algorithm. /DORMANT /DORMANT=(file-spec[,...]) /NODORMANT (default) The /DORMANT qualifier indicates files to be considered dormant when final file placement decisions are made. Dormant files are placed on the volume to allow placing other files in optimum disk locations. In general, they are placed further away from the ODS-2 data structures than /FREQUENT files and files not classified in any manner. If a file is indicated in both the DORMANT and FREQUENT lists, it is considered dormant. If a file is indicated in both the EXCLUDE and DORMANT lists, it is excluded. NOTE The amount of free space on the volume, the number of files currently being accessed, and other factors influence file placement. Thus, the Disk File Optimizer does not guarantee file placement, but makes every effort to place files as described. The file-spec field allows wildcard characters. You can specify wildcard characters in place of the directory name, file name, file type, or file version number field. The default file-spec for all wildcard operations is DISK:[000000...]*.*;*. Thus, specifying *.TMP;* selects all *.TMP;* files on the entire volume. /EPILOGUE /EPILOGUE={file-name} /NOEPILOGUE (default) The /EPILOGUE qualifier identifies a DCL command file which DFO executes upon completion of the DEFRAGMENT FILE operation. /EXCLUDE /EXCLUDE=(file-spec[,...]) /NOEXCLUDE (default) The /EXCLUDE qualifier specifies files to be excluded from processing. The defragmentation process ignores files matching the listed file specifications. Any file indicated in the EXCLUDE list and in either the FREQUENT or DORMANT lists is excluded from processing. The file-spec field allows wildcard characters. You can specify wildcard characters in place of the directory name, file name, file type, or file version number field. The default file-spec for all wildcard operations is DISK:[000000...]*.*;*. Thus, specifying *.TMP;* selects all *.TMP;* files on the entire volume. NOTE The defragmentation process always excludes system files, open files, files excluded in an options file (/OPTIONS qualifier), and files excluded using the /IGNORE qualifier. /FREQUENT /FREQUENT=(file-spec[,...]) /NOFREQUENT (default) The /FREQUENT qualifier indicates files to be considered frequently accessed when final file placement decisions are made. Frequent files are placed to optimize access speed. If a file is indicated in both the FREQUENT and DORMANT lists, it is considered dormant. If a file is indicated in both the FREQUENT and EXCLUDE lists, it is excluded. NOTE The amount of free space on the volume, the number of files currently being accessed, and other factors influence file placement. Thus, the Disk File Optimizer does not guarantee file placement, but makes every effort to place files as described. The file-spec field allows wildcard characters. You can specify wildcard characters in place of the directory name, file name, file type, or file version number field. The default file-spec for all wildcard operations is DISK:[000000...]*.*;*. Thus, specifying *.TMP;* selects all *.TMP;* files on the entire volume. /FULL /FULL /NOFULL (default) The /FULL qualifier requests a full log of all actions taken by the defragmentation process. The /FULL qualifier has no meaning if the /LOG qualifier is absent. The /FULL and /BRIEF qualifiers are mutually exclusive, and /NOFULL provides the same functionality as /BRIEF. /HOTFILE_DATABASE /HOTFILE_DATABASE /NOHOTFILE_DATABASE (default) The /HOTFILE_DATABASE qualifier causes the defragmenter to query the appropriate hotfile database and append the list of hotfiles to the defragmenter's /FREQUENT file list. /IGNORE /IGNORE=(keyword[,...]) /IGNORE=(PLACED) (default) /NOIGNORE The /IGNORE qualifier requests that the defragmentation process ignore certain types of files as specified by the following keywords: o INDEXED-Ignores all RMS indexed files o NOINDEXED-May defragment RMS indexed files o PLACED-Ignores all files with explicit placement flags set in their headers o NOPLACED-May defragment files with explicit placement flags Files indicated by the /IGNORE qualifier are added to the EXCLUDE list. The default value (/IGNORE=PLACED) indicates that files with explicit placement control should be ignored, and that RMS indexed files should be defragmented and placed in appropriate locations on the volume. /INHERIT /INHERIT={script-name} /NOINHERIT (default) The purpose of the /INHERIT qualifier is to make script creation easier. By inheriting most of the command data from a previously entered script and modifying only a few items (such as volume name), a completely new script can be created. The /INHERIT qualifier creates a database entry for a new script in the following way: o Copies all fields from the specified script to the new script. o Overwrites any qualifier or parameter values in the new script with those specified on the command line. o Names the new script as appropriate. The user may specify a script name using the /SCRIPT={script- name} qualifier. Otherwise, the defragmentation software creates a unique script name. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. /INTERVAL /INTERVAL={delta-time} /NOINTERVAL (default) The /INTERVAL qualifier causes a script to execute at regularly scheduled intervals. The /INTERVAL qualifier specifies the minimum time between two consecutive executions of a script. Specify time as a delta time. Refer to the VMS DCL Concepts Manual for more information on specifying times. If you do not specify a time with the /INTERVAL qualifier, a default value of one day is used. This value causes the associated script to run every 24 hours. If you specify the /AFTER qualifier with the /INTERVAL qualifier, the first defragmentation operation occurs at or after the time specified by the /AFTER qualifier; all subsequent operations execute at intervals set according to the /INTERVAL qualifier. /LEVEL /LEVEL={n} /LEVEL=1 (default) The defragmentation process selects files for defragmentation (from among those not excluded) based on the /LEVEL qualifier. Once a file is selected as a candidate, the defragmentation process attempts to fully defragment that file (make it 100 percent contiguous). Specify the level number as an integer ranging from one to five: o /LEVEL=1 (default) Any file that is not 100 percent contiguous, or can be selected using levels two through four, is a candidate for defragmentation. o /LEVEL=2 Any file whose extents cannot be completely mapped by the mapping window, or that can be selected using levels three or four, is a candidate for defragmentation. The default window value is seven and can be set for a given volume using: $ SET VOLUME {device-spec}/WINDOWS=[n] o /LEVEL=3 Any file with retrieval pointers in more than one file header, or that can be selected using level four, is a candidate for defragmentation. o /LEVEL=4 The defragmentation process for level 4 processing performs only free space consolidation. This level is used in conjunction with the /CONSOLIDATE_ FREESPACE qualifier. o /LEVEL=5 This level requests a volume analysis only; no defragmentation occurs. The statistical results are available in the log file, which is required when /LEVEL=5 is selected (see the /LOG qualifier). If level five is selected, the /LEVEL=2 candidate file specifications are listed in the full log file. /LOG /LOG={file-spec} /NOLOG (default) The /LOG qualifier causes the defragmentation process to create a file containing a list of all its operations. The information in the log file varies with the presence of the /FULL or /BRIEF qualifiers. The /FULL qualifier lists all files analyzed by the defragmentation process and reports their disposition during each phase of defragmentation. The /BRIEF qualifier lists only the statistics of each phase, such as number of files analyzed, and number of files defragmented. /MAIL_NOTIFICATION /MAIL_NOTIFICATION /NOMAIL_NOTIFICATION (default) The /MAIL_NOTIFICATION qualifier requests that brief status and termination messages regarding defragmentation processes be mailed to the mail distribution list provided in the file DFG$MAIL_ ADDRESS. /NODE /NODE=(node-name[,...]) /NONODE (default) The /NODE qualifier limits the scope of the DEFRAGMENT command to the node or set of nodes specified by /NODE=(node-name). By default, defragmentation processes may execute on any LMF licensed node in the system. /OPCOM_NOTIFICATION /OPCOM_NOTIFICATION (default) /NOOPCOM_NOTIFICATION The /OPCOM_NOTIFICATION qualifier requests that brief status and termination messages regarding defragmentation processes be sent to OPCOM. /OPTIONS /OPTIONS={file-spec} /NOOPTIONS (default) The /OPTIONS qualifier provides an alternate method for associating files with the /DORMANT, /EXCLUDE, or /FREQUENT qualifiers. If the list of files for any of these qualifiers is quite large, you can create a separate file that contains this information. Each record in the options file consists of a file name followed by one of the following keywords: o /EXCLUDE-File to be excluded o /FREQUENT-File to be considered frequently accessed o /DORMANT-File to be considered dormant The following example shows the contents of an options file called MYOPTFILE.OPT. This file specifies that all files on the target device called FILE1.EXE are frequent files, all files in the [ARCHIVE] directory are to be excluded, and all files in the [OLDSTUFF] directory and its subdirectories are dormant. FILE1.EXE/FREQUENT [ARCHIVE]*.*;*/EXCLUDE [OLDSTUFF...]*.*;*/DORMANT Files indicated by the /EXCLUDE qualifier and by either the /DORMANT or /FREQUENT qualifier are excluded. Files indicated by the /DORMANT qualifier and by the /FREQUENT qualifier are considered dormant. This rule is applied equally across all files specified in the /OPTIONS file, as well as those associated with these qualifiers on the command line. /PREDECESSOR /PREDECESSOR={script-name} /NOPREDECESSOR (default) The /PREDECESSOR qualifier links scripts. These scripts execute in sequence; one successfully completes before the next one begins. The predecessor script name must exist in the scheduling database or an error status message is returned. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script- name specification. /PRIORITY /PRIORITY=(DEFAULT=n, MINIMUM=n) /NOPRIORITY (default) The /PRIORITY qualifier specifies priorities for the defragment volume operation. /PROLOGUE /PROLOGUE={file-name} /NOPROLOGUE (default) The /PROLOGUE qualifier identifies a DCL command file which DFO executes just before the DEFRAGMENT FILE operation starts. /RVN /RVN=n /RVN=0 (default) When you have a bound volume set, use this qualifier to identify a disk from the volume set or all disks in the volume set. The default of zero tells the Disk File Optimizer to defragment all disks in the bound volume set. Specify a relative volume number (RVN) to defragment a specific disk that belongs to a bound volume set. /SCRIPT /SCRIPT={script-name} /NOSCRIPT (default) The /SCRIPT qualifier assigns a user-supplied name to a script. If a duplicate script-name is selected, defragmentation software issues a duplicate script name error message and does not enter the new script into the database-no defragmentation takes place. A script name may be up to 64 characters in length and may contain any of the following characters: o Any alphanumeric character o Underscore ( _ ) o Hyphen ( - ) o Dollar sign ( $ ) Observe the following rules when naming a script: o You can use any combination of uppercase and lowercase letters. o You cannot begin script names using the dollar sign, but you can include the dollar sign within the script name. (The dollar sign is reserved for special use by Digital Equipment Corporation.) o You should not end a script name with a hyphen, since the hyphen is the DCL continuation character. The VMS DCL Concepts Manual contains more information on naming conventions. /TIME_LIMIT /TIME_LIMIT={delta-time} /NOTIME_LIMIT (default) The /TIME_LIMIT qualifier specifies the maximum elapsed time allowed for a given defragmentation operation. If the time limit is exceeded, the defragmentation process is aborted. Specify time as a delta time. Refer to the VMS DCL Concepts Manual for more information on specifying times. For linked scripts, the time limit of the first script applies to the whole set. Time limits specified with successor scripts apply to these scripts only. If the time limit is set unreasonably low, the defragmentation process may not accomplish useful defragmentation. /WRITE_CHECK /WRITE_CHECK /NOWRITE_CHECK (default) The /WRITE_CHECK qualifier requests that a read- after-write check be performed on all defragmented or placed files. This qualifier significantly extends the execution time of a defragmentation process. 3 Examples The following examples show different ways to defragment a file or group of files and illustrate how to use the common qualifiers. 1. $ DEFRAGMENT FILE *.C This command defragments all files with a .C extension on the user's current default device. That is, the device portion of the directory specification returned from a DCL SHOW DEFAULT command. The RMS default string is [000000...]*.*;*. 2. DFO> DEFRAGMENT FILE *.C This command defragments all files with a .C extension on the user's current default device. The only difference between this command and the previous example is that this command is entered from within the Disk File Optimizer utility instead of from the DCL prompt. 3. $ DEFRAGMENT FILE *.C/VOLUME=SYS$SYSDEVICE: This command is the same as the previous one, except that the RMS default string is now SYS$SYSDEVICE:[000000...]*.C;*. 4. $ DEFRAGMENT FILE SYS$LOGIN:LOGIN.COM;2/EXCLUDE=*.OLD;* This command defragments the user's LOGIN.COM file and excludes all files with a .OLD extension. 5. $ DEFRAGMENT FILE/INHERIT=OTHER_FILE_SCRIPT.NOAFTER This commands creates a file script identical to the OTHER_ FILE_SCRIPT and allows the Disk File Optimizer to name it (DFG$XXX). 6. $ DEFRAGMENT FILE *.RDB/INHERIT=X $_/SCRIPT=Y/VOLUME=SYS$SYSTEM This command creates a script called Y that defragments all RDB files on SYS$SYSTEM. Other script characteristics, such as log file, are inherited from script X. 2 HELP The HELP subcommand invokes VMS help for the Disk File Optimizer utility. Format DEFRAGMENT HELP 3 Parameters None. 3 Restrictions None. 3 Qualifiers None. 3 Examples The following examples show the various ways you can access HELP for the Disk File Optimizer utility. 1. $ DEFRAGMENT HELP This command invokes HELP for the Disk File Optimizer utility directly from DCL. 2. $ HELP DEFRAGMENT This command invokes HELP for the Disk File Optimizer utility directly from DCL. 3. DFO> HELP This command invokes HELP from within the Disk File Optimizer utility. 2 MODIFY The MODIFY subcommand allows you to change the qualifiers associated with a particular script. Format DEFRAGMENT MODIFY { script-name } [ /QUALIFIERS ] 3 Parameters script-name The script-name parameter identifies the script to modify. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. 3 Restrictions o A script that has the /CONTINUOUS qualifier may not be named as the predecessor of another script. o If you specify the /INTERVAL qualifier, the /PREDECESSOR qualifier is not allowed. o If /LEVEL=5 is selected, the /LOG qualifier is required. o Do not use /BRIEF and /FULL concurrently. o Do not use /CONTINUOUS and /INTERVAL for a script. 3 Qualifiers /AFTER /AFTER={time} /AFTER={current_time} (default) /NOAFTER The /AFTER qualifier keeps the script from executing until after the specified time. You can specify time as either an absolute time or as a combination of absolute and delta times. For complete information on specifying time values, see the VMS DCL Concepts Manual. The /AFTER qualifier has three states. It can be specified with a valid time, it can be omitted from the command line, or it can be negated (/NOAFTER). If /AFTER is specified with a valid time, the script is scheduled to execute after that time. If the /AFTER qualifier is omitted, the defragmentation software processes the command as if the /AFTER qualifier were specified with the current time. If /NOAFTER is specified, no starting time is associated with the script being defined. The /NOAFTER qualifier allows you to define a script without scheduling it to execute. To subsequently start the script, use the START subcommand. /BRIEF /BRIEF (default) /NOBRIEF The /BRIEF qualifier has meaning only when the /LOG qualifier is also present. The /BRIEF qualifier requests a brief log of all actions taken by the defragmentation process. This log includes beginning and ending volume status information. The /BRIEF and /FULL qualifiers are mutually exclusive, and /NOBRIEF produces the same result as /FULL. The /BRIEF qualifier is the default. /CONSOLIDATE_FREESPACE /CONSOLIDATE_FREESPACE /NOCONSOLIDATE_FREESPACE (default) The /CONSOLIDATE_FREESPACE qualifier tells the Disk File Optimizer to use its free space consolidation algorithm. /CONTINUOUS /CONTINUOUS /NOCONTINUOUS (default) The /CONTINUOUS qualifier links the script with itself. Thus, the script repeatedly executes. After each successful defragmentation operation, the script becomes eligible for execution again. As long as any PROCESS_LIMITs (see the SET subcommand) are not violated, the script executes repeatedly. If all PROCESS_LIMITs have been reached, the script is queued until an outstanding defragmentation process completes, then the script is allowed to execute. By default, the defragmentation process associated with a script may execute on any appropriately licensed node in a cluster. Thus, successive defragmentation processes do not necessarily execute on the same node. /DORMANT /DORMANT=(file-spec[,...]) /NODORMANT (default) The /DORMANT qualifier indicates files to be considered dormant when final file placement decisions are made. Dormant files are placed on the volume to allow placing other files in optimum disk locations. In general, they are placed further away from the ODS-2 data structures than frequent files and files not classified in any manner. If a file is indicated in both the DORMANT and FREQUENT lists, it is considered dormant. If a file is indicated in both the EXCLUDE and DORMANT lists, it is excluded. NOTE The amount of free space on the volume, the number of files currently being accessed, and other factors influence file placement. Thus, the Disk File Optimizer does not guarantee file placement, but makes every effort to place files as described. The file-spec field allows wildcard characters. You can specify wildcard characters in place of the directory name, file name, file type, or file version number field. The default file-spec for all wildcard operations is DISK:[000000...]*.*;*. Thus, specifying *.TMP;* selects all *.TMP;* files on the entire volume. /EPILOGUE /EPILOGUE={file-name} /NOEPILOGUE (default) The /EPILOGUE qualifier identifies a DCL command file which DFO executes upon completion of the DEFRAGMENT FILE operation. /EXCLUDE /EXCLUDE=(file-spec[,...]) /NOEXCLUDE (default) The /EXCLUDE qualifier specifies files to be excluded from processing. The defragmentation process ignores files matching the listed file specifications. Any file indicated in the EXCLUDE list and in either the FREQUENT or DORMANT lists is excluded from processing. The file-spec field allows wildcard characters. You can specify wildcard characters in place of the directory name, file name, file type, or file version number field. The default file-spec for all wildcard operations is DISK:[000000...]*.*;*. Thus, specifying *.TMP;* selects all *.TMP;* files on the entire volume. NOTE The defragmentation process always excludes system files, open files, files excluded in an options file (/OPTIONS qualifier), and files excluded using the /IGNORE qualifier. /FILES /FILES=(file-spec[,...]) The /FILES qualifier modifies the list of files to be defragmented. /FREQUENT /FREQUENT=(file-spec[,...]) /NOFREQUENT (default) The /FREQUENT qualifier indicates files to be considered frequently accessed when final file placement decisions are made. Frequent files are placed to optimize access speed. If a file is indicated in both the FREQUENT and DORMANT lists, it is considered dormant. If a file is indicated in both the FREQUENT and EXCLUDE lists, it is excluded. NOTE The amount of free space on the volume, the number of files currently being accessed, and other factors influence file placement. Thus, the Disk File Optimizer does not guarantee file placement, but makes every effort to place files as described. The file-spec field allows wildcard characters. You can specify wildcard characters in place of the directory name, file name, file type, or file version number field. The default file-spec for all wildcard operations is DISK:[000000...]*.*;*. Thus, specifying *.TMP;* selects all *.TMP;* files on the entire volume. /FULL /FULL /NOFULL (default) The /FULL qualifier requests a full log of all actions taken by the defragmentation process. The /FULL qualifier has no meaning if the /LOG qualifier is absent. The /FULL and /BRIEF qualifiers are mutually exclusive, and /NOFULL provides the same functionality as /BRIEF. /HOTFILE_DATABASE /HOTFILE_DATABASE /NOHOTFILE_DATABASE (default) The /HOTFILE_DATABASE qualifier causes the defragmenter to query the appropriate hotfile database and append the list of hotfiles to the defragmenter's /FREQUENT file list. /IGNORE /IGNORE=(keyword[,...]) /IGNORE=(PLACED) (default) /NOIGNORE The /IGNORE qualifier requests that the defragmentation process ignore certain types of files as specified by the following keywords: o INDEXED-Ignores all RMS indexed files o NOINDEXED-May defragment RMS indexed files o PLACED-Ignores all files with explicit placement flags set in their headers o NOPLACED-May defragment files with explicit placement flags Files indicated by the /IGNORE qualifier are added to the EXCLUDE list. The default value (/IGNORE=PLACED) indicates that files with explicit placement control should be ignored, and that RMS indexed files should be defragmented and placed in appropriate locations on the volume. /INTERVAL /INTERVAL={delta-time} /NOINTERVAL (default) Causes a script to execute at regularly scheduled intervals. The /INTERVAL qualifier specifies the minimum time between two consecutive executions of a script. Specify time as a delta time. Refer to the VMS DCL Concepts Manual for more information on specifying times. If you do not specify a time with the /INTERVAL qualifier, a default value of 1 day is used. This value causes the associated script to run every 24 hours. If you specify the /AFTER qualifier with the /INTERVAL qualifier, the first defragmentation operation occurs at or after the time specified by the /AFTER qualifier; all subsequent operations execute at intervals set according to the /INTERVAL qualifier. /LEVEL /LEVEL={n} /LEVEL=2 (default) The defragmentation process selects files for defragmentation (from among those not excluded) based on the /LEVEL qualifier. Once a file is selected as a candidate, the defragmentation process attempts to fully defragment that file (make it 100 percent contiguous). Specify the level number as an integer ranging from one to five: o /LEVEL=1 Any file that is not 100 percent contiguous, or can be selected using levels two through four, is a candidate for defragmentation. o /LEVEL=2 (default) Any file whose extents cannot be completely mapped by the mapping window, or that can be selected using levels three or four, is a candidate for defragmentation. The default window value is seven and can be set for a given volume using: $ SET VOLUME {device-spec}/WINDOWS=[n] o /LEVEL=3 Any file with retrieval pointers in more than one file header, or that can be selected using level four, is a candidate for defragmentation. o /LEVEL=4 The defragmentation process for level 4 processing performs only free space consolidation. This level is used in conjunction with the /CONSOLIDATE_ FREESPACE qualifier. o /LEVEL=5 This level requests a volume analysis only; no defragmentation occurs. The statistical results are available in the log file, which is required when /LEVEL=5 is selected (see the /LOG qualifier). If level five is selected, the /LEVEL=2 candidate file specifications are listed in the full log file. /LOG /LOG={file-spec} /NOLOG (default) The /LOG qualifier causes the defragmentation process to create a file containing a list of all its operations. The information in the log file varies with the presence of the /FULL or /BRIEF qualifiers. The /FULL qualifier lists all files analyzed by the defragmentation process and reports their disposition during each phase of defragmentation. The /BRIEF qualifier lists only the statistics of each phase, such as number of files analyzed, and number of files defragmented. /MAIL_NOTIFICATION /MAIL_NOTIFICATION /NOMAIL_NOTIFICATION (default) The /MAIL_NOTIFICATION qualifier requests that brief status and termination messages regarding defragmentation processes be mailed to the mail distribution list provided in the file DFG$MAIL_ ADDRESS. /NODE /NODE=(node-name[,...]) /NONODE (default) The /NODE qualifier limits the scope of the DEFRAGMENT command to the node or set of nodes specified by /NODE=(node-name). By default, defragmentation processes may execute on any LMF licensed node in the system. /OPCOM_NOTIFICATION /OPCOM_NOTIFICATION (default) /NOOPCOM_NOTIFICATION The /OPCOM_NOTIFICATION qualifier requests that brief status and termination messages regarding defragmentation processes be sent to OPCOM. /OPTIONS /OPTIONS={file-spec} /NOOPTIONS (default) The /OPTIONS qualifier provides an alternate method for associating files with the /DORMANT, /EXCLUDE, or /FREQUENT qualifiers. If the list of files for any of these qualifiers is quite large, you can create a separate file that contains this information. Each record in the options file consists of a file name followed by one of the following keywords: o /EXCLUDE-File to be excluded o /FREQUENT-File to be considered frequently accessed o /DORMANT-File to be considered dormant The following example shows the contents of an options file called MYOPTFILE.OPT. This file specifies that all files on the target device called FILE1.EXE are frequent files, all files in the [ARCHIVE] directory are to be excluded, and all files in the [OLDSTUFF] directory and its subdirectories are dormant. FILE1.EXE/FREQUENT [ARCHIVE]*.*;*/EXCLUDE [OLDSTUFF...]*.*;*/DORMANT Files indicated by the /EXCLUDE qualifier and by either the /DORMANT or /FREQUENT qualifier are excluded. Files indicated by the /DORMANT qualifier and by the /FREQUENT qualifier are considered dormant. This rule is applied equally across all files specified in the /OPTIONS file, as well as those associated with these qualifiers on the command line. /PREDECESSOR /PREDECESSOR={script-name} /NOPREDECESSOR (default) The /PREDECESSOR qualifier identifies the name of the script that precedes the execution of this script in a linked set of scripts. These scripts execute in sequence; one successfully completes before the next one begins. The predecessor script name must exist in the scheduling database or an error status message is returned. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script- name specification. /PRIORITY /PRIORITY=(DEFAULT=n, MINIMUM=n) /NOPRIORITY (default) The /PRIORITY qualifier specifies priorities for the defragment volume operation. /PROLOGUE /PROLOGUE={file-name} /NOPROLOGUE (default) The /PROLOGUE qualifier identifies a DCL command file which DFO executes just before the DEFRAGMENT FILE or DEFRAGMENT VOLUME operation starts. /RVN /RVN=n /RVN=0 (default) When you have a bound volume set, use this qualifier to identify a disk from the volume set or all disks in the volume set. The default of zero tells the Disk File Optimizer to defragment all disks in the bound volume set. Specify a relative volume number (RVN) to defragment a specific disk that belongs to a bound volume set. /SCRIPT /SCRIPT={script-name} /NOSCRIPT (default) The /SCRIPT qualifier assigns a new name to a script. If a duplicate script-name is selected, defragmentation software issues a duplicate script name error message and does not enter the new script into the database-no defragmentation takes place. A script name may be up to 64 characters in length and may contain any of the following characters: o Any alphanumeric character o Underscore ( _ ) o Hyphen ( - ) o Dollar sign ( $ ) Observe the following rules when naming a script: o Use any combination of uppercase and lowercase letters. o Do not begin script names using the dollar sign. However, you can include the dollar sign within the script name. (The dollar sign is reserved for special use by Digital Equipment Corporation.) o Do not end a script name with a hyphen, since the hyphen is the DCL continuation character. The VMS DCL Concepts Manual contains more information on naming conventions. /TIME_LIMIT /TIME_LIMIT={delta-time} /NOTIME_LIMIT (default) The /TIME_LIMIT qualifier specifies the maximum elapsed time allowed for a given defragmentation operation. If the time limit is exceeded, the defragmentation process is aborted. Specify time as a delta time. Refer to the VMS DCL Concepts Manual for more information on specifying times. For linked scripts, the time limit of the first script applies to the whole set. Time limits specified with successor scripts apply to these scripts only. If the time limit is set unreasonably low, the defragmentation process may not accomplish useful defragmentation. /VOLUME /VOLUME={volume-name} /NOVOLUME (default) Identifies the volume where the files reside. /WRITE_CHECK /WRITE_CHECK /NOWRITE_CHECK (default) The /WRITE_CHECK qualifier requests that a read- after-write check be performed on all defragmented or placed files. This qualifier significantly extends the execution time of a defragmentation process. 3 Examples The following examples show how you can modify an existing script using the common qualifiers. 1. $ DEFRAGMENT MODIFY C/SCRIPT=A This command changes the name of script C to A. 2. $ DEFRAGMENT MODIFY */MAIL_NOTIFICATION This command turns on mail notification for all scripts in the database. 3. $ DEFRAGMENT MODIFY myscript/LOG=new_log/NOPREDECESSOR This command causes subsequent executions of myscript to generate a log file called NEW_LOG.LOG, located in the user's default directory. The NOPREDECESSOR qualifier disassociates myscript from its predecessor. However, any script for which myscript is a predecessor remains dependent upon the execution of myscript. 4. $ DEFRAGMENT MODIFY */SCRIPT=* This command renames all scripts to themselves. 5. $ DEFRAGMENT MODIFY *C/SCRIPT=*D This command changes the name of each script that ends in C to end in D. For instance, DAILYC becomes DAILYCD. 6. $ DEFRAGMENT MODIFY *C/SCRIPT=*D/PRED=*X This command shows the potential pitfalls with using multiple wildcards in a DEFRAGMENT command. Consider the following scenario: Suppose you have four scripts (ABC, ATLASX, ABCX, and DAILYC) and you enter this command. The Disk File Optimizer first finds all scripts whose names end in C (ABC and DAILYC). Then, according to what is written on the command line, we would expect it to change their names to end in D. Thus, ABC would become ABCD, and DAILYC would become DAILYCD. After renaming the files, we would expect the script ABCD to be modified such that it has a predecessor of ABCX, and DAILYCD to have a predecessor of DAILYCX. However, since there is no script named DAILYCX in the database, the command fails. Since this was entered on one command line, none of these changes actually occur. 2 MONITOR The MONITOR subcommand invokes the monitor function to illustrate the progress of ongoing defragmentation processes. Format DEFRAGMENT MONITOR { script-name|volume-name } [ /QUALIFIERS ] 3 Parameters script-name|volume-name The parameter for the MONITOR subcommand is either a script name or a volume name for Defrag PLUS. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. If a volume name is supplied, then you must use the /VOLUME qualifier to tell Defrag PLUS the parameter is a volume name, rather than a script name. 3 Restrictions o If a volume name is entered as a parameter, the /VOLUME qualifier must be used. 3 Qualifiers /CONTINUOUS /CONTINUOUS (default) NOCONTINUOUS The /CONTINUOUS qualifier invokes a continuous monitor display. Entering Ctrl/C, Ctrl/Y, or Ctrl /Z terminates this display. Using /NOCONTINUOUS indicates the monitor process should provide a snapshot display and then exit to the DCL prompt. /VOLUME /VOLUME (default) /NOVOLUME The /VOLUME qualifier indicates that a volume name instead of a script name is present on the command line. The /VOLUME qualifier must be used when a volume name is provided as a parameter to the MONITOR subcommand. 3 Examples The following examples show how to invoke the monitor. 1. $ DEFRAGMENT MONITOR MY_SCRIPT/NOVOLUME In this example, the monitor function displays ongoing run-time statistics for the defragmentation process associated with MY_ SCRIPT. It also displays an approximate free-space map of the target volume. The display continues until interrupted with a Ctrl/C, Ctrl/Y, or Ctrl/Z because the /CONTINUOUS qualifier is present by default. 2. $ DEFRAGMENT MONITOR DISK$ONE/NOCONTINUOUS In this example, the defragmentation process executing against DISK$ONE is monitored. Since the /NOCONTINUOUS qualifier was specified, the monitor function samples the defragmentation process statistics and the free space on DISK$ONE one time before exiting to the DCL prompt. 2 OFFLINE_VOLUME The DEFRAGMENT OFFLINE_VOLUME command defragments the INDEXF.SYS file on the offline volume given as a parameter to the command line according to the defragment command line qualifiers. Format DEFRAGMENT OFFLINE_VOLUME { volume-name } [ /QUALIFIERS ] [ /QUALIFIERS ]) 3 Parameters volume-name The volume-name is the name of the volume that is to have the INDEXF.SYS file defragmented. 3 Restrictions o This command is only valid on a disk device that is not mounted. If the device is mounted an error will occur and the process will abort. o For a bound volume set, this utility only works on the "ROOT" volume. 3 Qualifiers /AFTER /AFTER={time} /AFTER={current_time} (default) /NOAFTER The /AFTER qualifier keeps the script from executing until after the specified time. You can specify time as either an absolute time or as a combination of absolute and delta times. For complete information on specifying time values, see the VMS DCL Concepts Manual. The /AFTER qualifier has three states. It can be specified with a valid time, it can be omitted from the command line, or it can be negated (/NOAFTER). If /AFTER is specified with a valid time, the script is scheduled to execute after that time. If the /AFTER qualifier is omitted, the defragmentation software processes the command as if the /AFTER qualifier were specified with the current time. If /NOAFTER is specified, no starting time is associated with the script being defined. The /NOAFTER qualifier allows you to define a script without scheduling it to execute. To subsequently start the script, use the START subcommand. /EPILOGUE /EPILOGUE={file-name} /NOEPILOGUE (default) The /EPILOGUE qualifier identifies a DCL command file which DFO executes upon completion of the DEFRAGMENT VOLUME operation. /INTERVAL /INTERVAL={delta-time} /NOINTERVAL (default) Causes a script to execute at regularly scheduled intervals. The /INTERVAL qualifier specifies the minimum time between two consecutive executions of a script. Specify time as a delta time. Refer to the VMS DCL Concepts Manual for more information on specifying times. If you do not specify a time with the /INTERVAL qualifier, a default value of 1 day is used. This value causes the associated script to run every 24 hours. If you specify the /AFTER qualifier with the /INTERVAL qualifier, the first defragmentation operation occurs at or after the time specified by the /AFTER qualifier; all subsequent operations execute at intervals set according to the /INTERVAL qualifier. /LOG /LOG={file-spec} /NOLOG (default) The /LOG qualifier causes the defragmentation process to create a file containing a list of all its operations. The information in the log file varies with the presence of the /FULL or /BRIEF qualifiers. The /FULL qualifier lists all files analyzed by the defragmentation process and reports their disposition during each phase of defragmentation. The /BRIEF qualifier lists only the statistics of each phase, such as number of files analyzed, and number of files defragmented. /MAIL_NOTIFICATION /MAIL_NOTIFICATION /NOMAIL_NOTIFICATION (default) The /MAIL_NOTIFICATION qualifier requests that brief status and termination messages regarding defragmentation processes be mailed to the mail distribution list provided in the file DFG$MAIL_ ADDRESS. /NODE /NODE=(node-name[,...]) /NONODE (default) The /NODE qualifier limits the scope of the DEFRAGMENT command to the node or set of nodes specified by /NODE=(node-name). By default, defragmentation processes may execute on any LMF licensed node in the system. /OPCOM_NOTIFICATION /OPCOM_NOTIFICATION (default) /NOOPCOM_NOTIFICATION The /OPCOM_NOTIFICATION qualifier requests that brief status and termination messages regarding defragmentation processes be sent to OPCOM. /PROLOGUE /PROLOGUE={file-name} /NOPROLOGUE (default) The /PROLOGUE qualifier identifies a DCL command file which DFO executes just before the DEFRAGMENT FILE operation starts. /SCRIPT /SCRIPT={script-name} /NOSCRIPT (default) The /SCRIPT qualifier assigns a user-supplied name to a script. If a duplicate script-name is selected, defragmentation software issues a duplicate script name error message and does not enter the new script into the database-no defragmentation takes place. A script name may be up to 64 characters in length and may contain any of the following characters: o Any alphanumeric character o Underscore ( _ ) o Hyphen ( - ) o Dollar sign ( $ ) Observe the following rules when naming a script: o You can use any combination of uppercase and lowercase letters. o You cannot begin script names using the dollar sign, but you can include the dollar sign within the script name. (The dollar sign is reserved for special use by Digital Equipment Corporation.) o You should not end a script name with a hyphen, since the hyphen is the DCL continuation character. The VMS DCL Concepts Manual contains more information on naming conventions. 2 REMOVE The REMOVE subcommand deletes the specified script from the defragmentation scheduling and parameter database. Format DEFRAGMENT REMOVE { script-name[,...] } [ /QUALIFIERS ] 3 Parameters script-name The script-name parameter specifies the script to remove from the defragmentation database. You can use wildcards in the script- name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. This parameter is not allowed if the /ALL qualifier is used. 3 Restrictions o If the /ALL qualifier is used, then the script-name parameter cannot be used. 3 Qualifiers /AFTER /AFTER=time /NOAFTER (default) The /AFTER qualifier does not delete the script until after the specified time. Specify time as a VMS absolute time or combination absolute and delta time. Refer to the VMS DCL Concepts Manual for more information on how to specify time. /ALL /ALL /NOALL (default) The /ALL qualifier indicates that all scripts are to be removed from the scheduling and parameter database. If /ALL is used, the script-name parameter is not allowed. 3 Example The following example shows how to remove a script after a specified time. 1. $ DEFRAGMENT REMOVE MY_SCRIPT/AFTER=16:30 In this example, MY_SCRIPT is removed from the database. It is removed after 16:30 on the day this command is entered. 2 SET The SET subcommand defines or changes the value of the defragmentation process limits. Format DEFRAGMENT SET { (parameter=value[,...]) } [ /QUALIFIERS ] 3 Parameters keywords: o CPU_LIMIT: specifies the percent of CPU usage for any one defragmentation process. The CPU percent is the percent of a single CPU. o IO_LIMIT: specifies the maximum direct I/O rate (per second) of any one defragmentation process. o PROCESS_LIMIT: specifies the maximum number of defragmentation processes per node. 3 Restrictions o None. 3 Qualifiers /NODE /NODE=(node-name[,...]) /NONODE (default) The /NODE qualifier limits the scope of the SET subcommand. By default, a given parameter is set identically on all nodes in the scheduling database. To limit parameters to fewer nodes, specify the node names with the /NODE qualifier. 3 Examples The following examples show how to set limits using the SET subcommand and its qualifiers. 1. $ DEFRAGMENT SET PROCESS_LIMIT=3, IO_LIMIT=14/NODE=NODE_1 In this example, the maximum number of defragmentation processes that can occur on NODE_1 is three. Further, a restriction of 14 direct I/Os per second is placed on each of these three defragmentation processes. 2. $ DEFRAGMENT SET CPU_LIMIT=50 In this example, the maximum CPU percentage allocated to any defragmentation process is set to 50 percent on all nodes in the system. If a defragmentation process exceeds this limit, its priority is decremented each minute (approximately) until it reaches that specified by the /PRIORITY qualifier or three.. 2 SHOW The SHOW subcommand displays information about the fragmentation state of the given volume and information from the scheduling database. Format DEFRAGMENT SHOW { script-name|volume-name } [ /QUALIFIERS ] 3 Parameters script-name|volume-name The parameter for the SHOW subcommand is either a script name or a volume name, or it can be omitted if the /ALL qualifier is used. If a script name is supplied or if the /PARAMETERS qualifier is specified, the SHOW command queries the scheduling database and displays this information. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. If a volume name is supplied (/VOLUME required), the SHOW command displays information about the fragmentation state of the specified volume. If a list of names is provided, the list cannot contain both script and volume names. 3 Restrictions o If showing a script or volume, do not use the /ALL qualifier o If it is a volume, then you must use the /VOLUME qualifier 3 Qualifiers /ALL /ALL /NOALL (default) The /ALL qualifier is used when showing information from the scheduling database. It displays information about all scripts and parameters in the scheduling database. If /ALL is used, the script-name parameter is not allowed. /COMMAND_LINE /COMMAND_LINE /NOCOMMAND_LINE (default) The /COMMAND_LINE qualifier is used when showing information from the scheduling database. It formats the output of the SHOW subcommand as a valid DEFRAGMENT command line. Thus, all the data in the scheduling database can be extracted into a file ( /ALL/COMMAND_LINE/OUTPUT=file.ext). /DEVICE /DEVICE=(device_spec[,device_spec])... The /DEVICE qualifier selects only those scripts that match the script name provided on the command line and that target any devices named with this qualifier. /FILE_LIST /FILE_LIST=(min_extents) /FILE_LIST=(VOL_MAP_WINDOW + 1) (default) The /FILE_LIST qualifier is used when showing the fragmentation state of a volume. It lists all files on the volume that have min_extents or more extents (fragments). By default, the number of file window mapping pointers set for the volume (INITIALIZE {volume}/WINDOW=n) plus one is used. This value lists all files that require at least one window turn to completely map. /FREE_LIST /FREE_LIST /NOFREE_LIST (default) The /FREE_LIST qualifier is used when showing the fragmentation state of the volume. It lists the location and size of all of the freespace extents on the volume. /HISTOGRAM /HISTOGRAM /NOHISTOGRAM (default) The /HISTOGRAM qualifier is used when showing the fragmentation state of a volume. It generates two histograms. The first plots the number of files against the number of extents per file and provides information about how many files are fragmented and how badly they are fragmented. The second histogram plots the number of freespace extents (holes) against the size of these freespace extents. It provides information about how many freespace extents are on the volume and their sizes. /LOCATION /LOCATION=[file-spec[,...]] /NOLOCATION The /LOCATION qualifier is used when showing the fragmentation state of the volume. It prints the extents (fragments) associated with all specified files. If no files are specified, the /LOCATION qualifier appends location information to all files listed with the /FILE_LIST qualifier. The supplied file-spec may contain wildcards in place of the directory, file name, extension, or version fields. /NAMES /NAMES The /NAMES qualifier lists only the first line of the usual show output. The first line of the script includes the name of the script, whether the script is enabled or disabled, and the target device for the script. /NODE /NODE=(node-name[,...]) /NONODE (default) The /NODE qualifier selects only those scripts that match the script name provided on the command line and that match any of the node specifications provided with this qualifier. When used with the /PARAMETERS qualifier, the /NODE qualifier displays CPU_LIMIT, IO_LIMIT, and PROCESS_ LIMIT information for specified nodes only. If the /NODE qualifier is not used, the /PARAMETERS qualifier displays this information for all nodes in the scheduling database. /OUTPUT /OUTPUT={file-spec} /OUTPUT=SYS$OUTPUT (default) The /OUTPUT qualifier may be used when showing the volume fragmentation state or when showing information from the scheduling database. It directs the output of the SHOW subcommand to a file. By default, output is directed to SYS$OUTPUT. /PARAMETERS /PARAMETERS /NOPARAMETERS (default) The /PARAMETERS qualifier is used when showing information from the scheduling database. It displays the CPU_LIMIT, IO_LIMIT and PROCESS_LIMIT settings for all nodes in the scheduling database (unless specific nodes are designated with the /NODE qualifier). By default, these settings are not shown. /RUNNING /RUNNING The /RUNNING qualifier shows scripts that are currently running. /STATISTICS /STATISTICS /NOSTATISTICS (default) The /STATISTICS qualifier is used when showing the volume fragmentation state. It provides a summary of the file and free space fragmentation for the volume. /VOLUME /VOLUME /NOVOLUME (default) The /VOLUME qualifier must be used to show the fragmentation state of a volume. It indicates that any parameter supplied on the command line is a volume name instead of a script name. The /VOLUME qualifier is incompatible with any of the qualifiers used to show database information except the /OUTPUT qualifier. 3 Examples The following examples show how to SHOW limits using the SHOW subcommand and its qualifiers. 1. $ DEFRAGMENT SHOW/PARAMETERS In this example, the current values of CPU_LIMIT, IO_LIMIT and PROCESS_LIMIT for all nodes in the scheduling database are shown. 2. $ DEFRAGMENT SHOW MY_SCRIPT/OUTPUT=OUTPUT.TXT In this example, information associated with MY_SCRIPT is displayed. No parameter information is displayed. Output is directed to a file called OUTPUT.TXT. 3. $ DEFRAGMENT SHOW MY_SCRIPT/COMMAND_LINE/PARAMETERS In this example, information associated with MY_SCRIPT is displayed. The current values of CPU_LIMIT, IO_LIMIT and PROCESS_ LIMIT for all nodes in the scheduling database are also shown. The format for the information is a valid DEFRAGMENT command line. Output is directed to the user's SYS$OUTPUT device. 4. $ DEFRAGMENT SHOW DISK$ONE/VOLUME/HISTOGRAM In this example, the volume fragmentation report includes the summary statistics (/STATISTICS is default) and histograms for both file fragmentation and freespace fragmentation. The report is sent to the SYS$OUTPUT device. 2 SPAWN The Disk File Optimizer SPAWN command creates a subprocess and executes a DCL command in the subprocess, or transfers terminal control to the subprocess if no command is supplied. Format DEFRAGMENT SPAWN [ command ] 3 Parameters command This is a DCL command string of less than 132 characters that is to be executed in the context of the created subprocess. When the command completes execution, the subprocess terminates and control returns to the parent process. A command is optional. If no command is supplied, control passes to DCL. 3 Restrictions None. 3 Qualifiers None. 3 Examples The following examples show how to SPAWN processes from within the Disk File Optimizer utility. 1. DFO> SPAWN $ The SPAWN command creates a subprocess and transfers terminal control to the created subprocess. 2. DFO> SPAWN SHOW DEFAULT DISK$1:[JONES] DFO> The SPAWN command creates a subprocess and executes the DCL command SHOW DEFAULT in the created subprocess. Control then returns to the Disk File Optimizer parent process. 2 START The START subcommand starts the specified script. Format DEFRAGMENT START { script-name[,...] } [ /QUALIFIERS ] 3 Parameters script-name The script-name parameter is the name of the scripts to be started. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. 3 Restrictions None. 3 Qualifiers /AFTER /AFTER=time /NOAFTER (default) The /AFTER qualifier keeps the script from starting until after the specified time. You can specify time as either an absolute time or as a combination of absolute and delta times. For complete information on specifying time values, see the VMS DCL Concepts Manual. 3 Example The following example shows how to start a script. 1. $ DEFRAGMENT START MY_SCRIPT/AFTER=16:30 In this example, MY_SCRIPT is started. The /AFTER qualifier stipulates that MY_SCRIPT should start after 16:30 of the day this command is submitted. If the script is periodic, the period is unchanged. 2 VOLUME The DEFRAGMENT VOLUME command defragments the volume given as a parameter on the command line according to the defragment command line qualifiers. Format DEFRAGMENT VOLUME { volume-name } [ /QUALIFIERS ] 3 Parameters volume-name The volume-name parameter is the name of the volume to be defragmented. 3 Restrictions o A script that has the /CONTINUOUS qualifier may not be named as the predecessor of another script. o If you specify the /INTERVAL qualifier, the /PREDECESSOR qualifier is not allowed. o If /LEVEL=5 is selected, the /LOG qualifier is required. o Do not use /BRIEF and /FULL concurrently. o Do not use /CONTINUOUS and /INTERVAL for a script. 3 Qualifiers /AFTER /AFTER={time} /AFTER={current_time} (default) /NOAFTER The /AFTER qualifier keeps the script from executing until after the specified time. You can specify time as either an absolute time or as a combination of absolute and delta times. For complete information on specifying time values, see the VMS DCL Concepts Manual. The /AFTER qualifier has three states. It can be specified with a valid time, it can be omitted from the command line, or it can be negated (/NOAFTER). If /AFTER is specified with a valid time, the script is scheduled to execute after that time. If the /AFTER qualifier is omitted, the defragmentation software processes the command as if the /AFTER qualifier were specified with the current time. If /NOAFTER is specified, no starting time is associated with the script being defined. The /NOAFTER qualifier allows you to define a script without scheduling it to execute. To subsequently start the script, use the START subcommand. /BRIEF /BRIEF (default) /NOBRIEF The /BRIEF qualifier has meaning only when the /LOG qualifier is also present. The /BRIEF qualifier requests a brief log of all actions taken by the defragmentation process. This log includes beginning and ending volume status information. The /BRIEF and /FULL qualifiers are mutually exclusive, and /NOBRIEF produces the same result as /FULL. The /BRIEF qualifier is the default. /CONSOLIDATE_FREESPACE /CONSOLIDATE_FREESPACE (default) /NOCONSOLIDATE_FREESPACE The /CONSOLIDATE_FREESPACE qualifier tells the Disk File Optimizer to use its free space consolidation algorithm. /CONTINUOUS /CONTINUOUS /NOCONTINUOUS (default) The /CONTINUOUS qualifier links the script with itself. Thus, the script repeatedly executes. After each successful defragmentation operation, the script becomes eligible for execution again. As long as any PROCESS_LIMITs (see the SET subcommand) are not violated, the script executes repeatedly. If all PROCESS_LIMITs have been reached, the script is queued until an outstanding defragmentation process completes, then the script is allowed to execute. By default, the defragmentation process associated with a script may execute on any appropriately licensed node in a cluster. Thus, successive defragmentation processes do not necessarily execute on the same node. /DORMANT /DORMANT=(file-spec[,...]) /NODORMANT (default) The /DORMANT qualifier indicates files to be considered dormant when final file placement decisions are made. Dormant files are placed on the volume to allow placing other files in optimum disk locations. In general, they are placed further away from the ODS-2 data structures than /FREQUENT files and files not classified in any manner. If a file is indicated in both the DORMANT and FREQUENT lists, it is considered dormant. If a file is indicated in both the EXCLUDE and DORMANT lists, it is excluded. NOTE The amount of free space on the volume, the number of files currently being accessed, and other factors influence file placement. Thus, the Disk File Optimizer does not guarantee file placement, but makes every effort to place files as described. The file-spec field allows wildcard characters. You can specify wildcard characters in place of the directory name, file name, file type, or file version number field. The default file-spec for all wildcard operations is DISK:[000000...]*.*;*. Thus, specifying *.TMP;* selects all *.TMP;* files on the entire volume. /EPILOGUE /EPILOGUE={file-name} /NOEPILOGUE (default) The /EPILOGUE qualifier identifies a DCL command file which DFO executes upon completion of the DEFRAGMENT VOLUME operation. /EXCLUDE /EXCLUDE=(file-spec[,...]) /NOEXCLUDE (default) The /EXCLUDE qualifier specifies files to be excluded from processing. The defragmentation process ignores files matching the listed file specifications. Any file indicated in the EXCLUDE list and in either the FREQUENT or DORMANT lists is excluded from processing. The file-spec field allows wildcard characters. You can specify wildcard characters in place of the directory name, file name, file type, or file version number field. The default file-spec for all wildcard operations is DISK:[000000...]*.*;*. Thus, specifying *.TMP;* selects all *.TMP;* files on the entire volume. NOTE The defragmentation process always excludes system files, open files, files excluded in an options file (/OPTIONS qualifier), and files excluded using the /IGNORE qualifier. /FREQUENT /FREQUENT=(file-spec[,...]) /NOFREQUENT (default) The /FREQUENT qualifier indicates files to be considered frequently accessed when final file placement decisions are made. Frequent files are placed to optimize access speed. If a file is indicated in both the FREQUENT and DORMANT lists, it is considered dormant. If a file is indicated in both the FREQUENT and EXCLUDE lists, it is excluded. NOTE The amount of free space on the volume, the number of files currently being accessed, and other factors influence file placement. Thus, the Disk File Optimizer does not guarantee file placement, but makes every effort to place files as described. The file-spec field allows wildcard characters. You can specify wildcard characters in place of the directory name, file name, file type, or file version number field. The default file-spec for all wildcard operations is DISK:[000000...]*.*;*. Thus, specifying *.TMP;* selects all *.TMP;* files on the entire volume. /FULL /FULL /NOFULL (default) The /FULL qualifier requests a full log of all actions taken by the defragmentation process. The /FULL qualifier has no meaning if the /LOG qualifier is absent. The /FULL and /BRIEF qualifiers are mutually exclusive, and /NOFULL provides the same functionality as /BRIEF. /HOTFILE_DATABASE /HOTFILE_DATABASE /NOHOTFILE_DATABASE (default) The /HOTFILE_DATABASE qualifier causes the defragmenter to query the appropriate hotfile database and append the list of hotfiles to the defragmenter's /FREQUENT file list. /IGNORE /IGNORE=(keyword[,...]) /IGNORE=(PLACED) (default) /NOIGNORE The /IGNORE qualifier requests that the defragmentation process ignore certain types of files as specified by the following keywords: o INDEXED-Ignores all RMS indexed files o NOINDEXED-May defragment RMS indexed files o PLACED-Ignores all files with explicit placement flags set in their headers o NOPLACED-May defragment files with explicit placement flags Files indicated by the /IGNORE qualifier are added to the EXCLUDE list. The default value (/IGNORE=PLACED) indicates that files with explicit placement control should be ignored, and that RMS indexed files should be defragmented and placed in appropriate locations on the volume. /INHERIT /INHERIT={script-name} /NOINHERIT (default) The purpose of the /INHERIT qualifier is to make script creation easier. By inheriting most of the command data from a previously entered script and modifying only a few items (such as volume name), a completely new script can be created. The /INHERIT qualifier creates a database entry for a new script in the following way: o Copies all fields from the specified script to the new script. o Overwrites any qualifier or parameter values in the new script with those specified on the command line. o Names the new script as appropriate. The user may specify a script name using the /SCRIPT={script- name} qualifier. Otherwise, the defragmentation software creates a unique script name. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script-name specification. /INTERVAL /INTERVAL={delta-time} /NOINTERVAL (default) Causes a script to execute at regularly scheduled intervals. The /INTERVAL qualifier specifies the minimum time between two consecutive executions of a script. Specify time as a delta time. Refer to the VMS DCL Concepts Manual for more information on specifying times. If you do not specify a time with the /INTERVAL qualifier, a default value of 1 day is used. This value causes the associated script to run every 24 hours. If you specify the /AFTER qualifier with the /INTERVAL qualifier, the first defragmentation operation occurs at or after the time specified by the /AFTER qualifier; all subsequent operations execute at intervals set according to the /INTERVAL qualifier. /LEVEL /LEVEL={n} /LEVEL=2 (default) The defragmentation process selects files for defragmentation (from among those not excluded) based on the /LEVEL qualifier. Once a file is selected as a candidate, the defragmentation process attempts to fully defragment that file (make it 100 percent contiguous). Specify the level number as an integer ranging from 1 to 5: o /LEVEL=1 Any file that is not 100 percent contiguous, or can be selected using levels 2-4, is a candidate for defragmentation. o /LEVEL=2 (default) Any file whose extents cannot be completely mapped by the mapping window, or that can be selected using levels 3 or 4, is a candidate for defragmentation. The default window value is 7 and can be set for a given volume using: $ SET VOLUME {device-spec}/WINDOWS=[n] o /LEVEL=3 Any file with retrieval pointers in more than one file header, or that can be selected using level 4, is a candidate for defragmentation. o /LEVEL=4 The defragmentation process for level 4 processing performs only free space consolidation. This level is used in conjunction with the /CONSOLIDATE_ FREESPACE qualifier. o /LEVEL=5 This level requests a volume analysis only; no defragmentation occurs. The statistical results are available in the log file, which is required when /LEVEL=5 is selected (see the /LOG qualifier). If level 5 is selected, the /LEVEL=2 candidate file specifications are listed in the full log file. /LOG /LOG={file-spec} /NOLOG (default) The /LOG qualifier causes the defragmentation process to create a file containing a list of all its operations. The information in the log file varies with the presence of the /FULL or /BRIEF qualifiers. The /FULL qualifier lists all files analyzed by the defragmentation process and reports their disposition during each phase of defragmentation. The /BRIEF qualifier lists only the statistics of each phase, such as number of files analyzed, and number of files defragmented. /MAIL_NOTIFICATION /MAIL_NOTIFICATION /NOMAIL_NOTIFICATION (default) The /MAIL_NOTIFICATION qualifier requests that brief status and termination messages regarding defragmentation processes be mailed to the mail distribution list provided in the file DFG$MAIL_ ADDRESS. /NODE /NODE=(node-name[,...]) /NONODE (default) The /NODE qualifier limits the scope of the DEFRAGMENT command to the node or set of nodes specified by /NODE=(node-name). By default, defragmentation processes may execute on any LMF licensed node in the system. /OPCOM_NOTIFICATION /OPCOM_NOTIFICATION (default) /NOOPCOM_NOTIFICATION The /OPCOM_NOTIFICATION qualifier requests that brief status and termination messages regarding defragmentation processes be sent to OPCOM. /OPTIONS /OPTIONS={file-spec} /NOOPTIONS (default) The /OPTIONS qualifier provides an alternate method for associating files with the /DORMANT, /EXCLUDE, or /FREQUENT qualifiers. If the list of files for any of these qualifiers is quite large, you can create a separate file that contains this information. Each record in the options file consists of a file name followed by one of the following keywords: o /EXCLUDE-File to be excluded o /FREQUENT-File to be considered frequently accessed o /DORMANT-File to be considered dormant The following example shows the contents of an options file called MYOPTFILE.OPT. This file specifies that all files on the target device called FILE1.EXE are frequent files, all files in the [ARCHIVE] directory are to be excluded, and all files in the [OLDSTUFF] directory and its subdirectories are dormant. FILE1.EXE/FREQUENT [ARCHIVE]*.*;*/EXCLUDE [OLDSTUFF...]*.*;*/DORMANT Files indicated by the /EXCLUDE qualifier and by either the /DORMANT or /FREQUENT qualifier are excluded. Files indicated by the /DORMANT qualifier and by the /FREQUENT qualifier are considered dormant. This rule is applied equally across all files specified in the /OPTIONS file, as well as those associated with these qualifiers on the command line. /PREDECESSOR /PREDECESSOR={script-name} /NOPREDECESSOR (default) The /PREDECESSOR qualifier links scripts. These scripts execute in sequence; one successfully completes before the next one begins. The predecessor script name must exist in the scheduling database or an error status message is returned. You can use wildcards in the script-name specification. Use an asterisk (*) to take action on all scripts on the VMScluster system. Use a percent sign (%) to match a single character in the script- name specification. /PRIORITY /PRIORITY=(DEFAULT=n, MINIMUM=n) /NOPRIORITY (default) The /PRIORITY qualifier specifies priorities for the defragment volume operation. /PROLOGUE /PROLOGUE={file-name} /NOPROLOGUE (default) The /PROLOGUE qualifier identifies a DCL command file which DFO executes just before the DEFRAGMENT VOLUME operation starts. /RVN /RVN=n /RVN=0 (default) When you have a bound volume set, use this qualifier to identify a disk from the volume set or all disks in the volume set. The default of zero tells the Disk File Optimizer to defragment all disks in the bound volume set. Specify a relative volume number (RVN) to defragment a specific disk that belongs to a bound volume set. /SCRIPT /SCRIPT={script-name} /NOSCRIPT (default) The /SCRIPT qualifier assigns a user-supplied name to a script. If a duplicate script-name is selected, defragmentation software issues a duplicate script name error message and does not enter the new script into the database-no defragmentation takes place. A script name may be up to 64 characters in length and may contain any of the following characters: o Any alphanumeric character o Underscore ( _ ) o Hyphen ( - ) o Dollar sign ( $ ) Observe the following rules when naming a script: o You can use any combination of uppercase and lowercase letters. o You cannot begin script names using the dollar sign, but you can include the dollar sign within the script name. (The dollar sign is reserved for special use by Digital Equipment Corporation.) o You should not end a script name with a hyphen, since the hyphen is the DCL continuation character. The VMS DCL Concepts Manual contains more information on naming conventions. If you do not supply a script name using the /SCRIPT qualifier, the defragmentation software generates a unique script name. This internally generated name has the format DFG$SCRIPTX[X...], where X is a hexadecimal number that keeps the script names unique. Names beginning with DFG$ are reserved for use by the defragmentation software. /TIME_LIMIT /TIME_LIMIT={delta-time} /NOTIME_LIMIT (default) The /TIME_LIMIT qualifier specifies the maximum elapsed time allowed for a given defragmentation operation. If the time limit is exceeded, the defragmentation process is aborted. Specify time as a delta time. Refer to the VMS DCL Concepts Manual for more information on specifying times. For linked scripts, the time limit of the first script applies to the whole set. Time limits specified with successor scripts apply to these scripts only. If the time limit is set unreasonably low, the defragmentation process may not accomplish useful defragmentation. /WRITE_CHECK /WRITE_CHECK /NOWRITE_CHECK (default) The /WRITE_CHECK qualifier requests that a read- after-write check be performed on all defragmented or placed files. This qualifier significantly extends the execution time of a defragmentation process. 3 Examples The following examples show different ways to defragment a volume and illustrate how to use the common qualifiers. 1. $ DEFRAGMENT VOLUME DISK$USER_1 This command defragments DISK$USER_1 using default qualifiers. The defragmentation process executes once and does not repeat. In a VMScluster system, the defragment operation begins on a node selected at random from among those nodes in the scheduling database having fewer executing processes than the limit imposed by the SET PROCESS_LIMIT={value} subcommand. If all nodes are busy with a maximum number of defragment processes, the script does not execute until one of the outstanding defragmentation operations concludes. After the defragmentation process stops, the script is removed from the scheduling database. 2. $ DEFRAGMENT VOLUME DISK$ONE/SCRIPT=MY_SCRIPT- $ _/IGNORE=(INDEXED,PLACED)/INTERVAL=2-00:00/FREQUENT=*.EXE- $ _/LOG=MYLOG.LOG/FULL/DORMANT=*.ARCHIVE/NODE=(N1, N2) This command does the following: o Defragments DISK$ONE o Names the script MY_SCRIPT o Instructs the defragmentation process to ignore all RMS indexed files and files with explicit placement control information in their headers. (These files are added to the EXCLUDE list.) o Instructs the scheduler to execute this script every two days o Instructs the defragmentation process that all .EXE files on the entire volume should be considered frequently accessed when final file placement decisions are made o Requests a log file, MYLOG.LOG, which is placed in the directory from which this command was entered o Requests a /FULL log file o Instructs the defragmentation process that all .ARCHIVE files on the entire volume should be considered dormant (rarely accessed) when final file placement decisions are made o Limits the nodes available for the defragmentation process to nodes N1 and N2 3. $ DEFRAGMENT VOLUME DISK$TWO/INHERIT=MY_SCRIPT $_/SCRIPT=FIRST_SCRIPT This command inherits the script definition made in example 2. Thus, it creates a new script that is the same as MY_SCRIPT, except for the following differences: o The script name is FIRST_SCRIPT instead of MY_SCRIPT. o The target volume is DISK$TWO instead of DISK$ONE. In this case, MYLOG.LOG is also inherited. Thus, one version of the log file contains data from MY_SCRIPT, and the other version contains data from FIRST_SCRIPT. To prevent log file inheritance, specify the /LOG qualifier. 4. DFO> DEFRAGMENT VOLUME DISK$ONE /SCRIPT=SECOND_SCRIPT DFO>_ /PREDECESSOR=FIRST_SCRIPT This commands links SECOND_SCRIPT to FIRST_SCRIPT using the PREDECESSOR qualifier. SECOND_SCRIPT does not execute until FIRST_SCRIPT completes successfully. SECOND_SCRIPT uses default parameters. Note that this command supplies the DEFRAGMENT VOLUME options from within the Disk File Optimizer utility. 2 RELEASE_NOTES You can find the release notes for the defragmentation software in SYS$HELP:DFGvvu.RELEASE_NOTES, where vv is the major version number, and u is the update number. To list all the DEFRAGMENT release notes available, type: $ DIRECTORY SYS$HELP:DFG*.RELEASE_NOTES.