Detect Host OS and Client Version Levels within Client Software

March 12, 2008 Michael Sansoterra

Sometimes when coding a Windows client/server application it can be a bit pesky dealing with the problem of knowing everything about the operating environment. In the System i and AS/400 world, factors like the host i5/OS version and release, and the iSeries Access (now called System i Access) version and fix pack level, can determine whether or not your software can run correctly. In the “IBM AS/400 iSeries Access for Windows ActiveX Object” library, IBM has given developers the tools to programmatically detect this information and thereby circumvent potential problems for environments that are not at the correct software level.

Using Visual Basic for Applications (VBA) code, I’ll quickly demonstrate how to detect host OS and iSeries access version levels. In your VBA environment, you’ll need to add a reference to the “IBM AS/400 iSeries Access for Windows ActiveX Object” library in your project. For MS Office products, this is usually done under Tools→References.

Say you have a client/server application that creates a table function to perform a certain function. However, if the host OS level is below V5R2, the function will fail because V5R2 was the first release to allow the creation of table functions. In this scenario, it would be better to inform the user that an OS upgrade is required than to show a cryptic error thrown due to an unsupported SQL statement.

Dim host As cwbx.AS400System
Dim strHostOS As String
Set host = New cwbx.AS400System
host.Define "MYHOSTNAME"
strHostOS = "V" + CStr(host.HostVersion) + "R" + _
            CStr(host.HostRelease)
If strHostOS < "V5R2" Then
    MsgBox "This Host Requires a Minimum of V5R2 to Run"
    Exit Sub
End If

Sample 1 – Code to check the release level of the host i5/OS version.

The “AS400System” object provides HostVersion and HostRelease properties that indicate the host OS level. The Define method is used to register the name of the host System i or AS/400 to be used. This system must be registered within iSeries Navigator or an error will be thrown. See “Programmatically Retrieve Defined System i Names” to learn how to query the default system name or to retrieve a list of registered iSeries Navigator system names programmatically.

There is one caveat: the code in Sample 1 doesn’t connect to the host, it just uses the value stored within iSeries Navigator. So in the cases where the host OS was just upgraded (but the client hasn’t yet connected) or when the host has never been used, these properties can return an erroneous version. If necessary, connect to your host system before querying these values.

Now let’s look at how to examine the client version. I recently wrote a complex spreadsheet application for a client that had many users. The spreadsheet required the usage of the iSeries Access ODBC driver. However, this application worked for some users but generated an error for many others. It turns out that many of these users simply had older iSeries access installations that needed to be upgraded before the ODBC application would work. Adding code to verify a minimum client level before allowing the application to run is a good way to alert the user to the problem without generating ugly ODBC error messages!

Here is another sample code that makes use of the IBM-supplied ClientInfo object. In particular, the ClientVersion and ClientRelease properties are concatenated to form the familiar VxRy level. Further, the ClientFixLevel property can be used to verify that a specific service pack level is present.

Dim client As cwbx.ClientInfo
Set client = New cwbx.ClientInfo
Dim strClientVersion As String, strClientFixPack As String
strClientVersion = "V" + CStr(client.ClientVersion) + "R" +
 CStr(client.ClientRelease)
strClientFixLevel = client.ClientFixLevel
If strClientVersion < "V5R3" Or _
(strClientVersion = "V5R3" And strClientFixLevel < "SI21917") Then
    MsgBox "iSeries Access Client must be at a minimum level " & _
    "of V5R3 with Fix Pack SI21917 Installed. " & vbCrLf & _
    "Please Upgrade Client before using this Software"
    Exit Sub
End If

Sample 2 – Code to check the iSeries Access release level and fix pack level.

Use IBM’s APIs to verify that minimum system requirements are met before allowing a client/server app to run. In this world of unknown host OS versions and back-leveled client software, doing a little coding up front will go a long way toward avoiding unnecessary troubleshooting.

Michael Sansoterra is a programmer/analyst for i3 Business Solutions, an IT services firm based in Grand Rapids, Michigan. Click here to contact Michael Sansoterra by email.

Programmatically Retrieve Defined System i Names

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot