OpenVMS DCL Dictionary

Each data line is checked for COMMENTS, FORM_FEEDS, HEADER, and SPACING before it is tested for TRAILING_SPACES and then BLANK_LINES. Therefore, if you direct the DIFFERENCES command to ignore COMMENTS, TRAILING_SPACES, and BLANK_LINES, it ignores a record that contains several spaces or blank lines followed by a comment.

By default, the DIFFERENCES command compares every character in each file and reports all differences. Also, by default, the DIFFERENCES command lists records in the output file with all ignored characters deleted.

If you specify the /PARALLEL qualifier, output records are always formatted. To format output records, specify the following characters:

Character Formatted Output

Tab (Ctrl/I) 1--8 spaces

Return (Ctrl/M) <CR>

Line feed (Ctrl/J) <LF>

Vertical tab (Ctrl/K) <VT>

Form feed (Ctrl/L) <FF>

Other nonprinting characters . (period)

Character	Formatted Output
Tab (Ctrl/I)	1--8 spaces
Return (Ctrl/M)	<CR>
Line feed (Ctrl/J)	<LF>
Vertical tab (Ctrl/K)	<VT>
Form feed (Ctrl/L)	<FF>
Other nonprinting characters	. (period)

/MATCH=size

Specifies the number of records that should indicate matching data after a difference is found. By default, after the DIFFERENCES command finds unmatched records, it assumes that the files once again match after it finds three sequential records that match. Use the /MATCH qualifier to override the default match size of 3.

You can increase the /MATCH qualifier value if you feel that the DIFFERENCES command is incorrectly matching sections of the master and revision input files after it has detected a difference.

/MAXIMUM_DIFFERENCES=n

Terminates the DIFFERENCES command after the specified number of unmatched records (specified with the n parameter) is found.

The number of unmatched records is determined by finding the maximum number of difference records for each difference section and adding them together.

If the DIFFERENCES command reaches the maximum number of differences that you specify, it will output only those records that were detected before the maximum was reached. Also, it will output, at most, one listing format and return a warning message.

By default, there is no maximum number of differences. All records in the specified input files are compared.

/MERGED[=n]

Specifies that the output file contain a merged list of differences with the specified number of matched records listed after each group of unmatched records. The value of the parameter n must be less than or equal to the number specified in the /MATCH qualifier. By default, the DIFFERENCES command produces a merged listing with one matched record listed after each set of unmatched records (that is, /MERGED=1). If the /MERGED, the /SEPARATED, or the /PARALLEL qualifier is not specified, the resulting output is merged, with one matched record following each unmatched record.

Use the /MERGED qualifier to override the default value of the parameter n, or to include a merged listing with other types of output.

/MODE=(radix[,...])

Specifies the format of the output. You can request that the output be formatted in one or more radix modes by specifying the following keywords, which may be abbreviated: ASCII (default), HEXADECIMAL, or OCTAL. If you specify only one radix, you can omit the parentheses.

By default, the DIFFERENCES command writes the output file in ASCII. If you specify more than one radix, the output listing contains the file comparison in each specified radix. When you specify two or more radix modes, separate them with commas.

If you specify the /PARALLEL or the /SLP qualifier, the /MODE qualifier is ignored for that listing form.

/NUMBER (default)

/NONUMBER

Includes line numbers in the listing of DIFFERENCES.

/OUTPUT[=filespec]

Specifies an output file to receive the list of differences. By default, the output is written to the current SYS$OUTPUT device. If the filespec parameter is not specified, the output is directed to the first input file with a file type .DIF. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.

When you specify the /OUTPUT qualifier, you can control the defaults applied to the output file specification as described in the OpenVMS User's Manual. The default output file type is .DIF.

/PAGE[=keyword]

/NOPAGE (default)

Controls the display of difference information on the screen.

You can use the following keywords with the /PAGE qualifier:

CLEAR_SCREEN Clears the screen before each page is displayed.

SCROLL Displays information one line at a time.

SAVE[= n] Enables screen navigation of information, where n is the number of pages to store.

The /PAGE=SAVE qualifier allows you to navigate through screens of information. The /PAGE=SAVE qualifier stores up to 5 screens of up to 255 columns of information. When you use the /PAGE=SAVE qualifier, you can use the following keys to navigate through the information:

Key Sequence Description

Up arrow (<uparrow symbol>), Ctrl/B Scroll up one line.

Down arrow (<downarrow symbol>) Scroll down one line.

Left arrow ( <-) Scroll left one column.

Right arrow (->) Scroll right one column.

Find (E1) Specify a string to find when the information is displayed.

