CA Panvalet. Compare Reference Guide. r14.6

Transcription

1 CA Panvalet Compare Reference Guide r14.6

2 This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the Documentation ) is for your informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and CA. Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections , , and (c)(1) - (2) and DFARS Section (b)(3), as applicable, or their successors. Copyright 2004 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

3 CA Technologies Product References This document references the following CA Technologies products: CA Panvalet Contact CA Technologies Contact CA Support For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At you can access the following resources: Online and telephone contact information for technical assistance and customer services Information about user communities and forums Product and documentation downloads CA Support policies and guidelines Other helpful resources appropriate for your product Providing Feedback About Product Documentation If you have comments or questions about CA Technologies product documentation, you can send a message to techpubs@ca.com. To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at

4

5 Contents Chapter 1: General Information 7 Uses... 7 Features... 8 Flexible Input... 8 Direct Interface... 8 Optional Reports... 8 Audit File... 8 Update Decks... 8 Exit Facility... 9 Functions Inputs Command Stream OLD File NEW File Outputs COMMAND Summary DETAIL Report DELTA Report UPDATE Report COMPARE Summary DELTA File UPDATE File Changed Records Ambiguous Matches Commands Command Syntax Syntax Rules Example Chapter 2: Inputs 19 Library Members Sequential Data Sets z/os PDS Members User Exits Contents 5

6 Chapter 3: Outputs 21 Required Summaries Optional Reports COMMAND Summary DETAIL Report DELTA Report UPDATE Report COMPARE Summary Ambiguous Matches DELTA File UPDATE File Chapter 4: Commands 33 COMPARE Command Syntax Keywords OLD Command Syntax Keywords NEW Command Syntax UPDATE Command Syntax Keywords Chapter 5: Execution Requirements 43 Storage Requirements z/os JCL z/os Return Codes VSE JCL User Abend Codes Chapter 6: Defaults 49 Command Defaults File Defaults Index 51 6 Compare Reference Guide

7 Chapter 1: General Information Change is inevitable in the data processing industry. The purpose of any computer system is to manage, define, and monitor the change of data. Programmers, software testers, production control personnel, auditors, and managers need the power to identify change. Several times each day, the solution to a data processing problem is the answer to the question, "What's changed?" The Compare function of CA Panvalet can help you answer the question, "What's changed?" The Compare function has a single purpose: to read two files and report on the differences between them. The differences between two files are expressed as the changes made to the first file to produce the second file. Flexibility of inputs, variety of outputs, optional controls, and performance make the Compare function of CA Panvalet unique among file comparison systems. This section contains the following topics: Uses (see page 7) Features (see page 8) Uses You can use the Compare function as a tool in many applications. The Compare function: Reports the differences between two source files (old and new). It also helps you identify the changes made to the source code. Helps determine changes made during an edit session. You can use the reported changes to submit a batch update job. Helps you merge modifications into an existing program. This is valuable when several programmers are making modifications at the same time or when you have local modifications to vendor-supplied source. Helps you identify the cause of incorrect program results by comparing two files to see what has changed since the last correct run. Helps you identify areas of program change so you can build test cases that focus on the new code. Optionally stores reported changes on a history tape for future retrieval. Helps identify the changes made during a programming project by comparing the new source with the old. Chapter 1: General Information 7

8 Features Verifies that a file has not changed or helps you isolate the nature of a change to a critical file. Helps you measure the volume of programming changes and record the nature of those changes. Features The Compare function of CA Panvalet has a variety of features, described in the following subsections. Flexible Input Input files do not have to be in strict card-image format. You can compare any fixed-sequential file, blocked or unblocked, of any record length. In z/os, you can also compare variable files. Direct Interface In addition to sequential files, you can compare CA Panvalet library members. The directory information is updated when a member is compared, and CA Panvalet security is honored. You can expand INCLUDES and use format types to ignore sequence numbers. Optional Reports You can request a detailed listing of both files and their differences, a report of only the differences, or a short summary of the number of differences that are found. Audit File The Compare function produces a complete change log/audit. It contains before and after record images of all changes to a file. Update Decks The Compare function produces a change deck in the format used by batch CA Panvalet (++UPDATE). 8 Compare Reference Guide

9 Features Exit Facility The Exit Facility is described in the CA Panvalet for z/os Getting Started, CA Panvalet for VSE Getting Started, Option for ISPF User Guide, and the Option for TSO User Guide. Chapter 1: General Information 9

10

11 This chapter describes operational functions, the inputs to these functions, and the resulting outputs. This section contains the following topics: Functions (see page 11) Inputs (see page 12) Outputs (see page 13) Commands (see page 16) Command Syntax (see page 16) Functions The Compare function has the following general operational characteristics: It is a batch program invoked by job control language (JCL). You code commands to govern its operation. Missing command options assume default values. Defaults are set by the systems programmer when the product is installed. Each execution of Compare reads and compares two files. The two files are called the OLD file and the NEW file. The OLD and NEW files can be sequential files or members of CA Panvalet libraries. Compare prints reports on the differences between the OLD file and the NEW file. Chapter 1: General Information 11

