Getting Started With TimesTen Pro*C/C++

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.

Precompile the Pro*C/C++ source file by using the proc command from your system prompt. For example:
```
% proc iname=sample.pc
```
The proc utility takes a .pc source file as input and produces a .c file.
Compile the resulting C code file. On Linux platforms, enter a command similar to the following:
```
% gcc -c sample.c -I(instantclient)/sdk/include
```
Link the resulting object modules with modules in SQLLIB. For example:
```
% gcc -o sample sample.o -L(instantclient) -lclntsh
```

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 and sqlnet.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`	User name
`pwd`	Password
`user_string`	Alternative to separate `user` and `pwd` entries This is a user name and password separated by a slash, such as `user1/password`. After an "`@`" sign, you can also have a database identifier, instead of using `dbname`, or a TNS name or easy connect string, instead of using `connect_string`. See examples in the next section, Using tnsnames or Easy Connect.
`dbname`	Database identifier declared in a previous `DECLARE DATABASE` statement
`host_variable`	Variable whose value is a database identifier
`connect_string`	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 or ORA-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 the WHENEVER NOT FOUND directive, to go to a handling section if a "no data found" condition occurs. TimesTen does not support the WHENEVER SQLWARNING directive.

Examples:
```
EXEC SQL WHENEVER NOT FOUND GOTO close_cursor;
...
EXEC SQL WHENEVER SQLERROR GOTO error_handler;
```