DB2

I took a walk down memory lane this evening. I thought I might as well bore you with the details.

One of my first forays into the open source world was to participate in the Linux Documentation Project (TLDP). At the time (circa 1999), I was working for IBM as a technical writer for DB2 database. IBM was releasing DB2 on the Linux platform, I was part of the pre-release testing team, and I had turned to TLDP to provide me with an introduction to the world of Linux as a total n00b. It was a godsend of information.

When DB2 was officially released on the Linux platform, it only officially supported a handful of distributions. Given the normal technical writing and release cycle, the officially supported versions of the distributions were woefully out of date in the official documentation. That, and much of the required installation and configuration information was either missing, or wrong. Don't lay any blame on the people involved; that was just the way that the release process (including translation into umpteen languages that were all available on release day) forced the end product to be. My focus was on application development, but I had to get test environments set up so I could ensure what I was writing actually worked (that's the way I roll as a tech writer). Of course, I chose an unsupported-by-DB2 but much more current distribution (Mandrake Linux 5.3 "Venus" I believe) simply because it would install on my hardware, when Red Hat 5.2 would not.

It struck me that my install experiences would help other DB2 users as well. I realized it would also give IBM a way around the barrier imposed by the restriction that the official documentation for a given release was published once per release - no updates. By contributing a DB2 HOWTO to TLDP, I would not only be able to provide documentation on the distributions that people were actually using, I would also be able to update the HOWTO as circumstances warranted. My manager supported the project, and helped me stickhandle some obstacles. The result, I believe, was beneficial all around; I contributed some code to TLDP to help improve the PDF output and helped mentor some TLDP n00bs; DB2 got some usable documentation when it really needed it; and I had the opportunity to learn a technical writing DTD that made sense (DocBook) and play with an impressive open-source publishing toolchain.

Over time, my friend and co-worker Ian Hakes picked up the ball and drove the next iteration of the DB2 HOWTO with my help. It has been over a year and a half since I left IBM, so I haven't paid any attention to the DB2 HOWTO. Recently, however, as I was playing around with an updated version of the DocBook toolchain, I discovered that Ian has released a brand new version of the DB2 HOWTO to cover installation of DB2 Express-C on various distributions. He included a touching tip of the hat to me, as well. What a swell guy!

On one hand, I'm not sure that TLDP has nearly as much of a mandate as it did eight years ago. There are scads of books, a handful of good magazines, blogs, wikis, and web sites all publishing information about Linux these days. On the other hand, there's something to be said for a corpus of documentation maintained and edited by volunteers who just want to get information into the hands of people who need help -- without compensation, without publicity, and generally without thanks.

So, given how much TLDP has helped me - thank you, TLDP volunteers. And thank you, Norm Walsh and the entire DocBook community, for providing an open-source publishing toolchain that starts with semantic XML and results in professional-looking documentation.

P.S. I made another commit to the DB2 HOWTO tonight - just balancing out an XML element that was missing to return the document to valid XML state. And let me tell you, it felt good!

I should have mentioned this before, but now that I noticed Chris Jones' post on the Underground PHP and Oracle Manual, I felt obliged to point out that one of the final fruits of my labours at IBM is now visible in the DB2 "Viper" Information Center -- a set of task-oriented documentation that describes how to do all of the things that you really need to do with DB2 and PHP, using either the ibm_db2 or PDO_ODBC modules.

By "task-oriented" I mean that, instead of documenting a set of objects and methods, the docs take the perspective of a developer and describe how to accomplish specific tasks (like "Connecting to a DB2 database from PDO" or "Calling a stored procedure" or "Retrieving multiple result sets"). I hope it works as both a good introduction to PHP development for DB2 users, and a good introduction to DB2 for PHP developers. And, of course, the same approach will work for Apache Derby databases as well.

I find it interesting that Oracle has positioned their PHP documentation as "underground", while IBM has chosen to incorporate their PHP documentation into their official set of DB2 documentation. Oracle gets the points for coolness, but IBM's approach will make the pointy-headed types a bit more comfortable.

