Skip Headers
Oracle® TimesTen In-Memory Database C Developer's Guide
Release 11.2.1

Part Number E13066-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

1 C Development Environment

This chapter provides information about the C development environment and related considerations. The following topics are covered:

Setting the environment for development

Environment variable settings for TimesTen are discussed in "Environment variables" in the Oracle TimesTen In-Memory Database Installation Guide.

On UNIX platforms, set the environment for TimesTen by executing one of the following scripts:

install_dir/bin/ttenv.sh
install_dir/bin/ttenv.csh

On Windows, set the environment during installation or run the following:

install_dir\bin\ttenv.bat

Notes:

  • The 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.

Linking options

A TimesTen application can link with the TimesTen ODBC direct driver or ODBC client driver, or can link with a driver manager.

Linking directly with the TimesTen ODBC drivers

Applications to be used solely with TimesTen can directly link with either the TimesTen ODBC direct driver or the ODBC client driver. Direct linking avoids the performance overhead of a driver manager and is the simplest way to access TimesTen. However, developers of direct-linked applications should be aware of the following issues associated with direct linking.

  • 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 to direct-linked applications.

  • The ODBC cursor library is not available to direct-linked applications.

  • Applications cannot use the ODBC functions that are usually implemented by a driver manager. These functions include SQLDataSources and SQLDrivers.

  • Applications that use SQLCancel to close a cursor instead of SQLFreeStmt(..., SQL_CLOSE) will 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.

Linking with a driver manager

Applications that link with the ODBC driver manager on Windows 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 SQLBIGINT, SQLTINYINT, and SQLWCHAR 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.

Note:

Though it is not yet formally supported, TimesTen supplies a driver manager for both Windows and UNIX with the Quick Start sample applications. This driver manager is limited to support for the TimesTen direct driver and client driver only, but does not have the functionality or performance limitations described above. Applications that must concurrently use both direct connections and client/server connections can use this driver manager to achieve this with very little impact on performance and no impact on functionality.

Testing link options

To test whether an application was directly linked, you can call SQLGetInfo to examine the driver release of the database connection handle, as shown in Example 1-1.

For direct-linked applications, the call to SQLGetInfo returns the unchanged connection handle. For applications that use a driver manager, the returned connection handle differs from the passed-in handle.

Example 1-1 Testing whether an application is directly linked

RetCode = SQLDriverConnect(hdbc,NULL,szConnString, 
     SQL_NTS,szConnout,255,&cbConnOut,SQL_DRIVER_NOPROMPT);
rc = SQLGetInfo(hdbc, SQL_DRIVER_HDBC, &drhdbc,
     sizeof (drhdbc), &drhdbclen);
if (drhdbc != NULL && drhdbc != hdbc) {
     /* Linked with driver manager */
}
else {
     /* Directly linked with TimesTen driver */
}

Compiling and linking applications

This section discusses compiling and linking C applications on Windows or UNIX.

Compiling and linking applications on Windows

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.

The Makefile in Example 1-2 shows how to build a TimesTen application on Windows systems. This example assumes that install_dir\lib has already been added to the LIB environment variable.

Example 1-2 Building a TimesTen application in Windows

CFLAGS = "/Iinstall_dir\include"
LIBSDM = ODBC32.LIB
LIBS = tten1121.lib ttdv1121.lib
LIBSDEBUG = tten1121d.lib ttdv1121d.lib
LIBSCS = ttclient1121.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)

Compiling and linking applications on UNIX

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 ULONG, SLONG, USHORT or 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:

-Iinstall_dir/include

To link with the TimesTen ODBC direct driver, add the following to the link command:

-Linstall_dir/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:

-Linstall_dir/lib -lttclient

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-3 to guide you in creating your own Makefile.

Example 1-3 Makefile to link the application

CFLAGS = -Iinstall_dir/include
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)

Notes:

  • To directly link your application to the TimesTen debug ODBC driver, substitute -lttenD for -ltten on the link line.

  • On Solaris, when compiling with Sun C/C++ compilers, TimesTen applications must be compiled and linked with the -mt option.

About the TimesTen C demos

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 install_dir/quickstart.html, especially the links under SAMPLE PROGRAMS, for information on the following topics.