16
Using Oracle8 ConText Cartridge

This chapter describes how to use Oracle8 ConText Cartridge supplied external filters and Oracle8 ConText Cartridge demos that are provided as an addition to Oracle8 ConText Cartridge. It also describes how to set up and use the components of Oracle8 ConText Cartridge Workbench.

Before performing the tasks described in this chapter, complete the implementation tasks described in Oracle8 ConText Cartridge QuickStart Release 2.3

Specific topics discussed are:

Starting Oracle8 ConText Cartridge

Oracle8 ConText Cartridge servers can be started using one of two methods:

Oracle8 ConText Cartridge Control Utility

To help Oracle8 ConText Cartridge servers survive Windows NT console log off, use the Oracle8 ConText Cartridge control utility CTXCTL80.EXE to start, stop, and view the Oracle8 ConText Cartridge servers running on the Windows NT server/workstation.

The Oracle8 ConText Cartridge control utility interacts with a Windows NT service for Oracle8 ConText Cartridge. It is this service that manages the various Oracle8 ConText Cartridge server processes on that Windows NT server/workstation. The service is called OracleHOME_NAMEConTextService80 and must be started prior to using the Oracle8 ConText Cartridge control utility. By default the service start type is AUTO.

The Oracle8 ConText Cartridge control utility cannot list or kill Oracle8 ConText Cartridge servers started directly by executing CTXSRV80.EXE. It can only manage Oracle8 ConText Cartridge servers through the OracleHOME_NAMEConTextService80 Windows NT service.

To start Oracle8 ConText Cartridge Servers using the control utility:

Enter at the MS-DOS command prompt:
```
C:\> CTXCTL80 
```

Enter at the control utility prompt:

COMMAND> START 1 [DML | DDL | LOAD | LING | QUERY]

MS-DOS Command Prompt

To start Oracle8 ConText Cartridge server from the MS-DOS command prompt:

Enter at the MS-DOS command prompt:
```
C:\> START CTXSRV80 -USER CTXSYS/PASSWORD@CONNECT_STRING -PERSONALITY list
```
where:
- PASSWORD is the password for the CTXSYS user
- CONNECT_STRING is the service name or alias to the database you want to connect to
- LIST is the list of personalities you want to start the ConText server with
Oracle8 ConText Cartridge server processes started from the MS-DOS command prompt are killed by Windows NT when a console user logs off the Windows NT console.

Using Oracle8 ConText Cartridge Supplied External Filters

External filters extend the filtering capabilities of Oracle8 ConText Cartridge. Oracle8 ConText Cartridge Supplied External Filters are provided as a part of Oracle8 ConText Cartridge. These supplied external filters are installed and used on the server. You may also define your own external filters. See the section "Using User Defined External Filters" for more information on user defined external filters.

New in this release of Oracle8 ConText Cartridge, you do not need to create wrappers if you are installing Oracle8 ConText Cartridge for the first time (a fresh installation). If you have upgraded from release 8.0.3, then you need to upgrade your existing wrappers.

The steps to using Oracle8 ConText Cartridge Supplied External Filters are as follows:

Step 1: Identify Supplied External Filter and Wrapper

The following Oracle8 ConText Cartridge Supplied External Filters are supplied with Oracle8 ConText Cartridge for Windows NT. These filters can be used for filtering documents in many of the popular desktop publishing and word processor formats. The executables for the filters do not provide ConText with the required arguments, so ConText also provides scripts which act as wrappers for the executables.

The supplied external filters and their wrappers are installed automatically when you install Oracle8 ConText Cartridge. If your text file format is not listed in this table, then you need to provide your own external filter and wrapper. See the sections "Creating Wrappers for Oracle8 ConText Cartridge External Filters" and "Using User Defined External Filters" if your text file format is not listed in this table.

Note:

If you have upgraded from a release prior to release 2.3 of ConText, you may have existing external filters supplied by ConText. These external filters are no longer current and need to be replaced by the external filters provided in this release.

You may also need to change your wrappers accordingly or use the wrappers provided by ConText in this release.

