COMPARE—Edit Compare

The COMPARE command compares the file you are editing with an external sequential data set, member of a partitioned data set, or z/OS® UNIX file. Lines that exist only in the file being edited are marked, and lines that exist only in the file being compared are inserted as information lines in the file being edited. The command operates as a primary command or an edit macro.

You can use the Delete and Make Data line commands to merge changes between files that are being compared.

The COMPARE function supports all line lengths, but some SuperC options are ignored for line lengths greater than 256 characters long.

When you are editing a cataloged data set, explicit data set names refer to cataloged data sets. However, if you are editing an uncataloged data set, explicit member names refer to cataloged data sets, but if you specify only a member name, COMPARE searches for the member in the current uncataloged data set. For example, if you are editing an uncataloged data set called "userid.TEMP", the command

COMPARE TEMP

first looks for member TEMP in the current, uncataloged data set, then looks for a cataloged data set named TEMP (TSO prefix rules apply). If it finds data set TEMP, and the data set being edited is a PDS member, then the same named member is searched for in data set TEMP.

Use of COMPARE when editing concatenations that contain uncataloged data sets is not supported and can lead to unpredictable results.

If you have made changes to the data before issuing the COMPARE command, the COMPARE command uses the current contents of the edit session during the comparison. Because COMPARE does not require the data to be saved on disk, you can use the COMPARE command from EDIF, VIIF, or EDIREC sessions. However, COMPARE NEXT and COMPARE SESSION are not supported in EDIF, VIIF, or EDIREC sessions.

Syntax


>>-ISREDIT--COMPARE--+-dsname--+-------------+-+---------------->
                     |         '-VOL(volser)-' |   
                     +-NEXT--------------------+   
                     '-+-SESSION-+-------------'   
                       '- * -----'                 

>--+---------+--+------+--+---------------------------+--------><
   '-EXCLUDE-'  '-SAVE-'  '-SYSIN--+----------------+-'   
                                   +-(supercdsname)-+     
                                   '-(/)------------'

dsname

The name of a member, data set, or z/OS UNIX file to which the current file is compared. This variable can be specified as a fully qualified data set name (in quotation marks), a partially qualified data set name, a member name, or a path name. (Also, see Specifying z/OS UNIX pathnames with edit primary and macro commands.)

If you specify only a member name, it can be preceded by a left parenthesis symbol. The right parenthesis is allowed but not required. The current edit session must be of a member of a partitioned data set. The current edit concatenation is searched for the member to compare.

If you specify only a data set name and the current file is a member of a PDS, then the specified data set is searched for a member of the same name as the member being edited.

VOL(volser)

Used when comparing against an uncataloged data set. Specifies the volser of the volume containing the uncataloged data set.

NEXT

Specifies to do a comparison between the currently edited member and the next member of the same name found at a higher level of the hierarchy (or next level of the edit concatenation) than the current member. For example, if the current member is found in the third level of the concatenation, and a like-named member exists at the fourth level, then the third and fourth level members are compared. After data is saved in the lowest level, compares are done from that level upward.

SESSION

Specifies that you want to compare the changes you have made during the edit session with the copy of the data saved on disk. Use COMPARE SESSION or COMPARE * to see the changes you have made to the edit data since the beginning of the edit session or since the last SAVE command.

*

Same as SESSION.

EXCLUDE

Specifies that all matching lines in the compared data sets are excluded from the display except for a specified number of lines above and below the differences. The differences themselves are also shown in the display. The specified number of lines that are shown is set on the Edit Compare Settings and/or Command Parameters panel. If you do not specify a new number for this edit session, then whatever was the last number set is still valid. To change this number, issue the COMPARE command with no operand and change the EXCLUDE field on the Edit Compare Settings and/or Command Parameters panel. Valid numbers are 0 through 12, inclusive. You cannot display the Edit Compare Settings and/or Command Parameters panel from a macro.

You can also use the COMPARE EXCLUDE command at any time to exclude all lines in a file except lines with line labels and information lines, and the lines above and below those lines. When you specify EXCLUDE without a data set name or NEXT, no comparison is done. Instead the labels and information lines that already exist in the file are used to exclude functions. See Examples for a macro that uses this technique.

