Intermedia Text Option

I. Pre-Installation & Requirements

Use these sections to ensure that the product InterMedia Text has been properly installed by the Installer and to set the environment. It is assumed that the
requirements for the database are fullfilled (see the release note and the installation guide for the database server.)

 A)THE FILES HIERARCHY

   Before starting, make sure that the Intermedia Software tree is installed.
   Below is a description of the critical parts of this tree (there are others; for instance sample, migrate, and docs directories):

   On Unix:

   - ?/bin/ctxsrv
     Oracle8i still supports the ctxsrv server. However, the only valid
     personality mask is M. You need to run it only when you want background
     DML. Batch DML (sync) does not require a running server.

   - ?/ctx/admin
     Data dictionary scripts.

   - ?/ctx/admin/defaults
     Language-specific default preferences.

   - ?/ctx/bin
     This directory is for user-defined filters, which we'll talk about later.
     This directory should also contain the ctxhx program which is used by the
     INSO filter.

   - ?/ctx/data
     This directory has data files needed by interMedia Text, which includes the
     linguistic lexicon files, the Xerox stemming files, and the Korean lexer
     dictionary. If you get strange internal errors in linguistics, stemming,
     etc., check this directory.

   - ?/ctx/lib
     This directory has platform-specific shared libraries and template files
     used by the INSO filter. It also contains the safe callout used by indexing
     and document services libctxx8.so (HP-UX: libctxx8.sl).

   On NT:

   - ?/bin/ctxsrv.exe
     Oracle8i still supports the ctxsrv server. However, the only valid
     personality mask is M. You need to run it only when you want background
     DML. Batch DML (sync) does not require a running server.

   - ?/ctx/admin
     Data dictionary scripts. (<8.1.6!>: Upgrade scripts for ugrading from
     8.1.5).

   - ?/ctx/admin/defaults
     Language-specific default preferences.

   - ?/ctx/bin
     This directory is for user-defined filters, which we'll talk about later.
     This directory should also contain the ctxhx program which is used by the
     INSO filter. It also has platform-specific shared libraries and template
     files used by the INSO filter. It also contains the safe callout used by
     indexing and document services oractxx8.dll.

   - ?/ctx/data
     This directory has data files needed by interMedia Text, which includes the
     linguistic lexicon files, the Xerox stemming files, and the Korean lexer
     dictionary. If you get strange internal errors in linguistics, stemming,
     etc. check this directory.
 

 B)INIT<SID>.ORA.

   Check the values of the following parameters in the parameter file:

   - text_enable.

     This parameter had to be set to 'true' in Context(Pre interMedia Text 8.1.5). Ensure that the parameter now is set to false, as described below:

        text_enable = false

   - shared_pool_size.

     The size of the shared pool SGA area is defined by the 'shared_pool_size' parameter.
     You have to set this to at least 115343336. The DB Assistant
     will even fail if this size is below this value.

        shared_pool_size = 115343336

     NOTE! This is the entry for the MINIMUM value of shared pool during
     installation of IMT. After installation this size may be reduced.

   - db_block_size.

     To get the most of of your environment you should set the
     value of this parameter to 8192. Be aware that you have to recreate the
     database if you have to change this value later.

        db-block_size = 8192

     The size of the data buffer cache SGA area is defined by the two parameters
     'db_block_size' and 'db_block_buffers'.

   - compatible.

     The installation (section II or III) will fail if the value of this
     parameter is below  8.1.0.0.0. Ensure that the value of this parameter is
     set to 8.1.0.0.0:

        compatible = 8.1.0.0.0

 C)THE CTXSYS' TABLESPACE.

   The InterMedia Text system user is CTXSYS. In an installation with the DB
   Assistant(section II) a DRSYS tablespace is created. CTXSYS' objects are
   installed in the DRSYS tablespace.

   If you are installing InterMedia Text manually in most cases it is
   recommended to create a separate tablespace for CTXSYS - for instance named
   DRSYS:

   CREATE TABLESPACE DRSYS DATAFILE '<path>\dr01.dbf' SIZE <size>
   DEFAULT STORAGE <storage clause>;

II.AUTOMATIC INSTALLATION OF INTERMEDIA TEXT WITH THE DB ASSISTANT

 You can use the DBCA to automatically create an IMT database. The two following sections guides you through the steps of:

 A)Create a new database
 B)Modify an exixting database

 NOTE: If you want to install InterMedia Text manually go directly to section III.

 <8.1.6!> When you use the DBCA to create the database automatic, the Java Server will also be installed together with IMT - it's not possible to
 exclude JServer.

 A)USE THE DB ASSISTANT TO CREATE A NEW DATABASE OR TO CREATE THE SCRIPTS TO CREATE THE NEW DATABASE.

   Go through the steps below to create a new database. At the end of step 4 you decide whether to create the database now, or to save the information
   to a batch file:

   1.Start the Database Configuration Assistant.
   2.Select the procedure 'Create a database'.
   3.When prompted to 'select the type of database to create' - choose 'custom'.
   4.The next steps allows you to configure your database. Go through these
     steps and make the choices that suit your application. Be careful when
     you come to the last step. The last form in the assistant prompts you for:
     'Do you want the assistant to create the database now?'. Here it is
     important that you DO SELECT 'Save information to a batch file' and then
     push the 'Finish' button if you don't want to create the database now.

     NOTE! Read the rest of this subsection if you have decided to  'Save
     information to a batch file'. Otherwise go to section IV.

     This will produce some scripts in the prefered directory. Among these
     scripts the two important are <db_name>drsys.sql and <db_name>context.sql.
     Where <db_name> is the name you chose for the database in db assistant.

     -drsys.sql creates the drsys tablespace as described in I.C)

     -context.sql performs the steps in III.A(manual data dictionary installation) and III.C(default language installation).

     <8.1.6> NOTE! You will also get the scripts for the configuration of
     JSERVER and InterMedia(audio, video and sound). You do not have to install
     this. The scripts for InterMedia are ordinst.sql and ordinst.sql.

 B)USE THE DB ASSISTANT TO MODIFY AN EXISTING DATABASE.

  <8.1.6!> When you use the DBCA to create the database automatic, the Java Server will also be installed together with ImT - it's not possible to
  exclude JServer.

   Follow these steps:

   1.Start the Database Configuration Assistant.
   2.Select the procedure 'Modify a database'.
   3.Select the available instance among the available list - the instance's database has to be started.
   4.Type the INTERNAL password.
   5.Select "Oracle Intermedia" from the options list and push the "finish"
     button. If the option is "grey shaded" a possible reason is that the
     product is not properly installed.

   The installation is now in progress and IM Text will be installed with
   IM Text data dictionary(ref. III.A) and the default preferences(ref. III.B),
   which is the default preferences for the U.S. language.

   NOTE! If you in the install progress get ORA-1017, see [NOTE:101476.1].
 

