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.

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.

You should configure text search when you are installing your Db2 database product because the installer requires you to configure only two settings and uses defaults otherwise. However, for additional control of configuration settings or subsequent changes, you must use the Configuration Tool. For example, you can change the following settings:

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.

On Windows operating systems, the -configPath parameter is required.

Tool syntax

Parameters

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

Mandatory command options

list -system [-details] [-showAdvanced] [-parameter_name] -configPath-configdir

Prints system-level parameters and their current values. See the descriptions of each parameter.

-details: Prints detailed information about each parameter, including a description, default value, type, and whether it is modifiable.
-showAdvanced: Prints information about advanced configuration parameters.
-parameter_name: Prints detailed information about the specified parameter.

list -collectionName -collection [-details] [-parameter_name] -configPath-configdir

Prints configuration parameters for the specified collection and their current values.

-details: Prints detailed information about each parameter, including a description, default value, type, and whether the parameter is modifiable.

-parameter_name

Prints detailed information about the specified parameter.

set -system -parameter_name -value -configPath-configdir: Specifies the value of a system-level parameter.

set -collectionName -parameter_name -value -configPath-configdir: Specifies the value of a system-level parameter.

configureHTTPListener

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

-adminHTTPPortvalue: Specifies the port to be used by Db2 Text Search. This parameter is deprecated. Use the set -system -port command instead.

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

upgradeInstance

You can update the 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.

This parameter is deprecated. Use the upgradeConfigFolder -sourceConfigFolder -targetConfigFolder command instead.

For example,

On Linux® and UNIX operating systems, this path is
```
   -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 is
```
   -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. For details, see the DB2INSTPROF registry variable.

configureParams

Use to configure the various configurable parameters for Db2 Text Search.

This parameter is deprecated. Use the set command instead.

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. When you use configureParams, configPath is used to point to the configuration directory and 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.

-documentBatchSize value

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

-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.

-logLevelvalue

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. If given the same seed value, the Configuration Tool generates a unique token every time.

printToken

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

sysinfo

Prints system information, such as the build version number, operating system, and JAR version.

help

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

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 is dynamic and does not require you to stop the instance services.

This parameter is deprecated. Use the list -system -port command instead.

upgradeConfigFolder -sourceConfigFolder path -targetConfigFolder path

Upgrades the server configuration.

-sourceConfigFolder: The fully qualified path to the new source configuration directory.
-targetConfigFolder: The fully qualified path to the destination configuration directory that is to be upgraded.

Server parameters

-acceptorThreads: Specifies the number of server threads that handle client requests. Specify an integer between 20 and 2000. Lower values can cause delays in handling server requests. Higher values can use too many system resources and cause out-of-memory errors. The default value of this parameter is 300.
-concatenateSmallFiles: Indicates whether to optimize the processing of small text files. This advanced parameter is enabled by default.
-configPath: Specifies the full path to the configuration directory. This directory contains configuration files and the \collections subdirectory. You cannot modify this parameter.
-defaultDataDirectorypath: Specifies the location of the collection configuration files for all collections. The collection data (index) files is in a subdirectory under the <defaultDataDirectory>\collection_name\data\text collection configuration directory. You can specify a different directory for the index files when you define a collection. If defaultDataDirectory is not specified or blank, the default is configPath\collections.
-docQueueDrainTimeInMillispath: Specifies the time (in milliseconds) to wait for the document queue to empty before shutting down the server.
-documentBatchMemorySizepath: Specifies the maximum size of a batch of documents that are retrieved from a queue in each call by the preprocessing and indexing threads.
-documentDeleteBatchSizepath: Specifies the default number of documents that are retrieved by indexing threads for deletion from the queue in each call.
-documentQueueSizepath: Advanced: Specifies the number of documents of the input and output queues on the indexing server. This parameter is disabled by default (value = -1). The inputQueueMemorySize parameter also defines the queue size (in MB). When the documentQueueSize parameter is specified, the lower of the two parameters defines the queue size. This parameter can be modified only when the server is not running.
-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.
-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.
-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 is faster, but consumes more resources. The default size is 50 MB.
-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.
-logFolder: Specifies the log path to be used by Db2 Text Search. This parameter can be modified only when text server is not running.
-maxConcurrentIndexingCollections: Specifies the maximum number of collections that can be opened for indexing concurrently. Set this value according to your available memory. The default value is 16. For partitioned environments, this value must at minimum be equal to the number of partitions.
-maxHeapSize: Specifies the maximum heap size of the server. This value should be set according to JVM heap size specifications.
Note: The output from running the command configTool printAll -configPath lists the maxHeapSize parameter as startupHeapSize.
-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.
-numberOfSearchablesvalue: Specifies the maximum number of collections that can be open concurrently for search.
-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.
-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.
-outsideInMaxProcessableDocumentsvalue: Specifies how frequently (in number of documents) the text extractor is restarted.
-port value: Specifies the number of the port on which the server will listen to nonsecure requests. You can disable the port by specifying a value of 0.
-queryExpansionLimit value: Specifies the maximal number of terms that a wildcard query can expand to. If the query exceeds this limit, an exception is thrown.
-rangeQueryExpansionLimit value: Specifies the maximal number of values that a range query can expand, for example, [aTO z]. If the range query exceeds this limit, an exception is thrown.
-stellentEnabled value: Specifies whether the use of Outside In filters are enabled.
-stellentVersion value: Specifies the Outside In version that is in use by text search. You cannot modify this parameter.