1 TTClasses Development Environment

This chapter provides information to help you get started with your TTClasses development environment.

TTClasses comes compiled and preconfigured during TimesTen installation. If you have a different C++ runtime than what TTClasses was compiled with, recompile the library using the make (UNIX) or nmake (Microsoft Windows) utility.

The information here includes a discussion of environment variables and compilation for TTClasses itself, information for compiling and linking your TTClasses applications, and an introduction to the Quick Start demo applications for TTClasses. The following topics are covered:

Setting up TTClasses

This section discusses how to set up TTClasses, covering the following topics:

Setting up TTClasses on UNIX

This section covers the following topics for setting up TTClasses in a UNIX environment:

Set UNIX environment variables

To use TTClasses, ensure that your shell environment variables are set correctly through the appropriate ttenv script in the install_dir/bin directory, which is ttenv.sh or ttenv.csh for UNIX platforms (where which you use depends on your shell). See "Environment variables" in the Oracle TimesTen In-Memory Database Installation Guide for details.

Instead of doing this directly, you can add a line for the appropriate script to your login initialization script (for example, .profile or .cshrc).

Compile TTClasses on UNIX

If you have application linking problems, which can be caused by using a different C++ runtime than what TTClasses was compiled with, recompile the library using the make utility.

To recompile TTClasses, change to the ttclasses directory, where install_dir is your TimesTen installation directory:

$ cd install_dir/ttclasses

Run make clean for a fresh start:

$ make clean

Recompile TTClasses for direct connections as follows:

$ make

To recompile TTClasses for client/server connections, use the MakefileCS Makefile:

$ make -f MakefileCS

Compilation options on UNIX

The following make target options are available when you compile TTClasses in a UNIX environment:

  • all: Build a shared optimized library or libraries (default). Use this with Makefile for direct connections, or with MakefileCS for client/server connections.

  • shared_opt: Build a shared optimized library. Currently this has the same effect as all.

  • shared_debug: Build a shared debug library.

  • static_opt: Build a static optimized library.

  • static_debug: Build a static debug library.

  • opt: Build the optimized libraries (shared and static).

  • debug: Build the debug libraries (shared and static).

  • clean: Delete the TTClasses libraries and object files.

To specify a make target, use the name of the make target on the command line.

For example, to build a shared debug version of TTClasses:

$ make clean shared_debug

Install TTClasses after compilation (UNIX only)

After compilation, install the library so all users of the TimesTen instance can use TTClasses. The following shows the steps to install the TTClasses library on a UNIX system.

$ cd install_dir/ttclasses
$ make install

Setting up TTClasses on Windows

This section covers the following topics for setting up TTClasses in a Windows environment:

Note:

On Windows, the TTClasses library is automatically installed after compilation.

Set Windows environment variables

Before recompiling, ensure that the PATH, INCLUDE, and LIB environment variables point to the correct Visual Studio directories. Execute the applicable Visual Studio C++ batch file (for example, VCVARS32.BAT or VSVARS32.BAT) to accomplish this.

Then set environment variables for TimesTen (if they were not already set during installation) by running the following:

install_dir\bin\ttenv.bat

Compile TTClasses on Windows

If you have application linking problems, which can be caused by using a different C++ runtime than what TTClasses was compiled with, recompile the library using the nmake utility.

To recompile TTClasses, change to the ttclasses directory, where install_dir is your TimesTen installation directory:

install_dir\ttclasses

Run nmake clean for a fresh start:

install_dir\ttclasses> nmake clean

Then recompile. By default this is for both direct and client/server connections:

install_dir\ttclasses> nmake

Compilation options on Windows

The following make target options are available when you compile TTClasses in a Windows environment.

  • all: Build shared optimized libraries for direct and client/server connections (default).

  • client: Build shared optimized library for client/server only.

  • msdm: Build shared optimized library for Microsoft driver manager.

  • clean: Delete the TTClasses libraries and object files.

To specify a make target, use the name of the make target on the command line.

For example, to build only the client/server TTClasses library:

install_dir\ttclasses> nmake clean client

TTClasses compiler macros

When necessary, you can modify the TTClasses Makefile manually to add flags for the TTClasses compiler macros. For UNIX, add -Dflagname. For Windows, add /Dflagname.

This section includes information about the following compiler macros:

TTEXCEPT: Throw C++ exceptions

Compile TTClasses, as well as your applications, with the -DTTEXCEPT flag to make TTClasses throw C++ exceptions. (TTClasses is compiled this way by default.) Put {try/catch} blocks around all TTClasses function calls and catch exceptions of type TTStatus.

An alternative, although discouraged, mode of operation is to compile TTClasses and your application without TTEXCEPT enabled. In this mode, error handling is accomplished using older method versions with an explicit TTStatus& parameter, as in earlier TimesTen releases.

See "TTStatus".

TTC_USE_STRINGSTREAM, USE_OLD_CPP_STREAMS: For C++ I/O streams

There are multiple types of C++ streams and they are not compatible with each other. TimesTen provides two related flags. Which streams you use in your application determines which flag to set, or whether you should set neither, as follows (from newer stream types to older):

  • For streams where you are including <iostream> and using the ostringstream class, set the TTC_USE_STRINGSTREAM flag.

  • For streams where you are including <iostream> and using the ostrstream class, set neither flag. This is the default for most platforms and compilers.

  • For streams where you are including <iostream.h> and using the ostrstream class, set the USE_OLD_CPP_STREAMS flag. This is the default for some older platforms and compilers.