Insert Here (E2) Scroll right one half screen.

Remove (E3) Scroll left one half screen.

Select (E4) Toggle 80/132 column mode.

Prev Screen (E5) Get the previous page of information.

Next Screen (E6), Return, Enter, Space Get the next page of information.

F10, Ctrl/Z Exit. (Some utilities define these differently.)

Help (F15) Display utility help text.

Do (F16) Toggle the display to oldest/newest page.

Ctrl/W Refresh the display.

Key Sequence	Description
Up arrow (<uparrow symbol>), Ctrl/B	Scroll up one line.
Down arrow (<downarrow symbol>)	Scroll down one line.
Left arrow ( <-)	Scroll left one column.
Right arrow (->)	Scroll right one column.
Find (E1)	Specify a string to find when the information is displayed.
Insert Here (E2)	Scroll right one half screen.
Remove (E3)	Scroll left one half screen.
Select (E4)	Toggle 80/132 column mode.
Prev Screen (E5)	Get the previous page of information.
Next Screen (E6), Return, Enter, Space	Get the next page of information.
F10, Ctrl/Z	Exit. (Some utilities define these differently.)
Help (F15)	Display utility help text.
Do (F16)	Toggle the display to oldest/newest page.
Ctrl/W	Refresh the display.

The /PAGE qualifier is not compatible with the /OUTPUT qualifier.

/PARALLEL[=n]

Lists the records with differences side by side. The value of the parameter n specifies the number of matched records to merge after each unmatched record; it must be a non-negative decimal number less than or equal to the number specified in the /MATCH qualifier.

By default, the DIFFERENCES command does not list records after each list of unmatched records. Also by default, the DIFFERENCES command creates only a list of merged differences.

/SEARCH="string"

Use with the /PAGE=SAVE qualifier to specify a string that you want to find in the information being displayed. Quotation marks are required for the /SEARCH qualifier, if you include spaces in the text string.

You can also dynamically change the search string by pressing the Find key (E1) while the information is being displayed. Quotation marks are not required for a dynamic search.

/SEPARATED[=MASTER, REVISION]

Lists sequentially only the records from the specified file that contain differences. Use the MASTER keyword to list the differences in the first input file specified; use the REVISION keyword to list the difference in the second input file specified.

By default, the DIFFERENCES command creates only a merged list of differences.

/SLP

Requests that the DIFFERENCES command produce an output file suitable for input to the SLP editor. If you use the /SLP qualifier, you cannot specify any of the following output file qualifiers: /MERGED, /PARALLEL, /SEPARATED, or /CHANGE_BAR.

Use the output file produced by the SLP qualifier as input to SLP to update the master input file, that is, to make the master input file match the revision input file.

When you specify the /SLP qualifier and you do not specify the /OUTPUT qualifier, the DIFFERENCES command writes the output file to a file with the same file name as the master input file with the file type DIF.

/WIDTH=n

Specifies the width of the lines in the output file. The default is 132 characters. If output is written to the terminal, the /WIDTH qualifier is ignored and the terminal line width is used.

Use the SET TERMINAL command to change the terminal line width.

/WINDOW=size

Searches the number of records specified by the size parameter, before a record is declared as unmatched. By default, the DIFFERENCES command searches to the ends of both input files before listing a record as unmatched.

The window size is the minimum size of a differences section that will cause the DIFFERENCES command to lose synchronization between the two input files.

/WRAP

/NOWRAP (default)

Use with the /PAGE=SAVE qualifier to limit the number of columns to the width of the screen and to 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 and can be seen when you use the scrolling (left and right) features provided by the /PAGE=SAVE qualifier.

Examples

$ DIFFERENCES EXAMPLE.TXT
************
File DISK1:[GEORGE.TEXT]EXAMPLE.TXT;2
    1   DEMONSTRATION 
    2   OF V3.0 DIFFERENCES
    3   UTILITY
******
File DISK1:[GEORGE.TEXT]EXAMPLE.TXT;1
    1   DEMONSTRETION 
    2   OF VMS DIFFERENCES
    3   UTILITY
************
Number of difference sections found: 1
Number of difference records found: 2
DIFFERENCES/MERGED=1-
       DISK1:[GEORGE.TEXT]EXAMPLE.TXT;2
       DISK1:[GEORGE.TEXT]EXAMPLE.TXT;1

In this example, the DIFFERENCES command compares the contents of the two most recent versions of the file EXAMPLE.TXT in the current default directory. The DIFFERENCES command compares every character in every record and displays the results at the terminal.

