**********************************************************************
*********************                             ********************
*******************          UPGRADE NOTES          ******************
*********************    VERSION 2 TO VERSION 3   ********************
**********************************************************************
This file contains information about converting from OMNIDEX version 2
to version 3. If you are performing such a conversion, be sure to read
this file and "Notes for Upgrades" in the OMNIDEX Software 
Installation Guide for MPE/iX.


This readme file is divided into the following sections:

  I.  VERSION 3 ENHANCEMENTS
 II.  OBSOLETE CONFIGURATION AND INDEXING OPTIONS
III.  TESTING THE SOFTWARE
 IV.  INTEGRATING OMNIDEX
  V.  INTEGRATING THIRD PARTY INDEXING (TPI)



**********************************************************************
********************             I.            ***********************
********************  VERSION 3 ENHANCEMENTS   ***********************
********************                           ***********************
**********************************************************************


Easier software installation

A new, menu-driven program called SETUP is provided to make software
installation fast and easy. Refer to your OMNIDEX Software
Installation Guide for complete details.


**********************************************************************
********************  PERFORMANCE ENHANCEMENTS ***********************

Increased indexing speed

If you've ever hesitated to reload your indexes because of the time
involved, you're in for a pleasant surprise. You will find that
indexing operations are much faster in OMNIDEX version 3. For example,
indexing 1 million parsed keywords on a Series 937 with OMNIDEX
version 2 takes about 9 minutes. With OMNIDEX version 3, the same
process takes only 2½ minutes...better than a 3-fold improvement!

Increased search speed

The time it takes to qualify records has decreased considerably as
well. Depending on CPU class, OMNIDEX version 3 qualifies from 40,000
to 225,000 records per second compared to 10,000 to 70,000 for OMNIDEX
version 2.

Index compression

Data compression techniques used in the version 3 indexes have
dramatically reduced the size of the indexes compared to version 2.
OMNIDEX version 3 requires about one third as much disk space for
indexing as OMNIDEX version 2.

Greater index capacity

With OMNIDEX version 3, you can index up to 128 million records or
record complexes per OMNIDEX domain. OMNIDEX version 2 limits you
to just over 8 million records.


**********************************************************************
********************  ENHANCEMENTS TO INDEXES  ***********************

OMNIDEX indexes are now kept in privileged MPE files. No structural
changes are made to the object database, and no separate index
database is created. Implementing the OMNIDEX indexes in MPE files
provides the following benefits:

  *  Most index file capacity management considerations are
     eliminated.
  *  OMNIDEX uses no data sets or data items, so OMNIDEX can be
     installed on databases that use the maximum number of data
     sets (199) or data items (1024).
  *  Separating the indexes from TurboIMAGE aids in the portability
     of the software to other platforms.

In addition to this change in index structure, the OMNIDEX indexes
underwent following improvements:

New maximum key sizes

The new OMNIDEX indexes can accommodate keywords up to 32 characters
long. The previous maximum was 24 characters. sorted keys can now be
up to 250 characters long. The previous maximum was 128.

Record-specific indexing

Because the 255-record limit for record-specific indexing has been
lifted in OMNIDEX version 3, and because record-specific keys provide
greater functionality, record-specific indexing is now the default
when installing a keyword (multiple) key on an OMNIDEX detail that is
part of an OMNIDEX master domain. Therefore, by default, OMNIDEX
qualifying counts in searches against detail data sets reflect the
number of detail records qualified by the search argument. You can use
ODXGET mode 11 or 21 to return the relative record number addresses of
the qualified detail records.
As in version 2, you can "compress" the list to reflect the OMNIDEX
search item count. You can still index record complexes for keys on
detail data sets by using the new "RC" option. It offers the same
record-complex retrieval results as in OMNIDEX version 2. Databases
that are converted from version 2 to version 3 are automatically
installed with the Record Complex option, where appropriate. Because
record-specific indexing is now the default, there is no longer an RS
option.

Natural binary collation

Binary OMNIDEX keys (TurboIMAGE types I, J, K, P, R and Z) now collate
in a "natural" order from the highest order negative number to highest
order positive number. In prior versions, negative and positive
numbers could be interleaved (as in packed decimal format) or positive
numbers could collate before negative numbers (as in twos complement
notation).

