+--- NOTE! ----------------------------------------------------------+ | | | Before using this information and the product it supports, be sure | | to read the general information under "Notices" | | | +--------------------------------------------------------------------+ This document contains proprietary information of IBM. It is provided under a license agreement and is protected by copyright law. The information contained in this publication does not include any product warranties and any statements provided in this manual should not be interpreted as such. Requests for publications and for technical information about IBM products should be made to your IBM software reseller or contact the IBM office nearest you. IBM is a registered trademark of International Business Machines Corporation, Armonk, N.Y. (C) COPYRIGHT INTERNATIONAL BUSINESS MACHINES CORPORATION 2001. ALL RIGHTS RESERVED. Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. CONTENTS ________ ABOUT THE DB2 NET SEARCH EXTENDER PREREQUISITES MIGRATION INSTALLATION INSTRUCTIONS CURRENT RESTRICTIONS AND USEFUL HINTS FIXES PROVIDED WITH THIS FIXPACK TRY & BUY NOTICES TRADEMARKS ABOUT THE DB2 NET SEARCH EXTENDER _________________________________ Welcome to the IBM* DB2 Universal Database* (DB2*) Net Search Extender Version 7.2.1 For general documentation on DB2 Net Search Extender, read the Adobe Acrobat Reader file, nsdoc.pdf included in the package. Additionally, read the information in the "CURRENT RESTRICTIONS" section below. PREREQUISITES ______________ DB2 Net Search Extender requires the installation of DB2 Enterprise Edition Version 7.1 or 7.2. Currently, installation of DB2 V7.2 is recommended. Before installing this fixpack, read the following "MIGRATION" section. MIGRATION _________ Migrating from version 7.1, 7.1.1, or 7.1.2 If you are using DB2 Net Search Extender version 7.1, 7.1.1, or 7.1.2, you firstly have to migrate to version 7.1.3 (using fixpack 3 for version 7.1), or perform the following steps BEFORE INSTALLING THIS FIXPACK: 1. Issue the DISABLE DATABASE command for all the databases that have been enabled for use with DB2 Net Search Extender. This will delete all your text indexes. Note that more than one DB2 Net Search Extender instance may exist. 2. Install this fixpack using the INSTALLATION INSTRUCTIONS" in the following section. Migrating from version 7.1.3 or 7.2 If you are using DB2 Net Search Extender 7.1.3 or 7.2, you can migrate existing text indexes for use under version 7.2.1 by using the migration tool "nxupd720". This is available in the bin directory of the DB2 Net Search Extender installation. Steps to perform: 1. Run the DEACTIVATE INDEX command for all existing text indexes of all the databases that have been enabled for use with DB2 Net Search Extender Note that more than one DB2 Net Search Extender instance may exist. 2. Install this fixpack using the "INSTALLATION INSTRUCTIONS" in the following section. 3. Run the nxupd720 command as described in the usage information displayed when using the -h option. Note that the command has to be issued with instance owner authority. Example: The command /usr/lpp/db2nx_07_01/bin/nxupd720 -d myDatabase -I will migrate the database myDatabase and all it's text indexes to DB2 Net Search Extender version 7.2.1 on an AIX system 4. Check if the migration was successful by issuing the GET INDEX STATUS command and check if the order of optimized columns, numeric columns, and tags, shown in the output is the same as used in the ENABLE TEXT COLUMN command when the text index was created. If the order is different, you MUST DROP AND RECREATE THE APPROPRIATE INDEX to avoid wrong search results. 5. This step is only required if you are migrating from version 7.1.3: If your indexes were created with an ORDER BY statement, no further action is required. If your indexes did not use a pre-sorted order of the in-memory table, a DB2NX UPDATE INDEX command must be issued for each index that you want to still use. This is necessary, as DB2 Net Search Extender now uses an implicit ORDER BY , if no ORDER BY is used during ENABLE TEXT COLUMN. If this is not the case, the correctness of search results involving numeric indexes cannot be guaranteed. See the "FIXED DEFECTS" section in this readme. 6. The migration is now complete. Note: Running the program more than once will not affect your system. INSTALLATION INSTRUCTIONS _________________________ INSTALLING THE DB2 NET SEARCH EXTENDER ON AIX 4 _______________________________________________ 1. Install the product component on the target machine. 2. Establish the DB2 Net Search Extender instance. STEP 1 - INSTALL THE PRODUCT COMPONENT ON THE TARGET MACHINE 1. Log in at the target machine as the root user. 2. Use installp to transfer the files from the package to the target machine. You can use the System Management Interface tool (SMIT) to run installp from a prompted interface, or you can enter the installp command. To run smit: a. Enter 'smit install_latest' to open The Software Installation and Maintenance Tool menu. b. Enter the directory of the install file in the 'INPUT device / directory for software' field. //aix where is your cdrom drive path. c. Click the DO button or press ENTER. This confirms the installation directory. d. Identify in the SOFTWARE TO INSTALL field the DB2 Net Search Extender component to be installed. e. Click the DO button or press ENTER. f. You are prompted for confirmation of the installation parameters. To confirm, press ENTER. g. If the registration screen does not display during installation, set your DISPLAY variable and call /usr/lpp/db2nx_07_01/register 3. Logout. STEP 2 - ESTABLISH THE DB2 NET SEARCH EXTENDER INSTANCE 1. Stop the db2instance you want to work with using: db2stop 2. Ensure you are active as the root user. 3. Enter: cd /usr/lpp/db2nx_07_01/instance 4. Run nxicrt as follows: ./nxicrt __________ where is an existing DB2 instance user ID. ___________ Running nxicrt creates the directory db2nx under the home directory of the DB2 instance user ID. Do not create additional files or directories under ~/db2nx; these files will be lost if the instance is deleted. A db2iupdt command will be completed during this call to ensure the transfer of the license file. 5. Logout. INSTALLING DB2 NET SEARCH EXTENDER ON WINDOWS NT ________________________________________________ 1. Use the setup.exe to transfer the files from the installation package to the target machine. 2. Reboot the system after data transfer. 3. Call nxstart.bat to start a DB2 Net Search Extender daemon process. If the daemon process is not available Net Search Extender queries cannot be performed. If the daemon has been stopped, for example, by a system reboot, call nxstart.bat and activate all indexes again. 4. To deinstall the product, use the Add/Remove Program icon in the Control Panel. INSTALLING THE DB2 NET SEARCH EXTENDER ON LINUX _______________________________________________ 1. Install the product component in the target machine. 2. Establish the DB2 Net Search Extender. STEP 1 - INSTALL THE PRODUCT COMPONENTS IN THE TARGET MACHINE 1. Log in at the target machine as the root user. 2. Install the Package You install packages with the 'rpm' command: rpm -i /linux/db2nse-7.2.i386.rpm where is your cdrom drive path. STEP 2 - ESTABLISH THE DB2 NET SEARCH EXTENDER INSTANCE 1. Log in as DB2 instance owner and stop the DB2 instance you want to work with using: db2stop 2. Ensure you are active as the root user. 3. Enter: cd /usr/IBMdb2nx/V7.1/instance 4. Run nxicrt as follows: ./nxicrt __________ where is an existing DB2 instance user ID. ___________ Running nxicrt creates the directory db2nx under the home directory of the DB2 instance user ID. Do not create additional files or directories under ~/db2nx; these files will be lost if the instance is deleted. A db2iupdt command will be completed during this call to ensure the transfer of the license file. 5. Logout. INSTALLING THE DB2 NET SEARCH EXTENDER ON SUNOS 5.6 AND 5.7 ___________________________________________________________ 1. Install the product component in the target machine. 2. Establish the DB2 Net Search Extender. STEP 1 - INSTALL THE PRODUCT COMPONENTS IN THE TARGET MACHINE 1. Log in at the target machine as the root user. 2. Install the Package You install packages with the 'pkgadd' command: pkgadd -d //solaris/ibmnets.pkg where is your cdrom drive path. The list of available packages is displayed. Select the 'IBMNETS' package. STEP 2 - ESTABLISH THE DB2 NET SEARCH EXTENDER INSTANCE 1. Stop the db2instance you want to work with using: db2stop 2. Ensure you are active as the root user. 3. Enter: cd /opt/IBMdb2nx/V7.1/instance 4. Run nxicrt as follows: ./nxicrt __________ where is an existing DB2 instance user ID. ___________ Running nxicrt creates the directory db2nx under the home directory of the DB2 instance user ID. Do not create additional files or directories under ~/db2nx; these files will be lost if the instance is deleted. A db2iupdt command will be completed during this call to ensure the transfer of the license file. 5. Logout. INSTALLING THE DB2 NET SEARCH EXTENDER ON HP-UX 11 __________________________________________________ 1. Install the product component in the target machine. 2. Establish the DB2 Net Search Extender. STEP 1 - INSTALL THE PRODUCT COMPONENTS IN THE TARGET MACHINE 1. Log in at the target machine as the root user. 2. Install the Package You install packages with the 'swinstall' command. Install packages using the following command: /usr/bin/swinstall -s : DB2NSE where is the fully qualified hostname of the machine where you install DB2 Net Search Extender and is the full pathname of the DB2NSE72.pkg file Alternatively you can use SAM to locate the package file and select DB2NSE as the software to be installed. See you system documentation for details on how to use SAM. STEP 2 - ESTABLISH THE DB2 NET SEARCH EXTENDER INSTANCE 1. Stop the db2instance you want to work with using: db2stop 2. Ensure you are active as the root user. 3. Enter: cd /opt/IBMdb2nx/V7.1/instance 4. Run nxicrt as follows: ./nxicrt __________ where is an existing DB2 instance user ID. ___________ Running nxicrt creates the directory db2nx under the home directory of the DB2 instance user ID. Do not create additional files or directories under ~/db2nx; these files will be lost if the instance is deleted. A db2iupdt command will be completed during this call to ensure the transfer of the license file. 5. Logout. CURRENT RESTRICTIONS AND USEFUL HINTS _____________________________________ You can find the latest information on DB2 Net Search Extender problems and solutions as well as the latest fixpacks on the following Web page: http://www-4.ibm.com/software/data/db2/extenders/netsearch/support.html 1. The DB2 database manager option INTRA_PARALLEL is not supported. 2. The ACTIVATE and DEACTIVATE commands are not supported for indexes which have been created using the FASTRECOVERY option of the ENABLE TEXT COLUMN command. The indexes will automatically be available when the system is rebooted. The GET INDEX STATUS command always returns "The index is active." 3. When an ENABLE TEXT COLUMN command fails, some temporary files may remain in the index directory of the index. All files and directories that start with "gtr!" or "#" can be removed. The contents of the appropriate directories can also be deleted. 4. Searching for terms surrounded by quotation marks requires additional quatation marks in the search term provided to DB2 NetSearch Extender: Example: If you want to find documents containing the term "Hitchhikers Guide" including the quotation marks, you have to provide "\"\"\"Hitchhikers Guide\"\"\"" to DB2 Net Search Extender. The outer quotation marks are removed by the command shell of the operating system. Note that if queries are not issued on the command line, the outer quotation marks and the backslashes can be omitted. In which case, the search term is """Hitchhikers Guide""" and DB2 Net search Extender interprets the outer quotation marks as the start and end identifiers of the search term. The remaining term, ""Hitchhikers Guide"" is sent to the internal search engine which transforms it to "Hitchhikers Guide". 5. If you are using Net Search Extender with a Unicode (codepage = 1208, code set = UTF-8) database, you have to perform additional steps during index creation, or the search may fail with: SQL1131N DARI (Stored Procedure) process has been terminated abnormally. SQLSTATE=38503 There is an FAQ available on the DB2 Net Search Extender support Web page explaining how to handle this problem. 6. The semantic of the maxHitCount search parameter has been changed in this release. It is now used to specify the maximum possible result size for a ranked result list. The parameter only has an effect when using the rank Stored Procedures textSearch_r or textSearch_rt. The maximum value is 64000 and a value of 0 means no restriction. Using large datasets and high values of maxHitCount could lead to out of memory errors during search. To avoid this problem, reduce the maxHitCount value. Note that ranking of a result size is very time consuming as the document with the highest rank score will be returned first. The value maxHitCount parameter restricts the size of the result set. 7. The value of the maxIntermediateHitCount search parameter can be positive or negative. A positive value specifies the maximum count of term occurences. A negative value specifies the maximum count of documents. 8. Documents in the Hewbrew language must be stored in the DB2 database as UTF-8 documents. 9. When using a CLOB datatype, large amounts of memory may have to be allocated during indexing. This may cause a DES7101N "Memory could not be allocated." error. To handle this problem, a new environment variable DB2NX_ROWS_TO_FETCH was introduced which allows the number of rows to be scroll fetched to be selected. The number must be between 1 and 100 and if the environment variable is not defined, a default of 100 is used. 10. The maximum amount of shared memory used for one index can now be limited by the DB2NX_MAXSHAREDMEM environment variable. If the number of rows to be copied to the in-memory table or the amount of memory needed by the optimized columns exceeds this maximum, a DES7101N "Memory could not be allocated." error message appears. 11. If you have problems with the using the Full Licence Version of DB2 Net Search Extender you can list the current license with the call: db2licm -l To add the license again, call: db2licm -a db2nse.lic (the db2nse.lic file can be found in the install directory) On AIX and Solaris you can also update your db2 instance with: db2iupdt and check your nodelock file under /var/ifor or /var/lum If you are using the Try&Buy Version you need to upgrade to the full license version after the end of the 90 days evaluation period if you want to continue using Net Search Extender. 12. If you get the following error message during search: SQL0104N An unexpected token "VALUES) as " was found ... check that the startRow is not equal to the resultsize. The startRow default value is 0. 13. When installing a new version of DB2, rebind the two bind files against your database using: db2 connect to db2 bind desfpssp.bnd db2 bind desfpiiu.bnd The files are located in the /db2nx/bnd (UNIX) or in \bnd (Windows) directory. 14. The stored procedure is registered with the instance owner schema. In order to complete searches with a different userid, it is necessary to qualify your stored procedure with the schema of the instance owner. 15. The attribute value is related to the tag order during ENABLE TEXT COLUMN. For example, use 'attribute(1)' for searches against the first numeric column, attribute(2) for the second, and so on. 16. The relational operators & (AND), | (OR), & NOT ( AND NOT) can be used between numeric search terms. 17. When choosing names for indexes, databases, and columns make sure that they are not keywords of any of the db2nx commands, such as 'index' 'numeric' or 'optimize'. 18. If you receive an error DES7302N during search and the message says 'index does not exists' check whether you issued a numeric search, but did not enable a numeric index. 19. The length of the search argument is limited to 32000 bytes. In the previous fixpack and in version 7.2 it was limited to 1000 bytes. 20. The output variable totalDocs of the stored procedure does not always reflect the number of documents returned. In particular, where the query combines a textual search with an SQL statement, as the value of totalDocs is the the total number of documents qualified by the query term. The subsequent SQL statement can increase or decrease the result set without reflecting this in a change of the value of totalDocs. 21. The syntax diagram for the UPDATE command on page 77 of the documentation is incorrect. The DATABASE keyword has to be specified before the INCREMENTAL and COMMITCOUNT can only be used together with the INCREMENTAL keyword. 22. On Linux, the settings for shared memory limits (SHMMAX), can be updated at runtime, but are reset after a reboot. The root user can change the value for one segment by calling the command: echo 35651584 > /proc/sys/kernel/shmmax This value changes the shared segment size to 34MB 23. On Linux, to permanently establish shared memory limits (SHMMAX), change /usr/src/linux/include/asm-i386/shmparam.h and then recompile the kernel. 24. The following limits apply: - the maximum number of numeric columns you can index is 20 - the maximum number of columns you can optimize on is 25 - the maximum length of pathnames for the index and the temporary directory is 128 characters. - A maximum of 8388608 Mio documents can be stored for one index. 25. During enable text column, data are fetched from the table in blocks of 100 rows. This can lead to a memory allocation error. Set the environment variable DB2NX_ROWS_TO_FETCH to reduce this number. Valid values for this variable are between 1 and 100. Values above 100 are ignored, and 100 is used instead. 26. New command line parameter for db2nx. Usage: DB2NX UPDATE INDEX index [DATABASE database] RESET Use this parameter whenever the index is unavailable because of an unexpected error occurring during update or a reorg. 27. The TABLESPACE parameter can now also be used for enabling text columns without incremental index update. The value of the parameter is used as tablespace for the administrative tables of Net Search Extender. 28. Performance has been improved during indexing for indexes enabled for incremental index update. 29. When searching for terms containing wildcards, such as %e%, the expansion of the wildcard expression into candidate words for matches is limited to a maximum of 1000. Only matches against those are returned in order to avoid long-running queries and storage-allocation problems. WINDOWS PLATFORMS ONLY 1. Due to an internal limitation in DB2 Net Search Extender, only DB2 schema names with a maximum length of 8 characters work reliably together with DB2 Net Search Extender. Note that the default schema name is the logon UserID, which may in some cases be longer than 8 characters, for example, 'Administrator'. If the condition is not met, a "CLI0002W Data truncated. " error message is received when enabling a text column. 2. After system shutdown or nxstop call "nxclean databasename", or you will get wrong information using: "db2nx get index status ...". 3. NT cannot currently handle a system load with more than 40 parallel DB2 dari processes and in-memory tables greater then 500 MB. A "index not activated" message will be displayed. To avoid this message, work with datasource = 1 and do not optimize on columns. 4. Using UNIX notation for path specification, such as d:/myindex/ on NT leads to index files not being correctly cleaned up. 5. Do not use blanks in the DB2 Net Search Extender installation path. 6. If your database contains columns with CLOBs, increase the DB2 parameter APP_CTL_HEAP_SZ according to the size of the CLOBs. UNIX PLATFORMS ONLY 1. After instance creation only the .profile will be updated. If the instance owner works with a UNIX shell not using the .profile, the following environment variables should be set: DB2NX_INSTOWNERHOMEDIR=// PATH=$PATH:DB2NX_INSTONWERHOMEDIR/db2nx/bin where $PATH = your existing PATH variable 2. If you put text data into the "In Memory Tables" the default limits for the user should be increased to avoid an out of memory error during indexing. On AIX, complete this change in the /etc/security directory and alter the following limits file values: data = -1 rss = -1 stack = -1 to not impose any usage limits on these resources. However, if your system environment requires it, then limit them appropriately,. For HP-UX, Solaris, and Linux refer to the operating system documentation on how to achieve the same effect. 3. Incremental index update tries to allocate a maximum amount of shared memory during enable text column. This can be limited by setting the environment variable DESMAXSHAREDMEM. The value is set in bytes. This allocation problem also occurs when using the FASTRECOVERY option. 4. Bus error : During Incremental index update, a bus error can occur when there is no space left on disk for FASTRECOVERY. See point 3 to reduce Shared Memory usage which is placed on disk for the FASTRECOVERY option. LINUX/390 ONLY In comparison to the workstation platforms, the following languages are not actively supported. Documents for those languages must be stored as UTF-8 documents in the DB2 database: Hebrew, Greek, Russian, Turkish FIXES PROVIDED WITH THIS FIXPACK ________________________________ APAR# Description ------------------------------------------------------------------------ IC31454 Problems with NULL parameters for index directories IC31455 Section support for UTF-8 documents fails IC31457 Negative startRowNumber/maxRowstoReturn->DARI ends abnormally IC31208 Running query with dataSource parameter set to 1 does not work IC31458 Searching for term surrounded by double quotation marks IC31481 NXSampleRank raised errors on Windows NT IC31482 Unexpected error SQL0804N when indexing CLOBS (see usage of DB2NX_ROWS_TO_FETCH environment variable above) IC31349 Incomplete section support when running incremental index update IC31351 Wrong numering of tags, optimized and/or numeric columns in the output of the get index status command IC31348 GTR crashes if search term contains too many wildcards TRY & BUY _________ If you are using the Try & Buy version you can use the product for 90 days for evaluation purposes. After that no further administrative operations are possible. For an upgrade to a full license please contact your IBM representative. NOTICES _______ This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation 500 Columbus Avenue Thornwood, NY 10594 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation W92/H3 555 Bailey Avenue P.O. Box 49023 San Jose, CA 95161-9023 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. TRADEMARKS __________ The following terms are trademarks of the IBM Corporation in the United States or other countries or both. +-------------------------------------+-------------------------------------+ | AIX | DB2 Universal Database | +---------------------------------------------------------------------------+ | DB2 | IBM | +-------------------------------------+-------------------------------------+ | DB2 Net Search Extender Net.Data | +-------------------------------------+-------------------------------------+ Microsoft, Windows, Windows NT, and the Windows logo are trademarks or registered trademarks of Microsoft Corporation. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company limited. Other company, product, and service names may be trademarks or service marks of others.