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.