Installing IBM DB2 Universal Database Express Edition Transparently with Your Application

DB2 UDB Express lets you use this handy response file method of installing DB2, which makes it easy to deploy DB2 UDB Express and which also lets you embed DB2 installation in your own application program.

Michael Gao, DB2 UDB Consultant, IBM Canada

Michael Gao is a DB2 Consultant from the IBM Toronto Lab where DB2 for distributed platforms is developed. He currently primarily works with IBM business partners in application development, performance tuning, porting and customerized education. He has presented at several international conferences and co-authored the book DB2 SQL Procedural Language for Windows, UNIX and Linux. You can reach Michael at xmgao at ca.ibm.com.



19 June 2003

Introduction

IBM® DB2® Universal DatabaseTM Express Edition (DB2 UDB Express) is the newest member of the IBM DB2 family. It is designed, priced, and marketed specifically to help small and medium businesses integrate and manage business processes. DB2 UDB Express offers:

  • Transparent installation with your application.
  • Enhanced autonomic manageability features.
  • Lower total cost of ownership.

This article describes the complete DB2 response file installation process on Microsoft® Windows® and Linux platforms, which are the platforms on which DB2 UDB Express is offered.

Unlike standard DB2 setup utilities, a DB2 response file installation lets you install DB2 without interactive user input. This is useful not only for large-scale deployments of DB2, but also for embedding the DB2 installation process transparently inside your own installation program. The response file installation is one of the reasons why DB2 provides a complete solution for your embedded database needs.

The DB2 response file installation is a background installation process that you can embed into an existing installation program, and it is transparent to end users. The installation is performed by DB2 setup utilities with user-generated response files. The response files are ASCII text files that contain setup and configuration information, which can be generated either with DB2 utilities or by manual editing.

This article covers response file generation, response file installation, database setup and de-installation in detail, along with special considerations for embedding the DB2 installation process into your own application installation program.


Generating response files

The first step of the response file installation process is to generate a response file. When installing DB2 using the interactive setup utility, you are prompted to make installation choices and provide necessary configuration data before installation takes place. Response files simply contain these installation choices and configuration data, which are already prepared for embedded use.

There are three methods to generate the responses files:

  • Using the DB2 Setup wizard
  • Using the DB2 response file generator utility (Windows only)
  • Generating the response file manually

The response files are ASCII text files. Listing 1 is a sample of a partial response file.

Listing 1. Sample of a partial response file

PROD= UDB_EXPRESS_EDITION 
LIC_AGREEMENT=ACCEPT 
FILE=C:\SQLLIB\ 
INSTALL_TYPE=CUSTOM 
 
COMP=DEVELOPMENT_CENTER
... 
COMP=CONTROL_CENTER 
COMP=CLIENT_TOOLS 
COMP=COMMAND_CENTER 
... 
COMP=TCPIP_DB2_CLIENT_SUPPORT 
COMP=TCPIP_DB2_LISTENER_SUPPORT 
 
LANG=EN 
DAS_CONTACT_LIST=LOCAL 
 
INSTANCE=DB2 
DB2.NAME=DB2 
DEFAULT_INSTANCE=DB2 
DB2.SVCENAME=db2c_DB2 
DB2.DB2COMM=TCPIP 
DB2.PORT_NUMBER=50000 
DB2.FEDERATED=YES 
...

You can find a complete sample response file on your DB2 installation CD in the following locations:

  • For Linux, it is located at <cd-rom>/db2/linux/samples, where <cd-rom> represents the location of the DB2 installable image.
  • For Microsoft Windows, it is located at x:\db2\windows\samples, where x: represents the CD-ROM drive.

The response file is named db2exp.rsp for DB2 UDB Express.

For a brief description of some of the DB2 response file keywords, see Manually generating response files.

Using the DB2 Setup wizard

The DB2 Setup wizard is the GUI installation utility available on both Microsoft Windows and Linux platforms. It is the program that you normally run interactively when you install DB2. Instead of, or in addition to, installing the product, you can also save all of your choices in the response file for later use.

To save your choices in a response file, you need to choose the custom installation type shown in Figure 1.

Figure 1. Choosing the customized installation type
Choosing the customized installation type

After you choose the custom installation, you have the choice of saving everything in a response file, performing the installation, or both. The page where you make these choices is shown in Figure 2.

