3 TimesTen Support for Oracle Call Interface

Oracle TimesTen In-Memory Database and Oracle IMDB Cache support the Oracle Call Interface (OCI) for C or C++ programs.

This chapter includes the following sections:

Overview of OCI
Overview of TimesTen OCI support
Getting started with TimesTen OCI
Additional features of TimesTen OCI
Call, handle, descriptor, SQL data type, and parameter attribute support

This chapter focuses on TimesTen-specific information regarding OCI support. For complete information, you can refer to Oracle Call Interface Programmer's Guide in the Oracle Database library.

Overview of OCI

OCI is an API that provides functions you can use to access the database server and control SQL execution. OCI supports the data types, calling conventions, syntax, and semantics of the C and C++ programming languages. You compile and link an OCI program much as you would any C or C++ program. There is no preprocessing or precompilation step.

The OCI library of database access and retrieval functions is in the form of a dynamic runtime library that can be linked into an application at runtime. The OCI library includes the following functional areas:

SQL access functions
Data type mapping and manipulation functions

The following are among the many useful features that OCI provides or supports:

Statement caching
Dynamic SQL
Facilities to treat transaction control, session control, and system control statements like DML statements
Description functionality to expose layers of server metadata
Ability to associate commit requests with statement executions to reduce round trips
Optimization of queries using transparent prefetch buffers to reduce round trips
Thread safety that eliminates the need for mutual exclusive locks on OCI handles

For general information about OCI, you can refer to Oracle Call Interface Programmer's Guide, included with the Oracle Database documentation set.

Overview of TimesTen OCI support

This chapter contains information specific to using OCI with TimesTen and IMDB Cache. For supported features, TimesTen OCI syntax and usage is the same as that in Oracle Database.

This section covers the following topics:

OCI libraries and architecture
Globalization support
TimesTen restrictions and differences
The ttSrcScan utility

OCI libraries and architecture

TimesTen OCI depends on the Oracle client library and the TimesTen ODBC libraries. TimesTen OCI support enables you to run many existing OCI applications with TimesTen in direct mode or client/server mode. It also enables you to use other Oracle products, such as Pro*C/C++ and ODP.NET, that use OCI as a database interface. (You can also call PL/SQL from OCI, Pro*C/C++, and ODP.NET applications.) Figure 3-1 sh ows where OCI support is positioned in the TimesTen architecture.

TimesTen includes Oracle Instant Client as the OCI client library. This is configured through the appropriate ttenv script, as discussed in "Setting the environment for development".

Figure 3-1 OCI in the TimesTen architecture

Description of "Figure 3-1 OCI in the TimesTen architecture"

TimesTen Release 11.2.1 OCI is based on Oracle Release 11.1.0.7 OCI and supports the contemporary OCI 8 style APIs. For example, the OCIStmtExecute() function is supported but not the older oexec() function. See "Obsolete OCI Routines" in Oracle Call Interface Programmer's Guide in the Oracle Database documentation.

Globalization support

This section discusses TimesTen OCI support for globalization.

Character sets

To specify a character set for the connection, OCI programs can set the NLS_LANG environment variable or call OCIEnvNlsCreate(). Any connection character set in the odbc.ini file is ignored. Setting the character set explicitly is recommended. The default is typically AMERICAN_AMERICA.US7ASCII.

Note that because TimesTen OCI does not support language or locale (territory) settings, the language and territory components of NLS_LANG, such as AMERICAN_AMERICA above, are ignored. Even when not specifying the language and locale, however, you must still include the period in front of the character set when setting NLS_LANG. For example, either of the following would work, although AMERICAN_AMERICA is ignored:

NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

Or:

NLS_LANG=.WE8ISO8859P1

Notes:

An NLS_LANG environment setting overrides the TimesTen default character set.
The TIMESTEN8 character set is not supported.
On Windows, the NLS_LANG setting is taken from the registry if it is not in the environment. If your OCI or Pro*C/C++ program has trouble connecting to TimesTen, verify that the NLS_LANG setting under HKEY_LOCAL_MACHINE\Software\ORACLE\ is valid and indicates a character set supported by TimesTen. (The NLS_LANG registry setting may be set to an invalid value, such as "NA". If the value is "NA", the TimesTen installer will replace it with AMERICAN_AMERICA.US7ASCII.) This is likely only an issue on systems that previously had Oracle9i or earlier Oracle versions installed.
Refer to "Choosing a Locale with the NLS_LANG Environment Variable" in Oracle Database Globalization Support Guide for information about NLS_LANG.
Refer to "OCIEnvNlsCreate()" in Oracle Call Interface Programmer's Guide for information about that OCI call.

Additional globalization features

TimesTen OCI also supports the following additional globalization features. These can be set either as environment variables or TimesTen general connection attributes. An environment variable setting takes precedence.

NLS_LENGTH_SEMANTICS: By default, the lengths of character data types CHAR and VARCHAR2 are specified in bytes, not characters. For single-byte character encoding this works well. For multibyte character encoding, you can use NLS_LENGTH_SEMANTICS to create CHAR and VARCHAR2 columns using character-length semantics instead. Supported settings are BYTE (default) and CHAR. (NCHAR and NVARCHAR2 columns are always character-based. Existing columns are not affected.)
NLS_SORT: This specifies the type of sort for character data. It overrides the default value from NLS_LANGUAGE. Valid values are BINARY or any linguistic sort name supported by TimesTen. For example, to specify the German linguistic sort sequence, set NLS_SORT=German. NLS_NCHAR_CONV_EXCP: This determines whether an error is reported when there is data loss during an implicit or explicit character type conversion between NCHAR or NVARCHAR data and CHAR or VARCHAR2 data. Valid settings are TRUE and FALSE. The default value is FALSE, resulting in no error being reported.

