Skip Headers
Oracle® TimesTen In-Memory Database C Developer's Guide
Release 11.2.1

Part Number E13066-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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:

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:

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

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

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 shows 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 follows
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.)

  • Array 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

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.

Compiling 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.

Connecting 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:

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 connect

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 connect

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.

Connecting 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.

Error 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.

Signal 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

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

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.

Duplicate 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

Unsupported values for the objptr_typ parameter:

  • OCI_OTYPE_REF

  • OCI_OTYPE_PTR

Unsupported values for the objtyp parameter:

  • OCI_PTYPE_PKG

  • OCI_PTYPE_SYN

  • OCI_PTYPE_TYPE

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