Abstract - A Continuus client has a release differences report that is generated from LCR (Locomotive Change Requests) in a Microsoft Access database and software changes in Visual SourceSafe. Upon changeover to Telelogic CM/Synergy and ChangeSynergy, they require the same sorts of reports to be generated.
While it would be nice to have them use ChangeSynergy for this reporting capability, there is currently no way to compare two baseline releases for differences in change requests, tasks and objects. In fact, we originally thought it would be a royal bear to produce this sort of report in CM without a lot of extra coding. What no-one knew however, was that Nick Crossley had written this sort of neat baseline comparison tool as an Accent library and that said library had been distributed in the extras\contrib folder of the CM installation disks since who knows when (pre V4 even?)!!
This neat little trick got us mostly off the hook, but the client also wanted something that could be easily tweaked into a number of output formats including html displayable on a netscape browser in Unix land. Rather than write brute force html embedded into Perl scripts, Bill had an idea to try out XML and XSL stylesheets. The querying and generation would be done using a CM interface and Perl, but it would be a stylesheet translater that would convert the intermediate XML format into HTML, comma separated value or whatever the client might desire. The entire effort took only a day or two of work, and it inspired Ed to try his hand at writing a stylesheet himself. He wanted to document the CS 3.5 lifecycle customization that he had done for one of his clients, Systems Excellence. In fact, this method is worth learning for your own mischief, especially since future versions of CS will move more to XML concepts.
Table of Contents
hlquery Accent Library - Nick originally wrote his hlquery library to document builds of Continuus itself at Irvine. Being in control of what went on the CD-ROM's and thinking that its goodies would be something of interest to everything, Nick has put hlquery on every release since time began (yea verily, even 3.x or at least 4.0). However since no-one bothers to look in extras\contrib for anything useful, sales and services alike have hemmed and hawed every time a client asks for a baseline differences function that can list the tasks and change requests. hlquery.a has this function which can be set up as the simple command ccm changes.
hlquery can be installed simply by copying the hlquery.a library to your database's lib directory and then including the accompanying ccminit commands in your global or personal ccminit scripts. A more elegant approach would be to unpack a model database and officially add it as follows:
Now you will be able to do model installs and have hlquery and its commands automatically installed. You might not want to define some of the dangerous commands that can mess with the archiving methods and do other esoteric things. The more adventerous who know what a "modsup" model is all about, might even consider setting one up so that the hlquery library can be built from source along with the rest of the model libraries.
The changes command is documented in Nick's readme file as follows:
ccm changes [-objects] [-tasks] [-problems] [-mtasks] [-mprobs] oldproject newproject
Find all objects changed, or tasks and/or problems fixed, between two given releases. The -objects, -tasks and -problems flags determine which of these categories are shown; you may use any combination of these flags.
The -mtasks flag will produce a warning for each interesting changed object that does not have a related task. Objects deemed "not interesting" are projects, products, rejected and checkpointed CVs.
The -mprobs flag will produce a warning for each task that does not have a related problem, except for personal tasks.
The default output shows the full name for objects, and the number and synopsis for tasks and problems.
Nick doesn't specifically mention it, but you can use a -format option just like you would do with ccm query. Bill put that to use in his perl script that generates a release differences report. Other very interesting commands in hlquery include:
Release Differences Perl Script - The following Perl Script was written to use the ccm changes command to produce one of the reports requested by GM EMD. It is passed two project versions and produces an XML file such as the following sample output that can be validated by this Document Template. Those of you clicking on those links with Microsoft Internet Explorer browsers may be pleasantly surprised by the formatting. Since version 4.0 of IE, Microsoft has included a non-validating xml parser called msxml which can also be set up as a command line driven utility by downloading the msxml utility from msdn. If you try this on a CS 3.5 lifecycle process file such as the cruser_process, you will get a nicely formatted parse tree instead of the jumbled together trainwreck that you would get in a text editor.
Microsoft isn't the only kid on the block when it comes to XML technology and their implementation of XSL, the XML Stylesheet Language, started with an early rev that quickly changed. Sun and the Apache group both have xml/xsl distributions. You can check out the official XML web-site for links to other resources.
The XML output from the Perl script is a format independent collection of data. Because of the way that the script runs, the data for each change request is displayed first, followed by a summary dump at the end of the run for total counts, averages, date/time etc. The report wants to display the summary first followed by the CR data. If we used the old fashioned way, we would have had to store the CR data in an array in Perl to gather the summary counts and then walk the array at the end to display the CR records. The formatting would also have had to be built into the Perl script to produce HTML, CSV or whatever was needed. This makes the resulting Perl script more complicated than it needs to be and more prone to need revisions as new formatting requirements arose. Since the customer wants to be able to change the formats on their own, they would need to supply someone conversant in both Perl and the relevant formatting language.
By using XML/XSL, we now split the report document into three pieces: the data itself represented by the xml file, a template for validating that the data is consistent and valid represented by the DTD file, and one or more style templates used to format the data represented by the XSL stylesheet files. This sample stylesheet file converts the data from the sample xml report into HTML. Since the stylesheet is itself an XML document file, the msxml and other xml tools are able to parse and display it. Since HTML and XML/XSL are subsets of SGML, it is easy to embed xsl commands into an html template. Layout programs like Macromedia DreamWeaver and Visual Interdev are able to directly edit the stylesheet file and can be used to tweak the layouts visually. Now instead of a Perl/HTML jockey, the customer is able to supply only a Web person knowledgeable in HTML and layout programs to tweak the report formats.
Sun XSLT Stylesheet Translator -
This is an unfinished document. I had intended it as a primer to introduce the former Continuus field technical sales and consulting staff to the new world of XML, but I had limited time to work on it while consulting on-site at the client. I left Telelogic before I could get back to it.