Note:

These environment variables override the corresponding TimesTen general connection attributes for OCI or Pro*C/C++ programs.

Refer to Oracle TimesTen In-Memory Database Operations Guide and Oracle Database Globalization Support Guide for additional information on these environment variables and related features.

TimesTen restrictions and differences

This section discusses restrictions and differences for OCI in TimesTen compared to in the Oracle Database.

Oracle Database features not supported

TimesTen does not support OCI calls that are related to functionality that does not exist in TimesTen or IMDB Cache. For example, TimesTen and IMDB Cache do not support these Oracle Database features:

Advanced Queuing
Any Data
Object support
LOB data types
Collections
Cartridge Services
Direct path loading
Date/time intervals
Iterators
BFILE
Cryptographic Toolkit
XML DB support
Spatial Services
Event handling
Session switching
Scrollable cursors

Additional TimesTen OCI restrictions

TimesTen OCI has the following restrictions:

The TypeMode data store attribute must be set to 0, which corresponds to Oracle behavior.
The DuplicateBindMode general connection attribute must be set to 0, which corresponds to Oracle behavior.
The DDLCommitBehavior general connection attribute must be set to 0, which corresponds to Oracle behavior.
Asynchronous calls are not supported.
Connection pooling and session pooling are not supported.
Describing objects with OCIDescribeAny() is supported only by name. Describing PL/SQL objects is not supported.
TimesTen Client/Server automatic client failover is not supported.
The TNSPING utility does not recognize connections to TimesTen.
Retrieving implicit ROWID values from INSERT, UPDATE, and DELETE statements is not supported. (This is supported for SELECT FOR UPDATE statements, however.)
TimesTen built-in procedures that return result sets are not supported directly.
Only a single REF CURSOR can be returned from a PL/SQL block, procedure call, or function call.
Binding and defining of structures through OCIBindArrayOfStruct() and OCIDefineArrayOfStruct() is supported for SQL statements but not for PL/SQL.
Oracle utilities such as SQL*Plus and SQL*Loader are not supported. (As alternatives for these two in particular, you can use the ttIsql utility and the ttBulkCp built-in procedure, respectively.)
Ar ray binding, the ability to bind associative arrays (index-by tables) and varrays (variable size arrays) into PL/SQL statements, is not supported.

Additional TimesTen OCI differences

Both TimesTen and Oracle support XA, but TimesTen does not support XA through OCI.

With OCI, TimesTen automatically disables autocommit for DML statements.

The ttSrcScan utility

If you have an existing OCI program and want to see whether it uses OCI features that TimesTen does not support, you can use the ttSrcScan command line utility to scan your program for unsupported functions, packages, types, type codes, attributes, modes, and constants. This is a standalone utility that can be run without TimesTen or Oracle being installed and runs on any platform supported by TimesTen. It reads source code files as input and creates HTML and text files as output. If the utility finds unsupported items, then they are logged and alternatives are suggested. You can find the ttSrcScan executable in the quickstart/sample_util directory in your TimesTen installation.

Specify an input file or directory for the program to be scanned and an output directory for the ttSrcScan reports. Other options are available as well. See the README file in the sample_util directory for information.

Getting started with TimesTen OCI

This section discusses the following topics for getting started with a TimesTen OCI application:

Environment variables for TimesTen OCI
Compiling and linking OCI applications
Connecting to a TimesTen database from OCI
Error reporting
Signal handling and diagnostic framework considerations
OCI demo programs

En vironment variables for TimesTen OCI

Environment variables for executing a TimesTen OCI application are described in Table 3-1. Settings apply to both direct mode and client/server mode except as noted.

After installation, you can modify environment variables as appropriate through the TimesTen install_dir/bin/ttenv script or quickstart/ttquickstartenv script applicable to your operating system.

You can also use the TimesTen OCI and Pro*C/C++ Makefiles provided with the Quick Start demos to implement appropriate environment settings. These are in the following locations:

quickstart/sample_code/oci/
quickstart/sample_code/proc/

Refer to "Environment variables" in Oracle TimesTen In-Memory Database Installation Guide for additional information about environment variables and ttenv.

Table 3-1 Environment variables for TimesTen OCI

Variable	Required or optional	Settings
`LD_LIBRARY_PATH` (UNIX) `PATH` (Windows)	Required	Must be set so that the Oracle Instant Client directory precedes the Oracle Database libraries in the path. The path will be set properly if you use either of the following scripts under `install_dir`: bin/ttenv quickstart/ttquickstartenv (Unless you installed Quick Start in a different location.)
`TNS_ADMIN`	Required if you use the `tnsnames` naming method	Specifies the directory where the `tnsnames.ora` file is located. This is also where TimesTen looks for a `sqlnet.ora` file.
`TWO_TASK` (UNIX) `LOCAL` (Windows)	Optional	You can use this, whichever is appropriate for your platform, instead of specifying the `dbname` argument in your OCI logon call. The setting consists of a valid TNS name or easy connect string. See "Connecting to a TimesTen database from OCI" for more information.
`NLS_LANG`	Optional	See "Character sets". Only the character set component is honored and it must indicate a character set supported by TimesTen. The language and territory values are ignored. This environment variable overrides the TimesTen default character set.
`NLS_SORT`	Optional	See "Additional globalization features". The sort order must be a value supported by TimesTen. This overrides the TimesTen `NLS_SORT` general connection attribute.
`NLS_LENGTH_SEMANTICS`	Optional	See "Additional globalization features". This overrides the TimesTen `NLS_LENGTH_SEMANTICS` general connection attribute.
`NLS_NCHAR_CONV_EXCP`	Optional	See "Additional globalization features". This overrides the TimesTen `NLS_NCHAR_CONV_EXCP` general connection attribute.

