Documentation
(C) IBM Corp. 1996, 1999

Text Extender: Administration and Programming


Chapter 12. Return codes

This chapter lists the codes that are returned by the Text Extender API in response to a function call. They are listed in alphabetic order.

All Text Extender API calls return a numeric return code as the C function value. The return codes are defined in the include file DES_EXT.H provided with Text Extender.

The Text Extender API intercepts error situations and reports error conditions with a return code.

Applications that call Text Extender API functions should always check the return code before trying to process any other output parameters. The return codes possible with each call are listed with their parameters in Chapter 11, API functions for searching and browsing.

In some cases, incorrect input such as an obsolete session pointer can cause an abnormal end condition in the API services that cannot be intercepted by Text Extender.

RC_ALLOCATION_ERROR 

Explanation: Cannot allocate storage for internal use.

What to do: Ensure that there is sufficient memory available.

RC_FILE_IO_PROBLEM 

Explanation: Text Extender could not read or write a file.

What to do: Check that there is sufficient disk space and memory available at the server. Check that the environment variables and the text configuration settings are set correct.

RC_INVALID_BROWSE_INFO 

Explanation: The browse information returned by DesGetSearchResultTable or by DesGetBrowseInfo and used as input for DesStartBrowseSession is not valid.

What to do: Check whether a programming error overrides the browse information.

RC_INVALID_BROWSE_OPTION 

Explanation: The browse option in DesGetSearchResultTable is not valid.

What to do: Ensure that the option is BROWSE or NO_BROWSE.

RC_INVALID_MATCH_OPTION 

Explanation: The match options used in DesOpenDocument is not valid.

What to do: Check that the option is FAST or EXTENDED.

RC_INVALID_PARAMETER 

Explanation: One of the input parameters is incorrect.

What to do: Read the error message returned by Text Extender to determine the cause.

RC_INVALID_SEARCH_OPTION 

Explanation: The search option in DesGetSearchResultTable is not valid.

What to do: Ensure that the option is DES_TEXTHANDLEONLY, DES_RANK, DES_MATCH, or DES_RANKANDMATCH.

RC_INVALID_SESSION 

Explanation: The session pointer specified in the current service call is incorrect or obsolete.

What to do: Save any information that can help to find the cause of the error, then end the application.

RC_NO_BROWSE_INFO 

Explanation: No browse information is returned by Text Extender. This is because the search argument resulted in an empty search result. This is not an error.

What to do: No action necessary.

RC_PARSER_INVALID_ESCAPE_CHARACTER 

Explanation: The search criteria contains an incorrect escape character. This error is reported if a blank is used as an escape character or if, for one word or phrase, more than one escape character is specified in the search criteria. Example: ESCAPE " " or ESCAPE "#$".

What to do: Check the syntax of the search argument, and try again.

RC_PARSER_INVALID_USE_OF_ESCAPE_CHAR 

Explanation: The escape character syntax in the search criteria cannot be interpreted.

What to do: Check the escape character syntax. For example, if $ is the specified escape character, the word or phrase can contain only $$, $_ or $%, where _ and % are the two masking symbols.

RC_PARSER_SYNTAX_ERROR 

Explanation: The search criteria syntax cannot be interpreted.

What to do: Check the syntax of the search argument, by referring to Chapter 10, Syntax of search arguments.

RC_RESULT_TABLE_NOT_EXIST 

Explanation: You are trying to store the result of a search in a table that does not exist.

What to do: Create a result table as shown in Figure 14.

RC_SE_BROWSER_TIME_OUT 

Explanation: The browse process was started but did not respond in an acceptable time. Text Extender then canceled the pending process.

This error can occur when your system does not have enough storage space or is overloaded.

What to do: Terminate the browse session by calling DesEndBrowseSession, free allocated storage by calling DesFreeBrowseInfo, and try again.

RC_SE_CAPACITY_LIMIT_EXCEEDED 

Explanation: The requested function cannot be processed. There is insufficient memory or disk space.

What to do: End the program and check your system's resources.

RC_SE_COMMUNICATION_PROBLEM 

Explanation: Communication with the Text Extender server failed. The error could be caused by a lack of storage space or by an incorrect installation of Text Extender.

What to do: Save any information that can help to find the error, then end the application.

RC_SE_CONFLICT_WITH_INDEX_TYPE 

Explanation: The linguistic specification of the search term of the query does not correspond to the type of index. For example, PRECISE FORM OF cannot be used with a linguistic index. The default linguistic specification is used as shown in Table 5.

What to do: Adapt your application to prevent the specification of query options that conflict with the index type.

RC_SE_DICTIONARY_NOT_FOUND 

Explanation: Text Extender linguistic services cannot find the dictionary files. The query is processed without linguistic support. The dictionary files corresponding to the specified language code(s) are not in the expected path.

