BSTPCOMP for Comparing Members or Files

2
cedraft
Endevor
provides a utility, BSTPCOMP, which compares the contents of two PDS or PDS/E members or sequential files, and reports the differences between them. The members/files being compared can be--but need not necessarily be--previously retrieved
Endevor
elements.
BSTPCOMP accepts two files as input; these files can be PDS or PDS/E members or sequential files. The files can be fixed or variable length, but cannot exceed an LRECL of 256 (260 for variable-length files).
BSTPCOMP reports the differences between the two files. The first file, NDVRIN1, is assumed to be the base file. The second file, NDVRIN2, is assumed to be the changed file. BSTPCOMP reports the differences in file 2 as compared to file 1.
The files are compared line-by-line, based on the contents of particular (contiguous) characters. The range of characters included in the compare is defined in terms of a from and through column, but cannot exceed 256. For example, you might want to compare two files based on the contents of positions 1-5 only.
If the files compare identically, no output is produced other than the syntax listing (if applicable). Data is only listed when differences are detected.
The output from BSTPCOMP can be formatted for browse (without ASA characters and headings) or for hardcopy printout (including ASA characters and headers).
Beware of problems when comparing fixed records to variable records. Spaces are not equal to nulls.
How to Control Compare Output
There are three methods for executing BSTPCOMP: no overrides, PARM-driven, and control card-driven. These methods specify which records display (if any), which columns are compared, and the format of the output data set (BROWSE or PRINT). A description of each method follows with accompanying sample syntax (as applicable).
No Overrides Method
By default, BSTPCOMP compares columns 1 through 72, lists changes only, and formats for printing if the NDVRLST DDname is available. If NDVRLST is unavailable, the output is formatted for BROWSE and written to file NDVRPCH.
If the input files are variable length, the comparison considers short records to be padded with blanks up to the through column.
Example: Sample JCL
In the following example, BSTPCOMP has been instructed to compare the data in DDname NDVRIN1 with data in DDname NDVRIN2 and report changes (if any) within columns 1 through 72. If there are changes, the output would be written to DDname NDVRLST with page headings.
NDVRIN1 and NDVRIN2 must be sequential data sets or a partitioned data set with a member name specified.
//* //* RESTRICTION: //* LRECL FOR INPUT FILES (NDVRIN1, NDVRIN2) MAY NOT EXCEED 256 //* //STEP1 EXEC PGM=BSTPCOMP,REGION=2000K, //STEPLIB DD DSN=iprfx.iqual.CSIQAUTH,DISP=SHR //* //* ONE OF THE FOLLOWING WILL RECEIVE YOUR OUTPUT //NDVRLST DD SYSOUT=*,DCB=(RECFM=FBA,LRECL=133) //* //* YOU MAY HAVE SOME OTHER WAY OF ALLOCATING SORT WORK FILES. //SORTWK01 DD UNIT=tdisk,SPACE=(CYL,(2,1)) //SORTWK02 DD UNIT=tdisk,SPACE=(CYL,(2,1)) //* //* THE NEXT TWO DESCRIBE THE FILES YOU WANT TO COMPARE //NDVRIN1 DD DISP=SHR,DSN=uprfx.uqual.FILE1(MEMBER) //NDVRIN2 DD DISP=SHR,DSN=uprfx.uqual.FILE2(MEMBER) /*
Control Card Execution Method
Control cards are supplied in file NDVRIPT and are freeform. The control cards consist of the word COMPARE followed by optional clauses, and ending with a period. This execution method provides the greatest degree of flexibility and control.
The syntax for the control card is shown next:
►►──COMpare────────────────────────────────────────────────────────────────────────► ►──¤──┬────────────────────────────────────────────────────────────┬──¤──.────────►◄ ├─COLumn──┬───┬──n──┬────┬──n────────────────────────────────┤ │ └─=─┘ └─TO─┘ │ │ ┌─CHAnge──┐ │ ├─OUTput──┬───┬──┼─HIStory─┼─────────────────────────────────┤ │ └─=─┘ └─NEW─────┘ │ │ ┌─DISplay──┐ │ ├─FORmat──┬───┬──┼─FILe─────┼────────────────────────────────┤ │ └─=─┘ └─IEBupdte─┘ │ │ ┌─BLAnk───┐ │ ├─PAD──┬───┬──┼─NULl────┼────────────────────────────────────┤ │ └─=─┘ └─'x'─────┘ │ ├─SIZe──┬───┬──nnnnnn────────────────────────────────────────┤ │ └─=─┘ │ ├─TITle──┬───┬──'______'─────────────────────────────────────┤ │ └─=─┘ │ └─RECord──┬───────────────────────────────────────────────┬──┘ │ ┌─FIXed────┐ │ └─TYPe──┬───┬──┴─VARiable─┴──LENgth──┬───┬──nnn─┘ └─=─┘ └─=─┘
A description of the syntax clauses follows:
  • COLUMN
    Specifies the range of columns to compare. If omitted, columns 1-72 are used.
  • OUTPUT
    Specifies which records are to be output. The default is CHANGES only. The other options are: HISTORY (shows the existing member together with inserts and deletes), and NEW (shows the new member, highlighting inserts only).
  • FORMAT
    Specifies the output format. The default is DISPLAY which writes the output to file NDVRLST. The syntax listing is produced first, followed by the original output file in report format--with carriage control and page headings. The FILE option (that is, BROWSE) writes the data to DDname NDVRPCH without page headings.
  • PAD
    PAD is applicable to variable length records only. The default is BLANK (which pads short records with blanks up to the compare length). The options are NULL (which pads with binary zeros) or “x” (which pads with the specified single character).
  • SIZE
    Specifies a file-size estimate for the sort. By default, this option is ignored.
  • TITLE
    Appears before the first data line as a line of asterisks, followed by the title string and another line of asterisks. Useful if FORMAT=FILE.
  • RECORD
    This clause is provided for DOS-compatibility only.