Figure 2. Creating a response file using the DB2 setup wizard
Creating a response file using the DB2 setup wizard

If you have never used the DB2 Setup wizard before, you can find it at the following locations:

  • For Microsoft Windows, it is named setup.exe and is located in the root directory of the installation CD.
  • For Linux, it is named db2setup and is located in the root directory of the installation CD or image.

When the DB2 Setup wizard process is complete, save the DB2 response file that was generated for you. You can choose the path and the file name for the generated response file.

You must manually modify the generated response files to accept the license agreement before they are useable.

Using the DB2 response file generator

The DB2 response file generator utility is available on Windows platforms only. The idea is to create a master installation first and then use the response file generator to create a response file that can install the same DB2 components as the master installation. The utility can also generate instance profiles to create and configure the instances.

Figure 3 shows the syntax for the response file generator utility, db2rspgn.

Figure 3. Syntax for db2rspgn utility
Syntax for db2rspgn utility

By default, db2rspgn generates profiles for all instances on the master installation along with the response file. You can choose not to create profiles for the Data Links File Manager (DLFM) instance and control server instance by using the -nodflm and -nocltsv options, respectively. You can also specify the individual instances for profile creation. The profile files are put in the same directory as the response file.

You must do some minor editing on the generated response files before they are useable:

  • Manually modify the file to accept the license agreement.
  • Enter the user ID and password for the new systems.

Generating response files manually

Because the response files are ASCII text files, you can create them manually. You can choose to modify the sample response files provided with the DB2 image or you can re-create them yourself. This method requires a solid understanding of the response file structure and keywords. Fortunately, the sample response files are well commented and self-explanatory.

Here are brief descriptions of some of the keywords that you specify in the response file.

PROD
Specifies the product that you want to install.

  • UDB_EXPRESS_EDITION for DB2 UDB Express.
  • ADMINISTRATION_CLIENT for the DB2 Administration Client.
  • APPLICATION_DEVELOPMENT_CLIENT for the DB2 Application Development Client.
  • RUNTIME_CLIENT for the DB2 Run-Time Client.

FILE
Specifies the destination directory for a DB2 product (for Windows only).

INSTALL_TYPE
Specifies the type of installation: COMPACT, TYPICAL or CUSTOM.

COMP
Specifies the components that you want to install. This keyword is ignored unless your INSTALL_TYPE is CUSTOM.

LANG
Specifies a language support you want to install.

REBOOT
Specifies whether to restart the Windows system when the installation has completed.

KILL_PROCESSES
Specifies if the installation will terminate the currently running DB2 processes without prompt (for Windows only).

Other options include those for:

  • DB2 Administration Server settings
  • Instance settings
  • Database settings

For a complete list of keywords, detailed description and usage information, see the sample response file on your installation CD and the DB2 UDB Express documentation.


Using response files for unattended installation

This section describes:

The installation process

After you generate the response files, installation is straightforward. Use the same executables that you used in the GUI installation. However, instead of typing the command only at the prompt or double-clicking setup.exe, you must provide the proper response file name. You can also specify other options such as log file path and name.

Figure 4 is the syntax for the setup utility on Windows. Only the response file name with the full path is mandatory for a response file installation.

Figure 4. Syntax for setup utility on Windows platforms

setup [/f] [/I <language>] [/l <log file>] [/u <response file>] 
[/t <trace file>] 
/? - generates this usage message 
/f - forces any db2 processes to stop before installing 
/i - two letter code for the preferred language 
/l - full path and name of the log file 
/u - full path and name of the response file 
/t - creates a file with install trace information

On Linux, use the db2setup syntax shown in Figure 5.

Figure 5. Syntax for db2setup on Linux
Syntax for db2setup on Linux

The unattended installation process runs in the background. No DB2 installation GUI appears. When embedded with your own installation program, the DB2 installation appears to be part of your installation process. Upon completion, the DB2 installation process returns a return code to your program. You can choose to monitor the return code in your installation program. Table 1 and Table 3 contain the primary return codes for Windows and Linux. The primary return codes are the most commonly received and you should code to handle them. There are also secondary return codes, which are less commonly seen. These codes are in Table 2 and Table 4. These four tables can also be found in the DB2 UDB Express documentation.

Table 1. Primary response file installation return codes on Windows

Return CodeDescription
0The action completed successfully.
1The action returns a warning.
1603A fatal error occurred during the installation.
3010Install was successful; however, a reboot is required to complete the installation.

