4 TimesTen Support for Pro*C/C++

TimesTen and TimesTen Cache support the Oracle Pro*C/C++ Precompiler for C and C++ applications. You can use the precompiler with embedded SQL and PL/SQL applications that access the TimesTen database.

This chapter provides an overview and TimesTen-specific information regarding Pro*C/C++, especially emphasizing differences between using Pro*C/C++ with TimesTen versus with Oracle Database. For complete information about Pro*C/C++, you can refer to Pro*C/C++ Programmer's Guide in the Oracle Database library.

Also note that Chapter 2, "Working with TimesTen Databases in ODBC", contains information that may be of general interest regarding TimesTen features.

This chapter includes the following topics:

Overview of the Oracle Pro*C/C++ Precompiler

The Oracle Pro*C/C++ Precompiler enables you to embed SQL statements or PL/SQL blocks directly into C or C++ code. Further, you can use your C or C++ program host variables in your embedded SQL or PL/SQL.

You use a precompilation step to convert the Pro*C/C++ source file into a C or C++ source file. The precompiler accepts the Pro*C/C++ file as input, translates embedded SQL statements into standard Oracle Database runtime library calls, and generates a modified source code file that you can then compile and link. Pro*C/C++ code is linked against the Oracle Database precompiler SQLLIB library, which is shipped with TimesTen as part of the Oracle Instant Client.

Overview of TimesTen support for Pro*C/C++

TimesTen support for the Oracle Pro*C/C++ Precompiler depends on TimesTen OCI. TimesTen OCI depends on the Oracle client library and the TimesTen ODBC libraries. See Figure 3-1 to see where OCI and Pro*C/C++ fit in the TimesTen architecture.

This chapter contains information specific to using the Oracle Pro*C/C++ Precompiler with TimesTen. The syntax and usage of the Oracle Pro*C/C++ Precompiler with TimesTen is essentially the same as with Oracle Database.

The rest of this section includes the following topics.

TimesTen OCI support

Because TimesTen support of the Oracle Pro*C/C++ Precompiler depends on TimesTen OCI support, restrictions for TimesTen OCI apply to Pro*C/C++ applications.

In addition, TimesTen does not support OCI calls that are related to functionality that does not exist in TimesTen.

For more information about TimesTen OCI support, see Chapter 3, "TimesTen Support for OCI." Much of the information there may apply to Pro*C/C++ applications as well.

Embedded SQL support and restrictions

The TimesTen Pro*C/C++ Precompiler does not support embedded SQL for functionality that TimesTen and TimesTen Cache do not support. See "TimesTen restrictions and differences".

TimesTen provides the following support for SQLLIB functions:

  • SQLErrorGetText (sqlglmt) is supported.

  • SQLRowidGet() is supported following only SELECT FOR UPDATE statements.

In addition, TimesTen support for the Oracle Pro*C/C++ Precompiler has the following restrictions:

  • REGISTER CONNECT is not supported.

  • Stored Java subprograms are not supported.

Semantic checking restrictions

TimesTen support for the Oracle Pro*C/C++ Precompiler does not provide semantic checking during precompilation. A SQLCHECK precompiler option setting that specifies semantic checking is permissible but has no effect.

It is important to be aware, however, that a setting of SEMANTICS results in a database connection even though precompilation semantic checking is not performed. Therefore, a setting of SEMANTICS requires the following during precompilation:

  • The database must be running.

  • The USERID precompiler option must be set, either on the command line or in the pcscfg.cfg configuration file. You must provide the user name and password for an existing TimesTen user, and a TNS name that points to the database. In the following example, you are prompted for the password:

    USERID=user1@my_tnsname
    

    Alternatively, you can enter USERID=user1/mypassword@my_tnsname, but for security reasons it is not advisable to specify a password on a command line or in a configuration file.

See "Connecting to a TimesTen database from Pro*C/C++" for information about usage and syntax for TNS names.

See the next section, "Embedded PL/SQL restrictions", for related information about Pro*C/C++ programs that use PL/SQL.

