4
Using interMedia Text in Oracle Portal

This chapter provides information on setting up built-in search capabilities by using interMedia Text in Oracle Portal.

This chapter contains the following sections:

4.1 Searching in Oracle Portal

As a user of Oracle Portal, you can perform a search using Oracle Portal's search capabilities. There are three levels of search provided with Oracle Portal: basic search, advanced search, and interMedia Text search.

4.1.1 Basic search

Search is performed on item attributes such as display name, description, and keywords of items, as well as the display name and description of folders, categories, and perspectives.

Use basic search to search the current content area for items, folders, categories, and perspectives that contain specific words.

See also:
"Performing a Basic Search" and "Setting up the search feature" topics in the Oracle Portal Online Help content area which is installed with the Oracle Portal.

4.1.2 Advanced search

If you have advanced search capabilities enabled in Oracle Portal, you can:

Find content that contains any of the specified words.
Search across a content area other than the current content area, or across all content areas.
Restrict the search to a particular folder, category, perspective, item type, or attribute.
Search to perform near, soundex, and fuzzy searches.

See also:
"Performing an Advanced Search" topic in the Oracle Portal Online Help content area which is installed with the product.

4.1.3 interMedia Text search

You use Oracle8i interMedia Text to build a text query application. Oracle8i interMedia Text provides search, retrieval, and viewing capabilities for text. In addition, interMedia Text provides concept searching and theme analysis of English language documents.

To index and query, you use standard SQL with a domain index of type ctxsys.context. You can also use the supplied interMedia Text PL/SQL packages for advanced features such as document presentation and thesaurus maintenance.

If interMedia Text is installed and enabled on Oracle Portal, a basic or advanced search also tries to find the specified search words in the content of uploaded documents and the first pages of URL items.

For example, Oracle Portal searches on files such as PDF, PowerPoint, and Word as well as searches on URLs, text, and HTML.

See also:

Oracle Portal Online Help content area about support for interMedia rich content such as GIF, JPG, AU, WAV, MP3, QT, and REAL in Oracle Portal reports and forms.

"Oracle8i interMedia Text Reference", Release 2 (8.1.6), (A77063-01).

4.1.4 Viewing interMedia Text search results

When interMedia Text is enabled in Oracle Portal and an index is created, a user can perform a search of all uploaded items of type file, text, or URL. From the search page, you can choose any of the following ways to view the resulting search items:

View an HTML version of the file.
View an HTML version of the file with search terms highlighted in any color or font set by the Oracle Portal administrator.
View major themes in a chart (document theme analysis).
View a short summary about the file's content (gist).

See also:

Oracle Portal Online Help content area, "Setting up interMedia Text searching" topic.

4.2 Prerequisites

Note::
You must be logged on as an Oracle Portal administrator to configure interMedia Text, and create, alter, update, and drop interMedia Text indexes.

Before using interMedia Text into Oracle Portal, you must perform the following tasks:

Install and configure the Oracle8i database with the interMedia Text option by running the Oracle Universal Installer (OUI) and the Database Configuration Assistant. See the Oracle8i documentation for more information about installing and configuring an Oracle8i database to use interMedia Text.
Install Oracle Portal 3.0 according to the instructions provided in the Oracle9i Application Server Installation Guide."
Create an Oracle Portal content area using the Content Area Creation Manager. See the "Creating a content area" topic in the Oracle Portal Online Help content area.
If this database was an existing ConText site, make sure to remove text_enable from the init.ora file. It is no longer used in Oracle8i, and will actually prevent 8i from operating properly. The error, "cannot find package DR_REWRITE" may appear.

4.2.1 interMedia Text on UNIX

For the interMedia Text feature to work, the following UNIX environment variables need to be set before starting the Oracle8i database and Net8 Listener.

Korn Shell (ksh):

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/ctx/lib
export LD_LIBRARY_PATH

C-Shell (csh):

setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${ORACLE_HOME}/ctx/lib

4.3 Setting up interMedia Text Searching

There are four main steps for setting up interMedia Text in Oracle Portal:

Note:
To obtain additional information for any Oracle Portal configuration page, click the small Help icon Text description of helps.gif follows.
Text description of the illustration helps.gif displayed on the page.