SAVE

Specifies that SuperC (which performs the actual compare function) create a listing. The listing is saved in a data set with one of these names:

tsopref.ISPFEDIT.COMPARE.LIST (where tsopref is your TSO prefix).
tsopref.userid.ISPFEDIT.COMPARE.LIST (where userid is your TSO user ID and it does not match your TSO prefix).
userid.ISPFEDIT.COMPARE.LIST (where no TSO prefix is defined in your TSO user profile).

Note: If the ISPF configuration table keyword USE_ADDITIONAL_QUAL_FOR_PDF_DATA_SETS is set to YES, an additional qualifier defined with the ISPF_TEMPORARY_DATA_SET_QUALIFIER keyword is included before the ISPFEDIT qualifier.

The save function is intended for debugging purposes, but it also provides a way to create a SuperC listing. The listing produced is a Change listing (option CHNGL). No notification is given regarding successful creation of the listing, and errors allocating the listing do not cause the comparison to end.

Note: Because of the way the SuperC comparison is done, the file currently being edited is shown in the SuperC listing as the old file, and the file to which the current file is being compared is listed as the new file. Therefore, insertions refer to lines that are not in the current file, and deletions refer to lines that are only in the current file.

SYSIN

Specifies not to free the ddname SYSIN before calling SuperC to compare files. This enables you to pass SuperC Process Statements to alter the comparison. No validation is done on the type of SYSIN allocation or the contents of the data set.

supercdsname: The name of a data set containing SuperC process statements.
/: Displays the Edit Compare SYSIN specification panel where you can specify the name of a data set containing SuperC Process statements that are used for the compare. The SYSIN data set is freed at the end of the compare.

Return codes

0: Normal completion
8: Member, data set, or z/OS UNIX file not found, or an error opening the member or data set occurred.
12: No parameters specified, or another parameter error such as not valid NEXT or member specification.
20: Severe error. SuperC, allocation, or delta file error occurred.

Examples

To compare the current file to another file called X.Y.Z and to save the SuperC output file in ISPFEDIT.COMPARE.LIST:

   ISREDIT COMPARE X.Y.Z SAVE

To compare the current file to a member in the same partitioned data set, and exclude everything but the context in which changes exist:

   ISREDIT COMPARE (memname) EXCLUDE

To find all of the occurrences of a string in a file and exclude lines to show the context in which the strings were found, you can use this macro:

/* REXX - Edit macro to find a string, show only lines with the   */
/*        string and a few lines above and below found strings.   */
/*        This uses the COMPARE EXCLUDE command to perform the    */
/*        line exclude function.                                  */
/* -------------------------------------------------------------- */
Address isredit                  /*                               */
'MACRO (PARM)'                   /* Accept input string           */
If parm ^= '' Then               /* Do nothing if no parameters   */
  Do                             /*                               */
    'RESET LABEL'                /* Remove all existing labels    */
    'F FIRST 'parm               /* Find first string occurrence  */
    Do While(rc=0)               /*   For each occurrence         */
      'LABEL .ZCSR = 'label()' 0'/*      Assign a label to line   */
      'RFIND'                    /*      Find next occurrence     */
    End                          /*                               */
    'COMPARE X'                  /* Exclude everything except     */
                                 /*  Labels and above/below lines */
    'RESET LABEL'                /* Remove all labels             */
    '(XSTAT) = XSTATUS .ZFIRST'  /* Save exclude status of line 1 */
    'LOCATE .ZFIRST'             /* Move display to line 1        */
    'XSTATUS .ZFIRST = 'xstat    /* Restore line 1 exclude status */
  End                            /*                               */
Exit 0                           /* Always return a zero          */
/* -------------------------------------------------------------- */
label:Procedure Expose labelnum  /* Routine to generate a unique  */
If datatype(labelnum,'N')=0 Then /*   Edit line label             */
  labelnum=0                     /*                               */
Else                             /*                               */
  labelnum=labelnum+1            /*                               */
Return '.'translate(right(labelnum,4,'0'),'ABCDEFGHIJ','0123456789')