$ DIFFERENCES/PARALLEL/WIDTH=80/COMMENT_DELIMITER="V" EXAMPLE.TXT
-------------------------------------------------------------------------------
File DISK1:[GEORGE.TEXT]EXAMPLE.TXT;2  |  File DISK1:[GEORGE.TEXT]EXAMPLE.TXT;1
------------------- 1 ------------------------------------- 1 -----------------
DEMONSTRATION                          |  DEMONSTRETION                    
-------------------------------------------------------------------------------
Number of difference sections found: 1
Number of difference records found: 1
DIFFERENCES/IGNORE=(COMMENTS)/COMMENT_DELIMITER=("V")/WIDTH=80/PARALLEL-
       DISK1:[GEORGE.TEXT]EXAMPLE.TXT;2-
       DISK1:[GEORGE.TEXT]EXAMPLE.TXT;1

The DIFFERENCES command compares the same files as in Example 1, but ignores all characters following the first "V" on any line. The command also specifies that an 80-column parallel list of differences be displayed.

$ DIFFERENCES/WIDTH=80/MODE=(HEX,ASCII) EXAMPLE.TXT/CHANGE_BAR
************
File DISK1:[GEORGE.TEXT]EXAMPLE.TXT;2
    1 ! DEMONSTRATION 
    2 ! OF V3.0 DIFFERENCES
    3   UTILITY
************
************
File DISK1:[GEORGE.TEXT]EXAMPLE.TXT;2
RECORD NUMBER 1 (00000001) LENGTH 14 (0000000E)  ***CHANGE***
     204E 4F495441 5254534E 4F4D4544 DEMONSTRATION .. 000000
RECORD NUMBER 2 (00000002) LENGTH 19 (00000013)  ***CHANGE***
 4E455245 46464944 20302E33 5620464F OF V3.0 DIFFEREN 000000
                              534543 CES............. 000010
RECORD NUMBER 3 (00000003) LENGTH 7 (00000007) 
                     595449 4C495455 UTILITY......... 000000
************
Number of difference sections found: 1
Number of difference records found: 2
DIFFERENCES /WIDTH=80/MODE=(HEX,ASCII) 
       DISK1:[GEORGE.TEXT]EXAMPLE.TXT;2/CHANGE_BAR-
       DISK1:[GEORGE.TEXT]EXAMPLE.TXT;1

The DIFFERENCES command compares the same files as in Example 1, but lists the differences in both hexadecimal and ASCII formats. The command also specifies that default change bars be used in the output. The default change bar notation for the hexadecimal output is ***CHANGE***. For the ASCII output, the default change bar character is the exclamation point.

$ DIFFERENCES/OUTPUT BOSTON::DISK2:TEST.DAT OMAHA::DISK1:[PGM]TEST.DAT

The DIFFERENCES command compares two remote files and displays any differences found. The first file is TEST.DAT on remote node BOSTON. The second file is also named TEST.DAT on remote node OMAHA. The DIFFERENCES output is located in the file DISK1:[PGM]TEST.DIF.

DIRECTORY

Provides a list of files or information about a file or group of files.
Requires execute (E) access to look up files you know the names of, read (R) access to read or list a file or to use a file name with the asterisk (*) and the percent sign (%) wildcard characters to look up files.

Format

DIRECTORY [filespec[,...]]

DIRECTORY/FTP directorySpec

PARAMETER

filespec[,...]
Specifies one or more files to be listed. The syntax of a file specification determines which files will be listed, as follows:

If you do not enter a file specification, the DIRECTORY command lists all versions of the files in the current default directory.
If you specify only a device name, the DIRECTORY command uses your default directory specification.
Whenever the file specification does not include a file name, a file type, and a version number, all versions of all files in the specified directory are listed.
If a file specification contains a file name or a file type, or both, and no version number, the DIRECTORY command lists all versions.
If a file specification contains only a file name, the DIRECTORY command lists all files in the current default directory with that file name, regardless of file type and version number.
If a file specification contains only a file type, the DIRECTORY command lists all files in the current default directory with that file type, regardless of file name and version number.

The asterisk (*) and the percent sign (%) wildcard characters can be used in the directory specification, file name, file type, or version number fields of a file specification to list all files that satisfy the components you specify. If you specify more than one file, separate the file specifications with either commas (,) or plus signs (+).
directorySpec
Specifies the standard DECnet remote file specification. Use a quoted file string to preserve the case (for case-sensitive systems such as UNIX) and to identify a foreign device/directory specification. See the /FTP qualifier for more information.

DESCRIPTION

