Getting Started With TimesTen OCI

Environment Variables for TimesTen OCI

You set certain environment variables for executing a TimesTen OCI application.

Settings apply to both direct connections and client/server connections except as noted.

Note:

After creating an instance, you can set your environment as appropriate through the timesten_home/bin/ttenv script applicable to your operating system. See Environment Variables in the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide for information about ttenv scripts.
To ensure proper generation of OCI programs to be run on TimesTen, ORACLE_HOME cannot be set for OCI compilations.

Table 3-1 Environment Variables for TimesTen OCI

Variable	Required or Optional	Settings
`LD_LIBRARY_PATH` (Linux or UNIX) `PATH` (Windows)	Required	Must be set so that the TimesTen Instant Client directory precedes the Oracle Database libraries in the path. The path is set properly if you use the following script under `timesten_home`: bin/ttenv
`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. See Connecting to a TimesTen Database From OCI.
`TWO_TASK` (Linux or 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.
`NLS_LANG`	Optional	See Specifying a Character Set. 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.

About Compiling and Linking OCI Applications

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

OCI programs that use the Oracle Client library shipped with TimesTen do not have to be recompiled or relinked to be executed with TimesTen unless there has been a major upgrade to the Oracle version provided 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. All but the first apply to only TimesTen Classic:

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.

Note:

Although the sqlnet mechanism is used for a TimesTen OCI connection, the connection goes through the TimesTen ODBC driver, not the Oracle Database sqlnet driver.

About Configuring OCI Connections in TimesTen Scaleout

In TimesTen Scaleout, TimesTen will automatically populate the tnsnames.ora file and sqlnet.ora file, as applicable, on all instances with entries for all TimesTen connectables you have defined.

See Connectable Operations in Oracle TimesTen In-Memory Database Reference.

The instructions here are not relevant, as the user is not allowed to manually configure those entries. The tnsnames, sqlnet, and related information for additional entries, such as for Oracle database connections (as applicable), is brought in and distributed through the ttGridAdmin TNSNamesImport and SQLNetImport commands. See Oracle Database Operations in Oracle TimesTen In-Memory Database Reference.

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 Database 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 sys.odbc.ini or user odbc.ini file that is visible to a user running the 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));

Note:

For TimesTen Classic, you can use the ttInstanceCreate -tnsadmin option or the ttInstanceModify -tns_admin option (in addition to the TNS_ADMIN environment variable) to set the tnsnames location. See ttInstanceCreate and ttInstanceModify in Oracle TimesTen In-Memory Database Reference.

Using an Easy Connect String to Connect

TimesTen supports easy connect syntax, which enhances the Instant Client package by enabling 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. For client/server connections, 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 appropriate, 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 a DSN ttclient in the sys.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 sys.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, as follows.

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 are tried and the order in which they are tried.

The Instant Client looks 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 in ORACLE_HOME/network/admin as noted in Parameters for the sqlnet.ora File in Oracle Database Net Services Reference.

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

In TimesTen, you can access sample copies of tnsnames.ora and sqlnet.ora in the timesten_home/install/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 first looks for tnsnames syntax in your OCI logon calls. If it cannot find tnsnames syntax, it looks for easy connect syntax.

OCI Error Handling

OCI error handling includes error reporting and transient errors.

This section discusses these topics:

OCI Error Reporting

Errors under TimesTen OCI applications return Oracle Database error codes.

TimesTen attempts to report the same error code as Oracle Database would under similar conditions. The error messages may come from either the TimesTen error catalog or the Oracle Database error catalog. Some error messages may indicate 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 is not freed until all active connections at the time of the error have disconnected.

Fatal errors in OCI are indicated by the Oracle Database 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 have a disconnect from the database.

Transient Errors (OCI)

TimesTen automatically resolves most transient errors (which is particularly important for TimesTen Scaleout), but if your application detects the following error, it is suggested to retry the current transaction.

ORA-57005: Transient transaction failure due to unavailability of resource. Roll back the transaction and try it again.

Note:

Search the entire error stack for errors returning these error types before deciding whether it is appropriate to retry.

This is returned in the errcodep parameter in OCIErrorGet() and may be encountered by any of the following OCI calls:

OCIBindArrayOfStruct()
OCIBindByName()
OCIBindByPos()
OCIDefineArrayOfStruct()
OCIDefineByPos()
OCIDescribeAny()
OCILogoff()
OCILogon()
OCILogon2()
OCIPing()
OCISessionBegin()
OCISessionEnd()
OCISessionGet()
OCISessionRelease()
OCIStmtExecute()
OCIStmtFetch()
OCIStmtFetch2()
OCIStmtGetBindInfo()
OCIStmtPrepare()
OCIStmtPrepare2()
OCIStmtRelease()
OCITransCommit()
OCITransRollback()

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 Controlling ADR Creation and Disabling Fault Diagnosability Using sqlnet.ora in Oracle Call Interface Programmer's Guide.