4 TimesTen Support for Oracle Pro*C/C++ Precompiler

TimesTen OCI support

Because TimesTen support of the Oracle Pro*C/C++ Precompiler depends on TimesTen OCI support, restrictions for TimesTen OCI apply to Pro*C/C++ applications.

In addition, TimesTen does not support OCI calls that are related to functionality that does not exist in TimesTen.

For more information about TimesTen OCI support, see Chapter 3, "TimesTen Support for Oracle Call Interface." Much of the information there may apply to Pro*C/C++ applications as well.

Embedded SQL support and restrictions

TimesTen supports SQL92 standards. Oracle supports SQL99 standards.

The TimesTen Pro*C/C++ Precompiler does not support embedded SQL for functionality that TimesTen and IMDB Cache do not support. See "TimesTen restrictions and differences".

TimesTen provides the following support for SQLLIB functions:

• SQLErrorGetText (sqlglmt) is supported.

• SQLRowidGet() is supported following only SELECT FOR UPDATE statements.

In addition, TimesTen support for the Oracle Pro*C/C++ Precompiler has the following restrictions:

• REGISTER CONNECT is not supported.

• Stored Java subprograms are not supported.

Semantic checking restrictions

TimesTen support for the Oracle Pro*C/C++ Precompiler does not include semantic checking during precompilation. A SQLCHECK precompiler option setting that specifies semantic checking is permissible but has no effect.

It is important to be aware, however, that a setting of SEMANTICS results in a database connection even though precompilation semantic checking is not performed. Therefore, a setting of SEMANTICS requires the following during precompilation:

• The database must be running.

• The USERID precompiler option must be set, either on the command line or in the pcscfg.cfg configuration file. You must provide the user name and password for an existing TimesTen user, and a TNS name that points to the database. In the following example, you will be prompted for the password:

  USERID=user1@my_tnsname
  

  Alternatively, you can enter USERID=user1/mypassword@my_tnsname, but for security reasons it is not advisable to specify a password on a command line or in a configuration file.

See "Connecting to a TimesTen database from Pro*C/C++" for information about usage and syntax for TNS names.

See the next section, "Embedded PL/SQL restrictions", for related information about Pro*C/C++ programs that use PL/SQL.

Embedded PL/SQL restrictions

In TimesTen, if a Pro*C/C++ application contains PL/SQL blocks, then Pro*C/C++ acts as though the SQLCHECK setting is SEMANTICS. It is important to be aware that this results in a database connection even though precompilation semantic checking is not performed. Therefore, using PL/SQL in a Pro*C/C++ application requires the following during precompilation:

• The database must be running.

• The USERID precompiler option must be set, specifying an existing TimesTen user. See the preceding section, "Semantic checking restrictions", for details about setting this option.

Transaction restrictions

Regarding transactions, TimesTen support for the Oracle Pro*C/C++ Precompiler does not include the following:

• SAVEPOINT SQL statement

• SET TRANSACTION SQL statement

  You can still have transactions with commit and rollback, just not the SET TRANSACTION SQL statement.

• Fetch across commits

• Distributed transactions

Connection restrictions

Regarding connections, TimesTen support for the Oracle Pro*C/C++ Precompiler does not include the following:

• ALTER AUTHORIZATION clause

• Automatic connections to the database

• Making connections to the database with SYSDBA or SYSOPER privilege, given that these privileges do not exist in TimesTen

• Implicit connections (dblinks) to a TimesTen or Oracle Database

For information about supported connection syntax, see "Connecting to a TimesTen database from Pro*C/C++".

Summary of unsupported or restricted executable commands and clauses

Given restrictions including those noted in the preceding sections, this section summarizes the Pro*C/C++ EXEC SQL executable commands, categories of commands, and command clauses that TimesTen does not support:

• ALTER AUTHORIZATION

• CACHE FREE ALL

• CALL: Supported only for calling PL/SQL. To call TimesTen built-in procedures, use dynamic SQL statements.

• Any "COLLECTION..." command

• COMMIT FORCE 'some text'

• COMMIT WORK COMMENT 'some text' RELEASE: The COMMENT clause is not supported.

• CONNECT BY

• CONTEXT OBJECT OPTION GET

• CONTEXT OBJECT OPTION SET