Note:

Refer to "NLS general connection attributes" in Oracle TimesTen In-Memory Database Reference for information about the NLS connection attributes mentioned in the table.

Co mpiling and linking OCI applications

No changes are required for the steps to compile and link an OCI application in TimesTen.

OCI programs that use the Oracle Client 11.1.0.7 library do not have to be recompiled or relinked to be executed with TimesTen.

Con necting to a TimesTen database from OCI

TimesTen OCI uses the Oracle Instant Client to connect to the TimesTen database. You can connect to the database through either the tnsnames or the easy connect naming method, similarly to how you would connect to an Oracle database through those methods.

This section covers the following topics:

Using the tnsnames naming method to connect
Using an easy connect string to connect
Configuring whether to use tnsnames.ora or easy connect
Connecting as an externally identified user in OCI

Refer to "Configuring Naming Methods" in Oracle Database Net Services Administrator's Guide for additional information about tnsnames, easy connect, and the tnsnames.ora file.

Notes:

Although the sqlnet mechanism is used for a TimesTen OCI connection, the connection goes through the TimesTen ODBC driver, not the Oracle sqlnet driver.
Privilege to connect to the database must be explicitly granted to every user other than the instance administrator, through the CREATE SESSION privilege. Refer to "Access control for connections".

Using the tnsnames naming method to con nect

TimesTen supports tnsnames syntax. You can use a TimesTen tnsnames.ora entry the same way you would use an Oracle tnsnames.ora entry.

The syntax of a TimesTen entry in tnsnames.ora is as follows:

tns_entry = (DESCRIPTION =
              (CONNECT_DATA =
                (SERVICE_NAME = dsn)
                (SERVER = timesten_direct | timesten_client)))

Where tns_entry is the arbitrary TNS name you assign to the entry. You can use this as the dbname argument in OCILogon(), OCILogon2(), and OCIServerAttach() calls.

DESCRIPTION and CONNECT_DATA are required as shown.

For SERVICE_NAME, dsn must be a TimesTen DSN that is configured in the odbc.ini or sys.odbc.ini file that is visible to a user running your OCI application. On Windows, the DSN can be specified by using the ODBC Data Source Administrator. See "Managing TimesTen Databases" in Oracle TimesTen In-Memory Database Operations Guide.

For SERVER, timesten_direct specifies a direct connection to TimesTen or timesten_client specifies a client/server connection. If you choose timesten_client, the DSN must be configured as a client/server database.

As always, the host and port of the TimesTen server are determined from entries in the sys.ttconnect.ini file, according to the DSN. See "Working with the TimesTen Client and Server" in Oracle TimesTen In-Memory Database Operations Guide.

Here is a sample tnsnames.ora entry for a direct connection:

my_tnsname = (DESCRIPTION = 
               (CONNECT_DATA = 
                 (SERVICE_NAME = my_dsn)
                 (SERVER = timesten_direct)))

You can use the TNS name, my_tnsname, in either of the following ways:

Specify "my_tnsname" for the dbname argument in your OCI logon call.
Specify an empty string for dbname and set TWO_TASK or LOCAL to "my_tnsname".

For example:

OCILogon2(envhp, errhp, &svchp,
         (text *)"user1", (ub4)strlen("user1"),
         (text *)"pwd1", (ub4)strlen("pwd1"), 
         (text *)"my_tnsname", (ub4)strlen((char*)"my_tnsname"), OCI_DEFAULT));

Refer to "Connect, Authorize, and Initialize Functions" in Oracle Call Interface Programmer's Guide for details about OCI logon calling sequences.

Or on a UNIX system, for example, you can set TWO_TASK to "my_tnsname" and use an OCI logon call with an empty string for dbname:

OCILogon2(envhp, errhp, &svchp,
         (text *)"user1", (ub4)strlen("user1"),
         (text *)"pwd1", (ub4)strlen("pwd1"), 
         (text *)"", (ub4)0, OCI_DEFAULT));

Using an easy connect string to con nect

TimesTen supports easy connect syntax, which enhances the Instant Client package by allowing connections to be made without configuring tnsnames.ora. An easy connect string has syntax similar to a URL, in the following format:

[//]host[:port]/service_name:server[/instance]

The initial double-slash is optional. A host name must be specified to satisfy easy connect syntax, but is otherwise ignored by TimesTen. The name "localhost" is typically used by convention. Any value specified for the port is also ignored. In client/server mode, the host and port of the TimesTen server are determined from entries in the sys.ttconnect.ini file, according to the TimesTen DSN.

Specify the DSN for service_name. Specify timesten_client or timesten_direct, as desired, for server.

TimesTen ignores the instance field and does not require that it be specified.

For example, the following easy connect string connects to a TimesTen server using the client/server libraries. Assume the DSN ttclient in the odbc.ini file is resolved as a client/server data source and connects to the corresponding host and port specified in the sys.ttconnect.ini file:

"localhost/ttclient:timesten_client"

The following easy connect string is for a direct connection to TimesTen. Assume the DSN ttdirect is defined in odbc.ini:

"localhost/ttdirect:timesten_direct"

You can use an easy connect string in either of the following ways:

Specify it for the dbname argument in your OCI logon call.
Specify an empty string for dbname and set TWO_TASK or LOCAL to the easy connect string, in quotes.

For example:

OCILogon2(envhp, errhp, &svchp,
         (text *)"user1", (ub4)strlen("user1"),
         (text *)"pwd1", (ub4)strlen("pwd1"),
         (text *)"localhost/ttclient:timesten_client",
         (ub4)strlen((char*)"localhost/ttclient:timesten_client"), OCI_DEFAULT));

