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. You can optionally source one of the following scripts or add a line to source one of these scripts in your login initialization script (.profile or .cshrc), where install_dir is your TimesTen installation directory.

install_dir/bin/ttenv.sh    (sh/ksh/bash)
install_dir/bin/ttenv.csh   (csh/tcsh)

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

You can recompile TTClasses for both direct and client/server connections as follows:

$ make

Alternatively, to compile TTClasses for client/server only, 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). When used with Makefile this can be for either direct or client/server connections. When used with MakefileCS this is for client/server only.

  • 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
$ make 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:

Installing TTClasses after compiling the TTClasses library happens automatically on Windows.

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
install_dir\ttclasses> nmake 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. Put {try/catch} blocks around all TTClasses function calls and catch exceptions of type TTStatus. Beginning with TimesTen release 11.2.1.6.0, this is the preferred mode for TTClasses (as opposed to error handling using method calls with an explicit TTStatus& parameter, as in earlier 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 types of streams where you are including <iostream> and using the ostringstream class, set the TTC_USE_STRINGSTREAM flag.

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

  • For types of 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 where you include <iostream> and use ostringstream, 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 or higher, the TTC_USE_STRINGSTREAM flag is set by default in the file install_dir/include/ttclasses/TTIostream.h.
Neither: For newer C++ I/O stream code with ostrstream

If your program uses C++ stream code where 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 where 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.

Note that 64-bit TTClasses has been tested on AIX, HP-UX, Solaris, Red Hat Linux, and Tru64.

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.

HPUX

Compile TTClasses with the -DHPUX flag when compiling on HP-UX.

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>

Table 1-1 summarizes the TTClasses libraries available for linking your applications.

Table 1-1 Summary of TTClasses libraries for UNIX

Usage Library

For TimesTen direct connections.

libttclasses.so

For TimesTen client/server connections.

libttclassesCS.so


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

On AIX, when linking applications with the TimesTen ODBC client driver, the C++ runtime library must be included in the link command (because 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>

Table 1-2 summarizes the TTClasses libraries available for linking your applications.

Table 1-2 Summary of TTClasses libraries for Windows

Usage Library

For TimesTen direct connections.

ttclasses1121.lib

For TimesTen client/server connections.

ttclasses1121CS.lib

For the Microsoft ODBC driver manager.

ttclasses1121DM.lib

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


Add the appropriate library, for example install_dir\lib\ttclasses1121.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 does not work.

  • REF CURSOR functionality does not work.

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

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 creates a sample database and demo schema. You must run this before you start using the demos.

  • Demo environment and setup: The ttquickstartenv script, a superset of the ttenv script generally used for TimesTen setup, sets up the demo environment. You must run this each time you enter a session where you want to compile and 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.