• DECLARE TABLE: Supports only Oracle data types.

• DECLARE TYPE

• EXPLAIN PLAN

• IN SYSDBA MODE

• IN SYSOPER MODE

• Any "LOB..." command

• LOCK TABLE

• Any "OBJECT..." command

• PARTITION

• REGISTER CONNECT

• RETURN

• RETURNING

• SAVEPOINT

• SET DESCRIPTOR: Cannot set CHARACTER_SET_NAME.

• SET TRANSACTION

• START WITH

• TO SAVEPOINT

The ttSrcScan utility

If you have an existing Pro*C/C++ program and want to see whether it uses Pro*C/C++ features that TimesTen does not support, you can use the ttSrcScan command line utility to scan your program for unsupported embedded SQL functions and types. 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, 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.

Building a Pro*C/C++ application

Before building a Pro*C/C++ application, you must set up your environment:

1. You can 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:

   install_dir/quickstart/sample_code/oci/
   install_dir/quickstart/sample_code/proc/
   

   (Unless you installed Quick Start in a different location.)

2. 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 will be set properly if you use the install_dir/bin/ttenv script or quickstart/ttquickstartenv script. See "Environment variables" in Oracle TimesTen In-Memory Database Installation Guide for information about environment variables and ttenv.

Then use steps such as the following 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 instant_client represents the directory where Oracle Instant Client is installed.

See the Quick Start Pro*C/C++ Makefile in the quickstart/sample_code/proc directory for complete, platform-specific examples.

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

2. Compile the resulting C code file. On Linux platforms, enter a command similar to the following:

   % gcc -c sample.c -I(instant_client)/sdk/include
   

3. Link the resulting object modules with modules in SQLLIB. For example:

   % gcc -o sample sample.o -L(instant_client)/lib -lclntsh
   

Connecting to a TimesTen database from Pro*C/C++

This section provides information on connecting to TimesTen from a Pro*C/C++ application. Also see "Connecting to a TimesTen database from OCI" for information about using the tnsnames naming method or easy connect naming method to connect to the database.

The following topics are covered here:

• Connection syntax and parameters

• Using tnsnames or easy connect

• Specifying the Oracle password in Pro*C/C++ for IMDB Cache

• Connecting as an externally identified user in Pro*C/C++

EXEC SQL CONNECT{:user IDENTIFIED BY :pwd | :user_string}
  [[AT{dbname |:host_variable}]USING :connect_string];

EXEC SQL CONNECT :dbstring

EXEC SQL CONNECT :user1 IDENTIFIED BY :pwd1

text *cacheuser = (text *)"cacheuser1";
text *cachepwds = (text *)"ttpwd;OraclePWD=orclpwd";
text *dbname = (text *)"tt_tnsname";
....
EXEC SQL CONNECT :cacheuser IDENTIFIED BY :cachepwds AT :dbname

text *instanceadmin = (text *)"[myadmin]";
text *instanceadminpwd = (text *)"";
text *dbname = (text *)"tt_tnsname";
....
EXEC SQL CONNECT :instanceadmin IDENTIFIED BY :instanceadminpwd AT :dbname

Error reporting and handling

Be aware of the following regarding error conditions and error reporting:

• Errors under TimesTen Pro*C/C++ 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. Pro*C/C++ applications that rely on parsing error codes should be checked.

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

Pro*C/C++ demo programs

TimesTen ships Pro*C/C++ demo programs. They are in the quickstart/sample_code/proc 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.

Precompiler option support

Table 4-2 describes TimesTen Pro*C/C++ Precompiler option support.

Setting precompiler options

You can set precompiler options in the following ways.

• At compile time, either in the configuration file pcscfg.cfg or on the Pro*C/C++ command line. A setting on the command line takes precedence over a setting in the configuration file.

• At runtime through the EXEC ORACLE OPTION command. A runtime setting takes precedence over a compile-time setting.

For example, the following shows portions of the configuration file that ships with TimesTen.

ltype=short
parse=full
close_on_commit=yes
...

The following command line would override the ltype=short setting from the configuration file:

% proc ltype=long ... iname=sample.pc

The following runtime command would override the ltype=long setting from the command line:

EXEC ORACLE OPTION LTYPE=NONE;