OpenVMS DCL Dictionary

Document revision date: 19 July 1999

OpenVMS DCL Dictionary

Contents

Index

DIFFERENCES

Compares the contents of two disk files and displays a listing of the records that do not match.

Format

DIFFERENCES input1-filespec [input2-filespec]

Parameters

input1-filespec
Specifies the first file to be compared. The file specification must include a file name and a file type. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.
input2-filespec
Specifies the second file to be compared. Unspecified fields default to the corresponding fields in the input1-filespec parameter. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.
If you do not specify a secondary input file, the DIFFERENCES command uses the next lower version of the primary input file.

Description

Use the DIFFERENCES command to determine whether two files are identical and, if not, how they differ. The DIFFERENCES command compares the two specified files on a record-by-record basis and produces an output file that lists the DIFFERENCES, if any.
The qualifiers for the DIFFERENCES command can be categorized according to their functions, as follows:

Qualifiers that request the DIFFERENCES command to ignore data in each record:

/COMMENT_DELIMITERS
/IGNORE

These qualifiers allow you to define characters that denote comments or to designate characters or classes of characters to ignore when comparing files. For example, you can have the DIFFERENCES command ignore extra blank lines or extra spaces within lines.
By default, the DIFFERENCES command compares every character in each record.
Qualifiers that control the format of the information contained in the list of differences:

/CHANGE_BAR
/IGNORE
/MERGED
/MODE
/PARALLEL
/SEPARATED
/SLP
/WIDTH

By default, the DIFFERENCES command merges the differences it finds in the files being compared. It lists each record in the file that has no match in the other input file and then lists the next record that it finds that does have a match.
By default, the DIFFERENCES command also supplies a line number with each listed record, and it lists the records with all designated ignore characters deleted.
You can specify combinations of qualifiers to request an output listing that includes the comparison in more than one format. Note that SLP output is incompatible with all other types of output; parallel output can be generated only in ASCII mode.
Qualifiers that control the extent of the comparison:

/MATCH
/MAXIMUM_DIFFERENCES
/WINDOW

By default, the DIFFERENCES command reads every record in the master input file and looks for a matching record in the revision input file. A search for a match between the two input files continues until either a match is found or the ends of the two files are reached. Sections of the two files are considered a match only if three sequential records are found to be identical in each file.

By default, DIFFERENCES command output is written to the current SYS$OUTPUT device. Use the /OUTPUT qualifier to request that the DIFFERENCES command write the output to an alternate file or device.
The DIFFERENCES command terminates with an exit status. The following severity levels indicate the result of the comparison:

SUCCESS Files are identical.

INFORMATIONAL Files are different.

WARNING User-specified maximum number of DIFFERENCES has been exceeded.

ERROR Insufficient virtual memory to complete comparison.

All severity levels other than SUCCESS indicate that the two input files are different.

Qualifiers

