/ $Header: readme.doc 19-apr-02.

09:27:28 apopat Exp $

/
/ Copyright (c) 2001, 2002 by Oracle Corporation

README FILE FOR THE OBJECT TYPE TRANSLATOR (OTT) 9.2.0

------------------------------------------------------

This file contains important information about the Object Type

Translator (OTT) version 9.2.0 and version 8.1.9, which are the
OTT release shipped with the 9.2.0 Oracle database. These notes
are divided into four sections:

* Section 1 describes compatibility and migration issues that

exist in OTT 9.2.0 with respect to previous versions of OTT.

* Section 2 briefly describes the new features introduced in

OTT versions 9.0.0, and 9.0.1.

* Section 3 answers several frequently asked questions about OTT.

This section presumes some knowledge of OTT.

* Section 4 lists known bugs and restrictions

* Section 5 lists bugs fixed

SECTION 1: COMPATIBILITY AND MIGRATION

--------------------------------------
OTT version 9.0.0 and above is a utility written entirely in Java,
while OTT version 8.x and below is written in C. New functionality
in OTT will only be available in versions 9.x and above.
Since version 9.0.0 and above are written in Java, OTT now
uses JDBC to communicate with the database. JDBC (Java Database Connectivity)
is the Java interface for connecting from Java to relational databases.
Developers who are familiar with the Oracle Call Interface (OCI)
layer of the client-side C code will recognize that JDBC provides the power
and flexibility that OCI does for the C or C++ programmer. Oracle
provides several JDBC drivers. The Thin driver is a java driver for
client-side use without an Oracle installation. The OCI drivers
(OCI8 and OCI7) is for client-side use with an Oracle client installation.
For information about the Oracle JDBC drivers, please refer to the
"JDBC Developer's Guide and Reference". OTT version 9.0.1 provides
a new command line option so that users may specify the JDBC driver
to connect to.

SECTION 2: NEW FUNCTIONALITY

----------------------------
Starting with version 9.0.1, OTT provides a parameter called URL which
specifies the URL of the database to connect to. The format is:
URL=url
The default value is jdbc:oracle:oci8:@. To specify the Thin driver,
enter URL=jdbc:oracle:thin:@host:port:sid where host is the name
of the host on which the database is running, port is the port
number and sid is the Oracle SID.

The Object Type Translator 9.0.0 maps database object types,

LOB types, and collection types to C++ classes for use in OCCI
applications. Oracle 9.0 provides a C++ API interface
as described in the Oracle C++ Call Interface (OCCI).
One of the functionalities of OCCI is to provide navigational
access. The OCCI navigational interface is a C++ interface that
lets you access and modify object-relational data as C++ objects
without having to use SQL. OTT 9.0 converts the SQL types in
the database to C++ class declarations and also implements a
few methods that are called by OCCI while instantiating the objects.
The declarations are stored in a header file which can be included
in the OCCI application and the method implementations are stored in
a C++ source code file to be linked with the OCCI application.
OTT also generates a function to register the mappings with the
environment in a separate file. To generate the C++ classes,
the new value CPP must be specified to the existing CODE parameter
along with other new parameters to be used only for C++ generation.
Please refer to the Object Type Translator Chapter in the OCCI manual
for more details.

Starting with version 9.0, OTT supports type inheritance of object.

For Pro*C/C++ and OCI users, OTT now generates a C struct to represent
an object subtype by declaring the inherited attributes in an
encapsulated struct with the special name '_super' before declaring
the attributes. Also, substitutable attributes of an object are
translated into a pointer rather than inlined. For OCCI users,
inherited types are derived from the parent type and the parent's
readSQL and writeSQL methods are called in the generated files.
Please refer to the OTT Chapter in the Pro*C/C++, OCI, and OCCI
manuals for more details about inheritance support.

SECTION 3: OTT FREQUENTLY ASKED QUESTIONS

-----------------------------------------

Question: OTT works when I put all the options on the command line,
but not when I use a CONFIG file. What am I doing wrong?

Check the format of your CONFIG file carefully. Each option must
appear on a separate line, and no whitespace is permitted within
a line.

Question: I forgot to specify the name of the INTYPE file, but OTT did
not complain about this. What happened?

If the INTYPE file is not specified, all types in the user's schema will
automatically be translated.

Question: Why can't I write C structs by hand for my object types?

It is possible for the OCI programmer to write C structs for object