Indexing IEEE real numbers

IEEE real numbers can be installed as OMNIDEX keys by using the "Type"
option in OmniUtil.

Indexing compound items as blobs

In prior versions of OMNIDEX, keyword keys installed on compound items
treated the elements of the item as a grouped key. This meant that
keywords were parsed not only by spaces and special characters, but
also by field boundaries. This effectively limited OMNIDEX keys to 256
bytes, the maximum size of a TurboIMAGE item. It also prevented words
that "wrapped around" or spanned item boundaries from being properly
indexed. 
In OMNIDEX version 3.1, a TurboIMAGE compound item can be treated as
one OMNIDEX key field, regardless of element boundaries. This is
accomplished by installing the "Blob" option on the key with OmniUtil.

Indexing 8-bit character sets

OMNIDEX provides support for 8-bit characters sets, such as Roman 8,
by automatically translating 8-bit characters to a 7-bit equivalent
instead of treating the 8-bit characters as delimiters. You can still
modify this translation by defining a translation table prior to
indexing.
To provide better support for character sets such as Hebrew and
Arabic, you can now specify a character to be untranslated. That is,
the character can be indexed in its 8-bit form and used as part of an
OMNIDEX keyword rather than as a keyword delimiter. To indicate that a
character should not be translated, enter a single backslash (\) at
its position in the translation file.

Sorting keyword-indexed records

Known in OMNIDEX version 2 as ID SORT, this feature allows records
qualified in an OMNIDEX keyword search to be returned in order, sorted
by a field or fields in the OMNIDEX master data set. As with version
2, the sort order is established at indexing time, but is not
preserved as records are added or deleted from the OMNIDEX domain.
Further, the feature is supported for transparent domains but is not
allowed on domains with double integer search items or on unlinked
detail sets.
This feature is supported through any OmniUtil reindexing option.
After selecting a database or table to reindex, you can specify Set ID
Sort Order and select several fields (up to a combined length of 248
bytes) by which to sort records before proceeding with the indexing
operation. 

Easier maintenance

The DBMGR database maintenance utility automatically maintains the
integrity of the OMNIDEX index files when copying or renaming a
database. A complimentary copy of DBMGR is provided to all OMNIDEX
version 3 customers.
NOTE:  You must use DBMGR version 2.04.04, which is included on your
OMNIDEX software tape, to copy databases installed with version 3.3 of
OMNIDEX. Using previous versions of DBMGR to copy version 3.3
databases can corrupt the OMNIDEX control file and cause a system halt
if the database is enabled for TPI.
Two new contributed utilities, CAPCHK and CAP, check the capacities of
index files and resize them to your specifications. See your OMNIDEX
Administrator's Guide, for more information.


**********************************************************************
********************  ENHANCEMENTS TO SEARCHES ***********************


Pattern matching

