Getting Started With TimesTen Pro*C/C++
There are methods to get started with a Pro*C/C++ application for TimesTen.
Environment and Configuration for TimesTen Pro*C/C++
The Pro*C/C++ system configuration file pcscfg.cfg
contains the precompiler options for precompilation of your Pro*C/C++ source code. In TimesTen, you must use the version of this file that TimesTen provides. This typically happens automatically if you ensure appropriate configuration for TimesTen through the timesten_home
/bin/ttenv
script.
Before building a Pro*C/C++ application, you must set up your environment. You can use the TimesTen Classic Quick Start OCI and Pro*C/C++ Makefiles to implement appropriate environment settings. See About TimesTen Quick Start and Sample Applications.
Then confirm LD_LIBRARY_PATH
or PATH
is set so that the Oracle Instant Client directory precedes the Oracle Database libraries in the path. The path is set properly if you use the ttenv
script.
See Environment Variables in the Oracle TimesTen In-Memory Database Installation,
Migration, and Upgrade Guide for information about ttenv
.
Note:
To ensure proper generation of OCI and Pro*C/C++ programs to be run on TimesTen, do not set ORACLE_HOME
for OCI and Pro*C/C++ compilations (or unset it if it was set previously).
Building a Pro*C/C++ Application
Once you have set up the environment, use steps to build a Pro*C/C++ application.
The steps shown here present a basic example for a UNIX system and assume the program has no other includes (#include
) or links to other libraries. The designation instantclient
represents the directory where Oracle Instant Client is installed.
Connecting to a TimesTen Database From Pro*C/C++
There are methods for connecting to a TimesTen database from a Pro*C/C++ application. TimesTen Pro*C/C++ and TimesTen OCI use the Oracle Instant Client to connect to the database.
Refer to Connecting to a TimesTen Database From OCI for additional configuration steps to use the tnsnames
naming method or easy connect naming method to connect to the database.
The following topics are covered here for TimesTen Classic:
Note:
-
Be aware that in TimesTen Scaleout, TimesTen will automatically populate the
tnsnames.ora
file andsqlnet.ora
file, as applicable, on all instances with entries for all TimesTen connectables you have defined. See Connecting to a TimesTen Database From OCI. -
A TimesTen connection cannot be inherited from a parent process. If a process opens a database connection before creating (forking) a child process, the child must not use the connection. In Pro*C/C++, to avoid having a child process inadvertently inherit a connection from its parent, use
EXEC SQL COMMIT RELEASE
in the parent before creating the child.
Connection Syntax and Parameters
TimesTen requires a connection syntax.
EXEC SQL CONNECT{:user IDENTIFIED BY :pwd | :user_string} [[AT{dbname |:host_variable}]USING :connect_string];
The parameters are described in Table 4-1.
Table 4-1 Connection Parameters
Parameter | Description |
---|---|
|
User name |
|
Password |
|
Alternative to separate This is a user name and password separated by a slash, such as |
|
Database identifier declared in a previous |
|
Variable whose value is a database identifier |
|
Valid TNS name or easy connect string for a TimesTen database |
Using tnsnames or Easy Connect
To connect to a TimesTen database from a Pro*C/C++ application, you must configure a TNS name or easy connect string for the database.
Perform the tnsnames
or easy connect steps described under Connecting to a TimesTen Database From OCI.
From Pro*C/C++, you can use a host variable to specify the user name, password, and a TNS name. For example:
EXEC SQL CONNECT :dbstring
Where dbstring
is set to "user1/
password
@my_tnsname
".
Alternatively, the host variable could specify the user name, password, and an easy connect string. For example, dbstring
could be set to "user1/
password
@localhost/ttclient:timesten_client
".
Or, if the TWO_TASK
or LOCAL
environment variable, as applicable for your operating system, is set to "my_tnsname
" or "localhost/ttclient:timesten_client
", you could connect as in the following example:
EXEC SQL CONNECT :user1 IDENTIFIED BY :pwd1
Specifying the Oracle Database Password in Pro*C/C++ for Cache
For use of Pro*C/C++ with cache operations, TimesTen enables you to pass the Oracle Database cache administration user's password through Pro*C/C++ by appending it to the password field in an EXEC SQL CONNECT
call when you log in to TimesTen.
To use cache operations, there must be a cache administration user in the TimesTen Classic database with the same name as an Oracle Database cache administration user who can select from and update the cached Oracle Database tables. This Oracle Database cache administration user could also be a schema user. The password of the TimesTen cache administration user can be different from the password of the Oracle Database cache administration user. See Setting Up a Caching Infrastructure in Oracle TimesTen In-Memory Database Cache Guide.
Use the attribute OraclePWD
in the connect string, such as in the following example:
text *cacheadmin = (text *)"cacheadmin1"; text *cachepwds = (text *)"ttpassword;OraclePWD=oraclepassword"; text *dbname = (text *)"tt_tnsname"; .... EXEC SQL CONNECT :cacheadmin IDENTIFIED BY :cachepassword AT :dbname
You must always specify OraclePWD
, even if the Oracle Database cache administration user's password is the same as the TimesTen cache administration user's password. Furthermore, in the circumstance of specifying an Oracle Database password for cache operations, you must use a form of EXEC SQL CONNECT
that specifies the password as a separate host variable. In this example, cacheadmin1
is the name of the TimesTen cache administration user as well as the name of the Oracle Database cache administration user who can access the cached Oracle Database tables, ttpassword
is the password of the TimesTen cache administration user, oraclepassword
is the password of the Oracle Database cache administration user, and 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 sys.odbc.ini
or user odbc.ini
file.
Alternatively, instead of using the AT
clause with a TNS name, you could use the TWO_TASK
or LOCAL
environment variable, as discussed in Connecting to a TimesTen Database From OCI.
Error Reporting and Handling
Be aware of restrictions regarding certain error conditions and error reporting.
-
Errors under TimesTen Pro*C/C++ 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 catalog or the Oracle Database catalog. Some error messages may indicate the accompanying TimesTen error code if appropriate. Pro*C/C++ applications that rely on parsing error codes should be checked.
-
TimesTen automatically resolves most transient errors (which is particularly important for TimesTen Scaleout), but if your application detects an
ORA-57005
orORA-57007
error, it is suggested to retry the current transaction or most recent API call, as applicable. See Transient Errors (OCI). -
TimesTen supports the
WHENEVER SQLERROR
directive, to go to an error handler if an error occurs, and theWHENEVER NOT FOUND
directive, to go to a handling section if a "no data found" condition occurs. TimesTen does not support theWHENEVER SQLWARNING
directive.Examples:
EXEC SQL WHENEVER NOT FOUND GOTO close_cursor; ... EXEC SQL WHENEVER SQLERROR GOTO error_handler;