Learn with our tutorials and training

developerWorks provides tutorials, articles and other
technical resources to help you grow your development skills
on a wide variety of topics and products. Learn about a specific
product or take a course and get certified. So, what do you want to learn
about?

Featured products

Featured destinations

Find a community and connect

Learn from the experts and share with other developers in one of our
dev centers. Ask questions and get answers with dW answers. Search for local events
in your area. All in developerWorks communities.

A seamless upgrade to DB2 Text Search V10.5

Introduction to DB2 Text
Search

IBM DB2 Text Search enables an IBM DB2 for Linux, UNIX®, and
Windows® database user to
create applications with full text-search capabilities by embedding full text-search
clauses in SQL and XQuery statements. It is a highly sophisticated and feature-rich
full text search engine from DB2 compared to its predecessor, Net Search Extender
(NSE). NSE is already deprecated, and it is therefore advisable for the existing DB2 NSE
customers to start using DB2 Text Search for managing their search applications.

Some of the key capabilities and differentiating features that make DB2 Text Search
a better replacement search engine than NSE are:

Integrated installation along with DB2

Stored procedures for administration

XPath-like syntax to search XML docs and from within XQuery

Stronger linguistic processing support for over 20 languages

Ability to control the index update processing

Work load distribution with stand-alone server support

Advantages of upgrading to
DB2 Text Search 10.5

The latest version of DB2 Text Search offers several new features and enhancements.
The following features are available from DB2 V10.1 and above:

Range-partitioned tables

Data Partitioning Feature (DPF)

Integration of a new text search server, including search feature improvements
and better performance/scalability

Infrastructure enhancements

Support for a stand-alone server so the users can have a choice of integrated
or stand-alone server

In addition, with DB2 V10.5, the following enhancements are available:

Additional options to control the index update processing. The administrators
can now define a time window where the index update can be executed, thus avoiding
the load on system during peak time.

Simplifies the indexing procedure by combining both create and initial
update. The administrators can also control which data to be processed during the
execution of initial update.

Upgrading DB2 Text
Search

The upgrade procedure of DB2 Text Search can be viewed as a two-step
process that
includes installation of DB2 10.5 and configuration of a DB2 instance:

Installation of DB2 10.5 with Text Search

Figure 1. Different ways of DB2 Text Search
installation

Script install method

The script install method is an interactive way of installing DB2 using the utility db2_install. With this
mode of installation, the DB2 Text Search component is installed by default. This method
of installation is preferred where configuration is done after
installation. This is the preferred way to install DB2 when you are
upgrading DB2 Text Search.Note: This is not available on Windows.

GUI install method

This method provides a GUI to install and configure DB2. The
utility db2setup is used in this installation method. There is no option to directly
upgrade an existing DB2 copy, so you can use this only to install and not
to configure in the case of an upgrade scenario. With this method, DB2 Text Search
is not installed by default (with typical install), so you need to choose
custom install to select the text search component.

Silent install method

This method provides a command line interface to install and configure DB2. A
response file is used for the installation. Like the GUI method, you can
only use this for installation and not configuration in the case of an upgrade scenario. The keywords
related to Text Search are:

Only the first keyword is used for installation and the next three keywords are used
for configuration.

Configure Text Search and the DB2 instance

This step of the upgrade procedure assumes that you successfully installed DB2 Text
Search using any of the previously listed install methods. The
configuration tasks need to be performed for DB2 and Text Search to use the new
capabilities of DB2 V10.5. The necessary steps are depicted in Figure 2:

Figure 2. DB2 Text Search upgrade
configuration

Scenario 1: An
already up and running DB2 Text Search exists and planning to upgrade to DB2 V10.5.

Scenario 2: DB2 Text search does not exist prior to upgrade but
user wants to configure after upgrading to DB2 V10.5.

Configure DB2 Text Search for Scenario 1:

As an instance owner, stop the DB2 instance and DB2 Text Search services.

Back up the config folder and run configTool to upgrade the
configuration of the text server.

As root, run db2iupgrade from DB2 V10.5 installation path to upgrade DB2
instance.

As an instance owner, run bkuptscfg.sh script to back up all Text Search
configuration information.

Perform a database upgrade to upgrade the database to DB2 10.5.

Verify the text search server information is correct in the DB2 catalog table
SYSIBMTS.TSSERVERS. If the value of the token or port number in the catalog table is
empty or incorrect, update the text server information manually.

Configure DB2 Text Search for Scenario 2:

Run db2iupgrade with –j option from DB2 V10.5 installation path to
upgrade the DB2
instance and also to configure Text Search using the default/provided values for
service name and TCP/IP port number.

Perform a database upgrade to upgrade the database to DB2 10.5.