Example: Control Card JCL
The sample JCL which follows would produce a report:
NDVRIN1 and NDVRIN2 must be sequential data sets or a partitioned data set with a member name specified.
//COMPARE EXEC PGM=BSTPCOMP,REGION=2000K //STEPLIB DD DSN=iprfx.iqual.CSIQLOAD,DISP-SHR //* //NDVRIN1 DD DSN=OLD.FILE.LIBRARY(MEMBER),DISP=SHR //NDVRIN2 DD DSN=NEW.FILE.LIBRARY(MEMBER),DISP=SHR //* //NDVRLST DD SYSOUT=* **SYNTAX LISTING + COMPARE OUTPUT** //*SORTWORK FILES USED ONLY IF FILES TOO LARGE FOR IN-MEMORY COMPARE //SORTWK01 DD UNIT=DASD,SPACE=(TRK,(1,30) //SORTWK02 DD UNIT=DASD,SPACE=(TRK,(1,30) //* //NDVRIPT DD * COMPARE COLUMN=1 TO 80 OUTPUT=HISTORY. /*
The sample JCL which follows would produce a file for browsing:
//COMPARE EXEC PGM=BSTPCOMP,REGION=2000K //STEPLIB DD DSN=iprfx.iqual.CSIQLOAD,DISP-SHR //* //NDVRIN1 DD DSN=OLD.FILE.LIBRARY(MEMBER),DISP=SHR //NDVRIN2 DD DSN=NEW.FILE.LIBRARY(MEMBER),DISP=SHR //* //NDVRLST DD SYSOUT=* **SYNTAX LISTING + COMPARE OUTPUT** //*SORTWORK FILES USED ONLY IF FILES TOO LARGE FOR IN-MEMORY COMPARE //SORTWK01 DD UNIT=DASD,SPACE=(TRK,(1,30) //SORTWK02 DD UNIT=DASD,SPACE=(TRK,(1,30) //* //NDVRIPT DD * COMPARE COLUMN=1 TO 80 OUTPUT=HISTORY. //*OUTPUT OF COMPARE: NOTE: RECORD LENGTH=#COMPARE COLUMNS + 16 //NDVRPCH DD DSN=OUTPUT.FILE.NAME,DISP=(,CATLG), // UNIT=DASD,SPACE=(TRK,(5,5),RLSE), // DCB=(LRECL=88,BLKSIZE=6072,RECFM=FB) //*
PARM-Controlled Execution Method
This method may be more convenient for CLIST operation than the previous Control Card method.The full syntax for the EXEC statement PARM values is shown next:
PARM='output-format,from,thru,rec-count,pad-char'
Specify the PARM values as described next. Separate the values using a single comma, leaving no spaces between the values.
  • output-format
    The two-character code that indicates the type of comparison information you want reported (character 1) and the format of the output file (character 2). The default is CD.
    Specify the first character (type of information you want) as follows:
    • C
      Print only the
      changes
      between the two files: that is, those lines that are in file 2 but not in file 1, or those lines that are deleted from file 2.
    • B
      Print
      (browse)
      the contents of file 2, highlighting those lines that are not in file 1 by printing “%INSERT” to the left of those lines: “%” lets you scan for changes easily; “INSERT” indicates that the line was new in file 2.
    • H
      Print a
      history
      of both files, including:
      • The entire contents of file 2, highlighting those lines that are not in file 1 by printing “%INSERT” to the far left.
      • Lines that were in file 1 but not in file 2, highlighting these lines with “%DELETE” to the far left.
    Specify the second character (output format) as follows:
    • F
      The output file is in browse format and does not have any ASA characters or headers. The output is written to DDname NDVRPCH
    • D
      The output file is formatted for print, and includes ASA characters and headers. The output is written to DDname NDVRLST
  • from
    Starting character for the compare. BSTPCOMP begins its search at this position in both files. The default is 1.
  • thru
    Ending character for the compare. BSTPCOMP ends its search with this position, within both files. For variable-length records, if the record in one file is longer than that in the other, and the through character extends beyond the end of the record, BSTPCOMP pads according to the pad-char specification before performing the compare.
    The default thru specification is 72.
  • rec-count
    Largest number of records in either file. The default is 10000. Estimate high when specifying this value.
  • pad-char
    Pad character used for variable-length records, as described previously for the through parameter. Specify this as follows. The default is BLANK.
    • BLANK--Blanks
    • NULL--Null values (binary zeroes)
  • nnn
    The hexadecimal equivalent of nnn, where nnn is a 1-3 character decimal value. Specify 64 to pad with X'40', 255 to pad with X'FF', and so forth.