What to do: You can continue to make API calls. For UNIX, check that the required dictionary is in the path {DB2TX_INSTOWNERHOMEDIR}/db2tx/dicts. For OS/2, check that the required dictionary is in the path specified in the text configuration setting DB2TX_DATA. If necessary, install the required dictionary.

RC_SE_DOCMOD_READ_PROBLEM 

Explanation: When a Text Extender instance is created, a document model file called desmodel.ini is put in the instance directory. When you create an index, a desmodel.ini file is also put in the index directory IXnnnnnn. This document model file could not be read.

What to do: Check that a document model file exists and that it is in the correct directory.

RC_SE_DOCUMENT_NOT_ACCESSIBLE 

Explanation: The requested text document is found, but is currently not accessible.

What to do: Check whether the document is accessed exclusively by another task or user.

RC_SE_DOCUMENT_NOT_FOUND 

Explanation: The requested text document was not found. The most likely cause is that a text document has been deleted from storage, but has not yet been removed from the Text Extender index. This can also occur if you are trying to browse a document identified by a damaged handle.

What to do: In most cases, you can ignore this return code. It will no longer be displayed after the next index update.

If it is persistent, check that your application program is passing the found handle correctly for browsing.

RC_SE_EMPTY_INDEX 

Explanation: The Text Extender index corresponding to the handle column addressed by the search request is empty. Either no text documents have been added to this index or all text documents have been removed from it.

This can occur when a text column has been enabled, but the documents in the column have not yet been indexed. That is, you specified in the ENABLE TEXT COLUMN command to create the index later, at a time determined by the periodic indexing settings.

This can also occur when a text table has been enabled to create an empty common index for all text columns, but none of the text columns has been enabled.

What to do: If ENABLE TEXT TABLE has been used to create an empty common index for all text columns, run ENABLE TEXT COLUMN for at least one of the text columns that contain text to be searched. In this command, you can determine whether the index is created immediately, or at a time determined by the periodic indexing settings.

Run GET INDEX STATUS to check that the index was built successfully.

RC_SE_EMPTY_QUERY 

Explanation: The specified search criteria was analyzed and processed linguistically by Text Extender. Either a programming error caused a query to be made containing no search terms, or all search terms were stop words (words not indexed by Text Extender) that are removed from a query. The result was no search terms.

What to do: Reword the query. If the problem persists, check for a programming error.

RC_SE_END_OF_INFORMATION 

Explanation: This is not an error. The end of the document has been reached. No further information is available for DesGetMatches.

What to do: Use this return code to end the iterative processing of the document with DesGetMatches.

RC_SE_FUNCTION_DISABLED 

Explanation: The requested function called a Text Extender function that has been prevented by the administrator.

What to do: Ask your administrator for assistance. It may be necessary to stop and restart Text Extender (txstop/txstart).

RC_SE_FUNCTION_IN_ERROR 

Explanation: The requested function has been locked due to an error situation on the Text Extender server. The API call cannot be processed.

What to do: Check the index status. Check the available space in the index directory. Reset the index status and retry the command.

RC_SE_INCORRECT_HANDLE 

Explanation: A handle specified in an input parameter such as browse session handle is not valid. It must be a handle that was returned by a previous call and that is not obsolete.

What to do: Save any information that can help to find the cause of the error, then terminate the session by calling DesEndBrowseSession.

Check whether a programming error produced an incorrect handle.

RC_SE_INDEX_DELETED 

Explanation: The Text Extender index being accessed is deleted.

What to do: Contact the Text Extender administrator to recreate the index.

RC_SE_INDEX_NOT_ACCESSIBLE 

Explanation: The Text Extender index cannot be accessed and the current call cannot be processed.

What to do: Ask the Text Extender administrator to check the accessibility of the index.

RC_SE_INDEX_SUSPENDED 

Explanation: Text Extender received a request relating to a Text Extender index that was suspended from another session or from the current session.

What to do: Ask the Text Extender administrator to check the status of the index.

RC_SE_INSTALLATION_PROBLEM 

Explanation: Text Extender has encountered an installation problem.

What to do: Check the current setting of the environment variables DB2INSTANCE, DB2TX_INSTOWNER, DB2TXINSTOWNERHOMEDIR. Use descfgcl -d and descfgsv -d -i txinsnnn to check your search service configuration.

RC_SE_IO_PROBLEM 

Explanation: An error occurred when the server attempted to open or read one of its index files. This can be due to one of the following:

An unintentional action by the administrator, such as the deletion of a Text Extender index file

Incorrect setting in the text configuration.

What to do: Terminate the application. Check with the administrator that:

All files of the current Text Extender index exist

The text configuration settings are correct.

RC_SE_LS_FUNCTION_FAILED 

Explanation: A function that accessed the database to retrieve text documents for browsing failed. Either the database is no longer accessible to the user, or the user is not authorized for the text table.