III.MANUAL INSTALLATION OF INTERMEDIA TEXT

 A)MANUAL DATA DICTIONARY INSTALLATION.

   1.Connected to sqlplus as SYS, run:
              @<ORACLE_HOME>/ctx/admin/dr0csys.sql <ctxsys> <system> <temp>

     Where:
         <ctxsys> is the ctxsys password
         <system> is the default tablespace for ctxsys
         <temp> is the temporary tablespace for ctxsys

     Comments:
         This module creates the user CTXSYS and grants full privileges to CTXSYS in
         order to create and insert into result tables, execute callbacks, rewrite
         queries, and perform system cleanup.

   2.Connected to sqlplus as CTXSYS, run:
        @<ORACLE_HOME>/ctx/admin/dr0inst.sql <ORACLE_HOME>/ctx/lib/libctxx8.so
        (on UNIX/Linux)

        @<ORACLE_HOME>/ctx/admin/dr0inst.sql <ORACLE_HOME>/ctx/lib/libctxx8.sl
        (on HP-UX)

        @<ORACLE_HOME>/ctx/admin/dr0inst.sql <ORACLE_HOME>\bin\oractxx8.dll
        (on NT)

     Comments: This module installs all Oracle database objects required by the TexTile system. This includes:

      a) Data dictionary tables, views, sequence, packages
      b) Server management tables, views and packages
      c) Dispatcher packages
      d) Service queue objects

     NOTE! You can check at the end of the install that the library is correctly
     installed by connecting as ctxsys and selecting from user_libraries:

         select library_name,file_spec,dynamic,status from user_libraries;

         LIBRARY_NAME FILE_SPEC                                D STATUS
         ------------ ---------------------------------------- - -------
         DR$LIBX      /oracle/db/dev118/ctx/lib/libctxx8.so    Y VALID

     The file extension depends on the OS.

 B)MANUAL INSTALLATION OF THE LANGUAGE PREFERENCES.

  The next step is to install appropriate language-specific default preferences.

  When you use CREATE INDEX to create an index or ALTER INDEX to manage an index,
  you can optionally specify indexing preferences in the parameter string. There
  are seven preference classes:

  - Lexer, defines the language being indexed. (<- LANG)
  - Wordlist, defines the expantion of stem and fuzzy queries. (<- LANG)
  - Stoplist, defines words and themes that are not be indexed. (<- LANG)
  - Datastore, defines document storage.
  - Filter, defines standards for converion of documents to plaintext.
  - Storage, defines the storage of the index tables.
  - Section group, enables possibilities to define document sections.

  An installation with the Database Configuration Assistant install the US
  default language preferences. To manually install the US default preferences,
  log into sqlplus as CTXSYS, and run 'drdefus.sql', as described below:

      @<ORACLE_HOME>/ctx/admin/defaults/drdefus.sql

  Comments:

  There are forty-odd scripts in ?/ctx/admin/defaults which create language-
  specific default preferences. They are named in the form drdefXX.sql, where
  XX is the language code. '?/ctx/admin/defaults' contents scripts for the
  following supported languages: English(UK), Danish(DK), Dutch(NL),
  Finnish(SF), French(FR), German(DE), Italian(IT), Portuguese(PR),
  Spanish(ES), and Swedish(S).

  NOTE! (<- LANG) refers to the language specific preference classes described above.
 

IV. Post Installation

Set up Net8 (to paraphrase the Net8 docs):

1.     Configure an IPC listener address.
        For example, change:

LISTENER =
    (ADDRESS_LIST=
        (ADDRESS=
                (PROTOCOL=tcp)(HOST=ap118sun.us.oracle.com)(PORT=1521)
        )
    )

to:

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

Note:  In this example, the key is called EXTPROC0 and ends in a zero. It does really matter what this is called as long as the key matches extactly in the
tnsnames below.
 

2.Add a system identifier (SID) name of PLSExtProc and a program name of EXTPROC in the server's LISTENER.ORA file.

For example, in the SID_LIST_LISTENER definition, insert:

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

3.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, add this to the end of tnsnames.ora:

extproc_connection_data, extproc_connection_data.world=
    (DESCRIPTION=
        (ADDRESS_LIST =
            (ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC0))
        )
        (CONNECT_DATA=
            (SID=PLSExtProc)
        )
    )

