4/7/2002: This is a preliminary document. That doesn't mean it's not right. It's just not finished. I just installed and got db2 running late Friday afternoon. These are the steps I followed.

Introduction
This document contains my experiences installing IBM DB2 on Linux Redhat 7.2 with php 4.1.2 and Apache 1.3.23. The php configuration to be described will be a base configuration that contains only IBM DB2, and no other php options, although you could add more options. This choice of only including IBM DB2 in the configuration will simplify any compilation and configuration errors.

I had a heck of a time searching for the port the AS/400 uses for DB2. The AS/400 uses port 446, and is listed in section 9.3 of DB2 Version 7.1 for Linux HOWTO. There are several steps that must also be taken on the AS/400 to allow remote connections. These were already setup on my AS/400 and are described in the prior document. There's an item in the instructions at the correct place to remind you to configure the AS/400.

Purpose and focus
This document is a compilation from three other documents that describe the installation of IBM DB2 on Linux and php. I found none of those documents described the actual configuration and installation of IBM DB2 for access to an IBM AS/400. These other documents are referenced here as
Getting IBM DB2/Apache 1x/PHP4.x to work together on Linux
DB2 Version 7.1 for Linux HOWTO
Connecting PHP Applications to IBM DB2 Univeral Database

These instructions will describe the particulars of setting up an Apache 1.3.x webserver with php, and IBM DB2 on Linux. The instructions are for a shared-object build of Apache and php. They will not describe in detail the installation of those products. The focus of this document is on getting php to access a remote IBM DB2 database on an AS/400 and should be used as an addendum to the many fine documents written on installing Apache and php.

Other sites worth mentioning are the php and Apache sites so you can get php and Apache help. The official php site is http://www.php.net/. The official Apache webserver site is http://www.apache.org/. Apache version 2.0 is still an experimental product, so don't try any of this with Apache 2.0 unless your willing to struggle.

It's worth mentioning early that the php support of IBM DB2 is through the unified ODBC (Open DataBase Connectivity) functions. When you compile php with the option --with-IBM-DB2=/path/to/db2instance, you will actually be enabling the unified ODBC functionality of php. You won't need an ODBC driver or driver manager, and as php will be using the IBM DB2 Connect Client.

1. Obtain Apache and php
   In order to use IBM DB2 Personal Developer's Edition Version 7.2 with Apache and php, you will first need to have Apache and php. If you already have Apache and php installed, then go to the next step which is Installing IBM DB2. If not, then you will need to get and install Apache from the Apache website. When you configure Apache, make sure you activate module mod_so:
   (I use --enable-shared=max but --activate-module=mod_so should work just fine). Get the latest stable php from http://www.php.net/. Do not install php yet, since we're going to build the DSO (Dynamic Shared Object) version of php. Detailed instructions for installing Apache with php support are in the INSTALL file in the distribution, and Installing PHP 4.x for Apache 1.x.x on Linux.