Embedded PL/SQL restrictions

In TimesTen, if a Pro*C/C++ application contains PL/SQL blocks, then Pro*C/C++ acts as though the SQLCHECK setting is SEMANTICS. It is important to be aware that this results in a database connection even though precompilation semantic checking is not performed. Therefore, using PL/SQL in a Pro*C/C++ application requires the following during precompilation:

  • The database must be running.

  • The USERID precompiler option must be set, specifying an existing TimesTen user. See the preceding section, "Semantic checking restrictions", for details about setting this option.

Transaction restrictions

Regarding transactions, TimesTen support for the Oracle Pro*C/C++ Precompiler does not provide the following:

  • SAVEPOINT SQL statement

  • SET TRANSACTION SQL statement

    You can still have transactions with commit and rollback, just not the SET TRANSACTION SQL statement.

  • Fetch across commits

  • Distributed transactions

Connection restrictions

Regarding connections, TimesTen support for the Oracle Pro*C/C++ Precompiler does not provide the following:

  • ALTER AUTHORIZATION clause

  • Automatic connections to the database

  • Making connections to the database with SYSDBA or SYSOPER privilege, given that these privileges do not exist in TimesTen

  • Implicit connections (dblinks) to a TimesTen or Oracle Database

For information about supported connection syntax, see "Connecting to a TimesTen database from Pro*C/C++".

Summary of unsupported or restricted executable commands and clauses

Given restrictions including those noted in the preceding sections, this section summarizes the Pro*C/C++ EXEC SQL executable commands, categories of commands, and command clauses that TimesTen does not support or supports only partially:

  • ALTER AUTHORIZATION

  • CACHE FREE ALL

  • CALL

    This is supported only for calling PL/SQL. To call TimesTen built-in procedures, use dynamic SQL statements.

  • Any "COLLECTION..." command

  • COMMIT FORCE 'some text'

  • COMMIT WORK COMMENT 'some text' RELEASE

    The COMMENT clause is not supported.

  • CONNECT BY

  • CONTEXT OBJECT OPTION GET

  • CONTEXT OBJECT OPTION SET

  • DECLARE CURSOR

    The WITH HOLD clause is not supported.

  • DECLARE TABLE

    Only Oracle Database data types are supported.

  • DECLARE TYPE

  • EXPLAIN PLAN

  • IN SYSDBA MODE

  • IN SYSOPER MODE

  • LOCK TABLE

  • Any "OBJECT..." command

  • PARTITION

  • REGISTER CONNECT

  • RETURN

  • RETURNING

  • SAVEPOINT

  • SET DESCRIPTOR

    You cannot set CHARACTER_SET_NAME.

  • SET TRANSACTION

  • START WITH

  • TO SAVEPOINT

The ttSrcScan utility

If you have an existing Pro*C/C++ program and want to see whether it uses Pro*C/C++ features that TimesTen does not support, you can use the ttSrcScan command line utility to scan your program for unsupported embedded SQL functions and types. This is a standalone utility that can be run without TimesTen or Oracle Database being installed and runs on any platform supported by TimesTen. It reads source code files as input and creates HTML and text files as output. If the utility finds unsupported items, they are logged and alternatives are suggested. You can find the ttSrcScan executable in the quickstart/sample_util directory in your TimesTen installation.

Specify an input file or directory for the program to be scanned and an output directory for the ttSrcScan reports. Other options are available as well. See the README file in the sample_util directory for information.

Getting started with TimesTen Pro*C/C++

This section covers the following topics for getting started with a Pro*C/C++ application for TimesTen:

Environment and configuration for TimesTen Pro*C/C++

The Pro*C/C++ system configuration file pcscfg.cfg contains the precompiler options for precompilation of your Pro*C/C++ source code. In TimesTen, you must use the version of this file that TimesTen provides. This typically happens automatically if you ensure appropriate configuration for TimesTen through the TimesTen ttenv script. See "Environment variables" in the Oracle TimesTen In-Memory Database Installation Guide for information about ttenv.