Refer to "Connect, Authorize, and Initialize Functions" in Oracle Call Interface Programmer's Guide for details about OCI logon calling sequences.

Or on a UNIX system, for example, you can set TWO_TASK to "localhost/ttclient:timesten_client" and use an OCI logon call with an empty string for dbname:

OCILogon2(envhp, errhp, &svchp,
         (text *)"user1", (ub4)strlen("user1"),
         (text *)"pwd1", (ub4)strlen("pwd1"), 
         (text *)"", (ub4)0, OCI_DEFAULT));

Configuring whether to use tnsnames.ora or easy connect

If a sqlnet.ora file is present, it specifies the naming methods that will be tried and the order in which they will be tried. The Instant Client will look for a sqlnet.ora file at the TNS_ADMIN location, if applicable. If TNS_ADMIN has not been set but ORACLE_HOME has been (such as if you had a previous Instant Client installation), the default sqlnet.ora location is the Oracle Database default location as noted in "Parameters for the sqlnet.ora File" in Oracle Database Net Services Reference.

If sqlnet.ora is found and does not include a particular naming method, you cannot use that method. If sqlnet.ora is not found, you can use either method.

In TimesTen, sample copies of tnsnames.ora and sqlnet.ora are in the install_dir/network/admin/samples directory. Here is the sqlnet.ora file that TimesTen provides, which supports both tnsnames and easy connect ("EZCONNECT"):

# To use ezconnect syntax or tnsnames, the following entries must be
# included in the sqlnet.ora configuration.
#
NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)

With this file, TimesTen will first look for tnsnames syntax in your OCI logon calls. If it cannot find tnsnames syntax, it will look for easy connect syntax.

Con necting as an externally identified user in OCI

You can connect through OCI as an externally identified user (external user) by specifying the user name in brackets, such as "[myadmin]", and the password as an empty string, "".

In particular, this is useful in connecting as the instance administrator, which in TimesTen is always an external user.

Adapting an earlier example:

OCILogon2(envhp, errhp, &svchp,
         (text *)"[myadmin]", (ub4)strlen("[myadmin]"),
         (text *)"", (ub4)strlen(""), 
         (text *)"my_tnsname", (ub4)strlen((char*)"my_tnsname"), OCI_DEFAULT));

This functionality uses OCI proxy syntax. You can refer to the discussion of client access through a proxy in Oracle Call Interface Programmer's Guide.

Er ror reporting

Errors under TimesTen OCI applications return Oracle error codes. TimesTen attempts to report the same Oracle error code as Oracle would under similar conditions. The error messages may come from either the TimesTen catalog or the Oracle catalog. Some error messages may include the accompanying TimesTen error code if appropriate.

Fatal errors are those that make the database inaccessible until after error recovery. When a fatal error occurs, all database connections are required to disconnect in order to avoid out-of-memory conditions. No further operations may complete. Shared memory from the old TimesTen instance will not be freed until all active connections at the time of the error have disconnected.

Fatal errors in OCI are indicated by the Oracle error code ORA-03135 or ORA-00600. Error handling for these errors should be different from standard error handling. In particular, the application error-handling code should include a disconnect from the database.

Sig nal handling and diagnostic framework considerations

The OCI diagnostic framework installs signal handlers that may impact any signal handling that you use in your application. You can disable OCI signal handling by setting DIAG_SIGHANDLER_ENABLED=FALSE in the sqlnet.ora file. Refer to "Fault Diagnosability in OCI" in Oracle Call Interface Programmer's Guide for information.

OCI demo programs

TimesTen ships OCI demo programs. They are in the quickstart/sample_code/oci directory. The README file in the directory explains how to compile and run the demos.

Refer to the Quick Start welcome page at install_dir/quickstart.html for information.

Additional features of TimesTen OCI

This section covers the following topics for developers using TimesTen OCI:

TimesTen deferred prepare
Using IMDB Cache in OCI
Duplicate parameter bindings in TimesTen OCI

TimesTen defer red prepare

In OCI, a prepare call is expected to be a lightweight operation performed on the client. To allow TimesTen to be consistent with this expectation, and to avoid unwanted round trips between client and server, the TimesTen client library implementation of SQLPrepare performs what is referred to as a deferred prepare, where the request is not sent to the server until required. See "TimesTen deferred prepare".

Using IMDB Cache in OCI

This section discusses TimesTen OCI features related using the IMDB Cache:

Specifying the Oracle password in OCI for IMDB Cache
Determining the number of cache groups affected by an action

Spe cifying the Oracle password in OCI for IMDB Cache

To use IMDB Cache, there must be a cache user in the TimesTen database with the same name as an Oracle Database user who can select from and update the cached Oracle tables. This Oracle user, for example, can be the cache administration user or a schema user. The password of the TimesTen cache user can be different from the password of the Oracle user with the same name. See "Setting Up a Caching Infrastructure" in Oracle In-Memory Database Cache User's Guide for details.