Note: Do NOT substitute your SID anywhere, do NOT change case of any text. This is the 'link' to entry in the listener.ora  (SID_DESC=(SID_NAME=PLSExtProc....AGAIN Please check the KEY=EXTPROC0 matches the entry in the listener.ora.
 

Domain Name

Add or check your entry to the Sqlnet.ora file on your server.
        NAMES.DEFAULT_DOMAIN = world
So, for example, if 'world' is your default domain.
    extproc_connection_data.world would be correct.

OR

    NAMES.DEFAULT_DOMAIN = us.oracle.com
    extproc_connection_data.us.oracle.com
 

To check installation and setup:

1.lsnrctl status -->> should give:

STATUS of the LISTENER
------------------------
Alias                      LISTENER
Version                    TNSLSNR for Solaris: Version 8.1.5.0.0 - Production
Start Date                 30-MAR-99 15:53:06
Uptime                     1 days 3 hr. 4 min. 42 sec
Trace Level                off
Security                   OFF
SNMP                       OFF
Listener Parameter File    /private7/oracle/oracle_home/network/admin/listener.ora
Listener Log File          /private7/oracle/oracle_home/network/log/listener.log
Services Summary...
    PLSExtProc has 1 service handler(s)
    oco815 has 3 service handler(s)

The important service summary item to check here is the service handler for PLSExtProc.
This can be tested with a simple sqlplus x/x@extproc_connection_data.world
If this is working correctly you should get a ORA-3113.

You can of course use tnsping
tnsping extproc_connection_data.world

TNS Ping Utility for IBM/AIX RISC System/6000: Version 8.1.5.0.0 - Production on 27-MAR-00 11:17:02
(c) Copyright 1997 Oracle Corporation.  All rights reserved.
Attempting to contact (ADDRESS=(PROTOCOL=ipc)(KEY=extproc))OK (10 msec)
=========================================================================

Congratulations!!  You now have a successful interMedia Text installation.

Create a user to work with interMedia Text
  As SYS or SYSTEM:
    create user ctxtest identified by ctxtest ;
    grant connect, resource to ctxtest;

You may want to create this user with a default tablespace and other grants and quotas. However, all that is required to work with interMedia text
this the ctxapp role.
            grant ctxapp to ctxtest ;

This can be checked by select * from user_role_privs; when connected as the user.

Create a Test Table
    * Create a test table with a primary key:
             Create table test(nr number primary key, test_text varchar2(500));
    * Insert some rows into the table:
             Insert into test values (1,'This is a test');
             Insert into test values (2,'of the InterMedia text installation');
             Commit;
    * Create at IMT index(domain index) on the "text" column:
             Create index test_idx on test(test_text) indextype is ctxsys.context;
    * Perform a query on the table:
             Select nr, test_text from test
             where contains (test_text,'installation') > 0;

      This should return:

       nr test_text
       -- ------------------------------------------
        2 of the InterMedia text installation
 

A Quick Look at the functions...

The CONTAINS function

Having created the text index you are then in a position to execute a text query.

SQL> SELECT text FROM quick
WHERE CONTAINS ( text,'sat on the mat' ) > 0;

TEXT
-----------
The cat sat on the mat

You should regard the CONTAINS function as boolean in meaning. It is implemented as a number since SQL does not have a boolean datatype
The only sensible way to use it is with >0.
The Paramaters of the CONTAINS function

CONTAINS ( text, 'sat on the mat', 42 ) > 0

The first parameter is the column. The second parameter is the Text Query Expression. Both these parameters are mandatory. The third parameter is the
target for the forward reference of the SCORE parameter. It is optional, and when omitted is defaulted to zero.
 

The SCORE Function

Consider the following select statement:

SELECT SCORE(42) s, text FROM quick
  WHERE CONTAINS ( text, 'dog', 42 ) >= 0
  ORDER BY s;

 S TEXT
-- ---------------------------
 7 The dog barked like a dog
 4 The fox jumped over the dog
 0 The cat sat on the mat

The better the match, the higher the score. The value can be used in ORDER BY but has no absolute significance. The score is zero when the query is not
matched.
 

Resolving Problems
 

• Make sure that $ORACLE_HOME/lib and $ORACLE_HOME/ctx/lib are both in your LD_LIBRARY_PATH when the listener is started.

Make sure that the $ORACLE_HOME/ctx/bin is in the environment PATH statement at the O/S level

• You need to create a soft link from $ORACLE_HOME/lib/libskgxp8.so to /usr/lib/libskgxp8.so