What to do: Check that the input to the function, such as the user ID, is correct. Check that the database is accessible and that the user is authorized for the task.

RC_SE_LS_NOT_EXECUTABLE 

Explanation: A function that is trying to access the database to retrieve text documents for browsing cannot be executed.

What to do: Check that Text Extender is installed correctly. If the problem persists, contact your IBM representative.

RC_SE_MAX_OUTPUT_SIZE_EXCEEDED 

Explanation: An unusually large number of matches have been found. the size of the browse information has exceeded the maximum that can be handled. The request cannot be processed.

What to do: Either make the query more specific or ensure that more system memory is available.

RC_SE_MAX_NUMBER_OF_BUSY_INDEXES 

Explanation: The requested function has been prevented by the search service, because the maximum number of indexes is currently active.

What to do: Reissue the function call after a short period of time. In general, the problem is only temporary.

RC_SE_NO_DATA 

Explanation: This is not an error. No text document matches the search criteria. If you request browse information, no browse information is returned. No storage is allocated for the browse information.

What to do: No action is necessary.

RC_SE_NOT_ENOUGH_MEMORY 

Explanation: There is not enough storage space on the client or on the server system. The current request cannot be processed.

What to do: Release storage space and end the application.

RC_SE_PROCESSING_LIMIT_EXCEEDED 

Explanation: The current search request exceeded the maximum result size or the maximum processing time specified for your client/server environment. The request was canceled.

What to do: Make the search request more specific. Consider increasing the maximum processing time.

RC_SE_QUERY_TOO_COMPLEX 

Explanation: The specified query is too complex.

What to do: Adapt your application to prevent excessive use of masking characters and synonyms.

Excessive use of masking symbols or excessive use of the SYNONYM option can expand a query to a size that cannot be managed by Text Extender.

RC_SE_REQUEST_IN_PROGRESS 

Explanation: A Text Extender browse API service was called while another browse API request was active for the same session.

What to do: End the session by calling DesEndBrowseSession and free storage by calling DesFreeBrowseInfo.

The Text Extender browse API does not support concurrent access to the same browse session.

All applications running concurrently in the same process should handle their own browse sessions.

RC_SE_SERVER_BUSY 

Explanation: The Text Extender client cannot currently establish a session with the requested Text Extender server, or the Text Extender server communication link was interrupted and cannot be re-established.

The Text Extender server has been started correctly, but the maximum number of parallel server processes was reached.

What to do: If this is not a temporary problem, change the communication configuration on the Text Extender server.

RC_SE_SERVER_CONNECTION_LOST 

Explanation: The communication between client and server was interrupted and cannot be re-established.

The Text Extender server task may have been stopped by an administrator or the server workstation may have been shut down.

What to do: Check whether either of these conditions have occurred, and have them corrected.

RC_SE_SERVER_NOT_AVAILABLE 

Explanation: The Text Extender API services could not establish a session with the requested Text Extender server.

The Text Extender server may not have been started.

What to do: Check that the Text Extender server has been started correctly. If the error persists, there is an installation problem.

RC_SE_STOPWORD_IGNORED 

Explanation: This informational code is returned when the specified query contained at least one search term consisting only of stop words. The search term was ignored when processing the query.

What to do: You can continue to issue API calls. Avoid using stop words in Text Extender queries.

RC_SE_UNEXPECTED_ERROR 

Explanation: An error occurred that could be caused by incorrect installation of Text Extender.

What to do: End the application, saving any information that may help to find the cause of the error.

RC_SE_UNKNOWN_INDEX_NAME 

Explanation: The name of the text index associated with a text column is part of the handle.

What to do: Ensure that the handle you use as input to DesGetBrowseInfo is correct.

RC_SE_UNKNOWN_SECTION_NAME 

Explanation: A specified section name is not part of a model specified in a document model file, or of the default model used.

What to do: Specify a section name that is part of the specified model or the default model.

RC_SE_UNKNOWN_SERVER_NAME 

Explanation: The name of Text Extender server is part of the handle.

What to do: Ensure that the handle you use as input to DesGetBrowseInfo is correct.

RC_SE_WRITE_TO_DISK_ERROR 

Explanation: A write error occurred that could be caused by a full disk on the Text Extender server workstation, or by incorrect installation of Text Extender.

What to do: End the application, saving any information that may help to find the cause of the error. Check that there is enough disk space available at the server.

RC_SQL_ERROR_WITH_INFO 

Explanation: An SQL error occurred. An error message is returned.

What to do: Check the error message returned by Text Extender for more information, such as the SQL error message, SQLState and native SQL error code.

RC_SQL_ERROR_NO_INFO 

Explanation: An SQL error occurred. No error message is returned.

RC_TEXT_COLUMN_NOT_ENABLED 

Explanation: The specified handle column is not a column in the table you specified.

What to do: Check whether the handle column name you specified is correct. Ensure that the text column in that table has been enabled.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]