/
/ $Header: readme.doc 06-mar-98.14:29:23 pthiesen Exp $
/
/ readme.txt
/
/ Copyright (c) Oracle Corporation 1996, 1997, 1998, 1999, 2000. All Rights Reserved.
/
/   NAME
/     readme.txt - <one-line expansion of the name>
/
/   DESCRIPTION
/     <short description of component this file declares/defines>
/
/   NOTES
/     <other useful comments, qualifications, etc.>
/
/   MODIFIED   (MM/DD/YY)
/   mjogleka    07/24/00 - update for 8.1.7
/   gstevens    02/09/99 - update for 8.1.5
/   pthiesen    07/16/98 - update readme for 8.1.4 release
/   pthiesen    03/12/98 - added notes on OTT with JDBC
/   pthiesen    03/06/98 - explain limitations of generated REF getters and set
/   pthiesen    03/18/97 - clarify name translation
/   pthiesen    02/07/97 - readme for version 8.1.2
/   pthiesen    08/01/96 - 8.0 beta1 release version
/   pthiesen    07/29/96 - fix typos
/   pccint      07/29/96 - readme file for ott 8.0 beta1
/   pccint      07/29/96 - Creation
/


README FILE FOR THE OBJECT TYPE TRANSLATOR (OTT) 8.1.7
------------------------------------------------------
 
This file contains important information about the Object Type
Translator (OTT) version 8.1.7, which is the OTT release shipped
with the 8.1.7 Oracle database.  These notes are divided into
two sections:
 
* Section 1 answers several frequently asked questions about OTT.
  This section presumes some knowledge of OTT.
 
* Section 2 lists known bugs and restrictions
 

SECTION 1: 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 this 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 2: 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.


