README FILE FOR THE OBJECT TYPE TRANSLATOR (OTT) 8.0.5
------------------------------------------------------
This file contains important information about the Object Type
Translator (OTT) version 8.0.5, which is the OTT release shipped
with the 8.0.5 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. Material here is
also discussed elsewhere, either in the OTT documentation or in
Section 2 of this README file, but deserves special emphasis.
* Section 2 lists known bugs in OTT.
SECTION 1: OTT FREQUENTLY ASKED QUESTIONS
-----------------------------------------
Question: Why can't I write C structs by hand for
my object types?
It is possible for the OCI programmer to write 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: 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: 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
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.
Question: How does OTT perform map an object type name or attribute name
to a C struct or member name?
When the INTYPE file does not give an explicit translation of a
type or attribute name to a C indentifier, OTT translates the name
as follows:
* Before OTT sees the type or attribute name, it is converted from
the database character set to the character set used by OTT.
The user selects the character set used by OTT by specifying the
NLS_LANG environment variable, or by some other platform-specific
mechanism.
In order for OTT to read the name correctly, all the characters of
the name must be found in the OTT character set specified by the
user, although the characters may have different encodings if the two
character sets are different. The easiest way to guarantee that
the OTT character set contains all the necessary characters is to
set it to be the same as the database character
set.
* Next, if the OTT character set is a multi-byte character set,
all multi-byte characters in the name that have single-byte
equivalents are converted to those single-byte
equivalents.
* Next, the name is converted from the OTT character set to the
compiler character set. The compiler character set is
a single-byte character set such as US7ASCII.
* Next, the case of letters is set according to the CASE option
in effect, and any character that is not legal in a C identifier
is replaced by an underscore. If at least one character is
replaced by an underscore, OTT gives a warning message. If all
the characters in a name are replaced by underscores, OTT gives
an error message.
SECTION 2: KNOWN BUGS 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 443456:
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 generated by OTT to
have the same name, or for two members of a struct to have the same
name. These errors will be detected by the C
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.