Document Format	Version	Format ID¹	Wrapper Name	Windows NT Executable
AmiPro for Windows	1, 2, 3	19	amipro	w033b16d.exe
Lotus Freelance for Windows	2	85	lotusfre	w114b16d.exe
Lotus 123	2, 3, 4	20	lotus123	w020b16d.exe
Lotus 123	5	N/A	lotus123	w020b16d.exe
MS Excel	5	21	msexcel	w021b16d.exe
MS Excel	7	N/A	msexcel	w021b16d.exe
MS PowerPoint for Windows	2, 3, 4	84	power234	w109b16d.exe
MS PowerPoint for Windows	7	N/A	power7	w116b16d.exe
MS Word for DOS	5.0, 5.5	8	worddos	w005b16d.exe
MS Word for Macintosh	3, 4, 5	28	wordmac	w054b16d.exe
MS Word for Windows	2	18	wordwn2	w044b16d.exe
MS Word for Windows	6	68	wordwn67	w049b16d.exe
MS Word for Windows	7	N/A	wordwn67	w049b16d.exe
PDF/Adobe Acrobat	N/A	57	acropdf	acront.exe
WordPerfect for DOS WordPerfect for Windows	5.0, 5.1 5.x	3	wp5	w007b16d.exe
WordPerfect for DOS WordPerfect for Windows	6.0 6.x	1	wp67	w048b16d.exe
WordPerfect for Windows	7.0	N/A	wp67	w048b16d.exe
Xerox XIF	5, 6	43	xeroxxif	w103b16d.exe

¹ The information provided in the column Format ID is used to create filter preferences for mixed-format columns that require external filters. A format id is not provided for the following formats, because Oracle8 ConText Cartridge does not support mixed-format columns for these document formats:
* Microsoft PowerPoint for Windows, version 7
* Microsoft Word for Windows, version 7
* Microsoft Excel for Windows, version 7
* WordPerfect for Windows, version 7
However, the Oracle8 ConText Cartridge External Filters for these formats can be used for single-format columns that contain any one of these formats.

Step 2: Setting Up Oracle8 ConText Cartridge External Filters

This section provides instructions on setting up Oracle8 ConText Cartridge External Filters. On Windows NT, external filters must be placed in the directory ORACLE_HOME\BIN.

How Did you Install Oracle8 ConText Cartridge? Set up the Supplied External Files This Way...

If you are installing Oracle8 ConText Cartridge for the first time...

The supplied external filters do not require any setup, aside from creating preferences that call the wrappers for the filters.

If you have upgraded from a previous release of Oracle8 ConText Cartridge, already have wrappers for the supplied external filters provided in the previous release, already have preferences that call the wrappers, and want to use the new wrappers provided in this release...

You must drop your indexes, policies, and preferences, then create new preferences, policies, and indexes.
To avoid this situation, choose one of the following actions:

modify the names of the new wrappers to match the names of the existing wrappers
modify the names of the new external filters to match the names of the previous external filters
modify your existing wrappers to call the new external filter executables

If you upgraded from a previous release of ConText and do not have any wrappers for your external filters...

Create wrappers. See the section "Creating Wrappers for Oracle8 ConText Cartridge External Filters".

How Did you Install Oracle8 ConText Cartridge?	Set up the Supplied External Files This Way...
If you are installing Oracle8 ConText Cartridge for the first time...	The supplied external filters do not require any setup, aside from creating preferences that call the wrappers for the filters.
If you have upgraded from a previous release of Oracle8 ConText Cartridge, already have wrappers for the supplied external filters provided in the previous release, already have preferences that call the wrappers, and want to use the new wrappers provided in this release...	You must drop your indexes, policies, and preferences, then create new preferences, policies, and indexes. To avoid this situation, choose one of the following actions: modify the names of the new wrappers to match the names of the existing wrappers modify the names of the new external filters to match the names of the previous external filters modify your existing wrappers to call the new external filter executables
If you upgraded from a previous release of ConText and do not have any wrappers for your external filters...	Create wrappers. See the section "Creating Wrappers for Oracle8 ConText Cartridge External Filters".

Note:

If you modify your existing wrappers, in general, the only information that needs to change in the wrappers is the name of the filter executable.

If you are using the BETA PDF filter provided for Windows NT in the previous release and wish to use the new production PDF filter, drop any ConText indexes that you created with the BETA PDF filter, as well as the policies and preferences that called the filter. Create new policies and preferences that use the new filter and create new ConText indexes using the policies.

Creating Wrappers for Oracle8 ConText Cartridge External Filters

If you upgraded from a previous release of Oracle8 ConText Cartridge, and you do not have wrappers already created and specified, then a wrapper must be created for each of the Oracle8 ConText Cartridge External Filters to be used to filter text stored in a column. The wrapper can be any type of executable, such as a Windows NT batch file, that calls the filter executable and provides two system-supplied variables as arguments. Once the required wrappers have been created, the external filters can be specified as the filters for the text column.