For use of OCI with the IMDB Cache, TimesTen allows you to pass the Oracle user's password through OCI by appending it to the password field in an OCILogon() or OCILogon2() call when you log in to TimesTen. Use the attribute OraclePWD in the connect string, such as in the following example:

text *cacheuser = (text *)"cacheuser1";
text *cachepwds = (text *)"ttpwd;OraclePWD=orclpwd";
text *ttdbname = (text *)"tt_tnsname";
....
OCILogon2(envhp, errhp, &svchp,
       (text *)cacheuser, (ub4)strlen(cacheuser),
       (text *)cachepwds, (ub4)strlen(cachepwds),
       (text *)ttdbname, (ub4)strlen(ttdbname), OCI_DEFAULT));

You must always specify OraclePWD, even if the Oracle user's password is the same as the TimesTen user's password.

Note the following for the example:

cacheuser1 is the name of the TimesTen cache user as well as the name of the Oracle user who can access the cached Oracle tables.
ttpwd is the password of the TimesTen cache user.
orclpwd is the password of the Oracle user.
tt_tnsname is the TNS name of the TimesTen database being connected to.

The Oracle database is specified through the TimesTen OracleNetServiceName general connection attribute in the odbc.ini or sys.odbc.ini file.

Alternatively, instead of using a TNS name, you could use easy connect syntax or the TWO_TASK or LOCAL environment variable, as discussed in preceding sections.

Determining the number of cache groups affected by an action

In TimesTen OCI, following the execution of a FLUSH CACHE GROUP, LOAD CACHE GROUP, REFRESH CACHE GROUP, or UNLOAD CACHE GROUP statement, the OCI Function OCIAttrGet() with the OCI_ATTR_ROW_COUNT argument returns the number of cache instances that were flushed, loaded, refreshed, or unloaded.

For related information, see "Determining the number of cache instances affected by an operation" in the Oracle In-Memory Database Cache User's Guide.

Du plicate parameter bindings in TimesTen OCI

"Binding duplicate parameters in SQL statements" discusses the two supported modes for binding duplicate parameters in a SQL statement, either the Oracle mode or the traditional TimesTen mode. As in that section, consider the following query. Note that in TimesTen OCI, only the Oracle mode is supported.

SELECT * FROM employees
  WHERE employee_id < :a AND manager_id > :a AND salary < :b;

In OCI, as in the Oracle mode in general, two occurrences of parameter a are considered to be separate parameters. However, OCI allows both occurrences of a to be bound with a single call to OCIBindByPos():

OCIBindByPos(..., 1, ...); /* both occurrences of :a */
OCIBindByPos(..., 3, ...); /* occurrence of :b */

Alternatively, OCI also allows the two occurrences of a to be bound separately:

OCIBindByPos(..., 1, ...); /* first occurrence of :a */
OCIBindByPos(..., 2, ...); /* second occurrence of :a */
OCIBindByPos(..., 3, ...); /* occurrence of :b */

Note that in both cases, parameter b is considered to be in position 3.

Note:

OCI also allows parameters to be bound by name, rather than by position, using OCIBindByName().

Call, handle, descriptor, SQL data type, and parameter attribute support

Table 3-2 lists TimesTen support for OCI calls that are documented for Oracle Database, release 11.1.0.7.

Some groups of calls are represented with an asterisk in the name. For example, the calls related to Advanced Queuing, which TimesTen does not support, have names that start with OCIAQ and are represented in the table as OCIAQ*(). OCI date functions, which TimesTen does support, are designated by OCIDate*().

Table 3-2 TimesTen OCI call support