/CHANGE_BAR[=([change-char][,[NO]NUMBER])]
Marks differences using the specified character. The /CHANGE_BAR qualifier displays output that depends on where the qualifier is placed. The following examples describe the result of /CHANGE_BAR qualifier placement.
The following placement displays the latest version of input.file with the pound sign (#) preceding any lines that differ from the preceding version of input.file:
$ DIFFERENCES input.file/CHANGE_BAR=#
The following placement displays input.file;2 with the pound sign (#) preceding any lines that differ from input.file;1:
$ DIFFERENCES input.file;1 input.file;2 /CHANGE_BAR=#
The following placement displays input.file;1 with the pound sign (#) preceding any lines that differ from input.file;2:
$ DIFFERENCES input.file;1/CHANGE_BAR=# input.file;2
The following placement displays input.file;1 with the percent sign (%) preceding any lines that differ from input.file;2, and also displays input.file;2 with the pound sign (#) preceding any lines that differ from input.file;1:
$ DIFFERENCES input.file;1/CHANGE_BAR=% input.file;2/CHANGE_BAR=#
If you do not specify a change bar character, the default is an exclamation point (!) for ASCII output.
If you specify hexadecimal or octal output (see the description of the /MODE qualifier), the change bar character is ignored and differences are marked by a "***CHANGE***" string in the record header. The keyword NONUMBER suppresses line numbers in the listing.
If neither the NUMBER nor the NONUMBER keyword is specified, the default is controlled by the /[NO]NUMBER command qualifier.
If you specify only one option, you can omit the parentheses.
If you use an exclamation point (!) as the specified character, you must enclose it in quotation marks (" "); for example, /CHANGE_BAR=("!",NUMBER).

/COMMENT_DELIMITER[=(character[,...])]
Ignores characters on a line to the right of (and including) a specified comment character.
If you specify just one character, you can omit the parentheses. Lowercase characters are automatically converted to uppercase unless they are enclosed in quotation marks. Nonalphanumeric characters (such as ! and ,) must be enclosed in quotation marks. Multicharacter comment characters are not allowed. You can specify up to 32 comment characters by typing the character itself or one of the following keywords. (Keywords can be abbreviated provided that the resultant keyword is not ambiguous and has at least 2 characters; single letters are treated as delimiters.)

Keyword Character

COLON Colon (:)

COMMA Comma (,)

EXCLAMATION Exclamation point (!)

FORM_FEED Form feed

LEFT Left bracket ([)

RIGHT Right bracket (])

SEMI_COLON Semicolon (;)

SLASH Slash (/)

SPACE Space

TAB Tab

If you specify the /COMMENT_DELIMITER qualifier, the /IGNORE=COMMENTS qualifier is implicitly also included.
If both the uppercase and lowercase forms of a letter are to be used as comment characters, the letter must be specified twice, once in uppercase and once in lowercase. If you do not include either a comment character or a keyword with the /COMMENT_DELIMITER qualifier, the DIFFERENCES command assumes a default comment character based on the file type. For some file types (.COB and .FOR), the default comment characters are considered valid delimiters only if they appear in the first column of a line.
The following characters are the default comment delimiters for files with the specified file types:

File Type Default Comment Character

.B2S, .B32, .BAS, .BLI !

.CBL, .CMD ! and ;

.COB * or / in the first column

.COM, .COR !

.FOR ! anywhere and C, D, c, d in the first column

.HLP !

.MAC, .MAR ;

.R32, .REQ !

/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.
/HIGHLIGHT[=keyword]
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.
/IGNORE=(keyword[,...])
Inhibits the comparison of the specified characters, strings, or records; also controls whether the comparison records are output to the listing file as edited records or exactly as they appeared in the input file. If you specify only one keyword, you can omit the parentheses. The keyword parameter refers to either a character or a keyword. The first set of keywords determines what, if anything, is ignored during file comparison; the second set of keywords determines whether or not ignored characters are included in the output. The following keywords are valid options for the /IGNORE qualifier:

Keyword Item Ignored

BLANK_LINES Blank lines between data lines.

CASE Case of the text being compared.

COMMENTS Data following a comment character. (Use the /COMMENT_DELIMITER qualifier to designate one or more nondefault comment delimiters.)

FORM_FEEDS Form feed character.

HEADER[=n] First n records of the file, beginning with a record whose first character is a form feed. The first record is not ignored if the only character it contains is a form feed. ( N indicates the number of records and defaults to 2. A record with a single form feed is not counted.)

SPACING Extra blank spaces or tabs within data lines.

TRAILING_SPACES Space and tab characters at the end of a data line.

Keyword Status of Ignored Items in Output

EDITED Omits ignored characters from the output records.

EXACT Includes ignored characters in the output records.

PRETTY Formats output records.

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)

/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 key, Ctrl/B Scroll up one line.

Down arrow key Scroll down one line.

Left arrow key Scroll left one column.

Right arrow key 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.

Keyword	Character
COLON	Colon (:)
COMMA	Comma (,)
EXCLAMATION	Exclamation point (!)
FORM_FEED	Form feed
LEFT	Left bracket ([)
RIGHT	Right bracket (])
SEMI_COLON	Semicolon (;)
SLASH	Slash (/)
SPACE	Space
TAB	Tab

File Type	Default Comment Character
.B2S, .B32, .BAS, .BLI	!
.CBL, .CMD	! and ;
.COB	* or / in the first column
.COM, .COR	!
.FOR	! anywhere and C, D, c, d in the first column
.HLP	!
.MAC, .MAR	;
.R32, .REQ	!

Keyword	Item Ignored
BLANK_LINES	Blank lines between data lines.
CASE	Case of the text being compared.
COMMENTS	Data following a comment character. (Use the /COMMENT_DELIMITER qualifier to designate one or more nondefault comment delimiters.)
FORM_FEEDS	Form feed character.
HEADER[=n]	First n records of the file, beginning with a record whose first character is a form feed. The first record is not ignored if the only character it contains is a form feed. ( N indicates the number of records and defaults to 2. A record with a single form feed is not counted.)
SPACING	Extra blank spaces or tabs within data lines.
TRAILING_SPACES	Space and tab characters at the end of a data line.
Keyword	Status of Ignored Items in Output
EDITED	Omits ignored characters from the output records.
EXACT	Includes ignored characters in the output records.
PRETTY	Formats output records.

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)

Key Sequence	Description
Up arrow key, Ctrl/B	Scroll up one line.
Down arrow key	Scroll down one line.
Left arrow key	Scroll left one column.
Right arrow key	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.

Examples

#1
$ DIFFERENCES EXAMPLE.TXT ********** File DISK1:[BOB.TEXT]EXAMPLE.TXT;2 1 DEMONSTRATION 2 OF V3.0 DIFFERENCES 3 UTILITY ** File DISK1:[BOB.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:[BOB.TEXT]EXAMPLE.TXT;2 DISK1:[BOB.TEXT]EXAMPLE.TXT;1

$ DIFFERENCES EXAMPLE.TXT
************
File DISK1:[BOB.TEXT]EXAMPLE.TXT;2
    1   DEMONSTRATION 
    2   OF V3.0 DIFFERENCES
    3   UTILITY
******
File DISK1:[BOB.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:[BOB.TEXT]EXAMPLE.TXT;2
       DISK1:[BOB.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.

#2
$ DIFFERENCES/PARALLEL/WIDTH=80/COMMENT_DELIMITER="V" EXAMPLE.TXT ------------------------------------------------------------------------------- File DISK1:[BOB.TEXT]EXAMPLE.TXT;2 \| File DISK1:[BOB.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:[BOB.TEXT]EXAMPLE.TXT;2- DISK1:[BOB.TEXT]EXAMPLE.TXT;1

$ DIFFERENCES/PARALLEL/WIDTH=80/COMMENT_DELIMITER="V" EXAMPLE.TXT
-------------------------------------------------------------------------------
File DISK1:[BOB.TEXT]EXAMPLE.TXT;2  |  File DISK1:[BOB.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:[BOB.TEXT]EXAMPLE.TXT;2-
       DISK1:[BOB.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.

#3
$ DIFFERENCES/WIDTH=80/MODE=(HEX,ASCII) EXAMPLE.TXT/CHANGE_BAR ********** File DISK1:[BOB.TEXT]EXAMPLE.TXT;2 1 ! DEMONSTRATION 2 ! OF V3.0 DIFFERENCES 3 UTILITY ******** ******** File DISK1:[BOB.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:[BOB.TEXT]EXAMPLE.TXT;2/CHANGE_BAR- DISK1:[BOB.TEXT]EXAMPLE.TXT;1

$ DIFFERENCES/WIDTH=80/MODE=(HEX,ASCII) EXAMPLE.TXT/CHANGE_BAR
************
File DISK1:[BOB.TEXT]EXAMPLE.TXT;2
    1 ! DEMONSTRATION 
    2 ! OF V3.0 DIFFERENCES
    3   UTILITY
************
************
File DISK1:[BOB.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:[BOB.TEXT]EXAMPLE.TXT;2/CHANGE_BAR-
       DISK1:[BOB.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.

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

Contents

Index

privacy and legal statement

9996PRO_014.HTML

SUCCESS	Files are identical.
INFORMATIONAL	Files are different.
WARNING	User-specified maximum number of DIFFERENCES has been exceeded.
ERROR	Insufficient virtual memory to complete comparison.

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.