4.3.1 Step 1: Setting up the Global page settings

The first step requires you to configure the global page settings in the following way:

In the Services portlet, click Global Settings. By default, the Services portlet is located on the Oracle Portal home page's Administer tab.

Figure 4-1 Global page settings - Proxy Server

Text description of interm1.gif follows.

Text description of the illustration interm1.gif

In the Proxy Server section:

Enter the host name of your proxy server for the HTTP Server.

Note: Do not prefix http:// to the proxy server name.
Enter the domains that you do not want redirected to the proxy server.
Enter the maximum amount of time (in seconds) that a connection should be attempted before timing out.

Click OK.

4.3.2 Step 2: Enabling interMedia Text searching

Before creating the interMedia Text indexes, you'll have to configure the interMedia Text settings in Oracle Portal in the following way:

In the Services portlet, click Search Settings. By default, the Services portlet is located on the Oracle Portal home page's Administer tab.

Figure 4-2 Services portlet - interMedia Text properties

Note:
If you see the message, "interMedia Text is not installed", interMedia Text was not installed with the database and is not available for your content areas. Arrange with your database administrator to have interMedia Text installed.

Text description of interm2.gif follows.

Text description of the illustration interm2.gif

Select Enable interMedia Text Searching to make interMedia Text searching available in your content areas.

Select Enable Themes And Gists to create a theme and gist for each item returned by the search.

A theme shows the nouns and verbs that occur most frequently within the item.
A gist displays a brief summary of the item, derived from how frequently those nouns and verbs appear.

Note:
Themes and gists are not available for all languages.

In the Highlight Text Color list, choose the color to highlight the search words in the HTML renditions of the items returned by the search.

In the Highlight Text Style list, choose the style to apply to the search words in the HTML renditions of the items returned by the search.

Click OK.

Now that you've enabled interMedia Text, you'll need to create a new interMedia Text index.

4.3.3 Step 3: Creating an interMedia Text index

To create an interMedia Text index:

Make sure that you have configured the interMedia Text settings in Oracle Portal as discussed in the previous section, Section 4.3.2, "Step 2: Enabling interMedia Text searching".
In the Specify interMedia Text Search Properties section, as shown on the previous page, click Create Index.

Notes:

The time required for creating indexes varies depending on the number of items you have in your content area.

If properly run, the message "Index created" appears and the interMedia Text index is created on the server.

If you fail to create the index, check that your system has met all the requirements in Section 4.2, "Prerequisites".

You can also run the following command in SQL*Plus. Log on using the user name and password for the schema that owns the Oracle Portal content area. For example, if the schema is named "SCOTT", log on with user name and password, "SCOTT".

ctxcrind.sql

The following interMedia Text indexes are created:

Table 4-1 interMedia Text indexes created

Index Name Description

WWSBR_CORNER_CTX_INDX

Index based on folders.

WWSBR_DOC_CTX_INDX

Index based on the items' filename.

WWSBR_PERSP_CTX_INDX

Index based on perspectives.

WWSBR_THING_CTX_INDX

Index based on items.

WWSBR_TOPIC_CTX_INDX

Index based on categories.

WWSBR_URL_CTX_INDX

Index based on the items' Uniform Resource Locator (URL).

Index Name	Description
WWSBR_CORNER_CTX_INDX	Index based on folders.
WWSBR_DOC_CTX_INDX	Index based on the items' filename.
WWSBR_PERSP_CTX_INDX	Index based on perspectives.
WWSBR_THING_CTX_INDX	Index based on items.
WWSBR_TOPIC_CTX_INDX	Index based on categories.
WWSBR_URL_CTX_INDX	Index based on the items' Uniform Resource Locator (URL).

4.3.4 Step 4: Maintaining your index

interMedia Text lets you create a text index (an inverted index) on documents stored in the database. Updating an inverted index requires heavy processing, so changes to a text column are queued and processed in batch. This is referred to as synchronizing the text index.

interMedia Text gives you full control over how often each text index is synchronized. You can choose to synchronize every five seconds, for example, if it is important for your application to reflect text changes quickly in the index. Or, you can choose to synchronize once a day, for more efficient use of computing resources and a more optimal index.