The formula for NDVRPCH DCB attributes is as follows:
DCB = (RECFM=FB,LRECL=LENGTH OF RECORD + 16, BLKSIZE=LRECL)Note the coding convention for each variable:
RECFM must be fixed block.
  • LRECL must equal the length of the RECORD plus 16.
  • Blocksize must be an even multiple of LRECL.
Sample Changes Report Output
The following report is returned when you run the defaults, or specify
OUTPUT=CHANGES
or
output format code CD
(Changes Report). It shows only the changes between the two files: that is, those lines that are in file 2 but not in file 1 (marked with “INSERT”), or those lines that are missing from file 2 that were in file 1 (marked with “DELETE”).
COPYRIGHT (C) CA, INC., E N D E V O R mm/dd/yy 11:58:23 PAGE 1 RELEASE X.XX SERIAL XXXXXX BSTPCOMP - FILE COMPARE UTILITY COMPARE OUTPUT=CHANGES . 00350002 INSERT MAIN $FUNCSTG PLSIZE=4 000006 DELETE MAIN $FUNCSTG 000006 INSERT WORD3 DS F 000010 INSERT SPACE 3 000012 INSERT MAIN999 $FEND 000014 DELETE $FEND 000012 %****** RECORDS: FILE 1 = 00014 FILE 2 = 00016 INSERTS = 00004 DELETES = 00002 ******
The following report is returned when you specify
OUTPUT=NEW
or
output-format code BD
(New Browse Report). It lists the contents of file 2, highlighting any lines that are not in file 1 with “%INSERT.”
COPYRIGHT (C) CA, INC., E N D E V O R mm/dd/yy 11:58:27 PAGE 1 RELEASE X.XX SERIAL XXXXXX BSTPCOMP - FILE COMPARE UTILITY COMPARE OUTPUT = NEW . 00490002 COMPTEST TITLE 'PROGRAM TO DEMONSTRATE COMPARE UTILITY' 000001 COMPT $MODNTRY LINKAGE=SUB 000002 TITLE 'DSECTS: DCB ' 000003 DCBD DSORG=PS 000004 TITLE MAIN: ENTRY FROM CALLER' 000005 %INSERT MAIN $FUNCSTG PLSIZE=4 000006 GLOBALS DS 0D 000007 WORD1 DS F 000008 WORD2 DS F 000009 %INSERT WORD3 DS F 000010 $FUNC 000011 %INSERT SPACE 3 000012 SR R15,R15 RETURN CODE = SUCCESS 000013 %INSERT MAIN999 $FEND 000014 $MODEND 000015 END 000016 %****** RECORDS: FILE 1 = 00014 FILE 2 = 00016 INSERTS = 00004 DELETES = 00002 ******
The following report is returned when you specify
OUTPUT=HISTORY
or
output-format code HD
(History Report). It lists the contents of file 2, highlighting inserts from file 2 and deletes from file 1.
COPYRIGHT (C) CA, INC., E N D E V O R mm/dd/yy 11:58:23 PAGE 1 RELEASE X.XX SERIAL XXXXXX BSTPCOMP - FILE COMPARE UTILITY COMPARE OUTPUT = HISTORY . 00630002 COMPTEST TITLE 'PROGRAM TO DEMONSTRATE COMPARE UTILITY' 000001 COMPT $MODNTRY LINKAGE=SUB 000002 TITLE 'DSECTS: DCB ' 000003 DCBD DSORG=PS 000004 TITLE MAIN: ENTRY FROM CALLER' 000005 %INSERT MAIN $FUNCSTG PLSIZE=4 000006 %DELETE MAIN $FUNCSTG 000006 GLOBALS DS 0D 000007 WORD1 DS F 000008 WORD2 DS F 000009 %INSERT WORD3 DS F 000010 $FUNC 000011 %INSERT SPACE 3 000012 SR R15,R15 RETURN CODE = SUCCESS 000013 %INSERT MAIN999 $FEND 000014 %DELETE $FEND 000012 $MODEND 000015 END 000016 %****** RECORDS: FILE 1 = 00014 FILE 2 = 00016 INSERTS = 00004 DELETES = 00002 ******
BSTPCOMP Return Codes
The following COND CODE values can be returned by BSTPCOMP. Code 3007 is the expected result. Other values might be returned, indicating a problem with the sort. If this happens, rerun the job to obtain the sort messages, specifying //SYSOUT DD SYSOUT=*.
  • 3000
    The input files are identical for the columns compared. No reports were produced.
  • 3001
    An input or output file could not be opened. Ensure that the DD statements are correct for all files and try again.
  • 3002
    The number of records in one or both of the input files exceeds the maximum count specified by the rec-count parameter. Increase the count and try again. It is better to estimate high rather than low.
  • 3003
    The LRECL for an input file exceeded 256 (260 for variable-length). You cannot use this file as input.
  • 3005
    The record format for an input file is Undefined. The record must specify Fixed or Variable.
  • 3006
    An input parameter is missing or invalid (for example, thru >from). Check your syntax against the previous parameter descriptions, correct the problem, and resubmit the job.
  • 3007
    BSTPCOMP completed its compare successfully and found differences between the files. This is the standard return code.