The DIRECTORY command lists the files contained in a directory. When you use certain qualifiers with the command, additional information is displayed, along with the names of the files.
The output of the DIRECTORY command depends on certain formatting qualifiers and their defaults. These qualifiers are as follows: /COLUMNS, /DATE, /FULL, /OWNER, /PROTECTION, and /SIZE. However, the files are always listed in alphabetical order, with the highest numbered versions listed first.
In studying the qualifiers and the capabilities they offer, watch for qualifiers that work together and for qualifiers that override other qualifiers. For example, if you specify the /FULL qualifier, the system cannot display all the information in more than one column. Thus, if you specify both the /COLUMNS and /FULL qualifiers, the number of columns you request is ignored.
You can also select other languages and formats that have been defined on your systems with international date and time formatting routines available in the run-time library. See the OpenVMS RTL Library (LIB$) Manual.

QUALIFIERS

/ACL
Controls whether the access control list (ACL) is displayed for each file. By default, the DIRECTORY command does not display the ACL for each file. Access control entries (ACEs) that were created with the hidden option are displayed only if the SECURITY privilege is turned on. The /ACL qualifier overrides the /COLUMNS qualifier.
For further information, see the OpenVMS Guide to System Security.
/BACKUP
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier selects files according to the dates of their most recent backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/BEFORE[=time]
Selects only those files dated prior to the specified time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.
For complete information on specifying time values, see the OpenVMS User's Manual or the topic SPECIFY Date_Time in online help.
/BRIEF (default)
Displays only a file's name, type, and version number. The brief format lists the files in alphabetical order from left to right on each line, in descending version number order. You can use the /ACL, /DATE, /FILE_ID, /FULL, /NOHEADING, /OWNER, /PROTECTION, /SECURITY, and /SIZE qualifiers to expand a brief display.
/BY_OWNER[=uic]
Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.
Specify the UIC by using standard UIC format as described in the OpenVMS User's Manual.
For further information, see the OpenVMS Guide to System Security.
/COLUMNS=n
Specifies the number of columns in a brief display. The default is four. However, you can request as many columns as you like, restricted by the value of the /WIDTH qualifier. The /COLUMNS qualifier is incompatible with the /ACL, /FULL, and /SECURITY qualifiers.
The number of columns actually displayed depends on the amount of information requested for each column and the display value of the /WIDTH qualifier. The system displays only as many columns as can fit within the default or specified display width, regardless of how many columns you specify with the /COLUMNS qualifier.
The DIRECTORY command truncates long file names only when you specify more than one column and you have asked for additional information to be included in each column. The default file name size is 19 characters. Use the /WIDTH qualifier to change the default. When a file name is truncated, the system displays one less character than the file name field size and inserts a vertical bar in the last position. For example, if the file name is SHOW_QUEUE_CHARACTERISTICS, and if you requested DIRECTORY to display both file name and size in each column, the display for that file would be SHOW_QUEUE_CHARACT| 120.
/CREATED (default)
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /CREATED qualifier selects files based on their dates of creation. This qualifier is incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/DATE[=option]

/NODATE (default)
Includes the creation, last modification, expiration, backup, effective, or recording date for each specified file; the default is the /NODATE qualifier. If you use the /DATE qualifier without an option, the creation date is provided. Possible options are as follows:

Option Description

ALL Specifies all optional dates in the following order: creation, last modification, expiration, backup, effective, and recording.

BACKUP Specifies the last backup date.

CREATED Specifies the creation date.

EFFECTIVE Specifies the effective date the contents are valid (ISO 9660).

EXPIRED Specifies the expiration date.

MODIFIED Specifies the last modification date.

RECORDING Specifies the recording date on the media (ISO 9660).

/EXACT
Use with the /PAGE=SAVE and /SEARCH qualifiers to specify a search string that must match the search string exactly and must be enclosed with quotation marks (" ").
If you specify the /EXACT qualifier without the /SEARCH qualifier, exact search mode is enabled when you set the search string with the Find (E1) key.
/EXCLUDE=(filespec[,...])
Excludes the specified files from the DIRECTORY command. You can include a directory but not a device in the file specification. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you specify only one file, you can omit the parentheses.
/EXPIRED
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier selects files according to their expiration dates. (The expiration date is set with the SET FILE/EXPIRATION_DATE command.) The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/FILE_ID
Controls whether the file identification (FID) number is displayed. By default, the FID is not displayed unless the /FULL qualifier is specified.
/FTP
Invokes the directory (dir or ls) operation of the FTP utility. The DIRECTORY/FTP command writes a listing of the contents of the specified remote directory to the local host over a TCP/IP connection by invoking the FTP utility.
/FULL
Displays the following information for each file:

File name
File type
Version number
File identification number (FID)
Number of blocks used
Number of blocks allocated
File owner's user identification code (UIC)
Date of creation
Date last modified and revision number
Date of expiration
Date of last backup
Date of effective usage
Date of recording on media
File organization
Shelved state
File attributes
Record format
Record attributes
RMS attributes
Journaling information
File protection
Access control list (ACL)
Value of the stored semantics tag (where applicable)

/GRAND_TOTAL
Displays only the totals for all files and directories that have been specified. Suppresses both the per-directory total and individual file information. (See the /TRAILING qualifier for information on displaying directory totals.)
/HEADING

/NOHEADING
Controls whether heading lines consisting of a device description and directory specification are printed. The default output format provides this heading. When the /NOHEADING qualifier is specified, the display is in single-column format and the device and directory information appears with each file name. The /NOHEADING qualifier overrides the /COLUMNS qualifier.
The combination of the /NOHEADING and /NOTRAILING qualifiers is useful in command procedures where you want to create a list of complete file specifications for later operations.
/HIGHLIGHT[=keyword]

/NOHIGHLIGHT (default)
Use with the /PAGE=SAVE and /SEARCH qualifiers to specify the type of highlighting you want when a search string is found. When a string is found, the entire line is highlighted. You can use the following keywords: BOLD, BLINK, REVERSE, and UNDERLINE. BOLD is the default highlighting.
/MODIFIED
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier selects files according to the dates on which they were last modified. This qualifier is incompatible with the /BACKUP, /CREATED, and /EXPIRED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time modifiers, the default is the /CREATED qualifier.
/OUTPUT[=filespec]

/NOOUTPUT
Controls where the output of the command is sent. By default, the display is written to the current SYS$OUTPUT device. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.
If you enter the /OUTPUT qualifier with a partial file specification (for example, /OUTPUT=[JONES]), DIRECTORY is the default file name and LIS the default file type. If you enter the /NOOUTPUT qualifier, output is suppressed.
If the output will be written to a file in the same directory, the output file name will appear in the directory listing.
/OWNER

/NOOWNER (default)
Controls whether the file owner's user identification code (UIC) is listed.
The default size of the owner field is 20 characters. If the file owner's UIC exceeds the length of the owner field, the information will be truncated. The size of this field can be altered by specifying /WIDTH=OWNER, along with a value for the owner field. For more information, see the description of the /WIDTH qualifier.
/PAGE[=keyword]

/NOPAGE (default)
Controls the display of directory information on the screen.
You can use the following keywords with the /PAGE qualifier:

CLEAR_SCREEN Clears the screen before each page is displayed.

SCROLL Displays information one line at a time.

SAVE[= n] Enables screen navigation of information, where n is the number of pages to store.

The /PAGE=SAVE qualifier allows you to navigate through screens of information. The /PAGE=SAVE qualifier stores up to 5 screens of up to 255 columns of information. When you use the /PAGE=SAVE qualifier, you can use the following keys to navigate through the information:

Key Sequence Description

Up arrow (<uparrow symbol>), Ctrl/B Scroll up one line.

Down arrow (<downarrow symbol>) Scroll down one line.

Left arrow ( <-) Scroll left one column.

Right arrow (->) Scroll right one column.

Find (E1) Specify a string to find when the information is displayed.

Insert Here (E2) Scroll right one half screen.

Remove (E3) Scroll left one half screen.

Select (E4) Toggle 80/132 column mode.

Prev Screen (E5) Get the previous page of information.

Next Screen (E6), Return, Enter, Space Get the next page of information.

F10, Ctrl/Z Exit. (Some utilities define these differently.)

Help (F15) Display utility help text.

Do (F16) Toggle the display to oldest/newest page.

Ctrl/W Refresh the display.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  9996P012.HTM
  OSSG Documentation
  26-NOV-1996 11:17:10.66
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

CLEAR_SCREEN	Clears the screen before each page is displayed.
SCROLL	Displays information one line at a time.
SAVE[= n]	Enables screen navigation of information, where n is the number of pages to store.

Option	Description
ALL	Specifies all optional dates in the following order: creation, last modification, expiration, backup, effective, and recording.
BACKUP	Specifies the last backup date.
CREATED	Specifies the creation date.
EFFECTIVE	Specifies the effective date the contents are valid (ISO 9660).
EXPIRED	Specifies the expiration date.
MODIFIED	Specifies the last modification date.
RECORDING	Specifies the recording date on the media (ISO 9660).