Note:

To ensure proper generation of OCI and Pro*C/C++ programs to be run on TimesTen, do not set ORACLE_HOME for OCI and Pro*C/C++ compilations (or unset it if it was set previously).

Building a Pro*C/C++ application

Before building a Pro*C/C++ application, you must set up your environment:

  1. You can use the TimesTen OCI and Pro*C/C++ Makefiles provided with the Quick Start demos to implement appropriate environment settings. These are in the following locations (assuming the standard Quick Start location):

    install_dir/quickstart/sample_code/oci/
    install_dir/quickstart/sample_code/proc/
    
  2. Confirm LD_LIBRARY_PATH or PATH is set so that the Oracle Instant Client directory precedes the Oracle Database libraries in the path. The path is set properly if you use the install_dir/bin/ttenv script or quickstart/ttquickstartenv script. See "Environment variables" in Oracle TimesTen In-Memory Database Installation Guide for information about environment variables and ttenv.

Then use steps such as the following to build a Pro*C/C++ application. The steps shown here present a basic example for a UNIX system and assume the program has no other includes (#include) or links to other libraries. The designation instant_client represents the directory where Oracle Instant Client is installed.

See the Quick Start Pro*C/C++ Makefile in the quickstart/sample_code/proc directory for complete, platform-specific examples.

  1. Precompile the Pro*C/C++ source file by using the proc command from your system prompt. For example:

    % proc iname=sample.pc
    

    The proc utility takes a .pc source file as input and produces a .c file.

  2. Compile the resulting C code file. On Linux platforms, enter a command similar to the following:

    % gcc -c sample.c -I(instant_client)/sdk/
    
  3. Link the resulting object modules with modules in SQLLIB. For example:

    % gcc -o sample sample.o -L(instant_client)/lib -lclntsh
    

Connecting to a TimesTen database from Pro*C/C++

This section provides information on connecting to TimesTen from a Pro*C/C++ application. TimesTen Pro*C/C++ and OCI use the Oracle Instant Client to connect to the TimesTen database. Refer to "Connecting to a TimesTen database from OCI" for additional configuration steps to use the tnsnames naming method or easy connect naming method to connect to the database.

The following topics are covered here:

Note:

A TimesTen connection cannot be inherited from a parent process. If a process opens a database connection before creating (forking) a child process, the child must not use the connection. In Pro*C/C++, to avoid having a child process inadvertently inherit a connection from its parent, use EXEC SQL COMMIT RELEASE in the parent before creating the child.

Connection syntax and parameters

TimesTen supports the following connection syntax:

EXEC SQL CONNECT{:user IDENTIFIED BY :pwd | :user_string}
  [[AT{dbname |:host_variable}]USING :connect_string];

The parameters are described in Table 4-1.

Table 4-1 Connection parameters

Parameter Description

user

User name

pwd

Password

user_string

Alternative to separate user and pwd entries

This is a user name and password separated by a slash, such as user1/pwd1. After an "@" sign, you can also have a database identifier, instead of using dbname, or a TNS name or easy connect string, instead of using connect_string. See examples in the next section, "Using tnsnames or easy connect".

dbname

Database identifier declared in a previous DECLARE DATABASE statement

host_variable

Variable whose value is a database identifier

connect_string

Valid TNS name or easy connect string for a TimesTen database


Using tnsnames or easy connect

To connect to TimesTen from a Pro*C/C++ application, you must configure a TNS name or easy connect string for a TimesTen database. Perform the tnsnames or easy connect steps described under "Connecting to a TimesTen database from OCI".

From Pro*C/C++, you can use a host variable to specify the user name, password, and a TNS name. For example:

EXEC SQL CONNECT :dbstring

Where dbstring is set to "user1/pwd1@my_tnsname".

Alternatively, the host variable could specify the user name, password, and an easy connect string. For example, dbstring could be set to "user1/pwd1@localhost/ttclient:timesten_client".

Or, if the TWO_TASK or LOCAL environment variable, as applicable for your operating system, is set to "my_tnsname" or "localhost/ttclient:timesten_client", you could connect as in the following example:

EXEC SQL CONNECT :user1 IDENTIFIED BY :pwd1

Specifying the Oracle Database password in Pro*C/C++ for TimesTen Cache

To use TimesTen Cache, there must be a cache user in the TimesTen database with the same name as an Oracle Database user who can select from and update the cached Oracle Database tables. This Oracle Database user, for example, can be the cache administration user or a schema user. The password of the TimesTen cache user can be different from the password of the Oracle Database user with the same name. See "Setting Up a Caching Infrastructure" in Oracle TimesTen Application-Tier Database Cache User's Guide for details.

For use of Pro*C/C++ with TimesTen Cache, TimesTen allows you to pass the Oracle Database user's password through Pro*C/C++ by appending it to the password field in an EXEC SQL CONNECT call when you log in to TimesTen. Use the attribute OraclePWD in the connect string, such as in the following example:

text *cacheuser = (text *)"cacheuser1";
text *cachepwds = (text *)"ttpwd;OraclePWD=orclpwd";
text *dbname = (text *)"tt_tnsname";
....
EXEC SQL CONNECT :cacheuser IDENTIFIED BY :cachepwds AT :dbname

You must always specify OraclePWD, even if the Oracle Database user's password is the same as the TimesTen user's password. Furthermore, in the circumstance of specifying an Oracle Database password for TimesTen Cache, you must use a form of EXEC SQL CONNECT that specifies the password as a separate host variable. In this example, cacheuser1 is the name of the TimesTen cache user as well as the name of the Oracle Database user who can access the cached Oracle Database tables, ttpwd is the password of the TimesTen cache user, orclpwd is the password of the Oracle Database user, and tt_tnsname is the TNS name of the TimesTen database being connected to. The Oracle database is specified through the TimesTen OracleNetServiceName general connection attribute in the sys.odbc.ini or user odbc.ini file.

Alternatively, instead of using the AT clause with a TNS name, you could use the TWO_TASK or LOCAL environment variable, as discussed in "Connecting to a TimesTen database from OCI".

Connecting as an externally identified user in Pro*C/C++

You can connect through Pro*C/C++ as an externally identified user (external user) by specifying the user name in brackets, such as "[myadmin]", and the password as an empty string, "".

In particular, this is useful in connecting as the instance administrator, which in TimesTen is always an external user.

Externally identified users can be used for direct mode or for client/server connections to a database on the local host, but not for client/server connections to a database on a remote host.

Consider the following example.

text *instanceadmin = (text *)"[myadmin]";
text *instanceadminpwd = (text *)"";
text *dbname = (text *)"tt_tnsname";
....
EXEC SQL CONNECT :instanceadmin IDENTIFIED BY :instanceadminpwd AT :dbname

This functionality uses OCI proxy syntax. You can refer to the discussion of client access through a proxy in Oracle Call Interface Programmer's Guide.

Error reporting and handling

Be aware of the following regarding error conditions and error reporting:

  • Errors under TimesTen Pro*C/C++ applications return Oracle Database error codes. TimesTen attempts to report the same error code as Oracle Database would under similar conditions. The error messages may come from either the TimesTen catalog or the Oracle Database catalog. Some error messages may indicate the accompanying TimesTen error code if appropriate. Pro*C/C++ applications that rely on parsing error codes should be checked.

  • TimesTen supports the WHENEVER SQLERROR directive, to go to an error handler if an error occurs, and the WHENEVER NOT FOUND directive, to go to a handling section if a "no data found" condition occurs. TimesTen does not support the WHENEVER SQLWARNING directive.

    Examples:

    EXEC SQL WHENEVER NOT FOUND GOTO close_cursor;
    ...
    EXEC SQL WHENEVER SQLERROR GOTO error_handler;
    

Pro*C/C++ demo programs

TimesTen ships Pro*C/C++ demo programs. They are in the quickstart/sample_code/proc directory. The README file in the directory explains how to compile and run the demos.

Refer to the Quick Start welcome page at install_dir/quickstart.html for information.

Additional features of TimesTen Pro*C/C++

This section covers additional features you can use with Pro*C/C++ in TimesTen:

Associative array bindings in TimesTen Pro*C/C++

As discussed in "Associative array bindings in TimesTen OCI", associative arrays, formerly known as index-by tables or PL/SQL tables, are supported as IN, OUT, or IN OUT bind parameters in TimesTen PL/SQL. See that section for additional information and limitations.

You can pass associative arrays between PL/SQL blocks and Pro*C/C++ applications as well as OCI applications. They can be indexed by a PL/SQL variable of type BINARY_INTEGER or PLS_INTEGER.

Normally, the entire host array is passed to PL/SQL, but you can use the Pro*C/C++ ARRAYLEN statement to specify a smaller array dimension.

For more information, refer to "PL/SQL Tables", "Host Arrays", and "ARRAYLEN Statement" under "Embedded PL/SQL" in Pro*C/C++ Programmer's Guide.

Example 4-1 Binding to an associative array from Pro*C/C++

This code excerpt shows the array salary[] being bound from Pro*C/C++ into the associative array num_tab in PL/SQL.

...
float salary[100];
/* populate the host array */
EXEC SQL EXECUTE
  DECLARE
    TYPE NumTabTyp IS TABLE OF REAL
                   INDEX BY BINARY_INTEGER;
    median_salary REAL;
    n BINARY_INTEGER;
...
  FUNCTION median (num_tab NumTabTyp, n INTEGER)
    RETURN REAL IS
  BEGIN
    -- compute median
  END;
  BEGIN
    n := 100;
    median_salary := median(:salary, n);
    ...
  END;
END-EXEC;
...

LOBs in TimesTen Pro*C/C++

TimesTen supports LOBs (large objects). This includes CLOBs (character LOBs), NCLOBs (national character LOBs), and BLOBs (binary LOBs).

See "Working with LOBs". That section is ODBC-oriented but also provides a general overview of LOBs, differences between TimesTen and Oracle Database LOBs, and LOB programming interfaces. Also see "LOBs in TimesTen OCI" for information about LOB locators, temporary LOBs, using the simple data interface or LOB locator interface in OCI, and additional OCI LOB features.

This section focuses on key Pro*C/C++ LOB features and TimesTen-specific support and restrictions.

See "LOB data types" in Oracle TimesTen In-Memory Database SQL Reference for additional information about LOBs in TimesTen.

For complete information about LOBs and how to use them in Pro*C/C++, refer to "LOBs" in Pro*C/C++ Programmer's Guide, keeping in mind that TimesTen does not support BFILEs, SecureFiles, array reads and writes for LOBs, or callback functions for LOBs. In particular, see "How to Use LOBs in Your Program" within that chapter.

The following topics are covered for Pro*C/C++:

Important:

As indicated in the OCI chapter, in TimesTen a LOB used in an application does not remain valid past the end of the transaction.

Note:

The LOB piecewise data interface is not applicable to OCI or Pro*C/C++ applications in TimesTen. (You can, however, manipulate LOB data in pieces through features of the LOB locator interface.)

Using the LOB simple data interface in Pro*C/C++

The simple data interface enables applications to manipulate LOB data similarly to how they would manipulate other types of scalar data, such as by using EXEC SQL INSERT and EXEC SQL SELECT. The application can use a LOB type that is compatible with the corresponding variable type.

An application can use the EMPTY_BLOB() or EMPTY_CLOB() function, as appropriate, to initialize a persistent LOB. This is similar to using ALLOCATE in the LOB locator interface, discussed next. Consider the following tables:

EXEC SQL CREATE TABLE lob_table ( a_blob BLOB, a_clob CLOB );
...
EXEC SQL INSERT INTO lob_table (a_blob, a_clob) 
                VALUES (EMPTY_BLOB(), EMPTY_CLOB());
...
EXEC SQL CREATE TABLE data_table
         ( name VARCHAR2(30), length NUMBER(10), bincol BLOB, charcol CLOB );

The following selects LOB data from data_table into myblob and myclob, then inserts the LOB data into lob_table.

...
OCIBlobLocator *myblob;
OCIClobLocator *myclob;
...
EXEC SQL SELECT bincol, charcol INTO :myblob, :myclob FROM data_table 
                WHERE name = :key;
...
// Put data into lob_table.
...
EXEC SQL INSERT INTO lob_table (a_blob, a_clob) VALUES (:myblob, :myclob);

To use an NCLOB, declare the variable as follows:

OCIClobLocator CHARACTER SET IS NCHAR_CS *mynclob;

Note:

The simple data interface, through OCI or Pro*C/C++, limits bind sizes to 64 KB.

Using the LOB locator interface in Pro*C/C++

You can use the Pro*C/C++ LOB locator interface to work with either LOBs from the database or temporary LOBs, either piece-by-piece or in whole chunks.

Refer to "LOB Statements" in Pro*C/C++ Programmer's Guide for detailed information about Pro*C/C++ statements for LOBs, noting that TimesTen does not support features specifically intended for BFILEs, SecureFiles, array reads and writes for LOBs, or callback functions for LOBs.

Refer to the lobdemo1.pc example in "LOBs" in Pro*C/C++ Programmer's Guide for an end-to-end example.

Also see "Using the LOB locator interface in OCI" for related information and usage notes.

Note:

If Pro*C/C++ syntax does not provide enough functionality to fully specify what you want to accomplish for any operation, you can use the corresponding OCI function as an alternative.
Create a temporary LOB in Pro*C/C++

A Pro*C/C++ application can create a temporary LOB by using the CREATE TEMPORARY embedded SQL feature, after first using the ALLOCATE feature to allocate the locator. Use FREE to free the allocation for the locator and FREE TEMPORARY to free the temporary LOB itself. This is shown below.

Also see "Create a temporary LOB in OCI".

Important:

In TimesTen, creation of a temporary LOB results in creation of a database transaction if one is not already in progress. To avoid error conditions, you must execute a commit or rollback to close the transaction.
OCIClobLocator *tempclob;
EXEC SQL ALLOCATE :tempclob;
EXEC SQL LOB CREATE TEMPORARY :tempclob;
...
// (Manipulate LOB as desired.)
...
EXEC SQL FREE TEMPORARY :tempclob;
EXEC SQL FREE :tempclob;

Alternatively, if you want to specify the LOB character set (here NCHAR), you can use the corresponding OCI function:

status = OCILobCreateTemporary(svc, err, tempclob, OCI_DEFAULT, SQLCS_NCHAR,
         OCI_TEMP_CLOB, TRUE, OCI_DURATION_TRANSACTION); 
Access the locator of a persistent LOB in Pro*C/C++

An application typically accesses a LOB from the database by using a SQL statement to obtain a LOB locator, then passing the locator to an appropriate API function.

Also see "Access the locator of a persistent LOB in OCI".

The following excerpts are from the previously mentioned lobdemo1.pc example in "LOBs" in Pro*C/C++ Programmer's Guide. The example uses a CLOB license_txt and table license_table whose columns are social security number, name, and text summarizing driving offenses (a CLOB column).

OCIClobLocator *license_txt;
...
EXEC SQL ALLOCATE :license_txt;
...
EXEC SQL SELECT name, txt_summary INTO :name, :license_txt FROM license_table
                WHERE sss = :sss;
Read and write LOB data using the Pro*C/C++ LOB locator interface

A Pro*C/C++ application can use LOB OPEN and LOB CLOSE to open and close a LOB, LOB READ to read LOB data, LOB WRITE or LOB WRITE APPEND to write or append LOB data, LOB DESCRIBE to obtain information about a LOB, and various other Pro*C/C++ features to perform a variety of other actions. All the Pro*C/C++ LOB locator interface features are covered in detail in "LOBs" in Pro*C/C++ Programmer's Guide.

To write data, use LOB WRITE ONE to write the data in a single chunk. TimesTen does not support LOB WRITE FIRST, LOB WRITE NEXT, or LOB WRITE LAST (features of the piecewise data interface).

Also see "Read and write LOB data using the OCI LOB locator interface".

Here is an example of an EXEC SQL LOB READ statement:

EXEC SQL LOB READ :amt FROM :blob INTO :buffer;

Refer to "Read a File, WRITE a BLOB Example" in "LOBs" in Pro*C/C++ Programmer's Guide for additional information.

Here is an example of an EXEC SQL LOB WRITE statement (writing the LOB data in one chunk):

EXEC SQL LOB WRITE ONE :amt FROM :buffer INTO :blob;

Refer to "READ a BLOB, Write a File Example" in "LOBs" in Pro*C/C++ Programmer's Guide for additional information.

Here is an example of an EXEC SQL LOB WRITE APPEND statement:

EXEC SQL LOB WRITE APPEND :amt FROM :writebuf INTO :blob;

Note:

Opening a LOB is similar conceptually, but not technically, to opening a file. Opening a LOB is more like a hint regarding resources to be required.

Be aware that a LOB being accessed by OCILobRead(), OCILobWrite(), or equivalent functionality is opened automatically as necessary.

Example 4-2 Write a LOB using Pro*C/C++ LOB locator interface

The following excerpt is from the previously mentioned lobdemo1.pc example in "LOBs" in Pro*C/C++ Programmer's Guide.

...
OCIClobLocator *a_clob;
char *charbuf;
ub4 ClobLen, WriteAmt;
int CharLen = strlen(charbuf);
int NewCharbufLen = CharLen + DATELENGTH + 4;
varchar *NewCharbuf;
NewCharbuf = (varchar *)malloc(2 + NewCharbufLen);
NewCharbuf->arr[0] = '\n';
NewCharbuf->arr[1] = '\0';
strcat((char *)NewCharbuf->arr, charbuf);
NewCharbuf->arr[CharLen + 1] = '\0';
strcat((char *)NewCharbuf->arr, curdate);
NewCharbuf->len = NewCharbufLen;
EXEC SQL LOB DESCRIBE :a_clob GET LENGTH INTO :ClobLen;
WriteAmt = NewCharbufLen;
EXEC SQL LOB WRITE ONE :WriteAmt FROM :NewCharbuf WITH LENGTH :NewCharbufLen 
                       INTO :a_clob;
...

Example 4-3 Write and append to a LOB using Pro*C/C++ LOB locator interface

This example, like the preceding one, uses LOB WRITE ONE. Then it also uses LOB WRITE APPEND to append additional data. It writes or appends to the BLOB in 1 K chunks up to MAX_CHUNKS.

...
 EXEC SQL select b into :blob from t where pk = 1 for update;
 EXEC SQL LOB OPEN :blob READ WRITE;
 
 // Write/append to the BLOB
 for (i = 0; i < MAX_CHUNKS; i++) {
   if (i==0) { // FIRST CHUNK
     /*
     Write the first piece
     */
     EXEC SQL LOB WRITE ONE :amt FROM :writebuf INTO :blob;
 
   }
   else { // All Other Chunks
     /*
     At this point, APPEND all the next pieces
     */
     EXEC SQL LOB WRITE APPEND :amt FROM :writebuf INTO :blob ;
   }
   ...
 }
...

TimesTen Pro*C/C++ Precompiler options

This section discusses Pro*C/C++ Precompiler option support by TimesTen.

Precompiler option support

Table 4-2 describes TimesTen Pro*C/C++ Precompiler option support.

Table 4-2 TimesTen Pro*C/C++ Precompiler option support

Option Notes

AUTO_CONNECT

Supported value: NO (default)

CHAR_MAP

Supported

CINCR

Not applicable

Setting has no effect because TimesTen supports only CPOOL=NO.

CLOSE_ON_COMMIT

Supported value: YES

The Oracle Database default value of NO is overridden by TimesTen.

CMAX

Not applicable

Setting has no effect because TimesTen supports only CPOOL=NO.

CMIN

Not applicable

Setting has no effect because TimesTen supports only CPOOL=NO.

CNOWAIT

Not applicable

Setting has no effect because TimesTen supports only CPOOL=NO.

CODE

Supported

COMP_CHARSET

Supported

CONFIG

Supported

CPOOL

Supported value: NO (default)

CPP_SUFFIX

Supported

CTIMEOUT

Not applicable

Setting has no effect because TimesTen supports only CPOOL=NO.

DB2_ARRAY

Supported

DBMS

Supported value: NATIVE (default)

DEF_SQLCODE

Supported

DEFINE

Supported

DURATION

Not applicable

Setting has no effect because TimesTen does not support objects.

DYNAMIC

Supported

ERRORS

Supported

ERRTYPE

Not supported

EVENTS

Not applicable

Both values allowed, but TimesTen OCI does not support Advanced Queuing.

FIPS

Supported

HEADER

Supported

HOLD_CURSOR

Supported

IMPLICIT_SVPT

Supported value: NO (default)

INAME

Supported

INCLUDE

Supported

INTYPE

Supported

LINES

Supported

LNAME

Supported

LTYPE

Supported

MAX_ROW_INSERT

Supported

MAXLITERAL

Supported

MAXOPENCURSORS

Supported

MODE

Supported

NATIVE_TYPES

Supported

NLS_CHAR

Supported

NLS_LOCAL

Supported value: NO (default)

OBJECTS

Not applicable

Setting has no effect because TimesTen does not support objects.

ONAME

Supported

ORACA

Supported

OUTLINE

Not applicable

All values are allowed, but TimesTen does not support Oracle Database optimization.

OUTLNPREFIX

Not applicable

Both values are allowed, but TimesTen does not support Oracle Database optimization.

PAGELEN

Supported

PARSE

Supported

PREFETCH

Supported

RELEASE_CURSOR

Supported

RUNOUTLINE

Not applicable

Both values (yes|no) are allowed but ignored.

SELECT_ERROR

Supported

SQLCHECK

Not applicable

Any of the SQLCHECK settings is allowed, but TimesTen does not support semantic checking during precompilation.

Whenever a Pro*C/C++ application uses PL/SQL, Pro*C/C++ acts as though the SQLCHECK setting is SEMANTICS.

Important: A setting of SEMANTICS (or FULL, which is synonymous) always results in a connection to the database, even though precompilation semantic checking is not performed.

See "Semantic checking restrictions".

STMT_CACHE

Supported

SYS_INCLUDE

Supported

THREADS

Supported

TYPE_CODE

Supported

UNSAFE_NULL

Supported

USERID

Supported

UTF16_CHARSET

Supported value: NCHAR_CHARSET

VARCHAR

Supported

VERSION

Not applicable

Setting has no effect because TimesTen does not support objects.


Note:

TimesTen does not support the default value for CLOSE_ON_COMMIT. TimesTen supports only CLOSE_ON_COMMIT=YES.

Setting precompiler options

You can set precompiler options in the following ways.

  • At compile time, either in the configuration file pcscfg.cfg or on the Pro*C/C++ command line

    A setting on the command line takes precedence over a setting in the configuration file.

  • At runtime through the EXEC ORACLE OPTION command

    A runtime setting takes precedence over a compile-time setting.

For example, the following shows portions of the configuration file that ships with TimesTen.

ltype=short
parse=full
close_on_commit=yes
...

The following command line would override the ltype=short setting from the configuration file:

% proc ltype=long ... iname=sample.pc

The following runtime command would override the ltype=long setting from the command line:

EXEC ORACLE OPTION LTYPE=NONE;