The etx_GetHilite() function

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

Syntax

etx_GetHilite (document, hilite_info)


Element	Purpose	Data type
document	Name of the column in the table that contains the document for which you want highlighting information	One of BLOB, CLOB, LVARCHAR, CHAR, VARCHAR, IfxMRData, or IfxDocDesc
hilite_info	Name given to the statement local variable (SLV) of the etx_contains() operator that returns internal highlighting information	etx_ReturnType

Return type

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

The etx_GetHilite() 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_GetHilite() 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

The etx_GetHilite() function is used to return the location of a clue in a document or search text. This is referred to as highlighting.

You can only use the etx_GetHilite() function in the SELECT list of a query. It has two required parameters. The first is the name of the column that contains the document to be highlighted. The second is the name given to the SLV of the etx_contains() operator that executes the search.

The etx_GetHilite() function does not have as input the clue or search string to be highlighted. The function uses the clue specified as the second parameter to the etx_contains() operator as the highlight string.

The etx_GetHilite() function returns highlighting information through the row data type etx_HiliteType. This row data type consists of two fields that contain the two parts of the highlighting information: vec_offset and viewer_doc.

The vec_offset field contains offset information about the location of the clue in the document in the form of ordered pairs of integers. The integers in a pair are separated by a blank. The first integer in the pair describes the offset of an instance of the clue in the document, and the second integer describes the length of the highlight. The first character in a document is assumed to have an offset of 0. The viewer_doc field contains the text document itself.

To view highlighted text contained in the etx_HiliteType object, use the etx_GetHilite() function with a function that can manipulate the etx_HiliteType data. See The etx_ViewHilite() routine for an example.

You can also use standard routines, such as ifx_lo_open() and ifx_lo_read(), or DataBlade® API large object routines, such as mi_lo_open() and mi_lo_read(), to manipulate etx_HiliteType objects. See the HCL OneDB™ ESQL/C Programmer's Manual and the HCL OneDB DataBlade API Programmer's Guide for information about these routines.

Important: If you use the etx_GetHilite() function in a query that returns more than one row, the function executes once for each row. This means that each row has its own highlighting information, contained in the etx_HiliteType row data type returned by the etx_GetHilite() function. This highlighting information pertains only to the document contained in the row, not to any other document.

Important: If you use the etx_GetHilite() routine to highlight the result of a phrase search, all instances of each word in the clue are highlighted, not just instances of the entire phrase. You execute a phrase search by setting either of the tuning parameters

SEARCH_TYPE
= PHRASE_EXACT

or SEARCH_TYPE = PHRASE_APPROX.

For example, if you execute a phrase search for the clue walk the dog and use the etx_GetHilite() routine to highlight the result, all instances of the individual words walk and dog (and the, if stopwords are significant) are highlighted in the resulting document, even if the instances are not close to each other.

Example

The following example shows a simple use of the etx_GetHilite() function:

SELECT etx_GetHilite (description, rc) FROM videos
    WHERE etx_contains(description, 
    'multimedia',  rc # etx_ReturnType);

The function etx_GetHilite() is executed on the description column, the same column being searched with the etx_contains() operator. The SLV declared in the etx_contains() operator, rc, is passed as the second parameter to the etx_GetHilite() function. The string to be highlighted is the clue of the etx_contains() operator, multimedia.