Updating a .NET Application to Use the V6R1/V7R1 Data Provider

Resolving The Problem

Important Note: This document discusses Client Access for Microsoft Windows 95 and Windows NT, Client Access Express, IBM iSeries Access, and IBM System i Access products. These names essentially refer to the same product; however, the functionality and name changed over the last several releases. For the purposes of this document, the terms Client Access, Client Access Express, iSeries Access, and System i Access can be used interchangeably. Where a difference is important, the version of the product is used to identify the differences.

Incompatible Changes

In V6R1, the System i Access .NET data provider underwent major changes. These changes caused some incompatibilities with the previous version, requiring a change in the AssemblyVersion property of the provider from 10.0.0.0 to 12.0.0.0. The following is a list of the major incompatible changes from previous versions of the provider:

o	The .NET 2.0 Framework (or later) is required. Many of the provider classes have been rewritten to extend the generic provider classes defined in the System.Data.Common namespace.
o	The method iDB2DataReader.GetSchemaTable returns a DataTable containing information about the columns in the result set. Previous versions of the provider returned key information in a column named IsKeyColumn. This column has been renamed IsKey in V6R1.
o	The column information returned by the iDB2DataReader class has been changed in some cases to be more consistent in type reporting.
o	Null parameter handling has changed. Previously, null/uninitialized parameters were reported as DbType=iDB2VarGraphic, Value=iDB2VarGraphic.Null. In V6R1 these parameters are reported as DbType=Object, Value=null.

An application that was built targeting a version of the provider prior to V6R1 can be updated to use the V6R1 provider as long as two conditions are met:

o	The target machine must have the .NET 2.0 Framework installed.
o	The application must not depend on any of the old behavior that was changed in the list above

Updating the Application

If it has been determined that an application can use the V6R1/V7R1 provider, there are two possible options to update the application to use the provider.

Option 1: Recompile the program.

If possible, the application can be recompiled with a compiler that targets the .NET 2.0 Framework on a machine with the V6R1/V7R1 provider installed. After updating the program references in the development environment, recompile the program. No further steps should be necessary.

Option 2: Redirect requests to the new provider assembly.

If it is not possible to recompile the application, a configuration file can be created or edited to redirect all requests for the .NET provider to the current assembly. There are multiple configuration files that can be used to redirect .NET applications to locate the V6R1 assembly.

o	machine.config - This file can be used to control behavior of .NET applications at a machine level.
o	web.config - This file is used to control the behavior of an ASP.NET web application.
o	Application configuration file - This file is used to change the behavior of an individual .NET application.

This document shows an example of what would be found in an application configuration file. The actual name of the configuration file depends on the name of the application. For example, if the application is named MyProgram.exe, then create (if it does not exist) a file named MyProgram.exe.config. The contents of the file should be as follows:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="IBM.Data.DB2.iSeries" publicKeyToken="9cdb2ebfb1f93a26"/>
        <bindingRedirect oldVersion="10.0.0.0" newVersion="12.0.0.0"/>
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

You should save the file, being sure to select the UTF-8 encoding to match what is listed in the configuration text. The file should be located in the same directory as the application file. The next time the program is run, it should implement the redirect request in the configuration file.

Notes:

1. This sample shows how to create an application configuration file. If using the machine.config or web.config files to control redirect behavior, consult Microsoft documentation for the appropriate process. If editing an existing configuration file, it is strongly recommended that a backup copy be created before making any changes. Also, if using the "ClickOnce" deployment process, the application reference added to the Windows Start menu is not an actual shortcut, and the application configuration file may not be located. You must create a shortcut to the executable, or run directly from the program directory for the desired behavior.

2. This process will not work for directing from the V6R1/V7R1 assembly to the V5R3/V5R4 assembly.