OCI call	Supported	Notes
`OCIAQ*()`	No	TimesTen does not support Advanced Queuing.
`OCIAnyData*()`	No	TimesTen does not support Any Data.
`OCIAppCtxClearAll()`	Yes
`OCIAppCtxSet()`	Yes
`OCIArrayDescriptorAlloc()`	Yes
`OCIArrayDescriptorFree()`	Yes
`OCIAttrGet()`	Yes	TimesTen support includes special usage with cache groups. See "Using IMDB Cache in OCI".
`OCIAttrSet()`	Yes
`OCIBinXml*()`	No	TimesTen does not support XML DB.
`OCIBindArrayOfStruct()`	Yes	Supported for SQL statements but not PL/SQL.
`OCIBindByName()`	Yes	Unsupported values for the `mode` parameter: `OCI_DATA_AT_EXEC` `OCI_IOV`
`OCIBindByPos()`	Yes	Unsupported values for the `mode` parameter: `OCI_DATA_AT_EXEC` `OCI_IOV`
`OCIBindDynamic()`	No
`OCIBindObject()`	No	TimesTen does not support user-defined objects.
`OCIBreak()`	No
`OCICache*()`	No	TimesTen does not support user-defined objects.
`OCICharSetConversionIsReplacementUsed()`	Yes
`OCICharSetToUnicode()`	Yes
`OCIClientVersion()`	Yes
`OCIColl*()`	No	TimesTen does not support collections.
`OCIConnectionPoolCreate()`	No
`OCIConnectionPoolDestroy()`	No
`OCIContext*()`	No	TimesTen does not support Data Cartridge.
`OCIDBShutdown()`	No
`OCIDBStartup()`	No
`OCIDate*()`	Yes	See Table 3-4 for information about descriptor support.
`OCIDefineArrayOfStruct()`	Yes	Supported for SQL statements but not PL/SQL.
`OCIDefineByPos()`	Yes
`OCIDefineDynamic()`	No
`OCIDefineObject()`	No
`OCIDescribeAny()`	Yes	PL/SQL objects are not supported. Describing objects is supported only by name. The following are unsupported values for the `objptr_typ` parameter: `OCI_OTYPE_REF` `OCI_OTYPE_PTR` The following are unsupported values for the `objtyp` parameter: `OCI_PTYPE_PKG` `OCI_PTYPE_FUNC` `OCI_PTYPE_PROC` `OCI_PTYPE_SYN` `OCI_PTYPE_TYPE` When you use the setting `OCI_PTYPE_DATABASE` for the `objtyp` parameter, use the predetermined name $TT_DB_NAME$ as the database name for the `*objptr` parameter.
`OCIDescriptorAlloc()`	Yes
`OCIDescriptorFree()`	Yes
`OCIDirPath*()`	No	TimesTen does not support Direct Path Loading.
`OCIDuration*()`	No	TimesTen does not support Data Cartridge.
`OCIEnvCreate()`	Yes	Unsupported values for the `mode` parameter: `OCI_EVENTS` `OCI_NEW_LENGTH_SEMANTICS` `OCI_NCHAR_LITERAL_REPLACE_ON` `OCI_NCHAR_LITERAL_REPLACE_OFF` `OCI_NO_MUTEX` (Instead use `OCI_ENV_NO_MUTEX`.)
`OCIEnvInit()`	Yes	Unsupported values for the `mode` parameter: `OCI_NO_MUTEX` `OCI_ENV_NO_MUTEX` Note: Use `OCIEnvCreate()` instead of `OCIEnvInit()`. `OCIEnvInit()` is supported for backward compatibility.
`OCIEnvNlsCreate()`	Yes	Unsupported values for the `mode` parameter: `OCI_EVENTS` `OCI_NCHAR_LITERAL_REPLACE_ON` `OCI_NCHAR_LITERAL_REPLACE_OFF` `OCI_NO_MUTEX` (Instead use `OCI_ENV_NO_MUTEX`.)
`OCIErrorGet()`	Yes
`OCIExtProc*()`	No	TimesTen does not support Data Cartridge.
`OCIExtract*()`	No	TimesTen does not support Data Cartridge.
`OCIFile*()`	No	TimesTen does not support Data Cartridge.
`OCIFormatInit()`	No	TimesTen does not support Data Cartridge.
`OCIFormatString()`	No	TimesTen does not support Data Cartridge.
`OCIFormatTerm()`	No	TimesTen does not support Data Cartridge.
`OCIHandleAlloc()`	Yes
`OCIHandleFree()`	Yes
`OCIInitialize()`	Yes	Unsupported values for the `mode` parameter: `OCI_NO_MUTEX` `OCI_ENV_NO_MUTEX` Note: Use `OCIEnvCreate()` instead of `OCIInitialize()`. `OCIInitialize()` is supported for backward compatibility.
`OCIInterval*()`	Yes	See Table 3-4 for information about descriptor support.
`OCIIter*()`	No	TimesTen does not support collections.
`OCILdaToSvcCtx()`	No
`OCILob*()`	No	TimesTen does not support LOB data types.
`OCILogoff()`	Yes
`OCILogon()`	Yes
`OCILogon2()`	Yes	`OCI_DEFAULT` is the only supported value for the `mode` parameter.
`OCIMemory*()`	No	TimesTen does not support Data Cartridge.
`OCIMessage*()`	No	TimesTen does not support Data Cartridge.
`OCIMultiByte*()`	Yes
`OCINls*()`	Yes
`OCINumber*()`	Yes
`OCIObject*()`	No	TimesTen does not support user-defined objects.
`OCIParamGet()`	Yes
`OCIParamSet()`	Yes
`OCIPasswordChange()`	No
`OCIPing()`	Yes
`OCIRaw*()`	Yes
`OCIRef*()`	No
`OCIReset()`	No
`OCIRowidToChar()`	Yes
`OCIServer*()`	Yes	`OCI_DEFAULT` is the only supported value for the `mode` parameter of `OCIServerAttach`.
`OCISessionBegin()`	Yes	`OCI_CRED_RDBMS` is the only supported value for the `credt` parameter. `OCI_DEFAULT` is the only supported value for the `mode` parameter.
`OCISessionEnd()`	Yes
`OCISessionGet()`	Yes
`OCISessionPoolCreate()`	No
`OCISessionPoolDestroy()`	No
`OCISessionRelease()`	Yes
`OCISharedLibInit()`	No
`OCIStmtExecute()`	Yes	Unsupported values for the `mode` parameter: `OCI_BATCH_ERRORS` `OCI_EXACT_FETCH` `OCI_STMT_SCROLLABLE_READONLY` Note: Using `OCI_COMMIT_ON_SUCCESS` results in improved performance, avoiding an extra round trip to the server to commit a transaction.
`OCIStmtFetch()`	Yes
`OCIStmtFetch2()`	Yes	The only supported values for the `orientation` parameter are `OCI_DEFAULT` and `OCI_FETCH_NEXT`.
`OCIStmtGetBindInfo()`	Yes
`OCIStmtGetPieceInfo()`	No
`OCIStmtPrepare()`	Yes	The only supported value for the `language` parameter is `OCI_NTV_SYNTAX`. Note: In TimesTen, `OCIStmtPrepare()` does not support statement caching. See `OCIStmtPrepare2()` that follows.
`OCIStmtPrepare2()`	Yes	The only supported value for the `mode` parameter is `OCI_DEFAULT`. For statement caching, TimesTen supports the `key` argument to tag a statement for future calls to `OCIStmtPrepare2()` or `OCIStmtRelease()`.
`OCIStmtRelease()`	Yes	The only supported value for the `mode` parameter is `OCI_DEFAULT`. For statement caching, TimesTen supports the `key` argument to tag a statement. This can be the key from `OCIStmtPrepare2()`.
`OCIStmtSetPieceInfo()`	No
`OCIString*()`	Yes
`OCISubscription*()`	No	TimesTen does not support Advanced Queuing.
`OCISvcCtxToLda()`	No
`OCITable*()`	No
`OCITerminate()`	No
`OCIThread*()`	Yes
`OCITransCommit()`	Yes	The only supported value for the `mode` parameter is `OCI_DEFAULT`.
`OCITransDetach()`	No
`OCITransForget()`	No
`OCITransMultiPrepare()`	No
`OCITransPrepare()`	No
`OCITransRollback()`	Yes
`OCITransStart()`	No
`OCIType*()`	No
`OCIUnicodeToCharSet()`	Yes
`OCIUserCallbackGet()`	Yes
`OCIUserCallbackRegister()`	Yes
`OCIWideChar*()`	Yes
`OCIXmlDbFreeXmlCtx()`	No	TimesTen does not support XML DB.
`OCIXmlDbInitXmlCtx()`	No	TimesTen does not support XML DB.