1. Ok, one qualification: this is the DB2 Viper beta 1 documentation, so calling it "official" is a tad premature... but you get my drift. An example of the beta-ness of these docs is the table of contents entry for Executing XQuery expressions that remains tantalizingly empty... hmm, might it have anything to do with this CVS commit?
2. Second qualification: I can't take full credit for the PHP docs in the DB2 manual, because they weren't frozen by the time I left IBM. And the DB2-related reference documentation from php.net has been incorporated into the DB2 manual, which represents the efforts of php.net doc writers as well. But I'll certainly take credit for any errors

Update: Corrected bad XHTML (unescaped ampersand in URL). Bad Dan. And corrupted an intermediate version with garbage from another posting. Even worse.

The stable release of the ibm_db2 PECL extension for IBM DB2, Cloudscape, and Apache Derby brought a high performing, highly functional database connectivity alternative to Unified ODBC for PHP 4 and 5 users. However, in and of itself a database extension does not enable you to use the many PHP applications that you might want to use. You either have to add a specific driver for each application that implements its own portability layer (such as phpMyFAQ), or if the application relies on one of the standard database abstraction layers (PEAR DB, MDB2, or ADOdb), then a driver needs to be added to the corresponding database abstraction layer.

To date, the standard database abstraction layers have offered support for DB2 only through the Unified ODBC extension (and despite substantial overlap in names, MDB2 does not offer support for DB2 at all). Due to some limitations of the Unified ODBC extension, access to DB2 would seem slow and buggy -- and access to Apache Derby or Cloudscape would be frought with minefields, as Unified ODBC does not provide a way of differentiating between the databases to which you are connected and their corresponding features. The ibm_db2 extension offers the db2_server_info() function which can tell you whether you are connected to DB2 on Linux, DB2 on a zSeries machine, or an Apache Derby database, and let your application or database abstraction layer perform the appropriate workarounds.

Now, however, as part of Larry Menard's efforts to enable Gallery 2, an ADOdb driver built on top of the ibm_db2 extension will, in all probability, be made available as part of a future ADOdb release. Undoubtedly there will be further testing to do, and tweaks and performance optimizations in the future code--for example, differentiating between the capabilities of Apache Derby and DB2--but this is a huge first step! Thanks to Larry and the Gallery 2 team for making this contribution.

It is perhaps a sad reflection on my life that I'm using a personal blog to offer technical information about a product that I work on, rather than telling you about what I ate last night (spinach and goat cheese salad with a raspberry vinaigrette dressing, quinoa, and a rather tomatoey coq au vin), how the weather is (freezing rain and snow last night), or the last time we got together with friends (Peter and Deb came over last night for a lovely visit over wine and dinner).

Instead, here are a few gotchas for DB2 on Linux that might otherwise take you a few hours to figure out.

Shiny new DB2 for Linux (2.6 kernel) requires compat RPMs?

DB2 for Linux Version 8.2 (aka Version 8.1 FixPak 7) has been validated on distributions running both 2.4 and 2.6 Linux kernels. However, starting with FixPak 9 (aka Version 8.2.2, which has replaced Version 8.2 if you order a brand new copy of DB2 with physical media today), you have to choose a 2.4 or 2.6 kernel-specific version of DB2 on the x86 and x86-64 architectures.

If you're unlucky, you might find that once you install this newer version of DB2 meant for a shiny new distribution running a 2.6 Linux kernel, DB2 suddenly stops running and complains that it can't find the libstdc++.so.5 library. The reason is because the new versions of DB2 are built for compatibility with the first enterprise Linux distribution that offered the 2.6 kernel -- SLES 9 -- and guess what level of libstdc++ SLES 9 comes with? Yeah, you guessed right. And the reason the older versions of DB2 don't need libstdc++ is because they shipped with their own copy of the Intel C++ libraries.

Fun stuff eh? The moral of the story is: install your compat-libstdc++ libraries (or whatever they're called), and you won't get hurt when you upgrade DB2.

DB2 for Linux on POWER aka PPC64 aka pSeries: searching for libibmc++

Here's another missing library problem for which Google turned up no help... After installing DB2 for Linux on POWER, the user tried to run any DB2 command and received the following error message:

db2: error while loading shared libraries: libibmc++.so.1: 
  cannot open shared object file: No such file or directory

The problem occurs because DB2 for Linux on POWER is compiled against the IBM XL C++ libraries. This means that you have to install the IBM XL C/C++ Advanced Edition V7.0 for Linux Runtime Environment as described in a DB2 technote.