2. Install IBM DB2 Personal Developer's Edition
   1. Obtain DB2 V7.2 for Linux
      You can download a free version of the IBM DB2 Personal Developers Edition from IBM. Choose the downloads link on the left side of the page, and grab the "Free Personal Developer's Edition Version 7.2". You will be required to register with IBM to download the product. Since I'm writing this right after I've completed installation, I'm not certain of the terms of the free license.

      The IBM DB2 Site is rather confusing with lots of different versions of DB2. What you are really looking for is IBM DB2 Connect, and it is part of the IBM DB2 Personal Developer's Edition mentioned above.

      For some reason IBM didn't gzip the file, so it's a rather large tarball approximately 323MB in size, and is a long download. You don't need any other files so don't waste your time downloading any others.

   2. Detar the downloaded tarball
      
      1. Make a directory for the installation files
         

         mkdir /usr/local/db2Install

      2. Change directories to where the db2 tarball is
         cd /to/where/db2install.tar.ball is
      3. Extract the files
         The version I downloaded and installed was db2cpelnx.tar. To extract the files, use tar:
         

         tar xf db2cpelnx.tar -C /usr/local/db2install

         The command listed above will extract the tarball to the directory you created in step one.
   3. Create DB2 Users
      For some reason, when I ran the db2setup program, db2 couldn't create db2 users and groups. You can skip this step now if you want to try it the right way first, but you'll save a little trouble if you add them now. It won't hurt anything, as the db2setup program looks for them first.

      IBM DB2 needs two users and two groups. One of the user/groups is the DB2 Administrator, user name db2inst1, group name db2iadm1. The other user name is the IBM DB2 fenced user, and the user name is db2fenc1 and it's group is db2fadm1.

      Make sure you set passwords for these users as they will have access to the DB2 Connect Client from the Linux command line, and thus your AS/400.

      Now, I'm really a FreeBSD person, so I struggled a bit here. The Linux command to add a user is useradd and it resides in /usr/sbin, so to add a user, use:
      

      /usr/sbin/useradd db2fenc1

      I then used vi to edit the group file and changed the group name from db2fenc1 to db2fadm1. Do the same steps for db2inst1.

   4. Run the db2setup program to install db2
      

      cd to /usr/local/db2Install/db2 (or some other directory you may have placed the extracted tarball in. Execute the db2setup command: ./db2setup

      I chose all three options, DB2 Admin, DB2 Connect Personal Edition, and DB2 Application Development Client.

      Make sure to choose to create a DB2 Instance. As the instance is what is used by php to talk to DB2 Connect.

      When the installation completes, you'll receive a summary report on the terminal. This report is also in /tmp.

      Assuming the installation completed without errors, you now have the IBM DB2 Personal Developer's Edition Version 7.2 installed on your machine.

3. Preparing DB2 for AS/400 to accept connections

   In this step you configure the AS/400 database name to be used in the next step when DB2 Personal Developer's Edition for Linux is configured. These steps are from an IBM Document DB2 Linux HOWTO

   The IBM AS/400 has a special service that must be run and other steps that need to be taken:

   1. Name the database and make a *LOCAL entry Command WRKRDBDIRE. There should be an entry with a remote location name of *LOCAL. The relational database name specified with that entry is the external name of the AS/400 database. Typically this is the same name as the system name.

   2. Set the code page to 37 for the user that connects (TBD in a php script), change the CCSID parameter from *SYSVAL to 37, or change it system-wide:

      WARNING: Code Page 37 is US-English, if you're not using english on your system then you need to do further research on how these code pages work. DON'T MAKE ANY CHANGES SYSTEM WIDE WITHOUT CONSIDERING THE CONSEQUENCES. CERTAINLY DON'T CHANGE IT SYSTEM WIDE IF YOUR SYSTEM IS NOT RUNNING US-ENGLISH.

      CHGUSRPRF USRPRF(user) CCSID(37)

      or

      CHGSYSVAL SYSVAL(QCCSID) VALUE(37)

   3. Start a service to listen on port 446. To start the service once:

      STRTCPSVR SERVER(*DDM)

      To automatically start the service:

      CHGDDMTCPA AUTOSTART(*YES)

   4. Create a NULLID collection by issuing the following SQL statement:

      CREATE COLLECTION NULLID

   5. Possibly create a collection for the user ID to connect with:

      CREATE COLLECTION userid

4. Configuring DB2 Personal Developer's Edition for Linux
1. Telling DB2 where to find the remote database
   At a Linux command prompt su to root, and issue the following commands. (Note: do this at the command prompt because the db2 shell doesn't allow editing of input so it you miss type something you will need to re-type the whole command again.)

   Note: This list was taken from section 9.3 of DB2 Version 7.1 for Linux HOWTO and contains a correction to that document. The original document used REMOTE_DATABASE instead of the correct REMOTE_INSTANCE in the first db2 command.

   su root

   su - db2inst1

   db2 CATALOG TCPIP NODE as400 REMOTE as400 \ SERVER 446 REMOTE_INSTANCE \ as400_dbname OSTYPE os400

   db2 CATALOG DCS DATABASE as400_dbname AS as400_dbname

   db2 CATALOG DATABASE as400_dbname AS as400_dbname \ AT NODE as400 AUTHENTICATION DCS

   Note: 1) In the above instructions replace as400 with a resolvable as/400 system name. The name must lookup with DNS. If it doesn't you can add an entry to the /etc/hosts file so it will resolve. 2) Replace as400_dbname with a collection name on the as/400.

   Note: You will notice that there are no user names and passwords here. That doesn't mean that your as/400 isn't secure. The user name and password is required when a connection attempt is made in the php script with the odbc_connect function. PHPs DB2 Connectivity is provided through the php unified ODBC set of functions, but doesn't require ODBC drivers or a Driver Manager. The DB2 Personal Developer's Edition Version 7.2 provides all of the needed functionality.

2. Tell Apache About IBM DB2 PE for Linux
   You must configure Apache to load the DB2 environment variables or php won't be able to find IBM DB2 on your linux box. The symptoms of this problem is a php error message stating "odbc_connect failed for reason %%$%" (where %%$% is some random gibberish).

   To successfully use the DB2 function that we have compiled in our version of PHP, we have to set up the DB2 environment variables for Apache. The easiest way to do this is to source the /home/db2inst1/sqllib/db2profile script in the wrapper that starts Apache.

   If you installed Apache using RPM packages, Apache is started by a SysV init script called /etc/rc.d/init.d/httpd. We can ensure that Apache inherits the DB2 environment variables by adding the following line to the top of /etc/rc.d/init.d/httpd:

   . /home/db2inst1/sqllib/db2profile

   Since I compiled Apache from source, I instead modified the apachectl script to include the preceding line. Stop and Start Apache so that a new process is started with the new environment variables (i.e. don't use restart)

5. Configuring php
   Since the focus of this document is on php and DB2, that's all we're going to configure php for in the example. Also, the build described here is for a DSO (dynamic shared object) build of php.

   php can also be built as a compiled in apache module as well but we're not going to describe that here. You can easily adapt these instructions to the static module instructions described in the INSTALL file included in the php distribution.

   To DSO or to not DSO?

   DSO is the preferred build of php. A DSO build of php is easier to maintain and provides several capabilities that are not available in the static (compiled into) Apache module. The DSO does add extra load on the server because it must be loaded as (each time) the server needs php. On a busy server that doesn't need, say http authentication, a static module is probably a better choice because it would only load php one time. However, the DSO is easier to maintain if you need to reconfigure and add features to php often (or need http authentication, etc, because after building a newer php parser, you simply restart Apache to load the new instance of php.

   WE ARE ASSUMING HERE THAT YOU'VE ALREADY COMPILED AND INSTALLED APACHE WITH mod_so SUPPORT.

   NOTE BELOW THAT THE OPTION IS --with-ibm-db2 AND *NOT* --with-db2 (WHICH IS FOR BERKLEY DB2).

   If this is a new build of php:

   cd /usr/local/php-version ./configure --with-apxs=/path/to/apache/bin/apxs --with-ibm-db2=/home/db2inst1 make make install /path/to/apache/bin/apachectl start

   Machines with an existing php parser:

   cd /usr/local/php-version ./config.nice --with-ibm-db2=/home/db2inst1 make make install /path/to/apache/bin/apachectl restart

   By using ./config.nice instead of ./configure we are retaining the existing php configuration which is stored in config.nice. Look at the top of config.nice to see what options were used last time php was compiled. DO NOT JUST KEEP RE-RUNNING a ./config.nice --with-new-option because the ./config.nice will end up with lots of --with-new-option lines in it. If you run into configuration trouble after adding the --with-ibm-db2, you can just re-run ./config.nice on subsequent attempts.