Check your TTClasses Makefile. If the flags are not set properly, then update the Makefile as appropriate, recompile TTClasses, and replace the previous TTClasses library file with the recompiled one.

Also see the subsections that follow.

TTC_USE_STRINGSTREAM: For C++ I/O stream code with ostringstream

This compiler flag is for use with C++ compilers that reliably support C++ stream types utilizing the ostringstream class. If your program uses C++ stream code and you include <iostream> and use the ostringstream class, then TTClasses must be compiled with the -DTTC_USE_STRINGSTREAM setting.

Also note that in this case, the USE_OLD_CPP_STREAMS flag must not be set.

Note:

With gcc version 3.2 and higher, the TTC_USE_STRINGSTREAM flag is set by default in the file install_dir/include/ttclasses/TTIostream.h.
Neither: For C++ I/O stream code with ostrstream

If your program uses C++ stream code and you include <iostream> and use the ostrstream class, neither the TTC_USE_STRINGSTREAM flag nor the USE_OLD_CPP_STREAMS flag should be set.

USE_OLD_CPP_STREAMS: For older C++ I/O stream code with ostrstream

This compiler flag is for older C++ compilers that do not support <iostream>. If your program uses old C++ stream code and you include <iostream.h> and use the ostrstream class, then TTClasses must be compiled with the -DUSE_OLD_CPP_STREAMS setting.

Also note that in this case, the TTC_USE_STRINGSTREAM flag must not be set.

TTDEBUG: Generate additional debugging and error checking logic

Compile TTClasses with -DTTDEBUG to generate extra debugging information. This extra information reduces performance somewhat, so use this flag only in development (not production) systems.

TT_64BIT: Use TTClasses with 64-bit TimesTen

Compile TTClasses with -DTT_64BIT if you are writing a 64-bit TimesTen application.

Platform-specific compiler macros

The following compiler macros are specific to a particular platform or compiler combination. You should not have to specify these compiler macros manually. Their use is determined by the Makefile chosen by the configure program.

  • gcc: Compile TTClasses with the -DGCC flag when using gcc on any platform.

Compiling and linking applications

This section discusses how to compile and link your TTClasses applications on UNIX and Windows, including a section on considerations when using the ODBC driver manager on Windows.

You can also refer to the following sections in Oracle TimesTen In-Memory Database C Developer's Guide for related information:

Compiling and linking applications on UNIX

For compiling your applications, include the TTClasses header files that are in the install_dir/include/ttclasses directory. You can accomplish this simply by including TTInclude.h from that directory, as follows.

Use the following compile command:

-Iinstall_dir/include

And use the following line in your code:

#include <ttclasses/TTInclude.h>

TTClasses XLA programs must also include the following:

#include <ttclasses/TTXla.h>

The following table lists the TTClasses libraries available for linking your applications on UNIX platforms.

Usage Library
TimesTen direct connections libttclasses.so
TimesTen client/server connections libttclassesCS.so

For example, adding the following to the link command would result in use of the client driver:

-Linstall_dir/lib -lttclassesCS

The -L option tells the linker to search the TimesTen lib directory for library files. The -lttclassesCS option links in the driver.

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 -lttclassesCS -lC_r

You can use the Makefile in the quickstart/sample_code/ttclasses directory to guide you in creating your own Makefile.

Compiling and linking applications on Windows

For compiling your applications, include the TTClasses header files that are in the install_dir\include\ttclasses directory. You can accomplish this simply by including TTInclude.h from that directory, as follows.

Use the following compile command:

/Iinstall_dir\include

And use the following line in your code:

#include <ttclasses/TTInclude.h>

TTClasses XLA programs must also include the following:

#include <ttclasses/TTXla.h>

The following table lists the TTClasses libraries available for linking your applications on Windows platforms.

Usage Library
TimesTen direct connections ttclasses1122.lib
TimesTen client/server connections ttclasses1122CS.lib
Microsoft ODBC driver manager ttclasses1122DM.lib

See the next section, "Considerations when using an ODBC driver manager (Windows)".


Add the appropriate library, for example install_dir\lib\ttclasses1122.lib, to your link command.

You can use the Makefile in the quickstart\sample_code\ttclasses directory to guide you in creating your own Makefile.

Considerations when using an ODBC driver manager (Windows)

Be aware of the following limitations in TTClasses when you use the ODBC driver manager on Windows. (These restrictions do not apply to the demo ttdm driver manager supplied with the TimesTen Quick Start.)

  • XLA functionality is not supported.

  • REF CURSOR functionality is not supported.

  • 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 as documented in "Working with LOBs".

In addition, the driver manager does not support the ODBC C types SQL_C_BIGINT and SQL_C_TINYINT when used with TimesTen. When using the driver manager, you cannot call methods that use either of these data types in their signatures, such as the applicable overloaded versions of any of the following TTCmd methods: getColumn(), getColumnNullable(), getNextColumn(), getNextColumnNullable(), setParam(), getParam(), and BindParameter().

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 is limited to support for the TimesTen direct driver and client driver only. It 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.

About the TimesTen TTClasses demos

After you have configured your C++ environment, you can confirm that everything is set up correctly by compiling and running the 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 about the following.

  • 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 (.sh or .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 TTClasses and XLA in subdirectories under the install_dir/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 TTClasses (C++) under SAMPLE PROGRAMS.