Two requirements for wrappers are:

the file must be located in the ORACLE_HOME\BIN directory
the file extension must be .BAT or .CMD

The batch files for all other required external filters for Windows NT are identical to this example, except for the name of the filter executable supplied in each batch file.

The following example illustrates a simple Windows NT batch file that can be used as the wrapper AMIPRO.BAT for calling the AmiPro filter executable W033B16D.EXE for Windows NT:

REM AMIPRO FILTER
ORACLE_HOME\BIN\W033B16D %1 /N /T=%2

where:

AMIPRO is the wrapper name.
ORACLE_HOME is the drive letter and name of your Oracle home directory.
W033B16D is the filter executable name. Note that the .EXE extension for the filter executable file is not specified, because Windows NT does not require it.

The instructions for creating a wrapper for ACRONT.EXE are different than the instructions for creating wrappers for the rest of the executables.

For ACRONT.EXE, the wrapper text must be as follows:

	REM PDF FILTER 
	ORACLE_HOME\BIN\ACRONT %1 %2

Additional Information:

For examples of using the supplied external filters, see Chapter 9, "Setting Up and Managing Text" in the section "Creating a Filter Preference Using External Filters" in Oracle8 ConText Cartridge Administrator's Guide.

Step 3: Specifying Oracle8 ConText Cartridge External Filters

To specify one or more of the supplied external filters for a column, you first create a Filter preference in which you specify the wrapper (file name) for each of the filters to be used, then create a policy that calls the Filter preference.

You can create filter preferences for:

Single Format Columns

For single format columns, create a Filter preference that uses the COMMAND attribute (USER FILTER Tile) to specify the wrapper that invokes the filter executable for the format used in your column. The following example illustrates a script which calls PL/SQL packages that create a Filter preference for a column that contains documents only in AmiPro format:

BEGIN
CTX_DDL.SET_ATTRIBUTE('COMMAND','AMIPRO.BAT'); 
CTX_DDL.CREATE_PREFERENCE('AMIPRO_FILT', 
                             'AMIPRO FILTER', 
                             'USER FILTER'); 
END;

Mixed Format Columns

For mixed-format columns, create a Filter preference that sets the EXECUTABLE attribute (BLASTER Tile) once for each of the wrappers that invoke the formats you want to use in your column. The following example illustrates a script which calls PL/SQL packages that create a Filter preference for a column that contains documents in AmiPro, Adobe Acrobat, and WordPerfect 6.0 formats:

BEGIN 
CTX_DDL.SET_ATTRIBUTE('EXECUTABLE',19,'AMIPRO.BAT', 1); 
CTX_DDL.SET_ATTRIBUTE('EXECUTABLE',57,'ACROBAT.BAT', 2); 
CTX_DDL.CREATE_PREFERENCE('MULT_FILT', 
                            'MULTIPLE FILTERS', 
                            'BLASTER'); 
END;

In this example, it is not necessary to specify the filter executable for WordPerfect 6.0, because Oracle8 ConText Cartridge provides an internal filter for WordPerfect 6.0. By default, when the Filter preference for a column uses the EXECUTABLE attribute (BLASTER Tile), Oracle8 ConText Cartridge uses internal filters for all supported formats for which an external filter is not explicitly specified.

Additional Information:

See Chapter 6, "Text Concepts" in Oracle8 ConText Cartridge Administrator's Guide for more information about Oracle8 ConText Cartridge External Filters.

Using Oracle8 ConText Cartridge Supplied External Filters for Manual Filtering

The external filters can also be used to manually filter your documents (files) prior to storing them in the database.

To use the manual filtering method:

Call the appropriate external filter executable from the MS-DOS command prompt for each document to be filtered, and specify two arguments:
- the name of the document to be filtered
- the name of the output file used to store the filtered text
```
C:\ORACLE_HOME\BIN>W049B16D TEST.DOC /N /T=OUTPUT.TXT 
```
In the above example, a Microsoft Word 6 (or 7) document named TEST.DOC is filtered using the W049B16D.EXE filter executable. The filtered output is stored in OUTPUT.TXT.

For a Portable Document Format (PDF) file, the syntax is:
```
C:\ORACLE_HOME\BIN>ACRONT TEST.PDF OUTPUT.TXT
```