Table 3-3 lists the handles and attributes that TimesTen OCI supports.

Table 3-3 TimesTen OCI supported handles and attributes

Handle	C object	Supported attributes
Environment	`OCIEnv`	`OCI_ATTR_ENV_CHARSET_ID` `OCI_ATTR_ENV_NCHARSET_ID` `OCI_ATTR_ENV_UTF16` `OCI_ATTR_EVTCTX` `OCI_ATTR_OBJECT`
Error	`OCIError`	`OCI_ATTR_DML_ROW_OFFSET`
Service context	`OCISvcCtx`	`OCI_ATTR_ENV` `OCI_ATTR_IN_V8_MODE` `OCI_ATTR_SERVER` `OCI_ATTR_SESSION` `OCI_ATTR_TRANS`
Statement	`OCIStmt`	`OCI_ATTR_BIND_COUNT` `OCI_ATTR_CURRENT_POSITION` `OCI_ATTR_ENV` `OCI_ATTR_FETCH_ROWID` `OCI_ATTR_NUM_DML_ERRORS` `OCI_ATTR_PARAM_COUNT` `OCI_ATTR_PREFETCH_MEMORY` `OCI_ATTR_PREFETCH_ROWS` `OCI_ATTR_ROW_COUNT` `OCI_ATTR_ROWID` `OCI_ATTR_ROWS_FETCHED` `OCI_ATTR_SQLFNCODE` `OCI_ATTR_STATEMENT` `OCI_ATTR_STMT_TYPE`
Bind	`OCIBind`	`OCI_ATTR_CHARSET_FORM` `OCI_ATTR_CHARSET_ID` `OCI_ATTR_MAXCHAR_SIZE` `OCI_ATTR_MAXDATA_SIZE`
Define	`OCIDefine`	`OCI_ATTR_CHARSET_FORM` `OCI_ATTR_CHARSET_ID` `OCI_ATTR_MAXCHAR_SIZE`
Describe	`OCIDescribe`	`OCI_ATTR_PARAM` `OCI_ATTR_PARAM_COUNT`
Server	`OCIServer`	`OCI_ATTR_ENV` `OCI_ATTR_IN_V8_MODE` `OCI_ATTR_SERVER_GROUP` `OCI_ATTR_SERVER_STATUS`
User session	`OCISession`	`OCI_ATTR_CLIENT_IDENTIFER` `OCI_ATTR_CLIENT_INFO` `OCI_ATTR_CURRENT_SCHEMA` `OCI_ATTR_DRIVER_NAME` `OCI_ATTR_INITIAL_CLIENT_ROLES` `OCI_ATTR_MODULE` `OCI_ATTR_PROXY_CREDENTIALS` `OCI_ATTR_USERNAME`
Authentication	`OCIAuthInfo`	Same as for user session handle.
Transaction	`OCITrans`	`OCI_ATTR_TRANS_NAME` `OCI_ATTR_TRANS_TIMEOUT`
Thread	`OCIThreadHandle`

Table 3-4 lists the descriptors that TimesTen OCI supports.

Table 3-4 TimesTen OCI supported descriptors

Descriptor	C object
Parameter (read-only)	`OCIParam`
`ROWID`	`OCIRowid`
`ANSI DATE`	`OCIDateTime`
`TIMESTAMP`	`OCIDateTime`
`TIMESTAMP WITH TIME ZONE`	`OCIDateTime`
`TIMESTAMP WITH LOCAL TIME ZONE`	`OCIDateTime`
`INTERVAL YEAR TO MONTH`	`OCIInterval`
`INTERVAL DAY TO SECOND`	`OCIInterval`
User callback	`OCIUcb`

Table 3-5 lists the SQL data types that TimesTen OCI supports.

Table 3-5 TimesTen OCI supported SQL data types

