Getting Started With TimesTen OCI
Use these methods for getting started with a TimesTen OCI application.
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.
See Table 3-1.
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 aboutttenv
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 |
---|---|---|
|
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 bin/ttenv |
|
Required if you use the |
Specifies the directory where the |
|
Optional |
You can use this, whichever is appropriate for your platform, instead of specifying the |
|
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. |
|
Optional |
See Additional Globalization Features. The sort order must be a value supported by TimesTen. This overrides the TimesTen |
|
Optional |
See Additional Globalization Features. This overrides the TimesTen |
|
Optional |
See Additional Globalization Features. This overrides the TimesTen |
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 thedbname
argument in your OCI logon call. -
Specify an empty string for
dbname
and setTWO_TASK
orLOCAL
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 setTWO_TASK
orLOCAL
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.