, Pro*C/C++, or Java, " Large Objects ++, followed by a reference section that describes command line syntax, parameters,
INTYPE file structure, nested
#include file generation, schema names usage, default name mapping, and restrictions.
The first step in using OTT is to create object types or named collection types and store them in the database. This is accomplished through the use of the SQL CREATE TYPE statement.
See Also: For information about.
For global options -- that is, options on the command line or options at the beginning of the
INTYPE file before any TYPE statements -- the value on the command line overrides the value in the
INTYPE file. (The options that can be specified globally in the
INTYPE file are
CASE,
CODE,
INITFILE,
OUTDIR, and
INITFUNC, but not
HFILE.) Anything in the
INTYPE file in a TYPE specification applies to a particular type only, and overrides anything on the command line that would otherwise apply to the type. So if you enter
TYPE person HFILE=p.h, it applies to
person only and overrides the
HFILE on the command line. The statement is not considered a command-line parameter.
Parameters (also called options) set on the command line override any set elsewhere.
See Also: For information about creating object types and collections, refer to Chapter 17, " Objects". can be named on the command line. In addition, a default configuration file is always read. This default configuration file must always exist, but can be empty. The name of the default configuration file is
ottcfg.cfg, and the location of the file is system-specific., the name of the
INTYPE file is specified as
demoin.typ.
Specifies the name of the
OUTTYPE file. When OTT generates the C header file, it also writes information about the translated types into the
OUTTYPE file. This file contains an entry for each of the types that is translated, including its version string, and the header file to which its C representation was written.
In example one, the name of the OUTTYPE file is specified as
demoout.typ.
Specifies the target language for the translation. The following options are available:
C (equivalent to ANSI_C)
ANSI_C (for ANSI C)
KR_C (for Kernighan & Ritchie C)
There is currently no default value,. the
OUTTYPE file of a previous invocation of OTT. If the
INTYPE parameter is not used, all types in the schema to which "CASE" for further information regarding the
CASE option.
The lines that you do not use AS name contains characters other than letters, digits, and underscores
the name conflicts with a C keyword
the type name conflicts with another identifier in the same scope. This can happen, for example, if the program uses two types with the same name from different schemas.
the programmer prefers a different name
OTT may need to translate additional types that are not listed in the
INTYPE file. This is because OTT analyzes the types in the
INTYPE file for type dependencies before performing the translation, and translates other types as necessary. For example, if the ADDRESS type were not listed in the
INTYPE file, but the Person type had an attribute of type ADDRESS,, for example, CREATE TYPE "Person". A SQL identifier is case-sensitive if it was quoted when it was declared.
Quotation marks can also be used to refer to a SQL identifier that is).
Oracle also includes a set of predefined types:, OTT first generates the nested type (if TRANSITIVE = TRUE.) It then maps the object type attribute to a nested struct of the type of the nested object type.
The C datatypes to which OTT maps non-object database attribute types are structures, which, except for OCIDate, are opaque.
The following example demonstrates the various type mappings created that includes:
CASE = LOWER TYPE many_types
OTT would generate the following C structs:
. This is because the OTT parameter "TRANSITIVE", has the default value of TRUE. As described in that section, when TRANSITIVE=TRUE, OTT automatically translates any types which are used as attributes of a type being translated, in order to complete the translation of the listed type.
This is not the case for types that OTT generates a C struct to represent a database object type, it also generates a corresponding NULL indicator struct. When an object type is selected into a C struct, NULL indicator information can earlier discussion of object types in Oracle Call Interface Programmer's Guide.
To support type inheritance of objects, OTT 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 new attributes. Thus, for an object subtype that inherits from a supertype, the first element in the struct is named '_super', followed by elements corresponding to each attribute of the subtype.The type of the element named '_super' is the name of the supertype.
For example, given the type
Person_t, with subtype
Student_t and subtype
Employee_t, which are created as follows:
CREATE TYPE Person_t AS OBJECT ( ssn NUMBER, name VARCHAR2(30), address VARCHAR2(100)) NOT FINAL; CREATE TYPE Student_t UNDER Person_t ( deptid NUMBER, major VARCHAR2(30)) NOT FINAL; CREATE TYPE Employee_t UNDER Person_t ( empid NUMBER, mgr VARCHAR2(30));
and, given an
INTYPE file which includes:
CASE=SAME TYPE EMPLOYEE_T TYPE STUDENT_T TYPE PERSON_T
OTT generates the following C structs for
Person_t,
Student_t, and
Employee_t and their null indicator structs:
#ifndef MYFILENAME_ORACLE #define MYFILENAME_ORACLE #ifndef OCI_ORACLE #include <oci.h> #endif typedef OCIRef EMPLOYEE_T_ref; typedef OCIRef STUDENT_T_ref; typedef OCIRef PERSON_T_ref; struct PERSON_T { OCINumber SSN; OCIString * NAME; OCIString * ADDRESS; }; typedef struct PERSON_T PERSON_T; struct PERSON_T_ind { OCIInd _atomic; OCIInd SSN; OCIInd NAME; OCIInd ADDRESS; }; typedef struct PERSON_T_ind PERSON_T_ind; struct EMPLOYEE_T { PERSON_T _super; OCINumber EMPID; OCIString * MGR; }; typedef struct EMPLOYEE_T EMPLOYEE_T; struct EMPLOYEE_T_ind { PERSON_T _super; OCIInd EMPID; OCIInd MGR; }; typedef struct EMPLOYEE_T_ind EMPLOYEE_T_ind; struct STUDENT_T { PERSON_T _super; OCINumber DEPTID; OCIString * MAJOR; }; typedef struct STUDENT_T STUDENT_T; struct STUDENT_T_ind { PERSON_T _super; OCIInd DEPTID; OCIInd MAJOR; }; typedef struct STUDENT_T_ind STUDENT_T_ind; #endif
The earlier C mapping convention allows simple up-casting from an instance of a subtype to an instance of a supertype in C to work properly. For example:
STUDENT_T *stu_ptr = some_ptr; /* some STUDENT_T instance */ PERSON_T *pers_ptr = (PERSON_T *)stu_ptr; /* up-casting */
The null indicator structs are generated similarly. Note that for the supertype
Person_t null indicator struct, the first element is '_atomic', and that for the subtypes
Employee_t and
Student_t null indicator structs, the first element is '_super' (no atomic element is generated for subtypes).
For attributes of NOT FINAL types (and therefore potentially substitutable), the embedded attribute is represented as a pointer.
Consider a type
Book_t created as:
CREATE TYPE Book_t AS OBJECT ( title VARCHAR2(30), author Person_t /* substitutable */);
The corresponding C struct generated by OTT contains a pointer to
Person_t:
struct Book_t { OCIString *title; Person_t *author; /* pointer to Person_t struct */ }
The null indicator struct corresponding to the earlier type is:
struct Book_t_ind { OCIInd _atomic; OCIInd title; OCIInd author; }
Note that the null indicator struct corresponding to the
author attribute can be obtained from the
author object itself. See OBJECT GET.
If a type is defined to be FINAL, it cannot have any subtypes. An attribute of a FINAL type is therefore not substitutable. In such cases, the mapping is as before: the attribute struct is inline. Now, if the type is altered and defined to be NOT FINAL, the mapping will have to change. The new mapping is generated by running OTT again.
The
OUTTYPE file is named on the OTT command line. When OTT generates the C header file, it also writes the results of the translation into the
OUTTYPE file. This file contains an entry for each of the types that that should be translated. In two of these types, naming conventions are specified.
The following example shows what the
OUTTYPE file looks like after running that.
When the parameter TRANSITIVE has been set to TRUE (it is the default), OTT analyzes the types in the
INTYPE file for type dependencies before performing the translation, and translates other types as necessary..
SQL is used to create type definitions in the database.
OTT generates a header file containing C representations of object types and named collection types. It also generates an implementation file, as named with the
INITFILE option.
The application is written. User-written code in the OCI application declares and calls the
INITFUNC function.
The header file is included in an OCI source code file.
The OCI application, including the implementation file generated by OTT, is compiled and linked with the OCI libraries.
The OCI executable is run against the Oracle Server.
Figure 19-1 Using OTT with OCI
Within the application, the OCI program can perform bind and define operations using program variables declared to be of types that specifically designed to work on attributes of object types and named collection types.
Some of the available functions follow:
OCIStringSize() gets the size of an
OCIString string.
OCINumberAdd() adds two
OCINumber numbers together.
OCILobIsEqual() compares two LOB locators for equality.
OCIRawPtr() gets a pointer to an
OCIRaw raw datatype.
OCICollAppend() appends an element to a collection type (
OCIArray or
OCITable).
OCITableFirst() returns the index for the first existing element of a nested table (
OCITable).
OCIRefIsNull() tests if a REF (
OCIRef) is NULL
These functions are described in detail in allow OTT separately for each piece requiring, for each piece, one initialization file, containing an initialization function..
Square brackets [...] enclose optional items.
An ellipsis (...) immediately following an item (or items enclosed in brackets) means that the item can be repeated any number of times.
Punctuation symbols other than those described earlier are entered as shown. These include '.', '@', and so on.}] [TRANSITIVE=TRUE|FALSE]
The
HFILE parameter is almost always used. If omitted,
HFILE must be specified individually for each type in the
INTYPE file. If (enter it as one line):
OTT userid=scott/tiger (Oracle Net you omit it, OTT automatically attempts to connect to the default database as user CLUSTER$username, where username is the user's operating system user name.
The
INTYPE parameter specifies the name of the file from which to read the list of object type specifications.  be used as an
INTYPE file in a future invocation.. used only in OCI programs. It specifies the name of the initialization function generated by OTT. If this parameter is omitted, the name of the initialization function is derived from the name of the
INITFILE.
INITFUNC=filename
The name of the include (.h) file to be generated (if TRANSITIVE=TRUE),, that you supply this parameter, that parameter affects only those identifiers (attributes or types not explicitly listed) not mentioned in the
INTYPE file. Case conversion takes place after a legal identifier has been generated. on the command line, in a CONFIG file named on the command line, or both. Some parameters are also allowed in the
INTYPE file.
OTT is invoked as follows:
OTT username/password parameters
If one of the parameters on the command line is
CONFIG=filename
additional parameters are read from the configuration file named filename.
In addition, parameters are also read from a default configuration file in a platform-dependent location. This file must exist, but can be empty. Each line in the configuration may contain one parameter, with no whitespace on the line.
If OTT is executed without any arguments, an on-line parameter reference is displayed.
The types for OTT to translate are named in the file specified by the
INTYPE parameter. The parameters
CASE,
INITFILE,
INITFUNC, and
HFILE may also appear in the
INTYPE file.
OUTTYPE files generated OTT and provide all the information needed to determine how a type or attribute name is translated to a legal C identifier. These files contain one or more type specifications. These files also may contain specifications of the following options:
CASE
HFILE
INITFILE
INITFUNC OTT generates from it, see "OTT Support for Type Inheritance".
A type specification in the
INTYPE names an object datatype that is to be translated. The following is an example of a user-created
INTYPE file:. OTT
#includes other necessary files, and
#defines a symbol constructed from the name of the file, that, you can OTT includes
oci name beginning with /) should be used in the
INTYPE file to specify the location of
tott95a.h.
This parameter affects whether the name of a type from the default schema to which.Dept regardless of to which schema the application is connected. If this is the behavior you want, be sure to include schema names with your type names in the
INTYPE file.
In some cases, OTT connects to schema to qualify all type names with schema names in the
INTYPE file.
When OTT creates a C identifier name for an object type or attribute, it translates the name from the database character set to a legal C identifier. First, the name is translated from the database character set to the character set used by OTT. Next, if a translation of the resulting name is supplied in the
INTYPE file, that translation is used. Otherwise, OTT translates the name character-by-character to the compiler character set, applying the
CASE option. The following describes this in more detail.
When OTT reads the name of a database entity, the name is automatically translated from the database character set to the character set used by OTT. In order OTT uses by setting the NLS_LANG environment variable, or by some other platform-specific mechanism.
Once OTT has read the name of a database entity, it translates the name from the character set used by OTT to the compiler's character set. If a translation of the name appears in the
INTYPE file, OTT uses that translation.
Otherwise, OTT attempts to translate the name as follows:
First, if the OTT character set is a multibyte character set, all multibyte characters in the name that have singlebyte equivalents are converted to those singlebyte equivalents.
Next, the name is converted from the OTT character set to the compiler character set. The compiler character set is a singlebyte character set such as US7ASCII.
Finally, the case of letters is set according to the
CASE option in effect, and any character that is not legal in a C identifier, or that has no translation in the compiler character set, 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.
Character-by-character name translation does not alter underscores, digits, or single.