Table 2. Secondary response file installation return codes on Windows

Return CodeDescription
3The path was not found.
5Access was denied.
10An environment error occurred.
13The data is invalid.
87One of the parameters was invalid.
1602The installation was cancelled by the user.
1610The configuration data is corrupt. Contact your support personnel.
1612The installation source for this product is not available. Verify that the source exists and that you can access it.
1618Another installation is already in progress. Complete that installation first before proceeding with this installation.
1622There was an error opening the installation log file. Verify that the specified log file location exists and that it is writable.
1632The Temp folder is either full or inaccessible. Verify that the Temp folder exists and that you can write to it.
1633This installation package is not supported on this platform.
1638Another version of this product is already installed. Installation of this version cannot continue.
1639Invalid command line argument.

Table 3. Primary response file installation return codes on Linux

Return CodeDescription
0The action completed successfully.
1The action returns a warning.
67A fatal error occurred during the installation.

Table 4. Secondary response file installation return codes on Linux

Return CodeDescription
3The path was not found.
5Access was denied.
10An environment error occurred.
13The data is invalid.
87One of the parameters was invalid.
66The installation was cancelled by the user.
74Table data
76The installation source for this product is not available. Verify that the source exists and that you can access it.
82Another installation is already in progress. Complete that installation first before proceeding with this installation.
86There was an error opening the installation log file. Verify that the specified log file location exists and that it is writable.
96The Temp folder is either full or inaccessible. Verify that the Temp folder exists and that you can write to it.
97This installation package is not supported on this platform.
102Another version of this product is already installed. Installation of this version cannot continue.
103Invalid command line argument.

Logging the installation

The path and the name of the log file are optional parameters to the DB2 setup program. If you do not specify the name and the path of the log file, default log files are created for you in the default directory:

  • On Windows, the default file is db2.log in the My Documents\DB2LOG directory under the user ID with which the DB2 installation was performed.
  • On Linux, the default file is /tmp/db2setup.log.

Besides these log files, other auxiliary log files and dump or trace files are created in the default directories.

  • On Windows, in the path you specified or in the default path mentioned above, there is another log file from Windows Installer called db2wi.log. Log entries for the current installation are recorded into the db2wi.log file during the installation period. The db2.log file has information about the current and any previous installations for Windows. It is updated at the end of the DB2 installation.
  • On Linux, you may also find some other DB2-generated files in the /tmp directory. The db2setup.his log file maintains a history of the current and past installations. The db2setup.err log file contains all the error entries.

Tracing the installation

The path and the name of a trace file are also optional parameters to the DB2 setup program. Trace files contain service information for IBM support and are not for users. You can safely remove them after a successful installation. When you do choose to create the trace file, the DB2 installation log files are generated in verbose mode, which means that much more detailed information is generated in the log files.


Installation considerations

Whether you intend to use a DB2 response file installation for deploying on many machines or for embedding in an application, make sure you check prerequisites, ensure that no DB2 processes are running, and have a plan for handling a failed installation.

Checking prerequisites

As with the DB2 GUI setup, make sure that all prerequisites are met in your own installation script before kicking off the DB2 response file installation process. The prerequisites include both user privileges and system configuration. DB2 installation prerequisites are well documented in both the DB2 UDB Express documentation and the readme files on the DB2 installation CDs.

Killing DB2 processes

A DB2 installation cannot occur when there are active DB2 processes running. On Windows only, you could use either the KILL_PROCESSES keyword in the response file or the /F option to kill the active DB2 processes. However, killing DB2 processes can cause a loss of data. Instead, we recommend that you use the db2stop command on each instance, as described instead. See the DB2 UDB Express documentation for complete syntax before using the db2stop command.

User program intervention

User program intervention is not possible during the DB2 response file installation. After the installation process has started, it will run on its own. All your installation program can do is to monitor the final return code.

Failed installation

When the installation fails, the DB2 installation process normally would clean up the newly installed component. Your own installation program could parse and check the log files or check the return codes to pinpoint the problem. If the problems can be remedied, you can try to install DB2 again.


Creating and setting up databases

After you have DB2 UDB Express installed and configured, the next logical steps are:

  1. Create your database.
  2. Create your database objects, such as tables, views, triggers, functions and procedures.
  3. Populate your tables with data.

