There is one significant architectural difference between this article's sample application, dbspan_report.pl and the CAL sample application. Specifically, dbspan_report.pl uses a Visual Basic DLL to do some of its work. To create a solution that was as applicable to as many implementations of Perl as possible, I created a custom DLL which dbspan_report.pl relies on to access two specific Rational ClearQuest functions: GetInstalledDbSets and GetInstalledMasterDbs.
The "Why?" and "How?" of this Visual Basic DLL is somewhat technical, so you can skim over the following material if you are not overly curious and you don't think your situation will require these functions. The one important thing to note, however, is that the flexibility of Perl4 and the Rational ClearQuest API allow for many possible solutions to any problem, and in this case that flexibility allowed me to create a solution for a wide range of Perl environments.
First let's look at why the Visual Basic DLL is needed. There are many different "flavors" of Perl available, including one that is free from ActiveState5, and another called CQPerl, which is installed automatically along with Rational ClearQuest. In addition, Perl allows -- and encourages -- the use of modules as standardized, reusable software components. Organizations like Comprehensive Perl Archive Network6 (CPAN) maintain large collections of Perl software, documentation, and modules, including the Win32 modules that enable Perl scripts to interface with Windows systems and applications.
The GetInstalledDbSets and GetInstalledMasterDbs functions are designed for CQPerl only, and are not compatible with all third-party versions of Perl. Because I wanted to create a solution that would work with as many versions of Perl and Win32 modules as possible, I opted for a different approach. I decided to use the GetInstalledMasters method of the ClearQuest API, which is available only from Visual Basic --not Perl. In Visual Basic, the functionality of the two distinct methods GetInstalledDbSets and GetInstalledMasterDbs is represented with a single overloaded method. The solution was to create a very simple Visual Basic DLL that called GetInstalledMasters and returned the results to a Perl application.
Fortunately, explaining how to create the DLL is easier than explaining why it is needed. Using Microsoft Visual Studio, I started a new DLL project and named it CQDBSets.DLL. The DLL only implements two functions: GetInstalledDbSets and GetInstalledMasterDbs; and each function simply calls GetInstalledMasters and returns. The following Visual Basic source code did the trick:
' ' This function mimics the "GetInstalledDbSets" ClearQuest CQPerl API method ' It takes a valid ClearQuest Session Object as a parameter ' Public Function GetInstalledDbSets(aSession As ClearQuestOleServer.Session) _ As Variant Dim DBSets As Variant Dim Masters As Variant ' ' Use the COM GetInstalledMasters method to get the desired data ' and return the appropriate value. Note that GetInstalledMasters ' returns values for both of the parameters, but in this function ' we are only interested the DBSets parameter. ' Call aSession.GetInstalledMasters(DBSets, Masters) GetInstalledDbSets = DBSets End Function ' ' This function mimics the "GetInstalledMaseterDbs" ClearQuest CQPerl API method ' It takes a valid ClearQuest Session Object as a parameter ' Public Function GetInstalledMasterDbs(aSession As ClearQuestOleServer.Session) _ As Variant Dim DBSets As Variant Dim Masters As Variant ' ' Use the COM GetInstalledMasters method to get the desired data ' and return the appropriate value. . Note that GetInstalledMasters ' returns values for both of the parameters, but in this function ' we are only interested the Masters parameter. ' Call aSession.GetInstalledMasters(DBSets, Masters) GetInstalledMasterDbs = Masters End Function
To use the compiled DLL, it must be registered with Windows as a COM object so that it can be accessed by the dbspan_report.pl Perl application. This is easily accomplished from a Windows console, by typing:
Then, to encapsulate this functionality with a layer of abstraction, I created a separate Perl script, dbset_api.pl, whose sole purpose is to instantiate the DLL, interact with it as required to mimic the functionality of GetInstalledDbSets and GetInstalledMasterDbs, and return the appropriate values to the calling routine in a format easily manipulated in Perl -- namely a list.
To download a compiled version of this DLL along with the Perl source code for dbset_api.pl and dbspan_report.pl, click here (.zip 12K).
4 As Larry Wall, Perl's creator, says: "Perl is designed to make the easy jobs easy and the hard jobs possible.""
5 The author has no relationship with ActiveState. ActivePerl is available at www.activestate.com.
6 http://www.cpan.org/ (note: Rational Software has no relationship with this site)