The pattern-matching capabilities introduced with the IMAGE Retrieval
Interface in version 2.09/2.10 are now available in version 3 through
ODXFIND modes 3 and 5. That means you can now qualify records using
the pound sign (#), question mark (?) and at sign (@) anywhere in an
argument value.
Pattern matching for all OMNIDEX searches is also supported for the
Standard TurboIMAGE Interface to Third Party Indexing through DBFIND.

New ODXFIND mode 5

A new ODXFIND mode (mode 5) performs all of the pattern-matching
functions of ODXFIND mode 3 with a different Boolean order of
precedence. ODXFIND mode 5 evaluates AND operations before OR
operations, which is consistent with the order of precedence for
DBFIND mode 12 in the TurboIMAGE Interface to Third Party Indexing.

Universal NOT operation

A NOT operator can now begin a keyword search argument without
referencing a prior list of qualified OMNIDEX IDs. Such retrievals
qualify all records in the OMNIDEX domain that do not satisfy the
argument that follows the NOT operator.

Three ODXFIND qualifying counts

The ODXFIND intrinsic now returns three qualifying counts instead of
one. The counts appear in words 3 through 8 of the TurboIMAGE status
array and have the following meanings: 

   Words 3-4   contain the record-specific count, or the number of
               qualified detail records (relative record numbers),
               when a key on a detail data set is searched. If the key
               is on a master data set, or the Record Complex (RC)
               option is installed on the key, this location contains
               the number of search items qualified.
   Words 5-6   contain the record-complex count, or the number of
               search items qualified in the search. In an OMNIDEX
               detail data set that is not linked to an OMNIDEX master
               (Detail Record indexed), this is the number of detail
               records that qualified.
   Words 7-8   contain the OMNIDEX ID count for the current argument
               parameter before it is intersected (or merged) with the
               list of records previously qualified in the same
               OMNIDEX domain.


**********************************************************************
********************    OPEN SYSTEMS ACCESS    ***********************


OMNIDEX for Open Systems expands OMNIDEX indexing technology to work
across multiple platforms and database management systems. This lets
you install OMNIDEX on:
 
  *  network databases, like TurboIMAGE
  *  relational databases, like Oracle and Rdb/VMS
  *  indexed file systems like RMS and ISAM

It also lets you develop applications that can run on a variety
of operating systems including MPE, VAX/VMS, and different flavors of
UNIX.
OMNIDEX for Open Systems owes its portability to a new software
architecture and a suite of new maintenance and retrieval routines. It
has been rewritten in C to be POSIX compliant. Releases are currently
shipping for the HP-UX, OpenVMS and Alpha, SUN Solaris and Digital
UNIX platforms using Oracle, Rdb, RMS, Informix, Sybase and C-ISAM.
Future releases are planned for additional operating systems and data
management platforms.



**********************************************************************
********************   OMNIDEX CLIENT ACCESS   ***********************


OMNIDEX Client versions 1.4 and 1.5 introduced client-server access to
OMNIDEX indexing. Version 2, the latest and most powerful release of
this technology, provides both the traditional PPL connectivity, as
well as Sockets-based connectivity. OMNIDEX Client applications
distribute processing across client PCs and the host server to
optimize performance and eliminate bottlenecks. Sockets technology
further optimizes host server performance by eliminating the need for
idle client sessions on the server. Users love client-server
applications because they can find data in an easy to use,
object-oriented Windows environment.

Application enhancements
The following enhancements to OMNIDEX version 3 lend themselves to
writing more flexible applications.

Critical item update
Critical item update is a feature that was recently added to
TurboIMAGE. It lets you change TurboIMAGE search items of detail
records and dynamically maintains the internal pointers to the
TurboIMAGE detail chains. Before this enhancement, records had to be
deleted and re-added to change a TurboIMAGE search item.
To support critical item update, OMNIDEX was enhanced to track the
changes to OMNIDEX search items and maintain the indexes accordingly.

Optimized Locking
OMNIDEX index files are locked automatically when you call DBPUT,
DBDELETE, or DBUPDATE, much like the Optimized Locking introduced in
OMNIDEX version 2.05/2.06. As a result, discrete mode and IMAGE-only
locks are no longer provided. DBILOCK and DBIUNLOCK are still provided
for backward compatibility.

NOTE:  Programs that update OMNIDEX databases and perform TurboIMAGE
       locking must have MR capability. This allows update intrinsics
       to lock Index files while TurboIMAGE locks are held. MR
       capability is not required by programs that update databases
       enabled for Third Party Indexing.
       See "Linking and Testing Programs" in the "Programming" chapter
       of the oMNIDEX API Guide for more information about adding MR
       capability to program files.

Passive Error Handling
OMNIDEX version 2 introduced Passive Error Handling to allow a program
to continue processing TurboIMAGE transactions in the event of an
OMNIDEX indexing failure.

NOTE:  Passive Error Handling does not work on TPI-enabled databases.

To invoke this feature in OMNIDEX version 3, run the SETUP program in
the DISC account, and choose option  6. Configure Product Library,
followed by option  1. Configure Passive Error Handling (P.E.H.). When
prompted for a name of an executable library, enter the name XL.PUB,
or enter the name of a copy of the file XL.PUB.DISC. This enables
Passive Error Handling for all programs that reference the modified
library in the XL path specified at either link or run time.
For more information about Passive Error Handling, see "Passive Error
Handling" in chapter 3 of the OMNIDEX API Guide.

New OMNIDEX libraries
The new OMNIDEX Intrinsic, Call Conversion, and Intrinsic Switch Stub
libraries are designed to simplify software installation.
The new OMNIDEX Intrinsic library, XLOMNIDX.PUB.DISC, is automatically
copied into PUB.SYS when you run SETUP to install the software. A new
environment variable, DISC_XLNAME, lets you test an updated OMNIDEX
Intrinsic library before overwriting the existing one in PUB.SYS.
The new Call Conversion library, XL.PUB.DISC, lets you access any
OMNIDEX database for retrievals or updates using your existing
TurboIMAGE applications. The new Call Conversion library traps calls
to OMNIDEX intrinsics and calls to TurboIMAGE intrinsics, and
redirects them to the appropriate intrinsic library (XLOMNIDX.PUB.SYS
or XL.PUB.SYS).
When placed with the OMNIDEX Intrinsic Switch Stub library
(SL.PUB.DISC) in the same group as your compatibility mode programs,
the Call Conversion library gives your compatibility mode programs
access to OMNIDEX version 3's many features.


**********************************************************************
********************            II.            ***********************
********************  OBSOLETE CONFIGURATION   ***********************
********************   AND INDEXING OPTIONS    ***********************
**********************************************************************

Because of the speed and efficiency of the new OMNIDEX, several
configuration and indexing options are no longer required or supported
under OMNIDEX version 3.
The obsolete configuration options are:

  *  internal ODXFIND work file size
  *  Control Pointer File suffix
  *  optimized locking activation
  *  the Deferred Update feature

NOTE:  The obsolete indexing options for keyword keys are LIMIT,
       CHAIN, CONTINUE, NOLOAD, NOFREE, NORS, NOVERIFY, PAD, VERIFY,
       UFCAP.



**********************************************************************
********************            III.           ***********************
********************          TESTING          ***********************
********************      THE NEW SOFTWARE     ***********************
**********************************************************************


When you restore your OMNIDEX version 3 update software from tape, it
resides in an account named DISC30n, where n is the release level of
the software (DISC303, DISC304, for example).
This lets you test your update software before incorporating it into
your production applications. To use the new IMAGEPlus intrinsics in a
non-production environment, you must chose not to update your
XLOMNIDX.PUB.SYS when using SETUP to restore the update software. (See
"Automatic Installation" in your OMNIDEX Software Installation Guide
for MPE/iX.)
You can test your applications against the new version of XLOMNIDX
before you copy it by setting the DISC_XLNAME environment variable
before you run OMNIDEX applications.

     SETVAR DISC_XLNAME "XLOMNIDX.PUB.DISC30n"

     where n is the release level of the software

NOTE:  Disable any test databases for Third Party Indexing before
       accessing them through XLOMNIDX.PUB.DISCACCT.

Please call the DISC Response Center at (303) 444-6610 if you have
TPI-based applications that you want to test simultaneously with
different versions of XLOMNIDX.



**********************************************************************
********************             IV.           ***********************
********************    INTEGRATING OMNIDEX    ***********************
********************                           ***********************
**********************************************************************


TurboIMAGE OMNIDEX users have two available integration options:

  *  TurboIMAGE integration, where you install OMNIDEX keys directly
     on TurboIMAGE databases and use the OMNIDEX API and the Standard
     TurboIMAGE Interface to Third Party Indexing (TPI) to maintain
     and access OMNIDEX data.
  *  Open systems integration, where you define TurboIMAGE data in an
     environment catalog, install keys on the environment catalog, and
     use the OmniAccess API to maintain and access OMNIDEX data.

NOTE:  You can access OMNIDEX/TurboIMAGE databases directly using
       OmniAccess.  See your OMNIDEX Operating System Supplement for
       MPE/iX for information about "direct IMAGE access".

Each of these approaches has its own strengths and weaknesses. You
should pick one based on the data processing environment at your site,
as discussed next.


**********************************************************************
********************   TURBOIMAGE-ONLY SITES   ***********************


If you are using TurboIMAGE exclusively, and plan to continue using
TurboIMAGE exclusively, you should install OMNIDEX directly on your
TurboIMAGE databases. The reasons for this are:

  *  TurboIMAGE integration offers a more seamless interface between
     OMNIDEX and TurboIMAGE. This includes OMNIDEX access and
     automatic indexing through Hewlett Packard's TPI.
  *  The OMNIDEX API was designed exclusively for use with TurboIMAGE,
     and offers more features for TurboIMAGE than the OmniAccess API
     does.
  *  Other third-party vendors, like Speedware, directly interface to
     OMNIDEX through TurboIMAGE integration.

OMNIDEX TurboIMAGE integration is ideal if you are used to calling
TurboIMAGE intrinsics to add, delete, update or find records. The only
limitation to TurboIMAGE integration is that it will only work on
TurboIMAGE databases. For more information about TurboIMAGE
integration, see your OMNIDEX Administrator's Guide.
If you also use other database management platforms, like Oracle, or
if you want to manage your data in an SQL environment, you should
consider open systems integration, as discussed next.


**********************************************************************
***************** MULTIPLE DATA MANAGEMENT SYSTEMS *******************


If you are using several data management systems, like Oracle and
TurboIMAGE, and you want to be able to transport data across these
platforms, you should use open systems integration for OMNIDEX. Open
systems integration uses environment catalogs to define each of your
data management systems. You can write them using any text editor.
Some of the benefits of using open systems integration are:

  *  You can integrate TurboIMAGE and Oracle databases, as well as
     flat-file data management systems.
  *  Applications you develop using the OmniAccess API are portable
     across data management platforms and operating systems.
  *  You can select rows from databases using ANSI SQL syntax. This
     lets you return summary data, as well as field values, to your
     applications.

For more information about open systems integration, see the OMNIDEX
Reference Manual.


**********************************************************************
********************    OMNIDEX CLIENT SITES   ***********************


If you are using OMNIDEX Client, you can either install OMNIDEX
directly on your TurboIMAGE databases or you can use open systems
integration. Which you choose depends on your site and its needs.
Review the discussions above regarding the advantages of each. The
OMNIDEX PC Client Administrator's Guide also discusses the relative
advantages from an OMNIDEX client perspective.


**********************************************************************
********************             V.           ***********************
********************      INTEGRATING THIRD    ***********************
********************     PARTY INDEXING (TPI)  ***********************
**********************************************************************


OMNIDEX version 3 provides the option of full TurboIMAGE integration
through the Standard TurboIMAGE Interface to Third Party Indexing (or
"TPI Interface"). TPI integration offers the following benefits:
 
  *  OMNIDEX indexes are automatically updated by the TurboIMAGE DBMS.
     As records are added, modified or deleted, TurboIMAGE
     automatically invokes OMNIDEX routines to maintain indexes.
  *  Retrieval applications use familiar DBFIND/DBGET coding
     techniques with new retrieval modes.
  *  You can access OMNIDEX keys through some third-party software
     packages, like QUIZ.
  *  Programs that use standard TurboIMAGE intrinsics to update or
     retrieve from TPI-enabled databases need not reference any
     OMNIDEX libraries.
  *  OMNIDEX indexes are recovered along with TurboIMAGE data in the
     event of a system failure.
  *  The use of low-level operating system services improves the
     concurrence of operations.

TurboIMAGE integration requires TurboIMAGE version C.04.03 or later,
and OMNIDEX version 3.0 or later.
While the Standard TurboIMAGE/iX Interface to Third Party Indexing
offers many advantages, it may not be appropriate for all HP shops.
Some things to consider are discussed in "Integrating OMNIDEX."


**********************************************************************
******************  TPI AND OMNIDEX VERSION 3.0  *********************


Programs that call DBFIND mode 1 through the Call Conversion library,
or against databases enabled for Third Party Indexing (TPI),
automatically support generic retrieval capability for TurboIMAGE
keys on detail data sets that are also installed as OMNIDEX sorted
or keyword keys. This may be undesirable if the TurboIMAGE search
items contain such characters as the double quote ("), at-sign (@),
pound-sign (#), or question mark (?), which could be interpreted as
wildcard characters. To disable TPI and pattern matching for a
session, set the job control word (JCW) IMAGETPI to 100, as follows:
 
     SETJCW IMAGETPI 100

To disable TPI retrievals in QUICK screens for TurboIMAGE keys on
detail data sets, set the IMAGETPI JCW to 200, as follows:
 
     SETJCW IMAGETPI 200

NOTE:  These statements disable TPI searches for a session, until the
       IMAGETPI JCW is reset to zero.


**********************************************************************
*************  TPI AND OMNIDEX VERSIONS 3.1 AND LATER  ***************


In OMNIDEX versions 3.1 and later, DBFIND mode 1 (by default) no
longer performs OMNIDEX sorted or keyword searches on TurboIMAGE keys
in detail data sets that are also installed as OMNIDEX keys. This
change affects programs running through the Call Conversion XL
(XL.PUB.DISC) or programs running against TPI-enabled databases, and
is the same behavior invoked by setting the IMAGETPI JCW to 100 in
OMNIDEX version 3.0 as described in "TPI and OMNIDEX version 3.0".
OMNIDEX keyword and sorted key searches are still performed by DBFIND
mode 1 for all OMNIDEX key fields that are not also TurboIMAGE key
fields in detail data sets.
This change was made because of the possibility that a program calling
DBFIND mode 1 on TurboIMAGE keys could fail once a key is installed on
the TurboIMAGE search item. The failure could occur any time a
TurboIMAGE search item value legitimately contains wildcard characters
(?, # or @) or quotes ("). The likelihood of failure is enhanced by
the existence of a sorted key installed for internal use on any search
item of an OMNIDEX master data set that is not a double-word integer.
In order to override this change, and to enable automatic TPI
retrievals in DBFIND mode 1 against keys that are both TurboIMAGE
detail keys and OMNIDEX keys, set the IMAGETPI JCW to 400, as follows:
 
     SETJCW IMAGETPI 400

Setting this JCW ensures that DBFIND mode 1 performs OMNIDEX
retrievals against TurboIMAGE detail keys that are also OMNIDEX keys.

IMAGE/SQL
IMAGE/SQL supports OMNIDEX sorted (generic) keys on TPI-enabled
databases. When a sorted key is referenced in an SQL SELECT statement,
IMAGE/SQL calls DBFIND mode 1. Therefore, you should set the IMAGETPI
JCW to 400, as shown above, to support SQL retrievals against
TPI-enabled databases.


**********************************************************************
******************  TPI, OMNIDEX AND POWERHOUSE  *********************


Cognos' QUIZ version 7.29 has an embedded OMNIDEX interface that lets
you access OMNIDEX sorted keys through QUIZ, and provides a greater
integration of OmniQuest when run from within QUIZ. 

Sorted access
No additional software is needed from DISC to access OMNIDEX sorted
keys from QUIZ version 7.29. To access OMNIDEX sorted keys through
QUIZ: 

  *  You must declare any sorted keys as OMNIDEX type keys in a PDL
     dictionary.
  *  You must enable TPI for the database where the sorted keys
     reside.

Once you have done this, you can access these keys like any SORTED
keys in QUIZ (KSAM files, for example). QUIZ does all of the procedure
calls to determine if sorted keys are available, and to access the
keys. Most of the OMNIDEX sorted key functionality is available, as is
the much requested ability to link primary files to secondary files by
sorted keys. For more details, read the Cognos publication OMNIDEX
Support in PowerHouse for MPE/iX (version 7.29).

Keyword access
QUIZ 7.29 can access keyword keys through an integrated version of
OmniQuest (version 2.02.14 or later). This provides integrated
retrievals to sorted and keyword keys, so that users have a choice of
doing their sorted searches through embedded QUIZ against TPI-enabled
databases, or through OmniQuest. Embedded QUIZ access gives link
capability through sorted keys, but OmniQuest gives better access
to sorted composite keys, especially those with mixed data types.
The integrated OmniQuest also gives the following benefits: 

  *  compatibility with the SETJOB facility
  *  the ability to report search values entered at OmniQuest prompts
  *  Saving QUALIFY commands in compiled QUIZ procedures


**********************************************************************
***********  ACCESSING TPI FEATURES WITHOUT ENABLING TPI  ************


You can take advantage of the Standard TurboIMAGE Interface's extended
retrieval modes and automatic updating of indexes on databases not
enabled for TPI. To do so, run your native mode programs to reference
XL.PUB.DISC, the Call Conversion library. Compatibility mode programs
should reference SL.PUB.DISC, the Intrinsic Switch Stub library. See
Appendix D of the OMNIDEX Administrator's Guide for detailed
information about referencing OMNIDEX SLs and XLs.