types by hand. However, this is error-prone. The programmer must
correctly declare the struct for the object type, the parallel indicator
struct, and any necessary typedefs. If a hand-written declaration is
not equivalent to what OTT would generate, the program will not work.
The Pro*C/C++ programmer faces the additional obstacle that the Pro*C/C++
precompiler needs the OUTTYPE file generated by OTT (which, from the
point of view of the precompiler, is an INTYPE file) to determine which
structs are used for which object types.
Question: Should OTT use the same character set as my database?

Generally, yes. When OTT reads a the name of a database entity, the name
is automatically translated from the database character set to the character
set used by OTT. OTT then translates the name from the character set used
by OTT to the C compiler's character set. In order for OTT to read the name
of the database entity successfully, all the characters of the name must
be found in the OTT character set, although a character may have different
encodings in the two character sets.

The easiest way to guarantee that the character set used by OTT contains all
the necessary characters is to make it the same as the database character set.
The user specifies the character set that OTT uses by setting the NLS_LANG
environment variable, or by some other platform-specific mechanism.

Question: When should I quote the name of a type, attribute, or

schema in the INTYPE file?

Names in the INTYPE file are quoted for two reasons:

If a type, attribute, or schema name was quoted when it was first

declared, it is a case-sensitive name. Any use of the name in an
SQL statement or in the INTYPE file must be quoted, and the same
case must be used as when the name was declared.

If the type, attribute, or schema name is an OTT reserved word, it

must be quoted. If the name was not quoted when it was declared,
the name must be written in upper case.

Question: Why are OCI programs supposed to initialize the type

version table?

In the release of Oracle8, each type has only one version, but
future version of Oracle8 may support multiple versions of a type.
Initialization of the type version table makes an OCI program
compatible with future releases of Oracle8. It is the responsibility
of the OCI programmer to declare a function prototype for the
initialization function generated by OTT, and to call that function.

A Pro*C/C++ program does not call the initialization function

explicitly because the Pro*C run-time library, SQLLIB, initializes
the type version table.

Question: Can I override an option in the CONFIG file by respecifying

it on the command line?

Yes. If an option is specified in more than one place, its value on

the command line overrides its value in the INTYPE file, which overrides
its value in a CONFIG file named on the command line, which overrides
its value in the default CONFIG file.

SECTION 4: KNOWN BUGS AND RESTRICTIONS IN OTT

---------------------------------------------

OTT reports most, but not all, errors in the INTYPE file to the user.
A few errors in the INTYPE file are not reported by OTT, but cause
OTT to generate C declarations that will not compile successfully.
These errors are listed below:

bug 445456:
OTT doesn't warn the user if the user requests the same name for two
different types, or for two different attributes of the same type.
As a result, it is possible for two C structs or Java classes
generated by OTT to have the same name, or for two members of a
C struct or Java class to have the same name. These errors will be
detected by the compiler.

bug 449539:
If the user requests that declarations be generated into two (or more)
different #include files, each of which must include the other, OTT
does not report the error. The error is detected by the C compiler.

bug 1693635:
If a user is generating C++ (code=cpp) and uses the GENERATE AS clause
in the intype file to extend the generated OTT classes and a type
has attributes or parents of an extended type, then OTT does not
generate the proper includes in the header file. OTT should include
the header file(s) containing the extensions of the generated types,
not the generated header files. Please refer to the bug database
for more information.

SECTION 5: BUGS FIXED

---------------------

Bugs fixed in OTT 9.2.0

-----------------------

2187330 C++ DESTRUCTOR IS NOT GENERATED FOR OBJECTS WHICH HAVE VECTOR OF
PTR ATTRIBUTE

OTT should generate the destructor code for objects which have
vector of PTR attribute.

1913293 USE A DIFFERENT VERSION OF NEW IN READSQL

OTT should also generate new operator for each of the derived
classes (this include generation of the prototype in .h file
and the definition in .cpp file)

1821665 OTT NEEDS TO GENERATE GET/SETVECTOROFREFS TO ACCOMODATE BUG ON NT

OTT needs to generate "getVectorOfRefs" instead of "getVector" for

collections of REFs

1765059 OTT ATTEMPTS TO GENERATE .H FILE STRUCTURES FOR PL/SQL PACKAGES

When OTT was run to generate a .h file for all the object types
in a schema, it attempts to generate entries for PL/SQL packages

1764833 OTT GENERATES INCORRECT HEADER FILES WITH SUBTYPING AND INHERITANCE

There were multiple problems with the ott generated header when
types in the database were organized in type hierarchies