12 Inputs Compare writes files that define the differences between the OLD file and the NEW file. Compare can write an UPDATE file (a CA Panvalet PAN#1 ++UPDATE deck) or a DELTA file (a log containing record images of all changes). If needed, you can invoke user exits to customize input and output processing. User exits are described in the CA Panvalet for z/os Getting Started. Compare writes informational and diagnostic messages during operation. Messages are described in the Messages Guide. Inputs Three input files are required. These files are the command stream (control statements) and the two files you want to compare (the OLD file and the NEW file). Command Stream Compare lets you code commands in a free-form, keyword-oriented syntax. The commands specify a comparison of one pair of files only. The command file must be fixed, 80-byte records on a device supported by SYSIN processing. OLD File The OLD file is one of the two files being compared. It can be a sequential file or a CA Panvalet library member. For z/os, sequential files can reside on any card, tape, or disk device that the sequential access method supports. The record format can be fixed or variable. The record length can be any value supported by z/os data management. The OLD file can be a PDS member if you specify the member name in the JCL. For VSE, sequential files can reside on any disk device supported by the sequential access method. The record format can be fixed blocked or fixed unblocked. The record length can be any value up to the block size. NEW File The NEW file is one of the two files being compared. Its characteristics are identical to the OLD file. See the chapter "Inputs" for detailed information on Compare inputs. 12 Compare Reference Guide

13 Outputs Outputs The Compare output answers the question, "What changes were made to the OLD file to get the NEW file?" The output can take several formats. COMMAND Summary The COMMAND summary lists input commands and any error or informational messages. This file is always written. DETAIL Report A DETAIL report of the OLD and NEW files, side-by-side, shows the differences between the files. The differences are illustrated by showing which records must be deleted from and added to the OLD file to produce the NEW file. DELTA Report A DELTA report (change report) shows only the differences between OLD and NEW files. This is a printout of the additions and deletions. UPDATE Report An UPDATE report lists the contents of the UPDATE file. COMPARE Summary The COMPARE summary gives statistics on matches and differences for the OLD and NEW files. This file is always written. Chapter 1: General Information 13

14 Outputs DELTA File A DELTA file is a complete audit/log of all the differences between the OLD file and the NEW file. It contains images of all the added and deleted records. You can use it as input to an activity logging system, audit system, or backup/recovery system. The DELTA file is two-directional. You can use it to produce the NEW file from the OLD file or the OLD file from the NEW file. A record deleted from the OLD file is a record that is inserted in the NEW file. Therefore, you can successively apply a series of DELTA files kept in an archive to an old version to recreate a recent version. Likewise, you can back out changes, one version at a time, by applying DELTA files to the current version. UPDATE File You can use an UPDATE file as input to batch CA Panvalet, PAN#1. It is a ++UPDATE input stream. If you run the UPDATE file against the OLD file using PAN#1, the output is the NEW file. See the chapter "Outputs" for detailed information about Compare outputs. Changed Records An important Compare concept is that of a changed record. Compare determines only whether two records are identical. It cannot determine how unlike records came to be different. Consider these two files: OLD FILE NEW FILE AAAAAAAA Record-1 AAAAAAAA BBBBBBBB Record-2 BBBBBBBB CCCCCCC* Record-3 CCCCCCCC DDDDDDDD Record-4 DDDDDDDD To a human, the change between the OLD file and the NEW file is stated: "Change Record 3, Column 8 from * to C." Compare reports the change this way: Record-3 contents = CCCCCCC* DELETED Record-3 contents = CCCCCCCC INSERTED A changed record is indicated with a delete followed by an insert. 14 Compare Reference Guide

15 Outputs There is no single correct output of any compare routine. In the previous example, it is also correct to summarize the changes in this way: Delete record-1 through record-4 from the OLD file. Then, insert record-1 through record-4 into the NEW file. While this example illustrates a correct output, the compare routine is of poor quality. A good routine should accurately identify the differences between two files by showing a minimum of changed statements. A good routine should also attempt to show the differences in a way that you can easily understand. Compare has been designed with these concerns in mind and tries to report the minimum number of deleted and inserted records that are required to produce the NEW file. This attention to the internal compare algorithm, with its available format outputs, makes it suitable for many types of auditing, transaction logging, change control, and user inspection. Ambiguous Matches At end-of-job, the COMPARE summary lists the number of ambiguous matches. An ambiguous match is not an error, but it can affect the appearance of the DELTA and UPDATE reports. Compare encodes each record as a single value, called a hash code. Through this technique, you can represent the entire OLD and NEW files in machine storage. From time to time, the hash code of two different records is equal. This is called an ambiguous match. Ambiguous matches are discovered and corrected after the compare process, when the files and reports are processed. Thus, ambiguities are completely resolved. Ambiguous matches are rare. The odds that any two records will cause an ambiguous match is less than one in two billion. Even if an ambiguous match does occur, there is usually no effect on the output. When an ambiguous match occurs, the DELTA and UPDATE reports are still entirely accurate. However, the way in which records are matched in the output can be slightly different than if no ambiguous match occurred. Chapter 1: General Information 15

16 Commands Commands You can use the COMPARE, OLD, NEW, and UPDATE commands to control the Compare operation. The COMPARE command controls the functions that you want to perform and the format of the output. The OLD command describes the characteristics of the OLD input file and specifies the record field that you want to compare. The NEW command describes the characteristics of the NEW input file and specifies the record field that you want to compare. The UPDATE command supplies information for building CA Panvalet ++UPDATE commands. See the chapter "Commands" for detailed information on the use of the CA Panvalet/Compare commands. Command Syntax This is a general discussion of command syntax. Always refer to the full description of the command in question. Commands are constructed according to the following basic syntax: COMMAND KEYWORD1(value1) KEYWORD2(value2) KEYWORD3(value3)... Syntax Rules When coding commands, follow these rules: 1. Start each command on a new line. 2. Code commands anywhere in columns 1 through 72. Columns 73 through 80 are ignored. 3. Start all Compare commands with the command name. 4. Each operand is composed of a keyword and a value or values. You must code at least one non-blank value in the parentheses. 5. The value must immediately follow the keyword and be enclosed in parentheses. 6. If you code multiple values within parentheses, one or more blanks must separate each value. 7. You must balance parentheses (every open parenthesis must have a close parenthesis). 8. One or more trailing blanks must delimit the command and each operand. 16 Compare Reference Guide

17 Command Syntax 9. You can code blanks between any command, keyword, parenthesis, or value, but you cannot code blanks in them. 10. You can continue commands on successive statements by coding one or more blanks, then a hyphen (-) after the last operand and resuming operands on the next line. You cannot split commands, operands, keywords, or values across statements. 11. An asterisk (*) coded in column 1 causes the entire line to be ignored. Code comments on such a line. You cannot continue comments with a hyphen. 12. Abbreviate any command or operand (keyword or value) by truncating the right-most characters. Minimum abbreviations are shown in parentheses next to the margin entry. Truncation is allowed as long as the remaining character string uniquely identifies the operand. A character string uniquely identifies an operand when: The character string entered matches the leading characters of Compare operand. No ambiguity arises because the character string entered matches more than one operand on the same command. For example, two Compare keywords on the OLD command are: COLUMN CONTROL The minimum abbreviation for each is, respectively: COL CON Example In the following example, the two commands are equivalent. In the second command, each operand has been abbreviated to its minimum length. OLD COLUMN(1 72) CONTROL(1313) - FILEORG(PANVALET) MEMBER(GLS315) OLD COL(1 72) CON(1313) F(P) M(GLS315) Chapter 1: General Information 17

18

19 Chapter 2: Inputs Compare has two inputs known as the OLD and NEW files. It is assumed that the OLD file was changed to create the NEW file. The following inputs are allowed for use as OLD and NEW files: CA Panvalet library members Sequential files z/os PDS members (when the member is specified in JCL) Data from a user exit You can compare these inputs in any combination. The only requirement is that the OLD and NEW file record formats and lengths must be equivalent. Thus, it is possible for the OLD file to be a CA Panvalet library member, while the NEW file is a sequential data set. When comparing two CA Panvalet members, the two members can be in the same library or two different libraries. This section contains the following topics: Library Members (see page 19) Sequential Data Sets (see page 20) z/os PDS Members (see page 20) User Exits (see page 20) Library Members You can compare CA Panvalet library members by using the OLD and NEW command operands, FILEORG(PANVALET), MEMBER(name), and optionally LEVEL(level). CA Panvalet supersets and subsets are not supported and, if used, the results of a compare are unpredictable. CA Panvalet members have a record format of fixed and a record length of 80. All CONTROL and ACCESS security controls, which apply to WRITE WORK in batch CA Panvalet, apply to Compare. Similarly, all rules that apply to INCLUDE expansion are followed. Members are read from CA Panvalet in a format similar to the ++WRITE WORK command. The difference is that leading special comment records are not generated. The date of last access is updated for members retrieved by Compare. See the User Guide for detailed information. Chapter 2: Inputs 19

20 Sequential Data Sets Sequential Data Sets To compare sequential data sets, use the OLD and NEW commands with the operand FILEORG(SEQUENTIAL). The record length can be any value supported by the sequential access method. For z/os, the record format can be fixed or variable, blocked or unblocked. For VSE, the record format can be fixed block or fixed unblocked. z/os PDS Members PDS members are read as sequential data sets. The DD JCL statement defines the fully qualified data set and member name. User Exits See Exit Facilities in the CA Panvalet for z/os Getting Started for information about user exits. 20 Compare Reference Guide

21 Chapter 3: Outputs Compare writes the following reports and files: COMMAND Summary DETAIL Report DELTA Report UPDATE Report COMPARE Summary DELTA File UPDATE File This section contains the following topics: Required Summaries (see page 21) Optional Reports (see page 22) COMMAND Summary (see page 22) DETAIL Report (see page 23) DELTA Report (see page 25) UPDATE Report (see page 27) COMPARE Summary (see page 28) DELTA File (see page 29) UPDATE File (see page 31) Required Summaries Compare always writes the COMMAND and COMPARE summaries. The COMMAND summary lists the input commands, informational messages, and error messages (if any). The COMPARE summary gives match and difference statistics for the OLD and NEW files. Chapter 3: Outputs 21

22 Optional Reports Optional Reports The DETAIL, DELTA, and UPDATE reports are optional. The DETAIL report is a complete listing of all OLD and NEW file records that were matched, deleted, or inserted. When two records match, the record image from the OLD file is printed. The DELTA report is a listing of only the OLD and NEW file records that were deleted or inserted. When two files have a high incidence of matches, the DELTA report is much shorter than a DETAIL report. The UPDATE report lists the complete PAN#1 ++UPDATE stream needed to change the OLD file into the NEW file. A title in the first heading line of every page identifies all reports. The DELTA and UPDATE files are optional. The DELTA file identifies every record deleted from the OLD file or inserted in the NEW file. You can save it for archive and audit purposes. You can process the DELTA file to see how the OLD file was changed to the NEW file and vice versa. The UPDATE file contains the complete PAN#1 ++UPDATE stream needed to change the OLD file into the NEW file. It is suitable for direct input to PAN#1 for execution. The rest of this chapter gives detailed descriptions and examples of all the reports and output files. COMMAND Summary The COMMAND summary lists the input commands along with any error and informational messages. The input commands are listed exactly as read. If there are any command errors that prohibit Compare from executing, this is the only report written. If the input commands contain CA Panvalet control codes or access codes, the code values are replaced with Xs. The following example illustrates a sample COMMAND summary: COMPARE OUT(NO) REP(DET DEL UPD) LINE(56) OLD FIL(PAN) COL(1 72) M(EFFISAM) NEW FIL(SEQ) UPD S(++) L(12) M(ALS) TEMP(YES) 22 Compare Reference Guide

23 DETAIL Report DETAIL Report The DETAIL report is a complete listing of all OLD and NEW file records that were matched, deleted, or inserted. The OLD and NEW filenames are shown in the heading of every page. The DETAIL report is in a columnar format that includes OLD-NUM, NEW-NUM, CHANGE, and the record image. A scale line appears at the top and bottom of every page. The following describes the terms that appear on this report: OLD-NUM When the OLD and NEW files match, OLD-NUM is the relative record number of the matching OLD record. For deleted records, OLD-NUM is the relative record number of the deleted OLD record. For inserted records, OLD-NUM is blank. NEW-NUM When the OLD and NEW files match, NEW-NUM is the relative record number of the matching NEW record. For inserted records, NEW-NUM is the relative record number of the inserted NEW record. For deleted records, NEW-NUM is blank. CHANGE When the OLD and NEW files match, this field is blank. ///DELETE/// and ***INSERT*** mark deleted and inserted records, respectively. Record Image When the OLD and NEW files match, the record image field contains the corresponding OLD record image. For deleted records, this field contains the deleted OLD record image. For inserted records, the record image field contains the inserted NEW record image. For OLD and NEW files with record lengths greater than 100, up to 100 bytes of the first record is printed on the first line with the remaining detail wrapped to the next print line until the entire record is printed. If you want to truncate the report line at a specific location, data sets must be created using that LRECL. Unprintable characters appear as periods (.). A DETAIL report is useful when you need a complete hard copy audit of the similarities and differences between two files. Chapter 3: Outputs 23

24 DETAIL Report The following example shows a sample DETAIL report: COMPUTER ASSOCIATES LISLE DATA CENTER 12/12/00 DETAIL REPORT PAGE CA-PANVALET/COMPARE VERSION :34:44 1 OLD: LIBSYS.PANI.R143EBS.PANLIB NEW: LIBSYS.PANI.R143EBS.PANLIB USER78 - EXITMVS AT LEVEL 001 AS OF 12/12/00 USER78 - EXITVSE AT LEVEL 001 AS OF 12/12/00 OLD-NUM NEW-NUM CHANGE ///DELETE/// TITLE 'PVEXTLDR - SAMPLE EXIT LOADER' ***INSERT*** XLDR TITLE 'PVESTLDR - SAMPLE EXIT LOADER' ============ PRINT NOGEN ============ ********************************************************************** ============ * ============ * PROCEDURE: PVEXTLDR ============ * ============ * FUNCTION: FOR 'LOAD' FUNCTION - LOAD USER EXIT AND RETURN ADDRESS ///DELETE/// * FOR 'DELETE' FUNCTION - DELETE USER EXIT ***INSERT*** * FOR 'DELETE' FUNCTION - NO OPERATION: ***INSERT*** * DELETE NOT SUPPORTED BY VSE ============ * ============ * ENTRY : CALL PVEXTLDR,(FUNCTION,EXITID,ENVIRBLK,EXIT@) ============ * ============ * EXIT : RETURN CODE: ============ * ============ * 0 => SUCCESSFUL COMPLETION ============ * 8 => LOAD/DELETE ERROR ============ * ============ * PARAMETERS: ============ * ============ * NAME DECLARED AS DESCRIPTION ============ * ============ * FUNCTION CL8 'DELETE' OR 'LOAD' ============ * EXITID CL8 IDENTIFIER OF EXIT ============ * ENVIRBLK STRUCTURE ENVIRONMENT BLOCK ============ * EXIT@ A AREA TO RETURN ADDR OF EXIT LOADED ============ * ============ ********************************************************************** ============ EJECT ============ PVEXTLDR CSECT ============ STM R14.R12.12(R13) (* STORE CALLER'S REGS *) ============ LR R12.R15 (* BASE REG *) ============ USING PVEXTLDR.R ============ LR R11.R1 (* SAVE PARAMETER ADDRESS LIST *) ///DELETE/// GETMAIN R.LV=72 (* GET A REGISTER SAVE AREA *) ***INSERT*** * ***INSERT*** LA R0,GETVISL (* LENGTH OF SAVE AREA *) ***INSERT*** GETVIS ADDRESS=(1),LENGTH=(0) (* GET A REGISTER SAVE AREA *) ***INSERT*** LTR R15,R15 (* GETVIS SUCCESSFUL? *) ***INSERT*** BNZ ERRORVIS (* IF NOT, ERROR *) ***INSERT*** * ============ LR R14.R1 (* -> REGISTER SAVE AREA *) ///DELETE/// ST R13.4(R14) (* STANDARD *) ///DELETE/// ST R14.8(R13) (* MVS *) ///DELETE/// LR R13.R14 (* LINKAGE *) ***INSERT*** ST R13.4(R14) (* STANDARD *) ********************************************************************************************************************** 24 Compare Reference Guide

25 DELTA Report DELTA Report The DELTA report is a listing of all OLD and NEW file records that were deleted or inserted. The OLD and NEW file names are shown in the heading of every page. The DELTA report is in a columnar format that includes OLD-NUM, NEW-NUM, CHANGE, and the record image. A scale line appears at the top and bottom of every page. The following describes the terms that appear on this report: OLD-NUM When the OLD and NEW files match, OLD-NUM is the relative record number of the matching OLD record. For deleted records, OLD-NUM is the relative record number of the deleted OLD record. For inserted records, OLD-NUM is blank. NEW-NUM When the OLD and NEW files match, NEW-NUM is the relative record number of the matching NEW record. For inserted records, NEW-NUM is the relative record number of the inserted NEW record. For deleted records, NEW-NUM is blank. CHANGE When the OLD and NEW files match, this field contains ============. ///DELETE/// and ***INSERT*** mark deleted and inserted records, respectively. Record Image When the OLD and NEW files match, the record image field is blank. For deleted records, this field contains the deleted OLD record image. For inserted records, the record image contains the inserted NEW record image. For OLD and NEW files with record lengths greater than 100, up to 100 bytes of the first record is printed on the first line with the remaining detail wrapped to the next print line until the entire record is printed. If you want to truncate the report line at a specific location, data sets must be created using that LRECL. Unprintable characters appear as periods (.). Any block of two or more matching records is represented by only two report lines. The record numbers of the first and last records of the matching block are shown. A DELTA report is usually much shorter than a DETAIL report. It is useful when you need a hard copy audit of just the differences between two files. Chapter 3: Outputs 25

26 DELTA Report The following example shows a sample DELTA report: COMPUTER ASSOCIATES LISLE DATA CENTER 12/12/00 DELTA REPORT PAGE CA-PANVALET/COMPARE VERSION :34:44 1 OLD: LIBSYS.PANI.R143EBS.PANLIB NEW: LIBSYS.PANI.R143EBS.PANLIB USER78 - EXITMVS AT LEVEL 001 AS OF 12/12/00 USER78 - EXITVSE AT LEVEL 001 AS OF 12/12/00 OLD-NUM NEW-NUM CHANGE ///DELETE/// TITLE 'PVEXTLDR - SAMPLE EXIT LOADER' ***INSERT*** XLDR TITLE 'PVEXTLDR - SAMPLE EXIT LOADER' ============ ============ ///DELETE/// * FOR 'DELETE' FUNCTION - DELETE USER EXIT ***INSERT*** * FOR 'DELETE' FUNCTION - NO OPERATION: ***INSERT*** * DELETE NOT SUPPORTED BY VSE ============ ============ ///DELETE/// GETMAIN R.LV=72 (* GET A REGISTER SAVE AREA *) ***INSERT*** * ***INSERT*** LA R0,GETVISL (* LENGTH OF SAVE AREA *) ***INSERT*** GETVIS ADDRESS=(1),LENGTH=(0) (* GET A REGISTER SAVE AREA *) ***INSERT*** LTR R15,R15 (* GETVIS SUCCESSFUL? *) ***INSERT*** BNZ ERRORVIS (* IF NOT, ERROR *) ***INSERT*** * ============ ///DELETE/// ST R13.4(R14) (* STANDARD *) ///DELETE/// ST R14.8(R13) (* MVS *) ///DELETE/// LR R13.R14 (* LINKAGE *) ***INSERT*** ST R13.4(R14) (* STANDARD *) ***INSERT*** ST R14.8(R13) (* PANVALET *) ***INSERT*** LR R13.R14 (* SAVE AREA LINKAGE *) ***INSERT*** MVC O(4.R13).=C'XLDR' (* SAVE AREA ID *) ============ ============ ///DELETE/// CLC =CL8'LOAD'.FUNCTION (* IS THIS A LOAD? *) ///DELETE/// BNE CKDELETE (* NO - TRY DELETE *) ///DELETE/// LOAD EPLOC=EXITID (* YES - DO LOAD *) ///DELETE/// ST R0.EXIT@ (* SAVE EXIT@ *) ///DELETE/// B EXITOK ***INSERT*** CLC =CL8'LOAD'.FUNCTION (* IS THIS A LOAD? *) ***INSERT*** BNE CKDELETE (* NO - TRY DELETE *) ***INSERT*** LA R1.EXITID (* POINT TO EXIT PHASE NAME *) ***INSERT*** CDLOAD (1).RETPNF=YES (* YES - DO LOAD *) ***INSERT*** LTR R15.R15 (* WAS CDLOAD SUCCESSFUL? *) ***INSERT*** BNZ ERROR (* IF NOT, THEN ERROR *) ***INSERT*** ST R1.EXIT@ (* SAVE EXIT@ - ENTRY POINT *) ***INSERT*** B EXITOK (* SUCCESSFUL COMPLETION *) ============ ============ ///DELETE/// CLC =CL8'DELETE'.FUNCTION (* IS THIS A DELETE? *) ***INSERT*** CLC =CL8'DELETE'.FUNCTION (* IS THIS A DELETE? *) ============ ///DELETE/// DELETE EPLOC=EXITID (* YES - THEN DELETE IT *) ///DELETE/// LTR R15.R15 (* DELETE GO OK? *) ***INSERT*** * ********************************************************************************************************************* 26 Compare Reference Guide

27 UPDATE Report UPDATE Report The UPDATE report lists the complete PAN#1 ++UPDATE stream needed to change the OLD file into the NEW file. The OLD and NEW file names are shown in the heading of every page. A scale line appears at the top and bottom of every page. The UPDATE report always shows fixed length 80-byte records. If the OLD and NEW input files have a record size of less than 80, the inserted records are padded with blanks on the right. If the OLD and NEW input files have a record size of greater than 80, the inserted records are truncated on the right. When the OLD FILEORG is SEQUENTIAL and you do not supply an UPDATE command, the member and level fields of the UPDATE command contain $$$$$$$$$$ and ###, respectively. You can modify these dummy fields by a user exit or a manual process. The UPDATE report is useful for sight checking the UPDATE file contents before executing PAN#1. The UPDATE report is identical to the UPDATE file contents. For a complete description of the UPDATE stream, see the User Guide. Chapter 3: Outputs 27

28 COMPARE Summary The following example shows a sample UPDATE report: COMPUTER ASSOCIATES LISLE DATA CENTER 12/12/00 UPDATE REPORT PAGE CA-PANVALET/COMPARE VERSION :34:44 1 OLD: LIBSYS.PANI.R143EBS.PANLIB NEW: LIBSYS.PANI.R143EBS.PANLIB USER78 - EXITMVS AT LEVEL 001 AS OF 12/12/00 USER78 - EXITVSE AT LEVEL 001 AS OF 12/12/ UPDATE EXITMVS,001 ++D , XLDR TITLE 'PVEXTLDR - SAMPLE EXIT LOADER' D , * FOR 'DELETE' FUNCTION - NO OPERATION: * DELETE NOT SUPPORTED BY VSE D , * LA R0,GETVISL (* LENGTH OF SAVE AREA *) GETVIS ADDRESS=(1),LENGTH=(0) (* GET A REGISTER SAVE AREA *) LTR R15,R15 (* GETVIS SUCCESSFUL? *) BNZ ERRORVIS (* IF NOT, ERROR *) * D , ST R13,4(R14) (* STANDARD *) ST R14,8(R13) (* PANVALET *) LR R13,R14 (* SAVE AREA LINKAGE *) MVC 0(4,R13),=C'XLDR' (* SAVE AREA ID *) D , CLC =CL8'LOAD',FUNCTION (* IS THIS A LOAD? *) BNE CKDELETE (* NO - TRY DELETE *) LA R1,EXITID (* POINT TO EXIT PHASE NAME *) CDLOAD (1),RETPNF=YES (* YES - DO LOAD *) LTR R15,R15 (* WAS CDLOAD SUCCESSFUL? *) BNZ ERROR (* IF NOT, THEN ERROR *) ST R1,EXIT@ (* SAVE EXIT@ - ENTRY POINT *) B EXITOK (* SUCCESSFUL COMPLETION *) D , CLC =CL8'DELETE',FUNCTION (* IS THIS A DELETE? *) D , * * NO FUNCTION - NO PROGRAM DELETE FACILITY IN VSE * D , LR R1,R13 (* -> SAVE AREA TO BE FREED *) LA R0,GETVISL (* LENGTH TO BE FREED *) L R13,4(R13) (* -> CALLER'S REGISTER SAVEAREA *) FREEVIS ADDRESS=(1) (* FREE REGISTER SAVE AREA *) ERRORVIS L R14,12(R13) (* RESTORE CALLER'S *) LM R0,R12,20(R13) (* REGISTERS *) C LTORG DC OD'0'.C'********PVEXTLDR********' * GETVISL EQU 128 (* MINIMUM GETVIS LENGTH *) * ********************************************************************************* COMPARE Summary The COMPARE summary gives match and difference statistics for the OLD and NEW files. The OLD and NEW file names are shown in the heading. 28 Compare Reference Guide

29 DELTA File Ambiguous Matches The number of ambiguous matches encountered during the COMPARE process is listed. See the chapter "System Operation" for a detailed explanation of ambiguous matches. The following example shows a sample COMPARE summary: COMPUTER ASSOCIATES TRIAL INSTALLATION 12/12/00 COMPARE SUMMARY PAGE CA-PANVALET COMPARE VERSION :41:05 1 OLD: JONESAL.PANI.R11OVOWK.PANLIB NEW: JONESAL.RENTEFF.ASM USER53 - EFFISAM AT LEVEL 001 AS OF 03/31/00 USER MATCHED RECORDS OLD FILE DELETIONS NEW FILE INSERTIONS OLD FILE RECORDS NEW FILE RECORDS NO AMBIGUOUS MATCHES DELTA File The DELTA file identifies every record deleted from the OLD file or inserted in the NEW file. You can save it as part of a change log or audit trail facility. You can process the DELTA file to see how the OLD file changed to the NEW file and vice versa. Note: Compare might, on rare occasions, be unable to resolve some blocks of matching records, in which case it reports these records as deleted and inserted, rather than matched. This does not in any way compromise the integrity of the DELTA file. For this reason, however, Compare might not be suitable for some types of logging or auditing that require a high degree of granularity. For additional information on how Compare resolves inserts, deletes, and matches, see the chapter "System Operation." For z/os, the DELTA file can reside on any device supported by the sequential access method. For VSE, the DELTA file is a sequential disk file. The DELTA file consists of variable length records in the following format: Field Name Type Length Description RECORD PREFIX binary 4 Standard llbb field for variable records CHANGE character 1 D (for delete) - I (for insert) character 3 Reserved for future use Chapter 3: Outputs 29

30 DELTA File Field Name Type Length Description OLD-NUM binary 4 Old file record number NEW-NUM binary 4 New file record number character 4 Reserved for future use Record image character n Image of an old or new record (n is the old/new record length) The logical record length of the DELTA file is the logical record length of the OLD/NEW files, plus 20. The block size of the DELTA file is: Track capacity for CKD DASD devices Unblocked, CISIZE=16384 for FBA DASD devices for other devices The following describes the terms that appear on this report: CHANGE This field contains D (deleted record) or I (inserted record). OLD-NUM For deleted records, this is the relative record number of the deleted OLD record. For inserted records, this is the relative record number of the last OLD record that matched before this insertion. If there is no prior match, this field is zero. NEW-NUM For inserted records, this is the relative record number of the inserted NEW record. For deleted records, this is the relative record number of the last NEW record that matched before this deletion. If there is no prior match, this field is zero. Record Image For deleted records, this field contains the whole deleted OLD record image. For inserted records, this field contains the whole inserted NEW record image. 30 Compare Reference Guide

31 UPDATE File The following example shows two sample records from a DELTA file. The records are shown in three lines. The first line is the character representation of the file. The second and third lines show the hex value of each character. I RECORD # C000000I DCCDCC474FF FFFFFFFF A B D RECORD # C000000C000A0000DCCDDC474F FFFFFFFF F002C B UPDATE File The UPDATE file contains the complete PAN#1 ++UPDATE stream needed to change the OLD file into the NEW file. It is suitable for direct input to PAN#1 for execution. You can use the UPDATE file to update a current copy of source or save it as part of a change log or audit trail facility. For z/os, the UPDATE file contains fixed length 80-byte records. For VSE, the records are 81 bytes, with the first byte containing a stacker select character. It can reside on card, tape, or disk. For VSE, it is always unblocked. If the OLD and NEW input files have a record size of less than 80, the inserted records are padded with blanks on the right. If the OLD and NEW input files have a record size of greater than 80, the inserted records are truncated on the right. Note: The LRECL of the UPDATE file must match the total LRECL size of the files that are compared. The block size of the UPDATE file is: Unblocked for VSE Track capacity rounded down to a multiple of 80 for z/os DASD for other z/os devices When the OLD FILEORG is SEQ and you do not supply an UPDATE command, the member and level fields of the UPDATE command contain $$$$$$$$$$ and ###, respectively. These are dummy fields that you can modify with a user exit or a manual process. The UPDATE file does not contain the CA Panvalet commands CONTROL or ACCESS, or the keyword SEQxxy. For a complete description of the ++UPDATE stream, see the User Guide. Chapter 3: Outputs 31

32 UPDATE File The following example shows a sample UPDATE file: ++UPDATE EXITMVS,001 ++D , XLDR TITLE 'PVEXTLDR - SAMPLE EXIT LOADER' ++D , * FOR 'DELETE' FUNCTION - NO OPERATION: * DELETE NOT SUPPORTED BY VSE ++D , * LA R0,GETVISL (* LENGTH OF SAVE AREA *) GETVIS ADDRESS=(1),LENGTH=(0) (* GET A REGISTER SAVE AREA *) LTR R15,R15 (* GETVIS SUCCESSFUL? *) BNZ ERRORVIS (* IF NOT, ERROR *) * ++D , ST R13,4(R14) (* STANDARD *) ST R14,8(R13) (* PANVALET *) LR R13,R14 (* SAVE AREA LINKAGE *) MVC 0(4,R13),=C'XLDR' (* SAVE AREA ID *) ++D , CLC =CL8'LOAD',FUNCTION (* IS THIS A LOAD? *) BNE CKDELETE (* NO - TRY DELETE *) LA R1,EXITID (* POINT TO EXIT PHASE NAME *) CDLOAD (1),RETPNF=YES (* YES - DO LOAD *) LTR R15,R15 (* WAS CDLOAD SUCCESSFUL? *) BNZ ERROR (* IF NOT, THEN ERROR *) ST R1,EXIT@ (* SAVE EXIT@ - ENTRY POINT *) B EXITOK (* SUCCESSFUL COMPLETION *) ++D , CLC =CL8'DELETE',FUNCTION (* IS THIS A DELETE? *) ++D , * * NO FUNCTION - NO PROGRAM DELETE FACILITY IN VSE * ++D , LR R1,R13 (* -> SAVE AREA TO BE FREED *) LA R0,GETVISL (* LENGTH TO BE FREED *) L R13,4(R13) (* -> CALLER'S REGISTER SAVEAREA *) FREEVIS ADDRESS=(1) (* FREE REGISTER SAVE AREA *) ERRORVIS L R14,12(R13) (* RESTORE CALLER'S *) LM R0,R12,20(R13) (* REGISTERS *) ++C LTORG DC OD'0'.C'********PVEXTLDR********' * GETVISL EQU 128 (* MINIMUM GETVIS LENGTH *) * 32 Compare Reference Guide

33 Chapter 4: Commands Commands control how Compare makes its comparisons and what outputs to produce. There are four commands: COMPARE OLD NEW UPDATE The COMPARE command must be the first command in the input stream. It defines the output and reporting options. The OLD, NEW, and UPDATE commands can follow in any order. UPDATE defines the characteristics of the UPDATE file output. The OLD and NEW commands define the OLD and NEW input files. The input files can be CA Panvalet library members, sequential data sets, or other input provided by a user-written exit. You can specify each command only once. You can compare only one pair of files during each execution. The rest of this chapter gives a detailed description of the commands and their options. This section contains the following topics: COMPARE Command (see page 33) OLD Command (see page 35) NEW Command (see page 39) UPDATE Command (see page 40) COMPARE Command Use the COMPARE command to request the various reports and files that are available from the Compare function. Chapter 4: Commands 33

34 COMPARE Command Syntax COMPARE [LINES (lines per page)] [ { [DELTA] [UPDATE] } ] [OUTPUT ( { NO } ) ] [ { } ] [ { [DETAIL] [DELTA] [UPDATE] } ] [REPORT ( { NO } ) ] [ { } ] The COMPARE command is required, but all of its keywords are optional. It must be the first statement in the input stream. Installation defaults (see the appendix "Defaults") apply to those keywords that you do not supply. Keywords [LINES] [L] LINES is an optional keyword that indicates how many lines per page to print for the reports. (lines per page) Lines per page can be any numeric value from 20 through 99. The default is LINES(56), unless it has been changed for your installation. See the default table in the appendix "Defaults." [OUTPUT] [O] [OUT] OUTPUT is an optional keyword that requests the various file outputs available from the Compare function. When choosing from DELTA and UPDATE, you can specify either or both values. DELTA DEL DELTA writes a DELTA file for the Compare. You can save the DELTA file for audit or archive purposes. It is possible to interpret the DELTA file to see how the OLD file was changed to the NEW file or vice versa. Note: This file must have a DISP of NEW. UPDATE UPD UPDATE writes a CA Panvalet UPDATE file. The UPDATE file is the complete ++UPDATE stream required to modify the OLD file to look like the NEW file. It is suitable for direct input to PAN#1. 34 Compare Reference Guide

35 OLD Command NO NO instructs Compare not to write any output files. The default is OUTPUT(UPDATE) unless it has been changed for your installation. See the default table in the appendix "Defaults." [REPORT] [R] [REP] REPORT is an optional keyword that requests the various report formats from Compare. When supplied, you must give at least one or a combination of possible values. DETAIL DET DETAIL writes a DETAIL report. The DETAIL report is a complete listing that shows all of the differences between the OLD and NEW files. A single line shows matching OLD and NEW records. Differences are shown as deleted and inserted records. DELTA DEL DELTA writes a DELTA report. The DELTA report is a listing that shows the records that are different between the OLD and NEW files. The presence of a matched record or records is marked only by a single line or pair of lines. Differences are shown as deleted and inserted records. If the differences are few, a DELTA change report is much smaller than a DETAIL change report. UPDATE UPD NO UPDATE writes a CA Panvalet UPDATE report. The UPDATE report lists the complete ++UPDATE stream required to modify the OLD file to look like the NEW file. NO instructs Compare not to write the DETAIL, DELTA, or UPDATE reports. The COMMAND and COMPARE summaries are the only reports written. The default is REPORT(DELTA), unless it has been changed for your installation. See the default table in the appendix "Defaults." OLD Command The OLD command defines the OLD file input to the Compare function. Chapter 4: Commands 35

36 OLD Command Syntax OLD [ACCESS (CA-Panvalet access code)] [BLKSIZE (block size)] [COLUMN (begin column end column)] [CONTROL (CA-Panvalet control code)] VSE only [ {NO } ] [EXPAND ( {YES} ) ] [ { } ] [ {PANVALET } ] [FILEORG ( {SEQUENTIAL} ) ] [ { } ] [LEVEL (CA-Panvalet level number)] [MEMBER (CA-Panvalet member name)] [RECSIZE (record length)] VSE only The OLD command is optional. If you omit it, installation defaults are assumed for all its values. (See the default charts in the appendix "Defaults.") If you use the OLD command, it must appear after the COMPARE command. You can place it in any order with the other commands. For those keywords that have default values, the installation default is applied if you omit the keyword. Keywords [ACCESS] [A] ACCESS is an optional keyword that supplies a CA Panvalet library member access code. You can only specify it when FILEORG is PANVALET. It is only required for CA Panvalet members that are access controlled. (CA-Panvalet access code) Access code can be any numeric value in the range of 0 through If the same access code is needed for both the OLD and NEW inputs, it is only necessary to give the ACCESS keyword once on either the OLD or NEW command. There is no default for ACCESS. [BLKSIZE] [B] BLKSIZE is an optional keyword that specifies the block size of the file you want to compare. This operand is for VSE only. You can specify BLKSIZE only when FILEORG is SEQUENTIAL. 36 Compare Reference Guide

37 OLD Command (block size) Block size is the physical block size of the OLD file. It can be any numeric value from 1 up to the limit for the disk device. Block size must be an exact multiple of the RECSIZE value. If you omit BLKSIZE from either the OLD or NEW command, it uses the value specified on the other command. The default is BLKSIZE(80) unless it has been changed for your installation. [COLUMN] [COL] COLUMN is an optional keyword that determines which field to compare in the record. The field is expressed in terms of columns in the record. (begin column end column) Begin column defines the first column of the field you want to compare. Begin column must be a numeric value within the range of 1 through the logical record length. End column defines the last column of the field you want to compare. End column must be a numeric value within the range of 1 through the logical record length. End column must be greater than or equal to begin column. If you omit end column, the default is the logical record end. If the same choice is needed for both the OLD and NEW inputs, it is only necessary to give the COLUMN keyword once on either the OLD or NEW command. The CA Panvalet language type sets the default of COLUMN for CA Panvalet members. The columns compared are the actual positions stored in the library. The CA Panvalet options, NOFORMAT and TSO sequencing, do not affect the default columns. For more information about the effects of formatting, see the User Guide. See the column Actual Positions Stored in Library for the default columns. The COLUMN default for non-ca Panvalet input is COLUMN (1 logical record length). The width defined by begin column and end column must be equal between the OLD and NEW input files or Compare does not proceed. [CONTROL] [CON] CONTROL is an optional keyword that supplies a CA Panvalet library control code. You can specify CONTROL when FILEORG is PANVALET. It is only required for CA Panvalet libraries that are control protected. (CA-Panvalet control code) The control code can be any numeric value in the range of There is no default value for CONTROL. If the same control code is needed for both the OLD and NEW inputs, it is only necessary to give the CONTROL keyword once on either the OLD or NEW command. There is no default for CONTROL. Chapter 4: Commands 37