SQL data type	Notes
`SQLT_AFC`
`SQLT_AVC`
`SQLT_BDOUBLE`
`SQLT_BFLOAT`
`SQLT_BIN`
`SQLT_CHR`
`SQLT_DAT`
`SQLT_DATE`
`SQLT_FLT`
`SQLT_IBDOUBLE`
`SQLT_IBFLOAT`
`SQLT_INT`
`SQLT_INTERVAL_DS`	Not stored in TimesTen.
`SQLT_INTERVAL_YM`	Not stored in TimesTen.
`SQLT_LBI`
`SQLT_LNG`
`SQLT_LVB`	Truncated at 4 MB when stored in TimesTen.
`SQLT_LVC`	Truncated at 4 MB when stored in TimesTen.
`SQLT_NUM`
`SQLT_ODT`
`SQLT_RDD`	Rowids returned in Oracle format.
`SQLT_RSET`	Only one result set parameter is allowed for each statement.
`SQLT_STR`
`SQLT_TIME`
`SQLT_TIME_TZ`	Time zone is ignored when stored in TimesTen.
`SQLT_TIMESTAMP`
`SQLT_TIMESTAMP_LTZ`	Time zone is ignored when stored in TimesTen.
`SQLT_TIMESTAMP_TZ`	Time zone is ignored when stored in TimesTen.
`SQLT_UIN`
`SQLT_VBI`
`SQLT_VCS`
`SQLT_VNU`
`SQLT_VST`

Table 3-6 that follows lists supported parameter attributes.

Table 3-6 TimesTen OCI support for parameter attributes

Parameter	Supported attributes
All parameters	`OCI_ATTR_NUM_PARAMS` `OCI_ATTR_OBJ_NAME` `OCI_ATTR_OBJ_SCHEMA` `OCI_ATTR_PTYPE`
Table and view parameters	`OCI_ATTR_NUM_COLS` `OCI_ATTR_LIST_COLUMNS`
PL/SQL procedure and function parameters	`OCI_ATTR_LIST_ARGUMENTS`
PL/SQL subprogram parameters	`OCI_ATTR_LIST_ARGUMENTS` `OCI_ATTR_NAME`
PL/SQL package parameters	`OCI_ATTR_LIST_SUBPROGRAMS`
Sequence parameters	`OCI_ATTR_OBJID` `OCI_ATTR_MIN` `OCI_ATTR_MAX` `OCI_ATTR_INCR` `OCI_ATTR_CACHE` `OCI_ATTR_ORDER` `OCI_ATTR_HW_MARK`
Column parameters	`OCI_ATTR_CHAR_USED` `OCI_ATTR_CHAR_SIZE` `OCI_ATTR_DATA_SIZE` `OCI_ATTR_DATA_TYPE` `OCI_ATTR_NAME` `OCI_ATTR_PRECISION` `OCI_ATTR_SCALE` `OCI_ATTR_IS_NULL` `OCI_ATTR_TYPE_NAME` `OCI_ATTR_SCHEMA_NAME` `OCI_ATTR_CHARSET_ID` `OCI_ATTR_CHARSET_FORM`
Argument and result parameters	`OCI_ATTR_NAME` `OCI_ATTR_POSITION` `OCI_ATTR_DATA_TYPE` `OCI_ATTR_DATA_SIZE` `OCI_ATTR_PRECISION` `OCI_ATTR_SCALE` `OCI_ATTR_LEVEL` `OCI_ATTR_IS_NULL` `OCI_ATTR_CHARSET_ID` `OCI_ATTR_CHARSET_FORM`
List parameters	`OCI_LTYPE_COLUMN` `OCI_LTYPE_SCH_OBJ` `OCI_LTYPE_DB_SCH`
Database parameters	`OCI_ATTR_VERSION` `OCI_ATTR_CHARSET_ID` `OCI_ATTR_NCHARSET_ID` `OCI_ATTR_LIST_SCHEMAS` `OCI_ATTR_MAX_PROC_LEN` `OCI_ATTR_MAX_COLUMN_LEN` `OCI_ATTR_ATTR_CURSOR_COMMIT_BEHAVIOR` `OCI_ATTR_MAX_CATALOG_NAMELEN` `OCI_ATTR_CATALOG_LOCATION` `OCI_ATTR_SAVEPOINT_SUPPORT` `OCI_ATTR_NOWAIT_SUPPORT` `OCI_ATTR_AUTOCOMMIT_DDL` `OCI_ATTR_LOCKING_MODE`

3 TimesTen Support for Oracle Call Interface

Overview of OCI

Overview of TimesTen OCI support

OCI libraries and architecture

Globalization support

Character sets

Additional globalization features

TimesTen restrictions and differences

Oracle Database features not supported

Additional TimesTen OCI restrictions

Additional TimesTen OCI differences

The ttSrcScan utility

Getting started with TimesTen OCI

Environment variables for TimesTen OCI

Compiling and linking OCI applications

Connecting to a TimesTen database from OCI

Using the tnsnames naming method to connect

Using an easy connect string to connect

Configuring whether to use tnsnames.ora or easy connect

Connecting as an externally identified user in OCI

Error reporting

Signal handling and diagnostic framework considerations

OCI demo programs

Additional features of TimesTen OCI

TimesTen deferred prepare

Using IMDB Cache in OCI

Specifying the Oracle password in OCI for IMDB Cache

Determining the number of cache groups affected by an action

Duplicate parameter bindings in TimesTen OCI

Call, handle, descriptor, SQL data type, and parameter attribute support

En vironment variables for TimesTen OCI

Co mpiling and linking OCI applications

Con necting to a TimesTen database from OCI

Using the tnsnames naming method to con nect

Using an easy connect string to con nect

Con necting as an externally identified user in OCI

Er ror reporting

Sig nal handling and diagnostic framework considerations

TimesTen defer red prepare

Spe cifying the Oracle password in OCI for IMDB Cache

Du plicate parameter bindings in TimesTen OCI