While these tasks are beyond the scope of this article, they are discussed here briefly for the completeness.

How you create and set up your databases largely depends on the development languages you use. You can do this setup with scripts, or with programs written in C, JavaTM and many other programming languages of your choice. You can even do it with a combination of scripts and programs.

The simplest way to create a database is to manually add a database section in the response file. A database will be created for you at the end of the installation. Figure 6 is a sample database section that creates a MY_DB1 database under the DB2INST1 instance.

Figure 6. Sample database section in response file

DATABASE = MY_DB 
MY_DB.INSTANCE = DB2INST1 
MY_DB.DATABASE_NAME = MY_DB1 
MY_DB.LOCATION = LOCAL 
MY_DB.ALIAS = MY_DB1 
MY_DB.USERNAME = <i>username</i> 
MY_DB.PASSWORD = <i>password</i>

You can also create databases with scripts or with C DB2 APIs. If Java is your programming language of choice, you will have to use one of the above methods to create a database first. There is no Java administration API definition in the JDBCTM standard.

After the database is created, the database objects can be created and tables can be loaded. Again you can use many programming languages and their corresponding APIs for loading data, such as C and ODBC/CLI, or Java and JDBC.

If you have large amount of data to load, consider using DB2 IMPORT or LOAD utilities. For syntax and usage of IMPORT and LOAD, see the DB2 UDB Express documentation.


De-installing DB2 UDB Express

You can also embed DB2 UDB Express de-installation in your own de-installation programs. The following are the step-by-step instructions to de-install DB2 UDB Express on Windows and Linux.

De-installing DB2 UDB Express on Windows

On Windows systems, you need to perform the following steps, in this order:

  1. Drop all databases by entering the following command:
    <b> 
    DB2 DROP DATABASE database-alias</b>
  2. Disconnect all applications by entering the following command:
    <b>DB2 FORCE APPLICATION ALL</b>
  3. Stop all DB2 processes and services by entering the following commands:
    <b> 
    DB2STOP 
    DB2ADMIN STOP</b>
  4. Remove the DB2 UDB Express product. To do this programmatically, use the Windows Installer. The command you would use is:
    <b> 
    msiexec /x {58169F10-CA30-4F40-8C6D-C6DA8CE47E16}</b>

For more information on above commands, refer to the DB2 UDB Express documentation.

De-installing DB2 UDB Express on Linux

On Linux, you need to perform the following steps, in this order:

  1. Drop all databases by entering the following command:
    DB2 DROP DATABASE database-alias.
  2. Stop the DB2 Administration Server by logging in as the DB2 administration server owner and issuing the DB2ADMIN STOP command.
  3. Stop all DB2 instances by repeating the following steps for each instance you created:
    1. Log in as the instance owner.
    2. Stop all database applications by entering the DB2 FORCE APPLICATION ALL command.
    3. Stop the DB2 database manager by entering the DB2STOP command.
    4. Confirm that the instance is stopped by entering the DB2 TERMINATE command.
  4. Remove the Administration Server:
    1. Log in as root.
    2. Issue the command:
      /opt/IBM/db2/V8.1/instance/dasdrop.
  5. Remove DB2 instances by repeating the following steps for each instance you created:
    1. Log in as root.
    2. Issue /opt/IBM/db2/V8.1 /instance/db2idrop InstanceName command.
    3. Remove the instance owner's user ID and group if you created them during installation and if they are used only by your program.
  6. Remove DB2 UDB Express. You have two options on Linux. You must root authority for both. You can:
    • Use the db2_deinstall command in the root directory of the DB2 UDB Express CD or image.
    • Use the rpm command.

For more information on above DB2 commands, please refer to the DB2 UDB Express documentation. For more information on the rpm command, refer to the RPM Web site.


Conclusion

By using DB2 response file installation, you can transparently install DB2 UDB Express inside your own installation program. It eliminates the need for user input during the installation, and it provides you detailed and timely installation progress information through log files. Using response file installation is great for performing large-scale DB2 UDB Express deployments or for embedding DB2 UDB Express in your application's installation.


Acknowledgements

The author expresses his deep gratitude for the help he received from Andrew Hilden from the IBM Toronto Lab.

Resources

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 Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=13161
ArticleTitle=Installing IBM DB2 Universal Database Express Edition Transparently with Your Application
publish-date=06192003