The etx_HiliteDoc() function

The etx_HiliteDoc() function returns the location of a clue in a document.

Syntax

etx_HiliteDoc (document, index_name, clue)


Element	Purpose	Data type
document	Specifies the name of the column in the table that contains the document for which you want highlighting information.	One of BLOB, CLOB, LVARCHAR, VARCHAR, IfxMRData, or IfxDocDesc. You cannot specify columns of type CHAR.
index_name	Specifies the name of the search index.	LVARCHAR
clue	Specifies the search text.	Either a quoted clue or a Row() expression that contains the clue and optional tuning parameters. The clue can either be a quoted string or a document stored in an IfxDocDesc data type.

Return type

The etx_HiliteDoc() function returns etx_HiliteType, a named row data type defined by the module.

The etx_HiliteDoc() function returns a filtered document in the viewer_doc field of the returned etx_HiliteType value only if you have previously specified FILTER="STOP_ON_ERROR" or FILTER="CONTINUE_ON_ERROR" when you created the etx index.

If you previously created the etx index without filtering and you execute the etx_HiliteDoc() function on a document that contains proprietary formatting information (such as a Microsoft™ Word document), the viewer_doc field contains the unfiltered document in its original form. The vec_offset field contains offset values relative to the unfiltered document, which might include extra non-text characters. To avoid indexing binary data (which is not useful in etx searches), filter your documents before they are indexed.

For more information about the etx_HiliteType row data type, refer to The etx_HiliteType data type.

Usage

You can use the etx_HiliteDoc() routine in a select list to highlight occurrences of a clue in an individual document you have retrieved with an etx_contains scan.

You cannot use this routine by specifying EXECUTE FUNCTION.

See The etx_ViewHilite() routine for information about a related routine that allows you to view the highlighted text.

Example

Suppose you have retrieved a few rows with the following query:

SELECT id FROM videos
    WHERE etx_contains(description, Row('multimedia','SEARCH_TYPE=PHRASE_APPROX'
));

You can use the etx_HiliteDoc() routine to retrieve highlighting information for one or more of the documents you retrieved with the previous query:

SELECT etx_HiliteDoc(description, 'desc_idx1',
    Row('multimedia', 'SEARCH_TYPE=PHRASE_APPROX'))
    FROM videos
    WHERE id = 1;

See The etx_ViewHilite() routine for an example of how you can view the highlighted text returned by this query.