This chapter provides information about the C development environment and related considerations for developing TimesTen applications. These topics are covered:
Environment variable settings for TimesTen are discussed in "Environment variables" in the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide. Refer to that discussion for details.
Relevant scripts, in the timesten_home
/bin
directory, are ttenv.sh
and ttenv.csh
for Linux and UNIX platforms (where which you use depends on your shell) and ttenv.bat
for Windows platforms.
Notes:
The ttenv
scripts also configure access to the Oracle Instant Client, required for OCI programming.
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 connect only to a DSN (data source name) 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. (A DSN is a logical name that identifies a TimesTen database and the set of connection attributes used for connecting to the database.)
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 SQLDataSources
and SQLDrivers
.
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 "Optimizing query performance".
Transaction Log API (XLA) calls cannot be used when applications are linked with a driver manager.
The ODBC C types SQL_C_BIGINT
, SQL_C_TINYINT
, and 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 sample driver manager for Windows and for Linux or UNIX with the Quick Start sample applications. (See "TimesTen Quick Start and sample applications".) It supports the TimesTen direct driver and client driver and ODBC 2.5 and does not have the functionality or performance limitations described above. Applications that must concurrently use both direct connections and client/server connections to the database can use this driver manager to achieve this with very little impact on performance.This section discusses compiling and linking C applications on Windows and on Linux 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, to use TimesTen features you must indicate the location of the TimesTen include files in the /I
compiler option setting. (See "TimesTen include files".)
Link the appropriate libraries, as follows:
Directly link to the driver manager: odbc32.lib
Note that odbc32.lib
is for 64-bit systems too.
Directly link to TimesTen:
For direct mode: tten181.lib
and ttdv181.lib
For client/server mode: ttclient181.lib
The Makefile in Example 1-1 shows how to build a TimesTen application on Windows systems. This example assumes that timesten_home
\install\lib
has already been added to the LIB
environment variable (which is accomplished when you execute ttenv.bat
).
Important:
Applications should include timesten.h
, the TimesTen include file. This automatically includes standard ODBC files as well. See "TimesTen include files".
Include TimesTen files before any other include files and link TimesTen libraries before any other libraries.
TimesTen compiles against ODBC 2.5 by default. To compile an ODBC 3.5 application, use the compiler setting -DODBCVER=0x0351
.
Note:
On Windows, there is only one TimesTen instance per installation, and timesten_home
refers to installation_dir
\instance
.
The timesten_home
/install
directory is a symbolic link to installation_dir
.
Example 1-1 Building a TimesTen application in Windows
CFLAGS = "/Itimesten_home\install\include"
LIBSDM = ODBC32.LIB
LIBS = tten181.lib ttdv181.lib
LIBSDEBUG = tten181d.lib ttdv181d.lib
LIBSCS = ttclient181.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 Linux or UNIX platforms:
Compile TimesTen applications using the TimesTen header files in the include
directory of the TimesTen installation.
Link with the TimesTen ODBC direct driver or client driver, each of which is provided as a shared library.
Important:
Applications should include timesten.h
, the TimesTen include file. This automatically includes standard ODBC files as well. See "TimesTen include files".
Include TimesTen files before any other include files and link TimesTen libraries before any other libraries.
TimesTen compiles against ODBC 2.5 by default. To compile an ODBC 3.5 application, use the compiler setting -DODBCVER=0x0351
.
On Linux or UNIX, applications using the SQL_C_ULONG
, SQL_C_SLONG
, SQL_C_USHORT
or 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 if you are using TimesTen features, add the following to the C compiler command, where timesten_home
/install
is a symbolic link to installation_dir
, the TimesTen installation directory. (See "TimesTen include files".)
-Itimesten_home/install/include
To link with the TimesTen ODBC direct driver, add the following to the link command for the libtten.so
library:
-Ltimesten_home/install/lib -ltten
The -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 for the libttclient.so
library:
-Ltimesten_home/install/lib -lttclient
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:
-Ltimesten_home/install/lib -lttclient -lC_r
You can use Makefiles in subdirectories under the Quick Start sample_code
directory (see "TimesTen Quick Start and sample applications"), or you can use Example 1-2 to guide you in creating your own Makefile.
Example 1-2 Makefile to link the application
CFLAGS = -Itimesten_home/install/include LIBS = -Ltimesten_home/install/lib -ltten LIBSDEBUG = -Ltimesten_home/install/lib -lttenD LIBSCS = -Ltimesten_home/install/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)
Note:
To directly link your application to the debug TimesTen ODBC driver, substitute-lttenD
for -ltten
on the link line.The TimesTen Classic Quick Start and TimesTen Scaleout sample applications are available from the TimesTen GitHub location. For the TimesTen Classic Quick Start, there is a complete set of tutorials, how-to instructions, and sample applications. For TimesTen Scaleout, there are ODBC and JDBC sample applications.
After you have configured your environment, you can confirm that everything is set up correctly by compiling and running the sample applications. For TimesTen Classic, applications are located under the Quick Start sample_code
directory. For instructions on compiling and running them, see the instructions in the subdirectories. For TimesTen Scaleout, clone the oracle-timesten-examples
GitHub repository and follow the instructions in the README files.
For TimesTen Classic, the following are included:
Schema and setup: The build_sampledb
script (.sh
on Linux or UNIX or .bat
on Windows) creates a sample database and schema. Run this script before using the sample applications.
Environment and setup: The ttquickstartenv
script (.sh
or .csh
on Linux or UNIX or .bat
on Windows), a superset of the ttenv
script typically used for TimesTen setup, sets up the environment. Run this script each time you enter a session where you want to compile or run any of the sample applications.
Sample applications and setup: The Quick Start provides sample applications and their source code for ODBC, OCI, and Pro*C/C++.