ompare

Extensible side-by-side compare across two and more disconnected IRIS / Cache environments.
This code has had a lot of useful exercise in production environments and has been re-packaged to share freely in the hope it will be useful to wider Cache / IRIS user community.

What makes ompare different from other code comparison utilities:

1. Compare configuration, data and code

• For example: Namespace mappings, Scheduled Tasks (The Useful columns), Productions, Lookup Tables

2. Compare side-by-side 2,5,10 or even 20 environments that are deployed on different isolated networks
3. See a summary of what actual thing is different ie: Parameter, Property, Method Code, Method Signature, XData, Lookup Table, SQL View, HL7 structure, Include definiton

• Then drill down into that thing summary to view the detail of that property, method signature, code or row difference.

4. See only real functional differences:

• Ignores the order of Methods in Classes or LineLabels in Routines
• Ignores comments in Classes or routines
• Ignores irrelevant whitespace or empty lines.
• Ignores routine legacy formatting differences
• Can ignore version control strings in code

5. Extensible - Please suggest or add custom new comparitors and reuse the existing reporting framework
6. Reporting as interactive HTML application and also Excel for sharing ofline difference summaries with customers.
7. Excel Workbook - Aggregate multiple reports as summary level worsheets into a downloadable Excel Workbook.
8. Privacy - It is an option to profile only signatures of code and config instead of actual implementation, in case code is commercially sensitive.

• When “signature only”, then drill-down to source link is not available in HTML reporting but other functionality can work.

9. Pre-Filtered extract - Exclude system or platform code from being profiled to focus only on your product or customizations.
10. Profile code once and configure multiple reports that slice or focus on specific areas of differences.
11. Profile 2, 10 or even 50 different namespaces accross an instance with a single task.
12. Recently used for porting between code Cache 2010.2 and IRIS 2019.3. The Class Source Handler has been reimplemented to replace with IRIS naming conventions and defaults, to focus on real code differences while excluding platform version default differences.

Target Cache / IRIS instance install

Minimum components to Import to the Cache / IRIS instances that require analysis
Excludes any reporting elements of code that are not required for profiling systems

For Cache convenience a single XML install is available here .

How to configure the Schedule to Profile code

Install in one namespace for example can be the USER namespace

Generates one Signature file and optionally one Source file for ALL namespaces selected for profile on an instance.

Example from IRIS Session

set tBASE=##class(ompare.Schedule).%New()
set tBASE.Environment="BASE"
set tBASE.Namespaces="OMPARE-BASE,INST-*,-INST-TEMP"
set tBASE.RunSourceHandlers=1
set tBASE.ExportToFile=1
set tBASE.ExportDirectory="C:\TMP\ompare\"
set tBASE.ExportCompression=0
set tBASE.EnableLogging=0
set tBASE.RetainExportDays=100
set tBASE.IncludeSourceCode=1
set tBASE.EnableLogging=0
set tBASE.RetainSigSrcHistoricVersions=-1
set tBASE.Debug=0
set tBASE.DiscardProfileData=1
set tBASE.RetainExportDays=0
set tSC1=tBASE.OnTask()

Server install

Includes all elements required for reporting.

For Cache / IRIS (preferred) convenience a single XML install is available here .

Copy the generated export files from target instances to the report server.
Then load signatures and code profiled into the report instance.

Example from IRIS Session

set tRPT=##class(ompare.Schedule).%New()
set tRPT.Environment="RPT"
set tRPT.Namespaces="USER"
set tRPT.RunSourceHandlers=0
set tRPT.ExportToFile=0
set tRPT.ImportDirectory="/tmp/SourceCompare/Import/"
set tRPT.ImportFromFile=1
set tRPT.ReImportUpdatedFiles=1
set tRPT.DeleteImportedFiles=1
set tRPT.RetainExportDays=2
set tRPT.IncludeSourceCode=1
set tRPT.RetainSigSrcHistoricVersions=-1
set tRPT.OverwriteSourceOnReLoad=1
set tSC1=tRPT.OnTask()

