Use the WinMerge graphical compare and merge utility to aid with the synchronization of RPG and other i/OS source members.
One of the dreaded drudgeries of RPG programming is retrofitting custom modifications to application software. You know the sordid story. You've made modifications to a vendor application for the past several years, and now it's time to upgrade said software. Welcome to the challenge of putting all your changes into a new set of source code. You can enlist the help of good ol' SEU option 54 to compare two source members and generate an ugly printout of the differences. Or you can use a graphical, user-friendly tool like WinMerge!
WinMerge is a free open-source utility available at http://winmerge.org/. It is similar to the SEU option 54 in that it tries to "align" the similarities between two source members and highlight differences between them. Plus, WinMerge has the following great features:
- The ability to show files side by side so that the differences can be viewed easily
- A toolbar that allows you to quickly navigate to the next or previous difference in a source member and merge differing lines of source between the files
- A "Location Pane" (on the left) that gives a quick overview of where the differences lie among two files (handy for large files)
- A "Diff Pane" (at the bottom) that shows the differences between the current source lines
- Highlighting for specific portions of the line that are changed, such as a variable length or a keyword on an RPG D-spec
Figure 1: This picture shows WinMerge comparing two RPG files. (Click images to enlarge.)
I've used WinMerge frequently over the past year to compare SQL Server T-SQL and C# source files. I recently decided to try it for IBM i projects as well. It's not limited to the RPG programming language, so any source members are theoretically "alignable" with WinMerge, including traditional programming languages (C, C++, COBOL, Java, CL, and DB2 SQL files) as well as specialized text files (HTML, XML, display files, printer files, workstation customizing objects, and sort sequence tables).
The real power of WinMerge is its ability to let the user quickly review and merge changes with the click of a mouse. I never liked relying on modification markers or source line date stamps when comparing source file members. Inevitably, some markers would be forgotten, and sometimes dates would be erased. WinMerge shows a "bird's eye" view of all differences in the "location pane" and allows you to navigate among differences with the click of a button.
When you have to fix something manually, the original code file is right there to review. If the changes in the original file (whether an insert, update, or delete) can be brought over to the new file "as is," a click of a button will do it for you. That makes life easy!
To use WinMerge, simply download it, install it, and run it. You'll be prompted to select two files to compare and voila! You're on your way to synchronization paradise.
Editing Stream Files on the Integrated File System (IFS)
When working on the IBM i/OS, it is now common to store source files on a local PC or the IFS. In the case of IFS storage, you can reference the file members to open using a mapped drive or using a fully qualified UNC name.
If you need help understanding how to make an IBM i resource such as an IFS folder available as a mapped drive, see the references at the end of this tip.
Directly Editing Source File Members
Many shops still store legacy code in source file members. Fortunately, the IFS allows access to these members via a special file system called QSYS.LIB. Using NetServer, I was able to map a drive on my Windows machine directly to a source library using the following steps:
- Create a share in NetServer using the i5/OS NetServer configuration utility in System i Navigator (found under Network>Servers>TCP/IP). The path name for the share should map to /QSYS.LIB/MYLIB.LIB where MYLIB is the name of your library containing the source files. I typically name my share the same as my library.
- Within the Text Conversion tab for the share, check the Allow Text File Conversion checkbox, enter a file extension type of mbr and click Add. This option will take care of the EBCDIC-ASCII character conversion issues inherent when working on a source file.
Figure 2: Here's the window for text conversion.
- Once you have a share mapped, you can map a drive directly to your i/OS library. Bear in mind that you can only edit objects within source files that have a suffix of mbr (the standard suffix for source file members.)
- The ability to edit source members from mapped drives opens up the possibility of synchronizing source code between different libraries or even different systems.
Noteworthy Items for the "i"
- When saving a file, WinMerge normally makes a backup copy with an appended extension of .bak. However, because of the naming limitations of source file members (10 characters), WinMerge can't create this backup file when editing in the QSYS.LIB file system.
- Remember that member names are case-sensitive (all uppercase). For example, if you have drive S: mapped to \\iSeries\MYLIB, your file name will need to look something like this: S:\QRPGLESRC.FILE\MYRPGPGM.MBR.
- When saving a member directly to a source file, the member description is removed.
- RPG code generated by tools such as Synon often create a large volume of dynamically named variables and subroutines. These variable names can change between source revisions. When this happens, the before and after pictures of the source code cannot always be aligned correctly, which detracts from the tool's ability to accurately show what has changed.
- Fixed-length source members can be a pain to work with! If you accidentally insert extraneous spaces at the end of a line, WinMerge will not be able to save. Further, WinMerge (through no fault of its own) doesn't return a clear message as to why it couldn't save the changed member.
- Sometimes major source changes render the compare and merge utility ineffective. A good example of this occurs when fixed-format RPG is converted to free-form. The comparison utility will not do a good job of comparing C specs between these two versions.
- Generally, I try to keep source changes minimal to maximize WinMerge's ability to align the members appropriately. However, this is not always possible.
- For many file types, I've found that it's best to turn on the Ignore Whitespace option. Otherwise, there are just too many superfluous differences reported.
WinMerge isn't the only tool available in this arena. If you find it doesn't meet your needs, seek out another. WDSc and RDi developers will be happy to know that SoftLanding offers a free plug-in to aid IBM i developers with the compare and merge process as well.
The bottom line is that RPG developers no longer need to suffer when retrofitting legacy code. The cavalry of mature file comparison tools is here!
as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7,