Oracle ConText Option Workbench User's Guide, Release 2.3 Go to Product Documentation Library
Go to books for this product
Go to Contents for this book
Go to Index

Go to previous file in sequence Go to next file in sequence

Document Viewers

This chapter introduces usage aspects of the document viewers provided in the ConText Workbench. In particular, this chapter provides installation and usage information for the Viewer Plugin and Viewer Cartridge.

The topics covered in this chapter are:

Using the OCX Viewer

This section provides usage information for the OCX viewer provided by the ConText Workbench.

The OCX viewer can be used on Windows NT or 95 in any application environment that supports custom controls. It can also be used in a Web-based environement when accessed through the Viewer Cartridge/Plugin.

Online Help for Viewer

Usage information for the OCX viewer is provided online as a WinHelp file.

Registering the OCX Viewer

The OCX Viewer should normally be automatically registered for use during installation. If, for some reason, the viewer is not registered, it can be registered manually using the regsvr32 utility.


The viewer is not unregistered during deinstallation. You must manually unregister it using regsvr32 before deinstallation.

For example

regsvr32 /u ctxv32.ocx


Installing the Viewer Plugin

This section provides details for installing the Viewer plugin.

Pre-Installation Requirements

First, ensure the WebServer version to be installed against is or higher.

Then, install an Oracle JDBC driver and note the connection requirements. These are used when writing additional configuration file entries.

Under Windows NT, the Oracle JDBC driver is automatically installed.

For remote installations on Solaris, you need to navigate to and look for the free software page. Choose the Oracle JDBC option. Or you can navigate directly to the page; currently it is:

Otherwise, you can use an alternative driver.

See Also:

For more information about configuration files, see "Viewer Cartridge Configuration Files" in this chapter.

For more information about alternative JDBC drivers, see "Using an Alternative Oracle JDBC Driver" in this chapter.


Installing the Viewer Cartridge to a Remote Machine

On installation, the middle-tier cartridge files are placed in the following directory:


When installing the viewer cartridge to a remote machine, you need to copy or move all files from the locally installed directory <ORACLE_HOME>/ctxw/middle/ctxvcart/remote to a directory <ORACLE_HOME>/ctxw/middle/ctxvcart on the target machine.

The "install" subdirectory is not required.


If the target machine is not running Windows NT, all file and directory names must be in lowercase.


Installing the Viewer Plugin File

Under automatic installation, the viewer plugin file - called npctxvpi.dll - is placed in the Web browser 'plugins' directory.

If there is no Web browser installed, you must copy the file manually, as follows:

Copy the viewer plugin file (npctxvpi.dll) manually from the <ORACLE_HOME>\ctxw\Viewer\plugin directory to the Web browser 'plugins' directory.

Activating the Viewer Plugin

To activate the plugin file, you must first close down all open Web sessions (if applicable).

Then, start a new Web browser session to ensure that the file has been registered. You can do this by selecting the Help -> About Plug-ins menu item from Netscape.

Building URLs

To be able to view ConText-indexed documents from an Oracle database through the Viewer Cartridge, URLs must be built and embedded into HTML pages.

These URLs contain sufficient information for Web Request Broker to direct the request to the Viewer Cartridge. This enables the Viewer Cartridge to generate a database connection, plus parameters that define what the document is and any highlight information needed to service the request.

Parameters to the URL can be defined in GET format, or supplied through the POST method in an HTML form.

To build URLs:

  1. To get a representation of a highlighted document (in WYSIWYG, if supported, or ASCII, if not supported), use the URL parameters (GET or POST) to define:
    indexing policy:      COLSPEC=<policy_name>
    document selection:   TEXTKEY=<tk_value>

    and, optionally:

    query expression:     [QUERYEX=<term_specification>]

    To retrieve the document in its original, unhighlighted form:

    type info:            MIMETYPE=<mime_type_string>

    Then the browser can use its own mapping to invoke a helper application or plugin to handle the data.

    With the default Mime-type"application/x-ctxv", the browser tries to use the plugin, if it is available.

See Also:

For information about installing the Viewer Cartridge Plugin, see "Installing the Viewer Plugin" in this chapter.


  1. If the document in its original, unhighlighted form is required (without using ConText), and is stored internally in the database - that is, not URL or external data store - it is more efficient to go directly to the base table:
    table spec:           TABLE=<table_name>
    row selection         WHERE=<where_clause>
    col to fetch:         COLUMN=<column_name>
    Mime type:            MIMETYPE=<mime_type_string>

The following URL (GET parameter) example displays a document from the table field defined by <table_name>, <column_name> and <where_clause> as these elements would appear in a SQL select statement:


The optional parameter, MIMETYPE, may be used to define the Mime-type of the data. The MIME-type defaults to "application/octet-stream" for binary data and "text/plain" for textual data.

Using URLs

Once URLs have been built, they can be used in HTML in various ways:

URL as a Link Target

With this, highlighted documents are viewed full-frame if the Viewer Plugin has been installed on the client. The frame is resizable, but plugin parameters cannot be specified.