Load the filtered, plain (ASCII) text from the output file into a database column.
Create a policy for the column.

Be sure to specify a Filter preference that uses either the ASCII internal filter or no filter.

Index the column.

Additional Information:

See Chapter 7, "Understanding the ConText Data Dictionary: Indexing" and Chapter 9, "Setting Up and Managing Text" of Oracle8 ConText Cartridge Administrator's Guide for more information on policies.

Oracle8 ConText Cartridge Demos

The following Oracle8 ConText Cartridge Demos are installed and used on the server:

Product Demo Is Installed Under the Directory...

SQL*Plus

ORACLE_HOME\CTX80\DEMO\CTXPLUS

Linguistics

ORACLE_HOME\CTX80\DEMO\CTXLING

Product	Demo Is Installed Under the Directory...
SQL*Plus	ORACLE_HOME\CTX80\DEMO\CTXPLUS
Linguistics	ORACLE_HOME\CTX80\DEMO\CTXLING

Additional Information:

See "Configuring Oracle8 ConText Cartridge Demos" in Chapter 8, "Post-Installation Configuration Tasks" for further information on enabling the demo applications.

Using User Defined External Filters

If you define your own external filters (user defined external filters), the following list describes information specific to using user defined external filters on Windows NT:

On UNIX operating systems, Perl scripts and UNIX shell scripts can be executed as user defined external filters. On Windows NT, only .EXE, .CMD, and .BAT files are executed as user defined external filters by default.

To implement a filter as a shell script or Perl script on Windows NT, (for example, to run a Perl script FOO.PL), associate files with a .PL extension with a script processor such as CCPERL.EXE. When the Oracle8 ConText Cartridge server process executes your FOO.PL user defined filter, it calls CCPERL.EXE FOO.PL input file output file.

Additional Information:

See:

Oracle8 ConText Cartridge QuickStart Release 2.3
Oracle8 ConText Cartridge Administrator's Guide
Oracle8 ConText Cartridge Workbench User's Guide

for more information about configuring and using ConText components.

Using Oracle8 ConText Cartridge Workbench

Oracle8 ConText Cartridge Workbench provides administration and development applications for Oracle8 ConText Cartridge. The Workbench can be installed on both server and client and consists of the following components:

Administration Tools

Oracle8 ConText Cartridge Workbench includes two administration tools for Oracle8 ConText Cartridge:

Both tools offer the same functionality, except for two distinctions:

the Configuration Manager is web-based and platform-independent, whereas the System Administration Tool is supported on Windows NT and Windows 95 platforms only
there is one installation of the Configuration Manager per database, in contrast to the System Administration Tool, which may be installed on multiple client machines

Oracle8 ConText Cartridge Configuration Manager

The Configuration Manager is a web-based application that allows a ConText administrator to manage various administration tasks quickly and easily. It also incorporates a simple adhoc query tool.

In contrast to the System Administration Tool, which may be installed on multiple client machines, there is one installation of the Configuration Manager per database. Each installation of Configuration Manager runs under the CTXSYS user.

Configuration Manager includes a generic PL/SQL package for processing HTML pages extended with special tags that allow transparent interaction with a database.

An HTML-based online help system is delivered with the Configuration Manager. This online help system incorporates full text indexing facilities that enable you to search the help system. Therefore, usage information for the Configuration Manager is not included in this guide.

Oracle8 ConText Cartridge System Administration

The Oracle8 ConText Cartridge System Administration tool is a GUI application that can be used to perform system and text administration tasks. Before you can connect to the database using the Oracle8 ConText Cartridge System Administration tool:

an alias for the database that you want to connect to must be added to the TNSNAMES.ORA file on the computer where System Administration is installed. Centrally managed networks, for example those using Oracle Names Server, are not supported by the System Administration tool.

the CTXSYS user needs to connect once to each ConText database.The Oracle8 ConText Cartridge System Administration tool prompts you when you attempt to connect to the database.

Note:

The CTXSYS user needs to connect only once per database. Once CTXSYS connects to a database, the database is enabled thereafter for all users. See the online help with the Oracle8 ConText Cartridge System Administration tool for details on connecting to the database.

Document Viewers

Oracle8 ConText Cartridge Workbench includes three document viewer product components:

Oracle8 ConText Cartridge Viewer Plugin

The client-side Viewer Plugin can display most documents on the World Wide Web just as they would appear in their native format.

