DB2 Version 10.1 for Linux, UNIX, and Windows

Configuration Tool for DB2 Text Search

The Configuration Tool is a command-line tool that you can use for the initial text search configuration or the post-installation customization of the text search configuration for a DB2® instance.

Configuring text search during the installation of your DB2 database product provides an easy mechanism for the setup of DB2 Text Search as the installer requires you to configure only two settings and uses defaults otherwise. However, for additional control of configuration settings or subsequent changes, the Configuration Tool must be used. For example, the following settings can be changed:

Various paths, such as the configuration path, the log path, the installation path, and the temporary directory path
The log level
The heap size used
Resource configuration options

For details, see the Text Search planning topic for capacity planning considerations.

Start of change On Windows operating systems, the -configPath parameter is required. End of change

Tool syntax


>>-configTool--mandatory_command_option------------------------->

>-- -configPath--absolute-path-to-config-folder----------------->

>--+-----------------------------------+------------------------>
   '- -locale--five-char-locale-string-'   

>--individual_command_specific_arguments-----------------------><

Parameters

Only the parameters listed here are supported for DB2 Text Search.

mandatory-command-options

configureHTTPListener

Allows you to configure an administration HTTP port to allow communication between text search processes using TCP/IP. Specify the following argument:

-adminHTTPPortvalue: Specifies the port to be used by DB2 Text Search

You must stop the text search instance services before configuring the administration HTTP port.

upgradeInstance

You can update DB2 Text Search server for your instances by issuing the upgradeInstance command. Specify the following argument:

-installedConfigPath value

Specifies the fully qualified path to the installed configuration directory. For example,

On Linux and UNIX operating systems, this path might be
```
   -installedConfigPath $DB2DIR/cfg/db2tss/config
   -configPath $INSTHOME/sqllib/db2tss/config
```
where INSTHOME is the instance home directory and DB2DIR is the location of the DB2 Version 9.7 copy.
For Windows operating systems, this path might be
```
   -installedConfigPath "%DB2PATH%\CFG\DB2TSS\CONFIG"
   -configPath "%INSTPROFDIR%\instance-name\DB2TSS\CONFIG"
```
where DB2PATH is the location of the DB2 Version 9.7 copy and INSTPROFDIR is the instance profile directory. Refer to DB2INSTPROF for more details.

configureParams

Allows you to configure the various configurable parameters for DB2 Text Search. Specify one of the following arguments:

-configPath absolute-path-to-config-folder

Specifies the absolute path to the text search configuration folder, such as /opt/ibm/search/config. Note that when you use configureParams, configPath is used not only to point to the configuration directory but also to modify the configuration to use the specified configuration path.

Do not rename or remove the default config directory. The Text Search Server needs the existence of the default config directory even though the config directory is reconfigured by the user to a different path. To change the config directory from default path to user defined, you must ensure that the following requirements are met:

The proper config details are in the new the config directory.
The new config directory path is updated correctly in the config.xml file.

-maxDocumentSize

Specifies the maximum number of characters that are to be indexed for a document. If an error occurs, an error code of -3 is returned.

-defaultDataDirectory path

Specifies the location of the collection configuration files for all collections. The collection data (index) files will be in a subdirectory under the <defaultDataDirectory>\collection_name\data\text collection configuration directory. You can specify a different directory for the data (index) files when you define a collection. If defaultDataDirectory is not specified or blank, the default is configPath\collections.

-installPath path

Specifies the fully qualified path to the text search installation directory. The default installation path $DB2DIR/db2tss as present in config.xml can be configured to a new path. For example, on UNIX operating systems this path can be reconfigured to $HOME/sqllib/db2tss. End of change

-startupHeapSize value

Specifies the maximum heap size of the server. The default value is 1500 MB. This value influences throughput and response times and should be set as an integer according to JVM heap size specifications. For example, specify 1800 MB to indicate the maximum possible heap size of 1.8 GB that can be allocated to a 32-bit Java™ virtual machine. If an error occurs, an error code of -5 is returned.

-numberOfIndexerThreads value

Specifies the number of indexing threads that run on the server.

-numberOfPreprocessingThreads value

Specifies the number of preprocessing threads that run on the Text Search servers. Each preprocessing thread can include the following steps: document constructor, text extraction, language identification, tokenization, and language analysis.

-numberOfTokenizers value

Specifies the number of language processors that are used for parsing input into tokens. Typically this should be set to the number of preprocessing threads.

-inputQueueMemorySize value

Specifies the memory size of the input queue on the indexing server. The input queue contains documents that are waiting for preprocessing. A larger memory size will be faster, but will consume more resources. The default size is 50 MB.

-outputQueueMemorySize value

Specifies the memory size of the output queue on the indexing server. The output queue contains documents that are waiting to be indexed after preprocessing. A larger memory size will be faster, but will consume more resources. The default size is 50 MB.

-documentBatchSize value

Specifies the default number of documents that are retrieved from a queue in each call.

-documentTimeout value

Specifies the maximum time (in seconds) that is allowed for document preprocessing. If this value is exceeded, the documentRetryNumber parameter determines the number of times that preprocessing is retried.

-documentRetryNumber value

Specifies the number of attempts to try document preprocessing again. Each time that preprocessing exceeds the documentTimeout limit, the document is returned to the input queue on the indexing server for another attempt until the documentRetryNumber is exceeded. If document preprocessing is not completed within the specified number of attempts (documentRetryNumber + 1), an error is generated for the document.

-tempDirPath path

Specifies the temporary directory path to be used by the text search server.

-locale locale

Specifies the five-character locale for writing any error messages that are returned during the use of the tool, such as en_US, de_DE, or fr_FR. The default is en_US. For details see Supported locales

-logPath path

Specifies the log path to be used by DB2 Text Search.

-logLevel value

Specifies the logging level for messages in the log file for the text search server. . The settings (in order of severity) are as follows:

FINEST
FINER
FINE
WARNING
SEVERE
OFF

generateToken

Generates the authentication token. The following argument is the only one that you can use:

-seed value: Acts as an arbitrary string for generating an authentication token. Given the same seed value, the Configuration Tool generates the same token every time.

help

Prints the Configuration Tool command usage. The usage information is also printed if you run the Configuration Tool without a required argument.

printToken

Prints the authentication token. This option does not require you to stop the instance services.

printAll

Prints to standard output the values for all of the properties that are configurable. This option does not require you to stop the instance services.

printAdminHTTPPort

Prints the current value for the administration HTTP port. This command does not require you to stop the instance services.

Usage

Unless otherwise noted in a parameter description, you must stop the text search instance services to configure the parameter. For the configuration settings that require the instance services to be stopped, the Configuration Tool detects the related condition and returns a message indicating that the instance services are running and must be stopped.
The Configuration Tool and the other command-line tools do not authenticate users. However, you must have access to the configuration files to run these tools. For integrated Text Search server setups on Windows platforms, if the extended DB2 security model is implemented, only members of the DB2ADMNS group can run the command-line tools. If the extended DB2 security model is not implemented, the DB2 instance owner must control access to these tools.
The Configuration Tool does not update the services file. If you use the Configuration Tool for first-time configuration or changes to an existing configuration, you must update the services file manually.