This chapter provides information about the C development environment and related considerations for developing TimesTen applications. The following topics are covered:
Environment variable settings for TimesTen are discussed in "Environment variables" in the Oracle TimesTen In-Memory Database Installation Guide. Refer to that discussion for details.
ttenv scripts also configure access to the Oracle Instant Client, required for OCI programming.
You can optionally use the appropriate
ttquickstartenv script instead of
ttenv. This is a superset of
ttenv that also sets up the TimesTen Quick Start demo environment.
To ensure proper execution of OCI and Pro*C/C++ programs to be run on TimesTen, do not set
ORACLE_HOME (or unset it if it was set previously) for OCI and Pro*C/C++ compilations.
A TimesTen application can link specifically with the TimesTen ODBC direct driver or ODBC client driver without a driver manager, or can link with a driver manager.
Applications to be used solely with TimesTen can link specifically with either the TimesTen ODBC direct driver or the ODBC client driver, without a driver manager. This avoids the performance overhead of a driver manager and is the simplest way to access TimesTen. However, developers of applications linked without a driver manager should be aware of the following issues.
The application can only connect to a DSN that uses the driver with which it is linked. It cannot connect to a database of any other vendor, nor can it connect to a TimesTen DSN of a different TimesTen driver or a different version or type.
Windows ODBC tracing is not available.
The ODBC cursor library is not available.
Applications cannot use ODBC functions that are usually implemented by a driver manager, such as
Applications that use
SQLCancel to close a cursor instead of
SQLFreeStmt(..., SQL_CLOSE) receive a return code of
SQL_SUCCESS_WITH_INFO and a SQL state of
01S05. This warning is intended to be used by the driver manager to manage its internal state. Applications should treat this warning as success.
Applications that link with the ODBC driver manager can connect to any DSN that references an ODBC driver and can even connect simultaneously to multiple DSNs that use different ODBC drivers. Note, however, that driver managers are not available by default on most non-Windows platforms. In addition, using a driver manager may add significant synchronization overhead to every ODBC function call and has the following limitations:
The TimesTen option
TT_PREFETCH_COUNT cannot be used with applications that link with a driver manager. For more information on using
TT_PREFETCH_COUNT, see "Prefetching multiple rows of data".
Applications cannot set or reset the TimesTen-specific
TT_PREFETCH_CLOSE connection option. For more information about using the
TT_PREFETCH_CLOSE connection option, see "Enable TT_PREFETCH_CLOSE for Serializable transactions" in the Oracle TimesTen In-Memory Database Operations Guide.
Transaction Log API (XLA) calls cannot be used when applications are linked with a driver manager.
The ODBC C types
SQL_C_WCHAR are not supported for an application linked with a driver manager when used with TimesTen. You cannot call methods that have any of these types in their signatures.
The driver manager does not support LOB locator APIs or LOB data types, which are not part of the ODBC standard. However, you can use the LOB simple data interface or piecewise data interface as documented in "Working with LOBs".
Note:TimesTen supplies a driver manager for both Windows and UNIX with the Quick Start sample applications. This driver manager is not fully supported. It supports only the TimesTen direct driver and client driver and does not have the functionality or performance limitations described above. Applications that must concurrently use both direct connections and client/server connections to TimesTen can use this driver manager to achieve this with very little impact on performance.
This section discusses compiling and linking C applications on Windows or UNIX.
To compile TimesTen applications on Windows, you are not required to specify the location of the ODBC include files. These files are included with Microsoft Visual C++. However, you must indicate the location of TimesTen include files by using the
/I compiler option. (See "TimesTen include files".)
The Makefile in Example 1-1 shows how to build a TimesTen application on Windows systems. This example assumes that
\lib has already been added to the LIB environment variable.
CFLAGS = "/Iinstall_dir\" LIBSDM = ODBC32.LIB LIBS = tten1122.lib ttdv1122.lib LIBSDEBUG = tten1122d.lib ttdv1122d.lib LIBSCS = ttclient1122.lib # Link with the ODBC driver manager appldm.exe:appl.obj $(CC) /Feappldm.exe appl.obj $(LIBSDM) # Link directly with the TimesTen # ODBC production driver appl.exe:appl.obj $(CC) /Feappl.exe appl.obj\ $(LIBS) # Link directly with the TimesTen # ODBC debug driver appldebug.exe:appl.obj $(CC) /Feappldebug.exe appl.obj\ $(LIBSDEBUG) # Link directly with the TimesTen # ODBC client driver applcs.exe:appl.obj $(CC) /Feapplcs.exe appl.obj\ $(LIBSCS)
On UNIX platforms:
Compile TimesTen applications using the TimesTen header files from the TimesTen installation directory.
Link with the TimesTen ODBC direct driver or client driver, each of which is provided as a shared library.
On UNIX, applications using the
SQL_C_SSHORT ODBC data types must specify the
TT_USE_ALL_TYPES preprocessor option while compiling. This is typically done using the
-DTT_USE_ALL_TYPES C compiler option.
To use the TimesTen include files, add the following to the C compiler command, where
install_dir is the TimesTen installation directory path:
To link with the TimesTen ODBC direct driver, add the following to the link command:
-L option tells the linker to search the TimesTen
lib directory for library files. The
-ltten option links in the TimesTen ODBC direct driver.
To link with the TimesTen ODBC client driver, add the following to the link command:
On Solaris, the default TimesTen ODBC client driver was compiled with Studio 11. The library enables you to link an application compiled with the Sun Studio 11 C/C++ compiler directly with the TimesTen client.
On AIX, when linking applications with the TimesTen ODBC client driver, the C++ runtime library must be included in the link command (because the client driver is written in C++ and AIX does not link it automatically) and must follow the client driver:
-Linstall_dir/lib -lttclient -lC_r
You can use Makefiles in subdirectories under the
quickstart/sample_code directory, or you can use Example 1-2 to guide you in creating your own Makefile.
CFLAGS = -Iinstall_dir/ LIBS = -Linstall_dir/lib -ltten LIBSDEBUG = -Linstall_dir/lib -lttenD LIBSCS = -Linstall_dir/lib -lttclient # Link directly with the TimesTen # ODBC production driver appl:appl.o $(CC) -o appl appl.o $(LIBS) # Link directly with the TimesTen ODBC debug driver appldebug:appl.o $(CC) -o appldebug appl.o $(LIBSDEBUG) # Link directly with the TimesTen client driver applcs:appl.o $(CC) -o applcs appl.o $(LIBSCS)
To directly link your application to the debug TimesTen ODBC driver, substitute
-ltten on the link line.
On Solaris, when compiling with Sun C/C++ compilers, TimesTen applications must be compiled and linked with the
After you have configured your C environment, you can confirm that everything is set up correctly by compiling and running TimesTen Quick Start demo applications. Refer to the Quick Start welcome page at
/quickstart.html, especially the links under SAMPLE PROGRAMS, for information on the following topics.
Demo schema and setup: The
build_sampledb script (
.sh on UNIX or
.bat on Windows) creates a sample database and demo schema. You must use this before you start using the demos.
Demo environment and setup: The
ttquickstartenv script (
.csh on UNIX or
.bat on Windows), a superset of the
ttenv script generally used for TimesTen setup, sets up the demo environment. You must use this each time you enter a session where you want to compile or run any of the demos.
Demos and setup: TimesTen provides demos for ODBC, XLA, OCI, Pro*C/C++, and ODP.NET in subdirectories under the
quickstart/sample_code directory. For instructions on compiling and running the demos, see the README files in the subdirectories.
What the demos do: A synopsis of each demo is provided when you click the categories under SAMPLE PROGRAMS.