Documents of other Mime-types (such as jpeg files) are supported. They are downloaded and viewed on the client by the best means available to the browser for that Mime-type.

URL as an Embedded Plugin Tag

Here, the dimensions of the plugin are pre-determined. So the height and width of the document view are set by the Height and Width EMBED tag parameters.

Plugin parameters can also be specified. A link can be provided to the location of the plugin archive for an 'install-on-demand' mechanism. Other Mime-types are not supported.

EMBED Tag Parameters

To embed the viewer plugin, include the following EMBED tag.

This example displays a document from the table field implied by <policy> and <textkey>, using <query> to highlight hit words:

<EMBED width="nnn" height="nnn" src="http://<host>/<virtual_path>/

where nnn is a positive number, <host> is the WebServer host and <virtual_path> is the Viewer Cartridge alias. The src attribute value must be on a single line. An optional parameter, conf, is used to indicate which section name of the configuration file is used for database connection data. This parameter defaults to use the 'DEFAULT' section.

See Also:

For more information, see "Viewer Cartridge Configuration Files" in this chapter.


Plugin Parameters

You can also specify the following parameters to the plugin, as mentioned previously:


If toolbar is set to true, the toolbar is shown.

If silenterrors is set to true, it suppresses error information dialog boxes.

idleinterval represents a value (in milliseconds) between 1 and 500 that sets the interval between document section reads. A value of 0 means that there is no idle time reading of document sections.

If shortcutmenu is set to true, you can click the right mouse button to obtain a short cut menu.

If pageview is set to true, the document page will be represented as the page would be printed.

URL as a Helper Application

In this case, URLs are used to invoke a helper application to display the document in a separate window as a separate process.

The URL is used as a link URL where a Mime-type is mapped to the example viewer, as delivered by the ConText Workbench.

Security Mechanisms

Access can be restricted by use of realms. This is done by assigning users to groups that have passwords to authenticate against realms of information. This way, some groups are granted access to ConText-indexed documents that are held in a variety of databases.

To restrict access through realms:

  1. Map a virtual path to a realm through the Oracle WebServer Administration pages.
  2. Map that virtual path to Viewer Cartridge through the WebServer Administration pages.
  3. Create the configuration files to which the virtual paths are mapped.
    If the virtual path contains more than one element, the last element is used to map onto the name of the configuration file. In this manner, each realm can have a separate configuration file. This ensures that users in groups with access to a realm can be denied access to information available in other realms.
  4. Enter the connection details into the configuration file (using the conf URL parameter) for each database connection that is within that realm.
  5. Build URLs using the appropriate virtual paths.

See Also:

For more information about using the Oracle WebServer Administration pages, see Appendix A, "Viewer Cartridge: Manual Configuration".

For more information about the configuration file, see "Viewer Cartridge Configuration Files" in this chapter.

For more information about building URLs, see "Building URLs" in this chapter.


Viewer Cartridge Configuration Files

A Viewer Cartridge configuration file contains one or more entries that describe how the Viewer Cartridge connects to a database. This description includes the username and password, the database details, and the JDBC driver to be used.

The configuration files must reside on the same tier as the Web Server in the following directory:


Multiple Configuration Files

Multiple configuration files can be created to allow different database connection details to be protected by different realms. This is done by naming the configuration file the same as the last element of the virtual path of the Viewer Cartridge with a .cfg extension. The default is ctxvcart.cfg.

For example:

Virtual Path   Configuration File  













Section Name

Each section of a configuration file starts with a section name enclosed within square brackets and has a number of parameters associated with the section:


All lines with any other parameter names are ignored. If one or more parameters of the same name are found within one section then the value associated with last one is used. A value cannot be split over more than one line.


This is the name of the Oracle user that the database connection uses. Defaults to CTXSYS.


This value specifies the password of the Oracle user. Can be null.


This value depends on the subprotocol value used. If null, it defaults to the installation's default database.

For any subprotocol a full connect descriptor, as used in tnsnames.ora files, can be used. For example:


For the oci7 or oci8 subprotocol, a service name present in a tnsnames.ora file can be used.

For the thin protocol, a value in the form of '<host>:<port>:<sid>' can be used. For example:


This value is the Java class name of the JDBC driver. It should always be:


This parameter should be assigned one of the following values:

oci7 | oci8 | thin

If the subprotocol parameter name does not appear within the section, then a default of oci7 is used.

See Also:

For more information about the values you can specify for section names, see the documentation for the JDBC driver that you are using.


Using an Alternative Oracle JDBC Driver

To use an alternative Oracle JDBC driver:

See Also:

For more information about modifying the CLASSPATH, see Appendix A, "Viewer Cartridge: Manual Configuration".

For more information about modifying <LD_LIBRARY_PATH> in the configuration file, see "Viewer Cartridge Configuration Files" in this chapter.

For the precise requirements you must specify for your JDBC driver, see your JDBC driver documentation.


Go to previous file in sequence Go to next file in sequence
Prev Next
Copyright © 1997 Oracle Corporation.
All Rights Reserved.
Go to Product Documentation Library
Go to books for this product
Go to Contents for this book
Go to Index