The Viewer Plugin actually consists of a set of libraries. These libraries provide the means for viewing the file. The plugin currently supports WYSIWYG viewing and query term highlighting in the following formats:

WordPerfect 5.x, 6.x
MS Word 2, 6

All other formats supported by ConText are displayed, by default, as plain (ASCII) text.

In the Configuration Manager, the View Data form uses the Viewer Plugin to view a hit from the available query hitlist.

Oracle8 ConText Cartridge Viewer Cartridge

The Viewer Plugin requires the Viewer Cartridge. The Viewer Cartridge is installed separately. Viewer Cartridge is used to package data for the Viewer Plugin. It generates the highlight information for a document, fetches the document from the ConText database, and then sends the document as a file (Mime-type "application/x-ctxv") to the web browser, which uses the Viewer Plugin (if available) to display the document.

Alternatively, for other Mime-types, the web browser can use its own mapping to invoke a helper application or plugin which can display the ConText-indexed documents. In such cases, Viewer Cartridge does not need the Viewer Plugin as long as suitable URLs have been specified.

The URL format is:

http://machinename.domain:port/ctxwview/CtxwViewCart?colspec=policyname&textkey=xy&queryex=keyword

where:

machinename is the name of the web server computer
port is the port number of the listener (not the admin listener)
policyname is the name of the ConText policy
xy is the text key numerical identifier (this key can be identified using Configuration Manager)
keyword is the word that you want highlighted (this word must exist in the document)

Oracle8 ConText Cartridge Viewer Control

The Viewer Control is a 32-bit Windows custom control for use in client/server configurations. It can be embedded in Windows applications or in HTML pages (for display in Internet Explorer using the Object tag).

The Viewer Control is used to display retrieved documents using the intended layout and with search terms highlighted. The Viewer Control is delivered with a sample application implemented as a stand-alone container.

A viewed document can be in any of the supported server-side formats. For example, a Microsoft Word document can be viewed with the Viewer Control in a way similar to how it appears within Microsoft Word. The user can scroll through the document using the Next and Previous buttons to jump to other occurrences of the search term(s).

Oracle8 ConText Cartridge I/O Utility

The I/O Utility enables you to load and unload data between database tables and client-side files. The I/O Utility is a 32-bit, stand-alone executable that performs a series of operations carried out in sequence as defined by a parameter file.

Example parameter files are documented in Oracle8 ConText Cartridge Workbench User's Guide.

Additional Information:

See Chapter 3, " Input/Output (I/O) Utility" in Oracle8 ConText Cartridge Workbench User's Guide for more information about the I/O Utility.

TextServer3 Dictionary Migration Tool

The TextServer3 Dictionary Migration tool has been developed to assist users who are migrating from TextServer3 to ConText. It allows you to:

create a policy in ConText for each indexable column of a TextServer3 table
migrate TextServer3 thesauri and synonym rings to ConText
create a section group in ConText for each section group in TextServer3

The tool is delivered as a PL/SQL package called CTXWMG_MIGRATE. The package generates SQL scripts that you can customize to your requirements before running them.

This package must be created in the ConText database on the server after the ConText Workbench is installed on a client machine. The scripts for creating the CTXWMG_MIGRATE package are automatically copied to the client machine during installation of the ConText Workbench. The scripts must then be run after installation to create the package.

Note:

The TextServer3 Dictionary Migration Tool is not listed, in the Oracle Installer, under the list of available components for the ConText Workbench.

Additional Information:

See Chapter 2, "Document Viewers" in Oracle8 ConText Cartridge Workbench User's Guide for more information about the Viewer Control and Viewer Plugin.

A Windows-based online help system is delivered with the Viewer Control. Therefore, usage information for the viewer is not included in the Oracle8 ConText Cartridge Workbench User's Guide.

For more information about manually configuring the Viewer Cartridge, see Appendix A, "Viewer Cartridge: Manual Configuration" in Oracle8 ConText Cartridge Workbench User's Guide.

Oracle8 ConText Cartridge Workbench Demo

There is a sample application using Oracle Forms provided with Oracle8 ConText Cartridge Workbench. See Chapter 4, "CTXQUERY Forms Sample Application" in Oracle8 ConText Cartridge Workbench User's Guide for more information.

Additional Information:

See:

the online help provided with Oracle8 ConText Cartridge Workbench product components for usage information
Oracle8 ConText Cartridge Workbench User's Guide for information on how to use the Workbench products

16 Using Oracle8 ConText Cartridge