SQL extract Configuration for comparing CPF, Scheduled Tasks, Integration Productions

Please see detailed notes Reporting differences via SQL

Reporting

After importing code signatures and code views from another system you can configure one or reports to compare and examine differences with flexible options.
Navigate to page http://[reportServer]:[webport]/csp/user/ompare.Report.Main.cls

New settings for a report:

Select a source namespace in the “From Environment” and then namespaces from other environments to compare.

Classes, routines or compare just everything

After saving first time there will be a slew of options for what subset of reporting you actually require.
There is a Save button at both the top and the bottom of the page.
This makes it possible to select only what you need. For example a report that only looks at just class differences.
This is useful down the line, for example if you want to generate an Excel report summary with Class Differences in one tab and then Routine differences in a second seperate Tab.
You can choose to report on all aspect of classes or perhaps only on Properties and Method signatures (Useful for deployed code or third party libraries).

Extra, Missing, Difference, Same

Within this there are options to look at extra, missing, differences or same in each category and sub-category.
Generally selecting differences, extra plus missing checkboxes is a good starting configuration.

Exclude, Include

In some report configuration sections you will see textareas for “exclude” and “include”. These filter by name of the resource you need. For example if you had a project or application area with specific classes and routine names, you can configure the report to only include these specific items for comparison. Wild card suffix supported. You may find that profiling has imported a load of platform or intergation classes on one of the target instances. Using Exclude is where you can easily filter out all that noise instead of having to reun a profile in a slight different configuration.

Exclude and Include are complementary. For example: The coarse Exclude pattern “Tool.*” with include pattern “Tool.ProjectA.*”

This would give:

This form is extensible by adding new profile and report types.

HTML Report View

The HTML report view gives a side by side difference of characteristics selected in the report definition for each target environment.
Simply select View in list of Reports or select View within Report Edit mode.
There are in-page links to quickly jump to a given section for long reports. Also At the start of each section is an in-page link back to the top of the report, to speed up navigation.
Each section has an Item counter, useful for discussion of differences in a team call.
The “From Environment” column is useful in the case of class dependencies where we display the names of sub-classes that may be affected / impacted.
Subsequent columns are for each logical target environment where differences exist. Reminder you can have 2 or 20 target environments to compare against, and the reporting will still be expected to be quick.
Extra class means a whole resource is additional in a target environment (TEST) than compared with From Environment (BASE).
Missing class means a whole resource is missing in a target environment (TEST) than compared with From Environment (BASE).
For sub-types have their own descreet section. This is followed by a bulleted list of sub-type name. For example names of properties or Method Signature or Method Implementation with actual difference.

In brackets in there is a hyperlink (Different, Extra, Missing), this will launch drill down source code difference view
This uses functionality from the CodeMirror project to highlight code differences and also collapse sections of code that are the same to understand differences in large methods or routine LineLabels.

Examples of drill down code diff

Method signature:

Method implementation:

Global Mapping of Namespace difference

Comment collaberation

Activated to be visible in reports by the option “Show Comments” in report defintions.
When the detail of code difference is viewed there is an option to add a comment.

When the HTML report summary view is refreshed this comment is displayed against that specific code item.

Excel Report

To create a new Summary Excel sharable Report select New Excel Workbook.
Fill out the text items.
New Report Tabs are added by selecting from the worksheets select list.
To delete existing Report Tabs click the X in the Report column. (NB: This doesn’t destroy the original source report).

When there are multiple tabs already added their order can be rearranged by toggling the up-n-down buttons on the left.
A lot more conventient than forcing to be added in correct order.

The Excel Report is downloaded from the List Excel Workbooks view.
Click the link and select save. Open the Excel document to review. Resave as binary Excel if required.

A workbook has a coversheet (first tab) based on Excel Report settings given.

Examples of Report Tab. Demonstrates:

• Rows are pre-expanded to to view contents easily.
• There are no links to differences, only a summary with counts of differences encountered