After creating your interMedia Text index, you'll need to consider a strategy for maintaining the index. For example, if you have many inserts, updates, or deletes (DML) throughout the day, consider synchronizing the interMedia Text index on a daily basis.

4.3.4.1 Synchronizing the interMedia Text index

The following example, assumes that you've installed ctx_schedule.

Log on to SQL*Plus with the appropriate username and password:

Enter the following commands:

exec ctx_schedule.startup ( 'ex1_index', 'SYNC', 1 ) ; 
exec ctx_schedule.startup ( 'ex1_index', 'OPTIMIZE FAST', 120 ) ;

In this example, the index ex1_index is synchronized every minute, and optimized every two (2) hours. This is true even if the database is shutdown and restarted.

4.3.4.2 Stopping index maintenance

Log on to SQL*Plus with the appropriate username and password:
Enter the following commands:
```
exec ctx_schedule.stop ( 'ex1_index' ) ; 
exec ctx_schedule.stop ( 'ex1_index', 'OPTIMIZE FAST' ) ; 
```
ctx_schedule.stop assumes that the operation to be stopped is 'SYNC', unless you specify otherwise.

Note:
If you want new text to be searched immediately (every five seconds), consider using the drbgdml.sql script located in:
$ORACLE_HOME/ctx/sample/script/drbgdml.sql.

See also:
For interMedia Text technical papers, training materials, code samples, and so on, visit:
http://technet.oracle.com/products/intermedia

4.4 Updating an interMedia Text Index

Index maintenance is necessary after your application inserts, updates, or deletes documents in your base table. If your base table is static, that is, you do no updating, inserting or deleting of documents after your initial index, you do not need to update your index.

However, if you perform DML (inserts, updates, or deletes) on your base table, you must update your index. You can synchronize your index manually with ALTER INDEX. You can also run the Context Server in the background which synchronizes the index automatically at regular intervals. See "Starting the Context Server" for more information.

To update your index, enter the following command:

ALTER INDEX [schema.]index REBUILD [online] [parameters (paramstring)] ('SYNC');

where

[online]

Optionally specify the online parameter for non-blocking operation, which allows the index to be queried during an ALTER INDEX synchronize or optimize operation. You cannot specify online for replace, resume, or when adding stopwords or stop sections.

PARAMETERS (paramstring)

Optionally specify paramstring. If you do not specify paramstring, Oracle rebuilds the index with existing preference settings.

The syntax for paramstring is as follows:

paramstring = 'replace [datastore datastore_pref] 
                       [filter filter_pref] 
                       [lexer lexer_pref] 
                       [wordlist wordlist_pref] 
                       [storage storage_pref] 
                       [stoplist stoplist] 
                       [section group section_group]
                          [memory memsize]

           |    resume [memory memsize]
           |    optimize [fast | full [maxtime (time | unlimited)]
           |    sync [memory memsize]
           |    add stopword word
           |    add zone section section_name tag tag
           |    add field section section_name tag tag [(VISIBLE | INVISIBLE)]
           |    add attr section section_name tag tag@attr
           |    add stop section tag'

See also:
"Oracle8i interMedia Text Reference" included with your Oracle8i documentation.

4.5 Dropping an interMedia Text Index

In situations where you know that a significant amount of new content has been added to your content area, you might consider dropping and recreating your indexes. This of course is a very time-consuming and resource-intensive operation, so you would want to plan this task during non-business hours.

You can drop interMedia Text indexes in the following ways:

In the Services portlet, click Search Settings. By default, the Services portlet is located on the Oracle Portal home page's Administer tab.
In the interMedia Text Properties section, click Drop Index.

The interMedia Text index is dropped from the server.

Notes:

You can also drop an interMedia Text Index, by running the following script in Oracle SQL*Plus and logging in as the Oracle Portal schema owner:

ctxdrind.sql

4.6 Starting the Context Server

As an alternative to the ALTER INDEX command, you can also run the Context Server (ctxsrv) in the background which synchronizes the index automatically at regular intervals to update your index.

IMPORTANT:
Every time you restart your machine, you will have to restart the Context Server in the following way.

To create a bat file to start the Context Server:

In Windows NT, open Notepad to create a text document.

On UNIX, open an editor such as the "vi" editor.
Enter the following:
```
ctxsrv -user ctxsys/ctxsys
```
When saving the file, enter "StartContext.bat" as the filename (include the double-quotes in the filename). Save the file onto your Desktop (Save In field).

Figure 4-3 Saving StartContext.bat file

Text description of the illustration saveas.gif

Make sure that your database is running before you start the Context Server.

Double-click the StartContext.bat file icon on your Desktop to start the Context Server. A system command window opens and the Text description of baticon.gif follows.

Text description of baticon.gif follows.

Text description of the illustration baticon.gif file is run.

Figure 4-4 DOS box of Context Server startup

Text description of intermed.gif follows.

Text description of the illustration intermed.gif

4.7 Setting up your Environment for interMedia Text

Note:
If you are running Oracle8i Release 8.1.7, you can ignore this section as the database does not use external procedures to perform document filtering.

For Oracle8i Release 8.1.6.2, you must configure the listener.ora and tnsnames.ora files in your Oracle8i Home directory to support these external procedures. The listener.ora and tnsnames.ora files on your computer should look similar to the following examples:

4.7.1 listener.ora

The following lines define a complete listener definition in your listener.ora file.

LISTENER =
   (DESCRIPTION_LIST =
   (DESCRIPTION =
   (ADDRESS_LIST =
   (ADDRESS = (PROTOCOL = IPC) (KEY = EXTPROC0))
                    )
   (ADDRESS_LIST =
   (ADDRESS = (PROTOCOL = TCP) (HOST = oracle) (PORT=1521))

4.7.1.1 System ID

If you want to add a system identifier (SID) name of PLSExtProc and a program name of EXTPROC in the server's listener.ora file, you can insert the following in the SID_LIST_LISTENER definition:

SID_LIST_LISTENER =
  (SID_LIST =
  (SID_DESC = ...

  (SID_DESC =
  (SID_NAME=PLSExtProc)(ORACLE_HOME=/oracle/db/dev118)
  (PROGRAM=extproc)






Notes:






EXTPROC0 and PRESENTATION=RO ends with the letter "o" not the number zero.


SID=PLSExtProc is non-negotiable.

4.7.2 tnsnames.ora

Add the following lines to the end of your tnsnames.ora file, to add a net service name description entry for EXTPROC0 in the server's tnsnames.ora file, using SID rather than SERVICE_NAME in the CONNECT_DATA section. For example:

          extproc_connection_data =
             (DESCRIPTION=
                (ADDRESS_LIST =
                   (ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC0))
                )
                (CONNECT_DATA=
                   (SID=PLSExtProc)
                   (PRESENTATION = RO)
                )
             )

Notes:

Do not substitute your SID anywhere.

Do not change the case of any text.

EXTPROC0 ends with the letter "o" not the number zero.

Start the Net8 Assistant to help you configure the tnsnames.ora.

See also "Net8 Administrator's Guide" for more information about creating these configuration files.

4.8 Multilingual Functionality (Multilexer)

Note:
You may need to increase your tablespace to at least 20 MB to support multilexer.

Oracle8i (8.1.6 and above) provides multilexer which allows you to use language-specific features on documents of different languages stored in the same table. Multilexer is a feature of the index and is configured during index creation. Multilexer requires an extra column in your table, which identifies the language of each document.

At query time, the multilexer chooses a language-specific lexer to lex the query tokens. This is based on the NLS_LANG setting for the query session. Thus, a query session in the FRENCH language will use the lexer for FRENCH.

During installation of Oracle Portal, the sbrimtlx.sql script is run to create the language-specific lexer preferences and to gather them together under a single multilexer preference. The Oracle Portal installation creates the following procedures in the ctxsys schema.

WWSBR_CORNER_CTX_<n>
WWSBR_DOC_CTX_<n>
WWSBR_PERSP_CTX_<n>
WWSBR_THING_CTX_<n>
WWSBR_TOPIC_CTX_<n>

where <n> is the user_id of the Oracle Portal schema which may be different for each database. This value is the user_id column value from all_users.

See also:
"interMedia Text Reference" included with your Oracle8i documentation.

4 Using interMedia Text in Oracle Portal