The detailed steps along with the execution of required commands and their outputs
are captured in the following example.

Example for an end-to-end
upgrade (V97 FP8 to V10.5)

This example illustrates the complete flow of upgrading an up-and-running DB2 server
configured with Text Search to the latest release. In this setup, there is a DB2
database and text search indexes created on a DB2 V9.7 FP8 instance named
db2inst1,
and the following steps guide through the process of upgrading to V10.5 GA
release.

Note: If the DB2 Text Search instance is enabled with rich text
functionality, disable it before upgrading and enable it after successfully
upgrading.

Note: The configTool should be called from the location of the newly
installed DB2 copy the instance is upgrading to.

Step 5: As root, upgrade the DB2 instance to V10.5 by
running the
db2iupgrade command.

Note:‘-j’ option is not specified with ‘db2iupgrade’
because the
instance was already configured with Text Search in the previous DB2 version.

Step 6: As an instance owner, run the script
‘~/sqllib/db2tss/bin/bkuptscfg.sh’ to back up all Text Search configuration
information. These details are written to db2tssrvall.cfg and db2tssrvupg.cfg files
located under ~/sqllib/db2tss/config directory.

Note: ‘-j’ option is not specified with ‘db2iupgrade’
because the
instance was already configured with Text Search in the previous DB2 version.

Along with the other necessary database upgrade tasks, this command also internally
calls the following stored procedures to upgrade the text search specific catalog
tables and indexes to the latest version:

SYSTS_UPGRADE_CATALOG: This procedure performs the DB2 Text Search catalog table
upgrade, including the tasks to create/drop/update the required tables, views,
triggers, and so on.

Step 8: Check the server properties values in sysibmts.systsservers
table by comparing them with the values backed up in Step 6. If the token or port
number is incorrect or empty, then the catalog table should be manually updated with
the right value:

Ensure that the Text Search uses the correct and compatible version of the
server. For V10.5, the following command can be used to display the system
information including the server version, build number, operating
system details,
and JAR manifest version:

For the lower versions, configTool printAll command can be used to
display these details.

Ensure that the index updates and searches work successfully with no
errors.

Troubleshooting
hints

Problem: The command db2ts start for text fails with the
error message "CIE0774E Failed to fetch the text search
configuration."

Resolution: There are several possible reasons to receive this
error.

Verify if the authenticationToken is empty and generate one by running
configTool with generateToken option.

Execute the startup.sh script located in the /sqllib/db2tss/bin/ folder to
receive the complete error message. If it fails with the message similar
to "IQQG0149E The system cannot create the directory," verify that the
paths set for DB2 Text Search configuration parameters
(InstallPath, logPath, and tempDirPath) are valid and with write access to instance
owner.

Problem: The command db2ts start for text fails with the error message
"CIE00340 Cannot start executable program "/bin/sh." An attempt to run the
configTool throws the error "java.io.FileNotFoundException:" on any of the DB2
Text Search configuration files.

Resolution: The DB2 instance is upgraded to a new fix
pack/release, but
the text search server is not upgraded. Upgrade the text server by running the
configTool with the appropriate options.

Problem: The command db2ts start for text fails with the error message
"IQQD0040E The client specified the wrong authentication token."

Resolution: The port that is configured for text search is in use by
another application. Set it to a new value by running configTool.

Resolution: The option –j:"text_search" should be specified only to
configure the DB2 Text Search for the first time. If an instance is already
configured with DB2 Text Search and is updated/upgraded to the latest fix
pack/release with –j option, a default port number is assigned for
Text Search,
overwriting the previous value. Verify that the port number specified
in the
SYSIBMTS.TSSERVERS table matches with the value returned by configTool. If any
mismatch is found, update the catalog table manually.

DB2 Text Search and
compatible text servers

Refer to the following tables and verify the DB2 Text Search server version number for the
corresponding DB2 fix pack/release:

Table 1. Dependencies table for DB2 Text Search
V10.1

DB2 version

DB2 Text Search server version

V10.1 GA

1.5.0.1 build 2038

V10.1 FP1

1.5.0.1 build 2053

V10.1 FP2

1.5.0.1 build 2053

V10.1 FP3

1.5.0.1 build 2114

Table 2. Dependencies table for DB2 Text Search
V10.5

DB2 version

DB2 Text Search server version

V10.5 GA

2.1 build 3765

V10.5 FP1

2.1 build 3913

Conclusion

This article lists the salient features of DB2 Text Search, describes various
upgrade methods, and focuses on step-by-step procedures for upgrading to DB2 Text
Search V10.5. It also includes troubleshooting hints that can help you easily
fix the problems without having to contact IBM support.