from The Rational Edge: Created by IBM Rational's Tom Milligan, this is a custom DLL which dbspan_report.pl relies on to access two specific IBM Rational ClearQuest functions: GetInstalledDbSets and GetInstalledMasterDbs.

Share:

IBM staff (dwinfo@us.ibm.com), Staff, IBM

This article brought to you by IBM staff.



15 September 2002

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:

regsvr32 DRIVE:\PATH\TO\THE\LIBRARY\CQDBsets.dll

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).

Notes

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)

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=2770
ArticleTitle=Appendix A: A Visual Basic DLL
publish-date=09152002