Oracle® TimesTen In-Memory Database

C開発者ガイド

11gリリース2 (11.2.2)

B66444-05(原本部品番号:E21637-09)

2014年12月

Oracle TimesTen In-Memory Database C開発者ガイド 11g リリース2 (11.2.2)

B66444-05

Copyright © 1996, 2014, Oracle and/or its affiliates.All rights reserved.

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations.As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。オラクル社との間で該当する取決めにて別途規定しないかぎり、オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。オラクル社との間で該当する取決めにて別途規定する場合を除き、オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。

目次

タイトルおよび著作権情報

はじめに

- 対象読者

- 関連ドキュメント

- 表記規則

- ドキュメントのアクセシビリティについて

新機能

- リリース11.2.2.4.0の新機能

- リリース11.2.2.2.0の新機能

- リリース11.2.2.0.0の新機能

1 C開発環境

- 開発用の環境の設定

- リンク・オプション

- ODBCドライバ・マネージャを使用しないリンク

- ODBCドライバ・マネージャとのリンク

- アプリケーションのコンパイルおよびリンク

- Windowsでのアプリケーションのコンパイルおよびリンク

- UNIXでのアプリケーションのコンパイルおよびリンク

- TimesTen Cのデモについて

2 ODBCでのTimesTenデータベースの使用

- TimesTenデータベース接続の管理

- SQLConnect、SQLDriverConnect、SQLAllocConnect、SQLDisconnectの各関数

- データベースに対する接続および切断

- プログラムでの接続属性の設定

- デフォルトDSNの使用

- 接続のアクセス制御

- TimesTenデータの管理

- TimesTen includeファイル

- Cアプリケーション内でのSQL文の実行

- SQLExecDirect関数およびSQLExecute関数

- SQL文の実行

- 問合せの準備および実行とカーソルの使用

- TimesTenの遅延準備

- 複数のデータ行のプリフェッチ

- パラメータのバインドおよび文の実行

- SQLBindParameter関数

- パラメータのデータ型の割当ての決定および変換

- 入力パラメータのバインド

- 出力パラメータのバインド

- 入力/出力パラメータのバインド

- SQL文での重複したパラメータのバインド

- PL/SQLでの重複したパラメータのバインド

- 浮動小数点データに関する考慮事項

- ドライバ・マネージャを使用したSQL_WCHARおよびSQL_WVARCHARの使用

- REF CURSORの使用

- DML RETURNING(RETURNING INTO句)の使用

- ROWIDの使用

- LOBの使用

- LOBの概要

- TimesTen LOBとOracle Database LOBの相違点

- LOBプログラミング・インタフェース

- ODBCでのLOBの簡易データ・インタフェースの使用

- ODBCでのLOBのピース単位のデータ・インタフェースの使用

- ODBCでのパススルーLOB

- データベースに対する変更の実行とコミット

- その他のTimesTenデータ管理機能の使用

- プロシージャおよび関数を実行するためのCALLの使用

- SQL文の実行に対するタイムアウトまたはしきい値の設定

- SQL文のタイムアウト期間の設定

- SQL文のしきい値期間の設定

- TimesTen Cacheで使用する機能

- ttOptSetFlag組込みプロシージャを使用した一時的なパススルー・レベルの設定

- パススルー・ステータスの確認

- キャッシュ・グループの管理

- グローバリゼーション・オプションの設定

- TT_NLS_SORT

- TT_NLS_LENGTH_SEMANTICS

- TT_NLS_NCHAR_CONV_EXCP

- レプリケーションで使用する機能

- ODBC 3.0データ型

- アクセス制御に関するTimesTen機能の考慮事項

- エラーの処理

- エラーのチェック

- エラーおよび警告のレベル

- 致命的なエラー

- 致命的ではないエラー

- 警告

- 異常終了

- 致命的なエラーからのリカバリ

- アプリケーションでの自動クライアント・フェイルオーバーの使用

- 自動クライアント・フェイルオーバーの機能

- 自動クライアント・フェイルオーバーの構成

- フェイルオーバーのコールバック関数

3 TimesTenでのOCIのサポート

- OCIの概要

- TimesTen OCIサポートの概要

- OCIのライブラリおよびアーキテクチャ

- グローバリゼーション・サポート

- キャラクタ・セット

- その他のグローバリゼーション機能

- TimesTenの制限および相違点

- サポートされていないOracle Databaseの機能

- TimesTen OCIのその他の制限事項

- TimesTen OCIのその他の相違点

- ttSrcScanユーティリティ

- TimesTen OCIの使用

- TimesTen OCIの環境変数

- OCIアプリケーションのコンパイルおよびリンク

- OCIからTimesTenデータベースへの接続

- tnsnamesネーミング・メソッドを使用した接続

- 簡易接続文字列を使用した接続

- 使用する接続方法の設定(tnsnames.oraまたは簡易接続)

- OCIでの外部で識別されたユーザーとしての接続

- OCIエラー・レポート

- シグナル処理および診断フレームワークの考慮事項

- OCIのデモ・プログラム

- TimesTen OCIでの追加機能の使用

- TimesTenの遅延準備

- TimesTen OCIでのパラメータのバインド機能

- TimesTen OCIでの重複したパラメータのバインド

- TimesTen OCIでの連想配列バインド

- TimesTen OCIでのTimesTen Cache

- OCIでのTimesTen Cache用Oracle Databaseパスワードの指定

- アクションの影響を受けるキャッシュ・グループの数の確認

- TimesTen OCIでのLOB

- OCIでのLOBロケータ

- OCIでの一時LOB

- OCIでのTimesTen LOBとOracle Database LOBの相違点

- OCIでのLOBの簡易データ・インタフェースの使用

- OCIでのLOBロケータ・インタフェースの使用

- OCIクライアント側のバッファリング

- OCIでのLOBのプリフェッチ

- OCIでのパススルーLOB

- OCIでPL/SQLを使用してTimesTen組込みプロシージャをコール

- TimesTen OCI サポートのリファレンス

- サポートされているOCIコール

- サポートされているハンドルおよび属性

- サポートされている記述子

- サポートされているSQLデータ型

- サポートされているパラメータ属性

4 TimesTenでのPro*C/C++のサポート

- Oracle Pro*C/C++プリコンパイラの概要

- TimesTenでのPro*C/C++のサポートの概要

- TimesTen OCIサポート

- 埋込みSQLのサポートおよび制限

- セマンティック・チェックの制限

- 埋込みPL/SQLの制限

- トランザクションの制限

- 接続の制限

- サポートされていないか制限されている実行可能コマンドおよび句の概要

- ttSrcScanユーティリティ

- TimesTen Pro*C/C++の開始

- TimesTen Pro*C/C++の環境および構成

- Pro*C/C++アプリケーションの作成

- Pro*C/C++からTimesTenデータベースへの接続

- 接続の構文およびパラメータ

- tnsnamesまたは簡易接続の使用

- Pro*C/C++でのTimesTen Cache用Oracle Databaseパスワードの指定

- Pro*C/C++での外部で識別されたユーザーとしての接続

- エラー・レポートおよび処理

- Pro*C/C++のデモ・プログラム

- TimesTen Pro*C/C++のその他の機能

- TimesTen Pro*C/C++での連想配列バインド

- TimesTen Pro*C/C++でのLOB

- Pro*C/C++でのLOBの簡易データ・インタフェースの使用

- Pro*C/C++でのLOBロケータ・インタフェースの使用

- TimesTenのPro*C/C++プリコンパイラ・オプション

- プリコンパイラ・オプションのサポート

- プリコンパイラ・オプションの設定

5 XLAおよびTimesTenイベント管理

- XLAの概念

- XLAの基本

- XLAでレコードをトランザクション・ログから読み取る方法

- XLAおよびマテリアライズド・ビューについて

- XLAブックマークについて

- ブックマークの作成または再利用

- ブックマークの動作

- レプリケートされたブックマーク

- XLAブックマークおよびトランザクション・ログの保留

- XLAデータ型について

- アクセス制御がXLAに与える影響

- XLAの制限事項

- XLAのデモ

- XLAイベント・ハンドラ・アプリケーションの作成

- データベース接続ハンドルの取得

- XLAの初期化およびXLAハンドルの取得

- 更新を監視する表の指定

- トランザクション・ログからの更新レコードの取得

- レコード・ヘッダーの確認および行アドレスの検出

- 列データの確認

- 列記述の取得

- 固定長列データの読取り

- NOT INLINE可変長列データの読取り

- 返された文字列の空文字での終了

- 複合データ型の変換

- NULL値の検出

- すべての列確認コードの組合せ: PrintColValues()関数

- XLAエラーの処理

- XLAブックマークを使用する表の削除

- ブックマークの削除

- XLAアプリケーションの終了

- レプリケーション・メカニズムとしてのXLAの使用

- データベース間での表の互換性の確認

- 表および列の記述の確認

- 表および列のバージョンの確認

- データベース間での更新のレプリケート

- タイムアウトおよびデッドロックのエラーの処理

- 更新競合の確認

- TimesTen以外のデータベースに対する更新のレプリケート

- その他のXLA機能

- ブックマークの位置の変更

- アプリケーション・コンテキストの受渡し

6 分散トランザクション処理: XA

- XAの概要

- X/Open DTPモデル

- 2フェーズ・コミット

- TimesTenでのXAの使用

- XAのTimesTenデータベース要件

- TimesTenでのグローバル・トランザクション・リカバリ

- 標準のXA関数をTimesTenで使用する場合の考慮事項

- xa_open()

- xa_close()

- トランザクションID(XID)パラメータ

- XA接続からODBCハンドルを取得するTimesTen tt_xa_context関数

- TimesTenでのXA接続に対するODBC関数のコールに関する考慮事項

- 自動コミット

- ローカル・トランザクションのCOMMITおよびROLLBACK

- オープンしているカーソルのクローズ

- XAリソース・マネージャ・スイッチ

- xa_switch_t

- tt_xa_switch

- TimesTenでのXAエラー処理

- Windows ODBCドライバ・マネージャを介したXAサポート

- 考慮事項

- TimesTen ODBC XAドライバ・マネージャの拡張ライブラリへのリンク

- TimesTen XAを使用するためのTuxedoの構成

- $TUXDIR/udataobj/RMファイルの更新

- Tuxedoトランザクション・マネージャ・サーバーの構築

- UBBCONFIGファイルのGROUPSセクションの更新

- サーバーのコンパイル

7 ODBCアプリケーションのチューニング

- ドライバ・マネージャの回避(必要な場合)

- バッチ実行用パラメータ配列の使用

- 過剰なバインドの回避

- SQLGetDataの回避

- データ型の変換の回避

- TimesTenデータ行のバルク・フェッチ

8 TimesTenユーティリティAPI

- ttBackup

- ttDestroyDataStore

- ttDestroyDataStoreForce

- ttRamGrace

- ttRamLoad

- ttRamPolicy

- ttRamUnload

- ttRepDuplicateEx

- ttRestore

- ttUtilAllocEnv

- ttUtilFreeEnv

- ttUtilGetError

- ttUtilGetErrorCount

- ttXactIdRollback

9 XLAリファレンス

- XLA関数について

- リターン・コードについて

- パラメータ・タイプ(入力、出力、入力/出力)について

- 関数による出力結果について

- 必要な権限について

- カテゴリ別のXLA関数の概要

- XLAコア関数

- XLAデータ型変換関数

- XLAレプリケーション関数

- XLA関数リファレンス

- ttXlaAcknowledge

- ttXlaClose

- ttXlaConvertCharType

- ttXlaDateToODBCCType

- ttXlaDecimalToCString

- ttXlaDeleteBookmark

- ttXlaError

- ttXlaErrorRestart

- ttXlaGetColumnInfo

- ttXlaGetLSN

- ttXlaGetTableInfo

- ttXlaGetVersion

- ttXlaNextUpdate

- ttXlaNextUpdateWait

- ttXlaNumberToBigInt

- ttXlaNumberToCString

- ttXlaNumberToDouble

- ttXlaNumberToInt

- ttXlaNumberToSmallInt

- ttXlaNumberToTinyInt

- ttXlaNumberToUInt

- ttXlaOraDateToODBCTimeStamp

- ttXlaOraTimeStampToODBCTimeStamp

- ttXlaPersistOpen

- ttXlaRowidToCString

- ttXlaSetLSN

- ttXlaSetVersion

- ttXlaTableByName

- ttXlaTableStatus

- ttXlaTableVersionVerify

- ttXlaTimeToODBCCType

- ttXlaTimeStampToODBCCType

- ttXlaVersionColumnInfo

- ttXlaVersionCompare

- ttXlaVersionTableInfo

- XLAレプリケーション関数参照

- ttXlaApply

- ttXlaCommit

- ttXlaGenerateSQL

- ttXlaLookup

- ttXlaRollback

- ttXlaTableCheck

- XLAで使用されるCデータ構造体

- ttXlaNodeHdr_t

- ttXlaUpdateDesc_t

- 特別な更新データの書式

- ttXlaUpdateDesc_tヘッダーの後に続く行データのアドレスの検出

- ttXlaVersion_t

- ttXlaTblDesc_t

- ttXlaTblVerDesc_t

- ttXlaColDesc_t

- tt_LSN_t

- tt_XlaLsn_t

10 TimesTen ODBC関数およびオプション

- サポートされているODBC関数

- ODBCの接続関数および文関数のオプションのサポート

- SQLSetConnectOptionおよびSQLGetConnectOptionのオプションのサポート

- SQLSetStmtOptionおよびSQLGetStmtOptionのオプションのサポート

- SQLGetInfo用の情報型のサポート

- SQLColAttributes用の列記述子のサポート

索引

はじめに

Oracle TimesTen In-Memory Database (TimesTen)は、迅速な応答およびスループット用にメモリーが最適化されたリレーショナル・データベースです。実行時にはデータベース全体がメモリーに常駐し、リカバリおよび再起動できるようにディスク記憶域に保存されます。レプリケーション機能によって、高可用性が実現します。TimesTenでは、OracleインタフェースであるPL/SQL、OCIおよびPro*C/C++に加えて、標準的なアプリケーション・インタフェースであるJDBC、ODBCおよびODP.NETがサポートされます。TimesTenは、単独で使用することもOracle Databaseのキャッシュとして使用することもできます。

このドキュメントでは、TimesTenでのODBC、OCIおよびPro*C/C++のサポートについて説明します。

内容は次のとおりです。

- 対象読者

- 関連ドキュメント

- 表記規則

- ドキュメントのアクセシビリティについて

対象読者

このマニュアルは、ODBC、OCIまたはPro*C/C++を介してTimesTenを使用するアプリケーションを開発またはサポートするユーザーを対象としています。

読者は、使用する特定のプログラミング・インタフェースに加えて、TimesTen、SQL(Structured Query Language)およびデータベース処理を理解している必要があります。

関連ドキュメント

TimesTenのドキュメントは、次のURLのOracle Technology Networkで入手できます。

http://www.oracle.com/technetwork/database/database-technologies/timesten/documentation/index.html

Oracle DatabaseのドキュメントもOracle Technology Networkで入手できます。これは、OCIやPro*C/C++など、TimesTenでサポートされているが、詳しく説明されていないOracle Databaseの機能で役立ちます。

http://www.oracle.com/pls/db112/homepage

特に、次のOracle Databaseドキュメントが役立ちます。

- 『Oracle Call Interfaceプログラマーズ・ガイド』

- 『Pro*C/C++プログラマーズ・ガイド』

- 『Oracle Databaseグローバリゼーション・サポート・ガイド』

- 『Oracle Database Net Services管理者ガイド』

- 『Oracle Database SQL言語リファレンス』

このマニュアルでは、頻繁に詳細情報の参照先としてODBC APIのリファレンス・マニュアルに言及しています。このマニュアルは、Microsoft社など様々なサード・パーティから入手できます。次に例を示します。

http://msdn.microsoft.com/en-us/library/ms714562(VS.85).aspx

TimesTenでは、ODBC 2.5、拡張レベル1がサポートされており、拡張レベル2用の追加機能もありますが、これらの機能については、第10章「TimesTen ODBC関数およびオプション」を参照してください。

表記規則

TimesTenは複数のプラットフォームをサポートしています。このマニュアルに記述されている内容は、特に表記しないかぎり、サポートされるすべてのプラットフォームに適用されます。Windowsは、サポートされているすべてのWindowsプラットフォームを表します。UNIXという用語は、サポートされるすべてのUNIXおよびLinuxプラットフォームを表します。TimesTenでサポートされている具体的なプラットフォームのバージョンについては、『Oracle TimesTen In-Memory Databaseリリース・ノート』のプラットフォームに関する説明を参照してください。

注意:
TimesTenドキュメントでは、用語としての「データ・ストア」と「データベース」は同じです。両方の用語は、TimesTenデータベースを指します。

このマニュアルでは次の表記規則を使用します。

規則

意味

イタリック体

イタリックは、テキストで定義される用語、ドキュメントのタイトルまたは強調を示します。

固定幅フォント

固定幅フォントは、コード、コマンド、URL、ファンクション名、属性名、ディレクトリ名、ファイル名、画面に表示されるテキスト、または入力するテキストを示します。

固定幅フォントのイタリック

固定幅フォントのイタリックは、コード例で特定の値を指定または使用するプレースホルダまたは変数を示します。次に例を示します。
Driver=install_dir/lib/libtten.sl

install_dirをご使用のTimesTenインストール・ディレクトリに置き換えます。

[ ]

大カッコは、カッコ内の項目を任意に選択することを表します。大カッコは、入力しないでください。

{ }

中カッコは、カッコ内の項目のうち、1つが必須であることを表します。中カッコは、入力しないでください。

|

選択項目の引数を区切る縦線(パイプ)。

. . .

引数の後の水平の省略記号は、1行のコマンドラインで複数の引数を使用できることを表します。コード例の中の水平の省略記号は、例の一部だけが表示されていることを示します。

%

%は、UNIXのシェル・プロンプトを表します。

また、TimesTenのドキュメントでは、次の特別な表記規則を使用します。

規則

意味

install_dir

TimesTenがインストールされているディレクトリのパスです。

TTinstance

TimesTenのインストールで指定するインスタンス名です。インストール時に、一意のインスタンス名でTimesTenの各インストールを識別する必要があります。この名前はインストール・パスに表示されます。

bitsまたはbb

32または64の2桁の数字は、32-bitまたは64-bitのオペレーティング・システムを表します。

releaseまたはrr

リリース番号の最初の3つの部分(ドットが付く場合と付かない場合があります)。リリース番号の最初の3つの部分は、TimesTenのメジャー・リリースを表します。例: 1122および11.2.2は、TimesTen 11gリリース2(11.2.2)を表します。

DSN

TimesTenデータソースの名前(TimesTenデータベース用)です。

ドキュメントのアクセシビリティについて

Oracleのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイト(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc)を参照してください。

Oracle Supportへのアクセス

サポートをご契約のお客様には、My Oracle Supportを通して電子支援サービスを提供しています。詳細情報は(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info)か、聴覚に障害のあるお客様は(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs)を参照してください。

新機能

この項では、このマニュアルに記載されているOracle TimesTen In-Memory Database 11gリリース2(11.2.2)の新機能の概要を説明し、詳細情報を参照するためのリンクを示します。

リリース11.2.2.4.0の新機能

- このリリースのドキュメントでは、TimesTenでのODBC SQLGetInfoおよびSQLColAttributes関数のサポートについて説明します。
第10章「TimesTen ODBC関数およびオプション」を参照してください。

リリース11.2.2.2.0の新機能

- SQLCancelのサポートの向上
別のスレッド上の文ハンドルで実行中の操作が取り消されるという以前の制限が削除されました。

ODBC SQLCancel関数に対するTimesTenでのサポートの詳細は、「サポートされているODBC関数」を参照してください。

リリース11.2.2.0.0の新機能

- LOBのサポート
TimesTenではLOB(ラージ・オブジェクト)がサポートされています。これには、CLOB(Character LOB)、NCLOB(National Character LOB)およびBLOB(Binary LOB)が含まれます。

C APIでのサポートの詳細は、「LOBの使用」(一般的なLOBの概要およびODBCに対するサポート)、「TimesTen OCIでのLOB」および「TimesTen Pro*C/C++でのLOB」を参照してください。

- 連想配列バインド
連想配列(以前の索引付き表またはPL/SQL表)は、TimesTen PL/SQLでは、(OCIまたはPro*C/C++アプリケーションなどからの)IN、OUTまたはIN OUTバインド・パラメータとしてサポートされます。(TimesTen ODBCアプリケーションは該当しません。)これにより、アプリケーションとデータベース間で効率的に配列データを渡すことができます。

「TimesTen OCIでの連想配列バインド」および「TimesTen Pro*C/C++での連想配列バインド」を参照してください。

- ODBCのW関数
TimesTenでは、ODBC関数のW(ワイド・キャラクタ)版の一部がサポートされます。たとえば、SQLGetConnectOptionに加え、SQLGetConnectOptionWがサポートされます。

「サポートされているODBC関数」を参照してください。

- 非永続XLAの非推奨
XLA非永続モードの機能は、推奨されないため、ドキュメントから削除されました。永続XLAのユーティリティおよびAPIのみを使用してください。

1 C開発環境

この章では、C開発環境およびTimesTenアプリケーションを開発する際の関連の考慮事項について説明します。内容は次のとおりです。

- 開発用の環境の設定

- リンク・オプション

- アプリケーションのコンパイルおよびリンク

- TimesTen Cのデモについて

開発用の環境の設定

TimesTenの環境変数設定については、『Oracle TimesTen In-Memory Databaseインストレーション・ガイド』の環境変数に関する説明を参照してください。詳細はその説明を参照してください。

注意:

- ttenvスクリプトでは、OCIのプログラミングで必要な、Oracle Instant Clientへのアクセスも構成します。

- オプションで、ttenvのかわりに適切なttquickstartenvスクリプトを使用することもできます。これはttenvのスーパーセットで、TimesTenのクイック・スタート・デモ環境の設定も行います。

- TimesTenで動作するOCIおよびPro*C/C++プログラムが適切に実行されるためには、OCIおよびPro*C/C++コンパイルにORACLE_HOMEを設定しないでください(以前に設定されていた場合は設定解除してください)。

リンク・オプション

TimesTenアプリケーションは、ドライバ・マネージャなしでのTimesTen ODBCの直接ドライバまたはODBCクライアント・ドライバとの明確なリンク、あるいはドライバ・マネージャとのリンクが可能です。

ODBCドライバ・マネージャを使用しないリンク

TimesTenのみを使用するアプリケーションでは、ドライバ・マネージャを使用せずに、TimesTen ODBCの直接ドライバ、またはODBCクライアント・ドライバのいずれかを特定してリンクできます。これによって、ドライバ・マネージャのパフォーマンス・オーバーヘッドが回避され、TimesTenにアクセスする最も簡単な方法です。ただし、ドライバ・マネージャを使用せずにリンクされるアプリケーションを開発する開発者は、次の問題について注意する必要があります。

- アプリケーションは、リンクされているドライバを使用するDSNにのみ接続できます。他のベンダーのデータベースには接続できず、バージョンまたはタイプが異なるTimesTenドライバのTimesTen DSNにも接続できません。

- WindowsのODBCトレースは利用できません。

- ODBCカーソル・ライブラリは利用できません。

- アプリケーションでは、SQLDataSourcesやSQLDriversなどのドライバ・マネージャで通常実行されるODBC関数は使用できません。

- SQLFreeStmt(..., SQL_CLOSE)ではなく、SQLCancelを使用してカーソルをクローズするアプリケーションは、SQL_SUCCESS_WITH_INFOのリターン・コードおよびSQL State 01S05を受信します。この警告は、内部の状態をドライバ・マネージャで管理するために使用されます。アプリケーションでは、この警告は成功として処理されます。

ODBCドライバ・マネージャとのリンク

ドライバ・マネージャとリンクしているアプリケーションは、ODBCドライバを参照するすべてのDSNに接続でき、様々なODBCドライバを使用する複数のDSNに同時に接続することもできます。ただし、Windows以外のほとんどのプラットフォームでは、ドライバ・マネージャはデフォルトで使用可能ではないことに注意してください。また、ドライバ・マネージャを使用すると、すべてのODBC関数コールにかなりの同期オーバーヘッドが追加される可能性があるため、次のような制限があります。

- TimesTenオプションTT_PREFETCH_COUNTは、ドライバ・マネージャにリンクしているアプリケーションでは使用できません。TT_PREFETCH_COUNTオプションの使用に関する詳細は、「複数のデータ行のプリフェッチ」を参照してください。

- アプリケーションでは、TimesTen固有のTT_PREFETCH_CLOSE接続オプションを設定または再設定できません。TT_PREFETCH_CLOSE接続オプションの使用に関する詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のシリアライズ可能なトランザクションに対するTT_PREFETCH_CLOSEの有効化に関する説明を参照してください。

- アプリケーションがドライブ・マネージャとリンクされている場合、トランザクション・ログAPI(XLA)コールは使用できません。

- TimesTenで使用するドライバ・マネージャにリンクされているアプリケーションに対するODBC C型のSQL_C_BIGINT、SQL_C_TINYINTおよびSQL_C_WCHARは、サポートされていません。シグネチャにこれらの型が含まれるメソッドをコールすることはできません。

- ドライバ・マネージャでは、ODBC標準の一部ではないLOBロケータAPIまたはLOBデータ型はサポートされません。ただし、LOBの簡易データ・インタフェースまたはピース単位のデータ・インタフェースは使用できます(「LOBの使用」を参照)。

注意:
TimesTenでは、WindowsおよびUNIX用のどちらのドライバ・マネージャも用意されており、クイック・スタート・サンプル・アプリケーションが付属しています。このドライバ・マネージャは完全にはサポートされていません。TimesTenの直接ドライバおよびクライアント・ドライバのみをサポートしており、前述した機能またはパフォーマンスの制限はありません。TimesTenへの直接接続とクライアント・サーバー接続の両方を同時に使用する必要のあるアプリケーションでは、このドライバ・マネージャを使用することで、パフォーマンスにほとんど影響を与えることなくこの同時使用を実現できます。

アプリケーションのコンパイルおよびリンク

この項では、WindowsまたはUNIXでのCアプリケーションのコンパイルおよびリンクについて説明します。

Windowsでのアプリケーションのコンパイルおよびリンク

WindowsでTimesTenアプリケーションをコンパイルする場合は、ODBC includeファイルの場所を指定する必要はありません。これらのファイルは、Microsoft Visual C++に含まれています。ただし、/Iコンパイラ・オプション設定で、TimesTen includeファイルの場所を指定する必要があります。(「TimesTen includeファイル」を参照してください。)

例1-1のMakeファイルでは、WindowsシステムでTimesTenアプリケーションを構築する方法を示します。この例では、LIB環境変数にinstall_dir\libがすでに追加されたと想定しています。

重要:
他のincludeファイルより前にTimesTenファイルをインクルードし、他のライブラリより前にTimesTenライブラリをリンクしてください。

例1-1 WindowsでのTimesTenアプリケーションの構築

CFLAGS = "/Iinstall_dir\include"
LIBSDM = ODBC32.LIB
LIBS = tten1122.lib ttdv1122.lib
LIBSDEBUG = tten1122d.lib ttdv1122d.lib
LIBSCS = ttclient1122.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)

UNIXでのアプリケーションのコンパイルおよびリンク

UNIXプラットフォームでは、次の処理を行います。

- TimesTenインストール・ディレクトリにあるTimesTenヘッダー・ファイルを使用して、TimesTenアプリケーションをコンパイルします。

- TimesTen ODBCの直接ドライバまたはクライアント・ドライバとリンクしますが、これらは、共有ライブラリとして提供されます。

UNIXでは、SQL_C_ULONG、SQL_C_SLONG、SQL_C_USHORTまたはSQL_C_SSHORTのODBCデータ型を使用するアプリケーションは、コンパイル時にTT_USE_ALL_TYPESプリプロセッサ・オプションを指定する必要があります。通常、これは、Cコンパイラ・オプション-DTT_USE_ALL_TYPESを使用して実行します。

TimesTen機能をしている場合にTimesTen includeファイルを使用するには、次のCコンパイラ・コマンドを追加します。install_dirはTimesTenインストール・ディレクトリのパスです。(「TimesTen includeファイル」を参照してください。)

-Iinstall_dir/include

TimesTen ODBCの直接ドライバとリンクするには、次の指定をリンク・コマンドに追加します。

-Linstall_dir/lib -ltten

-Lオプションを指定すると、リンカーでライブラリ・ファイル用のTimesTen libディレクトリが検索されます。-lttenオプションを指定すると、TimesTen ODBCの直接ドライバでリンクが行われます。

TimesTen ODBCのクライアント・ドライバとリンクするには、次の指定をリンク・コマンドに追加します。

-Linstall_dir/lib -lttclient

Solarisでは、デフォルトのTimesTen ODBCのクライアント・ドライバは、Studio 11を使用してコンパイルされます。このライブラリによって、Sun Studio 11 C/C++コンパイラでコンパイルされたアプリケーションをTimesTenのクライアントに直接リンクできます。

AIXでは、アプリケーションがTimesTen ODBCのクライアント・ドライバとリンクしている場合は、C++ランタイム・ライブラリがリンク・コマンドに含まれている必要があり(クライアント・ドライバはC++で記述されていて、AIXでは自動的にリンクされないため)、クライアント・ドライバに従う必要があります。

-Linstall_dir/lib -lttclient -lC_r

quickstart/sample_codeディレクトリのサブディレクトリでMakeファイルを使用するか、または例1-2を使用して独自のMakeファイルを作成できます。

重要:
他のincludeファイルより前にTimesTenファイルをインクルードし、他のライブラリより前にTimesTenライブラリをリンクしてください。

例1-2 アプリケーションをリンクするMakeファイル

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)

注意:

- アプリケーションをデバッグTimesTen ODBCドライバに直接リンクするには、リンク行に-lttenのかわりに-lttenDを指定します。

- Solarisでは、Sun C/C++コンパイラを使用してコンパイルを実行した場合、-mtオプションを使用してTimesTenアプリケーションのコンパイルおよびリンクを実行する必要があります。

TimesTen Cのデモについて

C環境を構成した後、TimesTenクイック・スタート・デモ・アプリケーションをコンパイルおよび実行して、すべてが正しく設定されていることを確認できます。次のトピックの詳細は、クイック・スタートのようこそページ(install_dir/quickstart.html)で、特にサンプル・プログラムの下のリンクを参照してください。

- デモ・スキーマおよび設定: build_sampledbスクリプト(UNIXでは.sh、Windowsでは.bat)では、サンプル・データベースおよびデモ・スキーマを作成します。デモの使用を開始する前に、これを使用する必要があります。

- デモ環境および設定: 通常、TimesTenの設定に使用するttenvスクリプトのスーパーセットのttquickstartenvスクリプト(UNIXでは.shまたは.csh、Windowsでは.bat)では、デモ環境が設定されます。いずれかのデモをコンパイルおよび実行するセッションに入るたびに、これを使用する必要があります。

- デモおよび設定: TimesTenでは、quickstart/sample_codeディレクトリのサブディレクトリにODBC、XLA、OCI、Pro*C/C++およびODP.NET用のデモが用意されています。デモのコンパイルおよび実行方法については、サブディレクトリのREADMEファイルを参照してください。

- デモの内容: 各デモの内容は、「SAMPLE PROGRAMS」の下のカテゴリをクリックすると表示されます。

2 ODBCでのTimesTenデータベースの使用

この章では、TimesTenプログラミング機能について取り上げ、TimesTenデータベースに接続して使用するためにODBCを使用する方法について説明します。内容は次のとおりです。

- TimesTenデータベース接続の管理

- TimesTenデータの管理

- その他のTimesTenデータ管理機能の使用

- アクセス制御に関するTimesTen機能の考慮事項

- エラーの処理

- アプリケーションでの自動クライアント・フェイルオーバーの使用

TimesTenでは、ODBC 2.5、拡張レベル1がサポートされており、拡張レベル2用の追加機能もありますが、これらの機能については、第10章「TimesTen ODBC関数およびオプション」を参照してください。

注意:

- OCIを使用したCアプリケーションからのTimesTenへのアクセスについては、第3章「TimesTenでのOCIのサポート」を参照してください。

- Pro*C/C++を使用したCアプリケーションからのTimesTenへのアクセスについては、第4章「TimesTenでのPro*C/C++のサポート」を参照してください。

- C++アプリケーションからのTimesTenへのアクセスについては、Oracle TimesTen In-Memory Database TTClassesガイドを参照してください。

- C#アプリケーションからのTimesTenへのアクセスについては、『Oracle Data Provider for .NET Oracle TimesTen In-Memory Databaseサポート・ユーザーズ・ガイド』を参照してください。

TimesTenデータベース接続の管理

データベースにDSNを作成する方法の詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』を参照してください。作成するDSNのタイプは、アプリケーションがデータベースに直接接続するか、クライアント接続するかによって異なります。

データベースに直接接続する場合は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のTimesTenデータベースの管理に関する説明を参照してください。UNIXまたはWindowsから直接接続するためのDSNの作成方法に関する説明があります。

データベースへのクライアント接続を作成する場合は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のTimesTen ClientおよびTimesTen Serverの使用方法に関する説明を参照してください。UNIXまたはWindowsからクライアント/サーバー接続を行うためのDSNの作成方法に関する説明があります。

注意:

- TimesTenでは、ユーザー名およびパスワードは、データベースに接続するためのCREATE SESSION権限を付与されている有効なユーザーのものである必要があります。

- TimesTen接続は、親プロセスから継承することはできません。プロセスが子プロセスを作成(分岐)する前にデータベース接続をオープンした場合、子プロセスではそのデータベース接続を使用しないでください。

この項の以降の内容は次のとおりです。

- SQLConnect、SQLDriverConnect、SQLAllocConnect、SQLDisconnectの各関数

- データベースに対する接続および切断

- プログラムでの接続属性の設定

- デフォルトDSNの使用

- 接続のアクセス制御

SQLConnect、SQLDriverConnect、SQLAllocConnect、SQLDisconnectの各関数

データベースへの接続およびそれに関連する機能の実行には、次のODBC関数を使用できます。

- SQLConnect: ドライバをロードしてデータベースに接続します。接続ハンドルは、ステータス、トランザクションの状態、結果およびエラー情報などの接続情報が格納される場所を指します。

- SQLDriverConnect: SQLConnectでサポートされている情報(データソース(データベース)、ユーザー名およびパスワード)よりも詳細な情報が必要な場合に、SQLConnectのかわりに使用します。

- SQLAllocConnect: 指定した環境内の接続ハンドルにメモリーを割り当てます。

- SQLDisconnect: データベースから切断します。既存の接続ハンドルを唯一の引数として使用します。

これらの関数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。

データベースに対する接続および切断

この項では、データベースに対する接続および切断の例を示します。

例2-1 接続および切断(抜粋)

このコード部分では、SQLConnectおよびSQLDisconnectを起動して、FixedDsというデータベースに対する接続および切断を行います。アプリケーションで初めてSQLConnectを起動すると、データベースFixedDsが作成されます。その後のSQLConnectの起動では、既存のデータベースに接続されます。

#include <sql.h>
SQLRETURN retcode;
SQLHDBC hdbc;

...
retcode = SQLConnect(hdbc,
(SQLCHAR*)"FixedDs", SQL_NTS,
(SQLCHAR*)"johndoe", SQL_NTS,
(SQLCHAR*)"opensesame", SQL_NTS);
...
retcode = SQLDisconnect(hdbc);
...

例2-2 接続および切断(完全なプログラム)

この例には、データベースを作成し、データベースに対して接続および切断を行う完全なプログラムが含まれています。この例では、SQLConnectではなくSQLDriverConnectを使用して接続を設定し、SQLAllocConnectを使用してメモリーを割り当てます。また、エラー・メッセージの取得方法についても示します。(「エラー処理」も参照してください。)

#ifdef WIN32
#include <windows.h>
#else
#include <sqlunix.h>
#endif
#include <sql.h>
#include <sqlext.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

static void chkReturnCode(SQLRETURN rc, SQLHENV henv,
SQLHDBC hdbc, SQLHSTMT hstmt,
char* msg, char* filename,
int lineno, BOOL err_is_fatal);
#define DEFAULT_CONNSTR "DSN=sampledb_1122;PermSize=32"

int
main(int ac, char** av)
{
SQLRETURN rc = SQL_SUCCESS;
/* General return code for the API */
SQLHENV henv = SQL_NULL_HENV;
/* Environment handle */
SQLHDBC hdbc = SQL_NULL_HDBC;
/* Connection handle */
SQLHSTMT hstmt = SQL_NULL_HSTMT;
/* Statement handle */
SQLCHAR connOut[255];
/* Buffer for completed connection string */
SQLSMALLINT connOutLen;
/* Number of bytes returned in ConnOut */
SQLCHAR *connStr = (SQLCHAR*)DEFAULT_CONNSTR;
/* Connection string */
rc = SQLAllocEnv(&henv);
if (rc != SQL_SUCCESS) {
fprintf(stderr, "Unable to allocate an "
"environment handle\n");
exit(1);
}
rc = SQLAllocConnect(henv, &hdbc);
chkReturnCode(rc, henv, SQL_NULL_HDBC,
SQL_NULL_HSTMT,
"Unable to allocate a "
"connection handle\n",
__FILE__, __LINE__, 1);

rc = SQLDriverConnect(hdbc, NULL,
connStr, SQL_NTS,
connOut, sizeof(connOut),
&connOutLen,
SQL_DRIVER_NOPROMPT);
chkReturnCode(rc, henv, hdbc, SQL_NULL_HSTMT,
"Error in connecting to the"
" database\n",
__FILE__, __LINE__, 1);
rc = SQLAllocStmt(hdbc, &hstmt);
chkReturnCode(rc, henv, hdbc, SQL_NULL_HSTMT,
"Unable to allocate a "
"statement handle\n",
__FILE__, __LINE__, 1);

/* Your application code here */

if (hstmt != SQL_NULL_HSTMT) {
rc = SQLFreeStmt(hstmt, SQL_DROP);
chkReturnCode(rc, henv, hdbc, hstmt,
"Unable to free the "
"statement handle\n",
__FILE__, __LINE__, 0);
}

rc = SQLDisconnect(hdbc);
chkReturnCode(rc, henv, hdbc,
SQL_NULL_HSTMT,
"Unable to close the "
"connection\n",
__FILE__, __LINE__, 0);

rc = SQLFreeConnect(hdbc);
chkReturnCode(rc, henv, hdbc,
SQL_NULL_HSTMT,
"Unable to free the "
"connection handle\n",
__FILE__, __LINE__, 0);

rc = SQLFreeEnv(henv);
chkReturnCode(rc, henv, SQL_NULL_HDBC,
SQL_NULL_HSTMT,
"Unable to free the "
"environment handle\n",
__FILE__, __LINE__, 0);
return 0;
}

static void
chkReturnCode(SQLRETURN rc, SQLHENV henv,
SQLHDBC hdbc, SQLHSTMT hstmt,
char* msg, char* filename,
int lineno, BOOL err_is_fatal)
{
#define MSG_LNG 512
SQLCHAR sqlState[MSG_LNG];
/* SQL state string */
SQLINTEGER nativeErr;
/* Native error code */
SQLCHAR errMsg[MSG_LNG];
/* Error msg text buffer pointer */
SQLSMALLINT errMsgLen;
/* Error msg text Available bytes */
SQLRETURN ret = SQL_SUCCESS;
if (rc != SQL_SUCCESS &&
rc != SQL_NO_DATA_FOUND ) {
if (rc != SQL_SUCCESS_WITH_INFO) {
/*
* It's not just a warning
*/
fprintf(stderr, "*** ERROR in %s, line %d:"
" %s\n",
filename, lineno, msg);
}
/*
* Now see why the error/warning occurred
*/
while (ret == SQL_SUCCESS ||
ret == SQL_SUCCESS_WITH_INFO) {
ret = SQLError(henv, hdbc, hstmt,
sqlState, &nativeErr,
errMsg, MSG_LNG,
&errMsgLen);
switch (ret) {
case SQL_SUCCESS:
fprintf(stderr, "*** %s\n"
"*** ODBC Error/Warning = %s, "
"TimesTen Error/Warning "
" = %d\n",
errMsg, sqlState,
nativeErr);
break;
case SQL_SUCCESS_WITH_INFO:
fprintf(stderr, "*** Call to SQLError"
" failed with return code of "
"SQL_SUCCESS_WITH_INFO.\n "
"*** Need to increase size of"
" message buffer.\n");
break;
case SQL_INVALID_HANDLE:
fprintf(stderr, "*** Call to SQLError"
" failed with return code of "
"SQL_INVALID_HANDLE.\n");
break;
case SQL_ERROR:
fprintf(stderr, "*** Call to SQLError"
" failed with return code of "
"SQL_ERROR.\n");
break;
case SQL_NO_DATA_FOUND:
break;
} /* switch */
} /* while */
if (rc != SQL_SUCCESS_WITH_INFO && err_is_fatal) {
fprintf(stderr, "Exiting.\n");
exit(-1);
}
}
}

プログラムでの接続属性の設定

データベースへの接続時に接続文字列を指定して、プログラムで接続属性を設定または上書きできます。

接続属性の全般的な詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』を参照してください。一般接続属性には、特に権限は必要ありません。データベースが初めてロードされたときに最初の接続属性が設定され、すべての接続に持続的に使用されます。最初の接続属性の設定を変更してデータベースをロードできるのは、インスタンス管理者のみです。特定の接続属性に関する固有の情報を含む詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』の接続属性に関する説明を参照してください。

例2-3 接続およびストア・レベル・ロックの使用

このコード部分では、mydsnというデータベースに接続して、SQLDriverConnectコールで、アプリケーションがパススルー設定の3を使用することを示します。PassThroughは一般接続属性であることに注意してください。

SQLHDBC hdbc;
SQLCHAR ConnStrOut[512];
SQLSMALLINT cbConnStrOut;
SQLRETURN rc;

rc = SQLDriverConnect(hdbc, NULL,
"DSN=mydsn;PassThrough=3", SQL_NTS,
ConnStrOut, sizeof (ConnStrOut),
&cbConnStrOut, SQL_DRIVER_NOPROMPT);

注意:
データベースへの接続ごとに、いくつかのファイルがオープンします。多数のスレッドを使用し、スレッドごとに別々の接続を使用するアプリケーションでは、各スレッドに対して複数のファイルがオープンします。このようなアプリケーションでは、オペレーティング・システムで同時にオープンできるファイル記述子の許可された最大数(構成されている最大値)を超える可能性があります。この場合は、多数のオープン・ファイルを許可するようシステムを設定します。『Oracle TimesTen In-Memory Databaseリファレンス』のオープン・ファイルの数の制限に関する項を参照してください。

デフォルトDSNの使用

defaultという名前が付けられているデフォルトDSNは、odbc.iniファイルまたはsys.odbc.iniファイルで定義できます。デフォルトDSNの定義の詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のデフォルトDSNの設定に関する説明を参照してください。

SQLConnectまたはSQLDriverConnectがコールされた場合、次のような状況で関連するデータ・ソースが接続されます。

SQLConnectでは、デフォルトDSNが定義済の場合、ServerNameが検出できないデータソースを指定する場合、nullポインタを指定する場合、または明示的にdefaultの値に設定される場合に使用されます。参考に、SQLConnectコール・シーケンスを示します。

SQLRETURN SQLConnect(
SQLHDBC        ConnectionHandle,
SQLCHAR *      ServerName,
SQLSMALLINT    NameLength1,
SQLCHAR *      UserName,
SQLSMALLINT    NameLength2,
SQLCHAR *      Authentication,
SQLSMALLINT    NameLength3);

サーバー名としてdefaultを使用します。ユーザー名と認証値はそのまま使用します。

SQLDriverConnectでは、デフォルトDSNが定義済の場合、接続文字列にDSNキーワードが含まれない場合、またはデータソースが検出されない場合に使用されます。参考に、SQLDriverConnectコール・シーケンスを示します。

SQLRETURN SQLDriverConnect(
SQLHDBC         ConnectionHandle,
SQLHWND         WindowHandle,
SQLCHAR *       InConnectionString,
SQLSMALLINT     StringLength1,
SQLCHAR *       OutConnectionString,
SQLSMALLINT     BufferLength,
SQLSMALLINT *   StringLength2Ptr,
SQLUSMALLINT    DriverCompletion);

DSNキーワードとしてdefaultを使用します。ユーザー名とパスワードはそのまま使用します。

直接モードまたはドライバ・マネージャを備えたクライアント/サーバー・モードの場合、次のことに注意してください。

- ドライバ・マネージャを使用していない場合、TimesTenがこの機能を管理します。デフォルトDSNは、TimesTenデータベースである必要があります。

- ドライバ・マネージャを使用している場合、ドライバ・マネージャがこの機能を管理します。デフォルトDSNは、TimesTenデータベースである必要はありません。

接続のアクセス制御

任意のユーザー(インスタンス管理者以外)がデータベースに接続するには、CREATE SESSION権限を付与する必要があります。これはシステム権限であるため、インスタンス管理者、またはADMIN権限を持っただれかによって直接またはPUBLICロールを通してユーザーに付与する必要があります。例および詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のアクセス制御の管理に関する項を参照してください。

XLA接続を作成してXLA機能を実行するには、ユーザーにCREATE SESSIONだけでなく、XLA権限が付与されている必要があります(「アクセス制御がXLAに与える影響」を参照)。

TimesTenデータの管理

この項では、TimesTenデータベースのデータの処理について説明します。内容は次のとおりです。

- TimesTen includeファイル

- Cアプリケーション内でのSQL文の実行

- 問合せの準備および実行とカーソルの使用

- TimesTenの遅延準備

- 複数のデータ行のプリフェッチ

- パラメータのバインドおよび文の実行

- REF CURSORの使用

- DML RETURNING(RETURNING INTO句)の使用

- ROWIDの使用

- LOBの使用

- データベースに対する変更の実行とコミット

TimesTen includeファイル

TimesTenの機能を使用するには、次の表に示すTimesTenファイルをアプリケーションにインクルードする必要があります。

インクルード・ファイル

説明

timesten.h

TimesTenのODBC機能

tt_errCode.h

TimesTenのエラー・コード
このファイルは、TimesTenエラー・コードを定義済の定数マップします。

注意:
標準ODBCのsql.hファイルは、timesten.hの一部としてインクルードされます。標準のODBC機能のみを使用している場合:

- UNIXシステムでは、TimesTenのsql.hのコピーをインクルードするために、timesten.hをインクルードすることをお薦めします。

- Windowsシステムでは、sql.hのシステム・コピーを使用することをお薦めします。

インクルードされるファイルにアクセスするには、適切なインクルード・パスを設定します。関連情報については、「アプリケーションのコンパイルおよびリンク」を参照してください。

Cアプリケーション内でのSQL文の実行

SQLを使用してデータを管理する方法については、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のTimesTenデータベースのデータの処理に関する説明を参照してください。この項では、Cアプリケーション内でSQL文を実行するために使用される一般的な書式について説明します。内容は次のとおりです。

- SQLExecDirect関数およびSQLExecute関数

- SQL文の実行

注意:
アクセス制御の権限は、データベースでSQLが準備されるときと実行されるときの両方で確認されます。関連する情報は、「アクセス制御に関するTimesTen機能の考慮事項」を参照してください。

SQLExecDirect関数およびSQLExecute関数

SQL文を実行するODBC関数は次の2つです。

- SQLExecute: SQLPrepareで準備されている文を実行します。実行結果を使用してアプリケーションが実行された後、その結果を破棄して、別のパラメータ値でSQLExecuteを再実行することができます。
通常、バインド・パラメータを使用するDML文または複数回実行される文に使用します。

- SQLExecDirect: 文を準備して実行します。
通常、DDL文、または数回のみ実行される、バインド・パラメータを使用しないDML文に使用します。

これらの関数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。

SQL文の実行

SQLExecDirect関数は、例2-4に示すように使用できます。

SQLExecute関数とSQLPrepare関数の使用方法は、次の項「問合せの準備および実行とカーソルの使用」に示します。

例2-4 SQLExecDirectを使用したSQL文の実行

次のコード例では、CustIDおよびCustNameという2つの列を持つ、NameIDという表を作成します。この表では、名前(文字)が識別子(整数)にマップされます。

#include <sql.h>
SQLRETURN rc;
SQLHSTMT hstmt;
...
rc = SQLExecDirect(hstmt, (SQLCHAR*)
"CREATE TABLE NameID (CustID INTEGER, CustName VARCHAR(50))",
SQL_NTS);
if (rc != SQL_SUCCESS && rc != SQL_SUCCESS_WITH_INFO)
... /* handle error */

問合せの準備および実行とカーソルの使用

この項では、問合せの準備および実行とカーソル使用の基本的な手順を示します。アプリケーションでは、カーソルを使用して問合せの結果がスクロールされ、一度に1つの結果行が確認されます。

重要:
TimesTenでは、コミットやロールバックなど、トランザクションを終了する操作は、接続と関連付けられているすべてのカーソルをクローズします。

ODBC設定では、カーソルは常に結果セットに関連付けられています。この関連付けはODBCドライバによって行われます。アプリケーションでは、「SQLSetStmtOptionおよびSQLGetStmtOptionのオプションのサポート」で説明されているSQLSetStmtOptionオプションを使用して、一度にフェッチする行数などのカーソル特性を制御できます。問合せを実行する場合の手順は、通常は次のとおりです。

1. SQLPrepareを使用して、SELECT文を実行するための準備をします。

2. SQLBindParameter(文にパラメータが含まれている場合)を使用して、各パラメータをアプリケーション・アドレスにバインドします。「SQLBindParameter関数」を参照してください。(次の例2-5ではパラメータをバインドしていません。)

3. SQLBindColをコールして結果の列に記憶域およびデータ型を割り当て、列の結果をアプリケーション内のローカル変数記憶域にバインドします。

4. SQLExecuteをコールして、SELECT文を実行します。「SQLExecDirect関数およびSQLExecute関数」を参照してください。

5. SQLFetchをコールして結果をフェッチします。文ハンドルを指定します。

6. SQLFreeStmtをコールして文ハンドルを解放します。文ハンドルおよびSQL_CLOSE、SQL_DROP、SQL_UNBINDまたはSQL_RESET_PARAMSのいずれかを指定します。

これらのODBC関数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。例は、この章およびTimesTenクイック・スタート全体で表示されます(「SAMPLE PROGRAMS」の下の「ODBC (C)」リンク)。

注意:

- アクセス制御の権限は、データベースでSQLが準備されるときと実行されるときの両方で確認されます。関連する情報は、「アクセス制御に関するTimesTen機能の考慮事項」を参照してください。

- デフォルトでは(接続属性がPrivateCommands=0のとき)、TimesTenは接続間で準備済の文を共有するため、共有以降は複数の接続で同じ文の準備が迅速に実行されます。

例2-5 問合せの実行およびカーソルの使用

この例では、ODBCコールを使用して問合せを準備および実行する方法を示します。わかりやすくするために、エラーのチェックは省略してあります。前述のODBC関数以外に、この例では、SQLNumResultColsを使用して結果セット内の列数を返し、SQLDescribeColを使用して結果セットの1つの列の記述(列名、型、精度、スケールおよびNULL値可能)を返し、SQLBindColを使用して記憶域およびデータ型を結果セット内の列に割り当てます。これらすべての関数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。

#include <sql.h>

SQLHSTMT hstmt;
SQLRETURN rc;
int i;
SQLSMALLINT numCols;
SQLCHAR colname[32];
SQLSMALLINT colnamelen, coltype, scale, nullable;
SQLULEN collen [MAXCOLS];
SQLLEN outlen [MAXCOLS];
SQLCHAR* data [MAXCOLS];

/* other declarations and program set-up here */

/* Prepare the SELECT statement */
rc = SQLPrepare(hstmt,
(SQLCHAR*) "SELECT * FROM EMP WHERE AGE>20",
SQL_NTS);
/* ... */

/* Determine number of columns in result rows */
rc = SQLNumResultCols(hstmt, &numCols);

/* ... */

/* Describe and bind the columns */
for (i = 0; i < numCols; i++) {
rc = SQLDescribeCol(hstmt,
(SQLSMALLINT) (i + 1),
colname,(SQLSMALLINT)sizeof(colname), &colnamelen, &coltype, &collen[i],
&scale, &nullable);

/* ... */

data[i] = (SQLCHAR*) malloc (collen[i] +1);  //Allocate space for column data.
rc = SQLBindCol(hstmt, (SQLSMALLINT) (i + 1),
SQL_C_CHAR, data[i],
COL_LEN_MAX, &outlen[i]);

/* ... */

}
/* Execute the SELECT statement */
rc = SQLExecute(hstmt);

/* ... */

/* Fetch the rows */
if (numCols > 0) {
while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS ||
rc == SQL_SUCCESS_WITH_INFO) {
/* ... "Process" the result row */
} /* end of for-loop */
if (rc != SQL_NO_DATA_FOUND)
fprintf(stderr,
"Unable to fetch the next row\n");

/* Close the cursor associated with the SELECT statement */
rc = SQLFreeStmt(hstmt, SQL_CLOSE);
}

TimesTenの遅延準備

標準のODBCでは、結果セットの列記述のような文に関する情報をアプリケーションで使用可能にしたり、これらの情報にSQLDescribeColなどのコールでアクセスできるように、SQLPrepareコールはSQL文をコンパイルします。この機能を実現するには、SQLPrepareコールをサーバーに送信して処理する必要があります。

このことは、たとえば、Oracle Call Interface(OCI)で期待される動作とは対照的で、OCIでは、準備コールは単にパラメータの名前と位置を抽出するための、クライアントで実行される軽量処理であることが期待されています。

クライアントとサーバー間の不要なラウンドトリップを回避し、OCIが期待する動作との一貫性を実現するために、TimesTenクライアント・ライブラリに実装されたSQLPrepareでは、遅延準備と呼ばれる処理が実行され、リクエストは要求されるまでサーバーに送信されません。ラウンドトリップが必要になる場合の例を、次に示します。

- SQLExecuteコールがある場合。まだサーバーに送信されていない遅延準備コールがある場合、クライアント上のSQLExecuteコールはSQLExecDirectコールに変換されることに注意してください。

- SQLエンジンからのみ取得可能な、問合せに関する情報のリクエストがある場合(SQLDescribeColコールがある場合など)。標準のODBCのこのようなコールの多くは、以前にSQLPrepareコールで返された情報にアクセスできますが、遅延準備機能を使用している場合は、SQLPrepareコールがサーバーに送信され、情報は必要な場合にのみアプリケーションに返されます。

注意:
遅延準備機能はTimesTenの直接ドライバでは実装されていません(必須ではありません)。

遅延準備の実装には、アプリケーションまたはユーザー・レベルの変更は必要ありません。ただし、次の関数のいずれかをコールすると、以前に準備された文で必要とされた情報がまだ取得されていなかった場合には、サーバーに対するラウンドトリップが発生する可能性があります。

- SQLColAttributes

- SQLDescribeCol

- SQLDescribeParam

- SQLNumResultCols

- SQLNumParams

- SQLGetStmtOption(SQLエンジンでコンパイルされている文に依存するオプションの場合)

また、これらの関数のいずれかをコールすると、以前のSQLPrepareコールのエラーが、これらのコールの1つが実行されるまで遅延される場合があることに注意してください。また、これらのコールで、コール自体に固有のエラーの他に、SQLPrepareに固有のエラーも返される場合があります。

複数のデータ行のプリフェッチ

TimesTenによるODBCの拡張によって、アプリケーションはODBCドライバのバッファに複数のデータ行をプリフェッチできます。これにより、クライアント/サーバー・アプリケーションのパフォーマンスを向上させることができます。

TT_PREFETCH_COUNT文オプションによって、1回のSQLFetchコールでプリフェッチする行数が決定されます。このオプションは、TimesTenに直接接続するアプリケーションには何もメリットがないことに注意してください。

コールのTT_PREFETCH_COUNTは、SQLSetStmtOptionまたはSQLSetConnectOptionに設定できます(接続に関連付けられる文すべてのデフォルト値をオプションで設定します)。値には0(ゼロ)から128までの任意の整数を設定できます。次に、その例を示します。

rc = SQLSetConnectOption(hdbc, TT_PREFETCH_COUNT, 100);

この設定を使用すると、接続時の最初のSQLFetchコールで100行がプリフェッチされます。後続のSQLFetchコールは、ODBCバッファが使い果たされるまで、データベースのかわりにODBCバッファからフェッチします。ODBCバッファが使い果たされると、次のSQLFetchコールでは別の100行がバッファにフェッチされます。

プリフェッチを無効にするには、TT_PREFETCH_COUNTを1に設定します。

プリフェッチ数を0(ゼロ)に設定すると、TimesTenはデータベースに設定した分離レベルに応じてデフォルトのプリフェッチ数を使用し、プリフェッチ数をTT_PREFETCH_COUNT値に設定します。コミット読取り分離レベルでは、デフォルトのプリフェッチの値は5です。シリアライズ可能分離レベルでは、デフォルトは128です。デフォルトのプリフェッチの値はほとんどのアプリケーションに最適な設定です。一般的に、値を高く設定すると、リソースの使用量がわずかに増加しますが、大きい結果セットに対するパフォーマンスは向上する可能性があります。

「SQLSetStmtOptionおよびSQLGetStmtOptionのオプションのサポート」も参照してください。

パラメータのバインドおよび文の実行

この項では、SQL文の入力または出力パラメータをバインドする方法について説明します。内容は次のとおりです。

- SQLBindParameter関数

- パラメータのデータ型の割当ての決定および変換

- 入力パラメータのバインド

- 出力パラメータのバインド

- 入力/出力パラメータのバインド

- SQL文での重複したパラメータのバインド

- PL/SQLでの重複したパラメータのバインド

- 浮動小数点データに関する考慮事項

- ドライバ・マネージャを使用したSQL_WCHARおよびSQL_WVARCHARの使用

注意:
TimesTen開発者ガイドで使用される「バインド・パラメータ」という用語(ODBC用語に準拠)は、TimesTenのPL/SQLのマニュアルで使用される「バインド変数」という用語(Oracle Database PL/SQL用語に準拠)と同じです。

SQLBindParameter関数

ODBCのSQLBindParameter関数を使用して、SQL文のパラメータをバインドします。これには、入力、出力または入力/出力パラメータを含むことができます。

ODBCを介して入力パラメータをバインドするには、fParamType引数にSQL_PARAM_INPUTを設定してSQLBindParameter関数を使用します。SQLBindParameter関数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。表2-1に、この引数の簡単な概要を示します。

ODBCを介して出力または入力/出力パラメータをバインドするには、fParamType引数にSQL_PARAM_OUTPUTまたはSQL_PARAM_INPUT_OUTPUTをそれぞれ設定してSQLBindParameter関数を使用します。入力パラメータと同様に、fSqlType引数、cbColDef引数およびibScale引数を(必要に応じて)使用して、データ型を指定します。

表2-1 SQLBindParameterの引数

引数

型

説明

hstmt

SQLHSTMT

文ハンドル

ipar

SQLUSMALLINT

左から右へ順に、1から始まるパラメータ番号

fParamType

SQLSMALLINT

入力または出力を示す、SQL_PARAM_INPUT、SQL_PARAM_OUTPUTまたはSQL_PARAM_INPUT_OUTPUT

fCType

SQLSMALLINT

パラメータのCデータ型

fSqlType

SQLSMALLINT

パラメータのSQLデータ型

cbColDef

SQLULEN

バイナリ・データに対する最大バイト数、数値に対する最大桁数、文字データに対する最大文字数などのパラメータの精度

ibScale

SQLSMALLINT

該当する場合に、小数点より右の最大桁数を参照する、パラメータのスケール

rgbValue

SQLPOINTER

パラメータのデータに使用するバッファへのポインタ

cbValueMax

SQLLEN

rgbValueバッファの最大長(バイト)

pcbValue

SQLLEN*

パラメータの長さに使用するバッファへのポインタ

注意:
TimesTenのデータ型の精度およびスケールの詳細は、『Oracle TimesTen In-Memory Database SQLリファレンス』のデータ型に関する説明を参照してください。

パラメータのデータ型の割当ておよび変換

バインド・パラメータのデータ型の割当ては、次のように決定されます。

- TimesTenで実行される文のパラメータのデータ型の割当ては、TimesTenが決定します。具体的には、次のようになります。

- TimesTen内で実行されるSQL文の場合、TimesTenの問合せオプティマイザがSQLパラメータのデータ型を決定します。

- Oracle Databaseで実行されるか、Oracle Databaseの機能に基づいた文に対するパラメータのデータ型の割当ては、次のようにアプリケーションが決定します。

- Oracle Database内で実行されるSQL文(TimesTen Application-Tier Database Cache (TimesTen Cache)からのパススルー文)の場合は、アプリケーションは、ODBC SQLBindParameter関数にコールする際に、その関数のfSqlType、cbColDefおよびibScale引数に基づいて(該当する場合)、データ型を指定する必要があります。

- TimesTen内で実行されるPL/SQLブロックまたはプロシージャで、PL/SQL実行エンジンにOracle Databaseと同じ基本的な機能がある場合は、アプリケーションは、SQLBindParameterに対するコールでデータ型を指定する必要があります(Oracle Database内で実行されるSQL文の場合と同様)。
そのため、PL/SQLのホスト・バインド(PL/SQLブロック内でコロンより前にある変数やパラメータ)については、fSqlTypeおよび該当するその他の引数に従って、PL/SQLブロック内ではなく、SQLBindParameterへのコールでホスト・バインドのデータ型が事実上宣言されることに注意してください。

ODBCドライバは、C値とSQLまたはPL/SQLのデータ型間で必要な型の変換を行います。サポートされていないCとSQLやCとPL/SQLの組合せでは、エラーが発生します。それらは、C型からSQL型またはPL/SQL型(入力パラメータ)、SQL型またはPL/SQL型からC型(出力パラメータ)または両方(入力/出力パラメータ)の変換の場合です。

注意:
TimesTenのバインド・メカニズム(アーリー・バインディング)はOracle Databaseのバインド・メカニズム(レイト・バインディング)とは異なります。TimesTenは、問合せの準備の前にデータ型を必要とします。そのため、各バインド・パラメータのデータ型が指定されていないかSQL文から推測できないと、エラーが発生します。たとえば次のような文が、これに該当します。

SELECT 'x' FROM DUAL WHERE ? = ?;

この問題には、たとえば次のように対処できます。

SELECT 'x' from DUAL WHERE CAST(? as VARCHAR2(10)) =
CAST(? as VARCHAR2(10));

表2-2に、ODBCデータ型とSQL型またはPL/SQLデータ型とのマッピングを示します。

表2-2 ODBC SQLとTimesTen SQLまたはPL/SQLとのデータ型のマッピング

ODBCデータ型(fSqlType)

SQLまたはPL/SQLのデータ型

SQL_BIGINT

NUMBER

SQL_BINARY

RAW(p)

SQL_BIT

PLS_INTEGER

SQL_CHAR

CHAR(p)

SQL_DATE

DATE

SQL_DECIMAL

NUMBER

SQL_DOUBLE

NUMBER

SQL_FLOAT

BINARY_DOUBLE

SQL_INTEGER

PLS_INTEGER

SQL_NUMERIC

NUMBER

SQL_REAL

BINARY_FLOAT

SQL_REFCURSOR

REF CURSOR

SQL_ROWID

ROWID

SQL_SMALLINT

PLS_INTEGER

SQL_TIMESTAMP

TIMESTAMP(s)

SQL_TINYINT

PLS_INTEGER

SQL_VARBINARY

RAW(p)

SQL_VARCHAR

VARCHAR2(p)

SQL_WCHAR

NCHAR(p)

SQL_WVARCHAR

NVARCHAR2(p)

注意:

- (p)という表記は、精度がSQLBindParameterの引数cbColDefに従うことを示します。

- (s)という表記は、スケールがSQLBindParameterの引数ibScaleに従うことを示します。

- ほとんどのアプリケーションでは、文字データのバインドにSQL_CHARではなくSQL_VARCHARを使用してください。SQL_CHARを使用すると、パラメータ・タイプの完全な精度に不要な空白文字が含まれる可能性があります。

入力パラメータのバインド

TimesTenのPL/SQLに対する入力パラメータでは、ODBCのSQLBindParameter関数のfSqlType引数、cbColDef引数およびibScale引数を(必要に応じて)使用して、データ型を指定します。これは、「パラメータのデータ型の割当ての決定および変換」の記載されている、SQL入力パラメータのサポート方法とは異なります。

また、SQLBindParameterのrgbValue引数、cbValueMax引数およびpcbValue引数も、入力パラメータでは次のように使用します。

- rgbValue: 文を実行する前に、アプリケーションは、アプリケーションに渡されるパラメータ値を格納するバッファを指します。

- cbValueMax: 文字データおよびバイナリ・データの場合、rgbValueが指す入力値の最大長(バイト)を示します。他のすべてのデータ型の場合、cbValueMaxは無視され、rgbValueが指す値の長さはSQLBindParameterのfCType引数に指定したCデータ型の長さで決定されます。

- pcbValue: 文を実行する前に、次のいずれかを含むバッファを指します。

- rgbValueが指す値の実際の長さ
注意: 入力パラメータの場合、文字データまたはバイナリ・データにのみ有効です。

- 空文字で終了する文字列の場合は、SQL_NTS

- NULL値の場合は、SQL_NULL_DATA

出力パラメータのバインド

TimesTenのPL/SQLからの出力パラメータでは、前述の入力パラメータに記載したとおり、ODBCのSQLBindParameter関数のfSqlType引数、cbColDef引数およびibScale引数を(必要に応じて)使用して、データ型を指定します。

また、SQLBindParameterのrgbValue引数、cbValueMax引数およびpcbValue引数も、出力パラメータでは次のように使用します。

- rgbValue: 文の実行中に、文から返された値を格納するバッファを指します。

- cbValueMax: 文字データおよびバイナリ・データの場合、rgbValueが指す出力値の最大長(バイト)を示します。他のすべてのデータ型の場合、cbValueMaxは無視され、rgbValueが指す値の長さはSQLBindParameterのfCType引数に指定したCデータ型の長さで決定されます。
ODBCでは、データが切り捨てられる場合でも、すべての文字データが空文字で終了することに注意してください。そのため、出力パラメータに文字データが含まれる場合、cbValueMaxはデータの最長値+空文字を保持できる十分な大きさである必要があります(CHARおよびVARCHARパラメータでは1バイト大きい値、またはNCHARおよびNVARCHARパラメータでは2バイト大きい値)。

- pcbValue: 文を実行した後に、次のいずれかを含むバッファを指します。

- rgbValueが指す値の実際の長さ(文字データおよびバイナリ・データのみでなく、すべてのCデータ型が対象)
注意: rgbValueが指すバッファに値が収まるかどうかに関係なく、完全なパラメータ値の長さです。

- NULL値の場合は、SQL_NULL_DATA

例2-6 出力パラメータのバインド

この例では、PL/SQLの無名ブロックを準備、バインドおよび実行する方法を示します。無名ブロックでは、値abcdeをバインド・パラメータaに、値123をバインド・パラメータbに割り当てます。

SQLPrepareは無名ブロックを準備します。SQLBindParameterは、最初のパラメータ(a)をデータ型SQL_VARCHARの出力パラメータとしてバインドし、2番目のパラメータ(b)をデータ型SQL_INTEGERの出力パラメータとしてバインドします。SQLExecuteは無名ブロックを実行します。

{
SQLHSTMT      hstmt;
char          aval[11];
SQLLEN        aval_len;
SQLINTEGER    bval;
SQLLEN        bval_len;

SQLAllocStmt(hdbc, &hstmt);

SQLPrepare(hstmt,
(SQLCHAR*)"begin :a := 'abcde'; :b := 123; end;",
SQL_NTS);

SQLBindParameter(hstmt, 1, SQL_PARAM_OUTPUT, SQL_C_CHAR, SQL_VARCHAR,
10, 0, (SQLPOINTER)aval, sizeof(aval), &aval_len);

SQLBindParameter(hstmt, 2, SQL_PARAM_OUTPUT, SQL_C_SLONG, SQL_INTEGER,
0, 0, (SQLPOINTER)&bval, sizeof(bval), &bval_len);

SQLExecute(hstmt);
printf("aval = [%s] (length = %d), bval = %d\n", aval, (int)aval_len, bval);
}

入力/出力パラメータのバインド

TimesTenのPL/SQLに対する入力/出力パラメータでは、前述の入力パラメータに記載したとおり、ODBCのSQLBindParameter関数のfSqlType引数、cbColDef引数およびibScale引数を(必要に応じて)使用して、データ型を指定します。

また、SQLBindParameterのrgbValue引数、cbValueMax引数およびpcbValue引数も、入力/出力パラメータでは次のように使用します。

- rgbValue: 最初に、「入力パラメータのバインド」で説明したとおり、文を実行する前に使用します。次に、前の項「出力パラメータのバインド」で説明したとおり、文の実行中に使用します。入力/出力パラメータの場合、文の実行で出力された値は、アプリケーションによって上書きされないかぎり、直後に続く文の実行に対する入力値になります。また、実行時データの使用中にバインドされる入力/出力値の場合、rgbValueの値は、ODBCのSQLParamData関数で返されるトークンおよび出力値が格納されるバッファへのポインタの両方として機能します。

- cbValueMax: 文字データおよびバイナリ・データの場合、最初に、「入力パラメータのバインド」で説明したとおりに使用します。次に、前の項「出力パラメータのバインド」で説明したとおりに使用します。他のすべてのデータ型の場合、cbValueMaxは無視され、rgbValueが指す値の長さはSQLBindParameterのfCType引数に指定したCデータ型の長さで決定されます。
ODBCでは、データが切り捨てられる場合でも、すべての文字データが空文字で終了することに注意してください。そのため、出力/出力パラメータに文字データが含まれる場合、cbValueMaxはデータの最長値+空文字を保持できる十分な大きさである必要があります(CHARおよびVARCHARパラメータでは1バイト大きい値、またはNCHARおよびNVARCHARパラメータでは2バイト大きい値)。

- pcbValue: 最初に、「入力パラメータのバインド」で説明したとおり、文を実行する前に使用します。次に、前の項「出力パラメータのバインド」で説明したとおり、文の実行後に使用します。

重要:
文字データおよびバイナリ・データの場合、cbValueMaxに使用する値を慎重に検討してください。実際のバッファ・サイズよりも小さい値を使用すると、誤った切捨て警告が発生します。実際のバッファ・サイズよりも大きい値を使用すると、ODBCドライバによってrgbValueバッファが上書きされ、メモリーが破損することがあります。

SQL文での重複したパラメータのバインド

TimesTenでは、SQL文で重複したパラメータをバインドするための2つの異なるモードがサポートされます。(PL/SQL文については、「PL/SQLでの重複したパラメータのバインド」を参照してください。)

- Oracleモード: 同じパラメータ名の複数の出現は異なるパラメータとみなされます。

- 従来のTimesTenモード: 以前のリリースと同様に、同じパラメータ名の複数の出現は同じパラメータとみなされます。

DuplicateBindMode TimesTen一般接続属性を使用すると、目的のモードを選択できます。DuplicateBindMode=0(デフォルト)はOracleモードで、DuplicateBindMode=1はTimesTenモードです。この属性は一般接続属性であるため、同じデータベースに対する複数の接続でそれぞれ異なる値を使用できます。この属性の詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のDuplicateBindModeに関する項を参照してください。

この項の後半では、次の問合せを検討しながら各モードの詳細を説明します。

SELECT * FROM employees
WHERE employee_id < :a AND manager_id > :a AND salary < :b;

注意:

- この説明は、PL/SQL経由などではなく、ODBCから直接発行されるSQL文にのみ当てはまります。

- パラメータでの?の使用はOracle Databaseではサポートされていませんが、TimesTenではどちらのモードでもサポートされます。

重複したパラメータのOracleモード

Oracleモード(DuplicateBindMode=0)では、1つのSQL文に含まれる同じパラメータ名の複数の出現は異なるパラメータとみなされます。パラメータの位置番号が割り当てられるとき、名前の重複に関係なく、パラメータの出現ごとに番号が与えられます。アプリケーションは、少なくとも各パラメータ名の最初の出現時に値をバインドする必要があります。特定のパラメータ名の2回目以降の出現に関して、アプリケーションでは次の選択肢があります。

- 出現ごとに異なる値をバインドします。

- 出現したパラメータをバインドしないでおきます。この場合には、最初の出現時と同じ値が使用されます。

いずれの場合も、出現ごとに異なるパラメータ位置番号が付けられます。

前述のSQL文のaの2回目の出現に対して異なる値を使用するには、次のように指定します。

SQLBindParameter(..., 1, ...); /* first occurrence of :a */
SQLBindParameter(..., 2, ...); /* second occurrence of :a */
SQLBindParameter(..., 3, ...); /* occurrence of :b */

aの両方の出現に対して同じ値を使用するには、次のように指定します。

SQLBindParameter(..., 1, ...); /* both occurrences of :a */
SQLBindParameter(..., 3, ...); /* occurrence of :b */

いずれの場合も、パラメータbは位置3に存在するとみなされます。

Oracleモードでは、SQLNumParams ODBC関数はこの例のパラメータの数として3を返します。

重複したパラメータのTimesTenモード

TimesTenモード(DuplicateBindMode=1)では、重複したパラメータを含むSQL文は、異なるパラメータ名のみが別のパラメータとしてみなされるように解析されます。

バインドは、パラメータ名が最初に出現した位置に基づいて行われます。その後、このパラメータ名が出現しても、それ専用の位置番号は与えられません。同じパラメータ名が出現するたびに、すべて同じ値が使用されます。

前述のSQL文の場合、2つのaの出現は1つのパラメータとみなされるため、別々にバインドできません。

SQLBindParameter(..., 1, ...); /* both occurrences of :a */
SQLBindParameter(..., 2, ...); /* occurrence of :b */

TimesTenモードでは、パラメータbは位置3ではなく、位置2に存在するとみなされることに注意してください。

TimesTenモードでは、SQLNumParams ODBC関数はこの例のパラメータの数として2を返します。

PL/SQLでの重複したパラメータのバインド

前述の説明は、独自のセマンティクスを持つPL/SQLには当てはまりません。PL/SQLでは、それぞれの一意のパラメータ名に値をバインドします。たとえば、次のブロックを実行するアプリケーションは、:aに対応する1つのパラメータのみをバインドします。

DECLARE
x NUMBER;
y NUMBER;
BEGIN
x:=:a;
y:=:a;
END;

次のブロックを実行するアプリケーションでも、1つのパラメータのみをバインドします。

BEGIN
INSERT INTO tab1 VALUES(:a, :a);
END

さらに、次のCALL文でも同様です。

...CALL proc(:a, :a)...

次のブロックを実行するアプリケーションでは、:aを1番目のパラメータ、:bを2番目のパラメータとして、2つのパラメータをバインドします。各INSERT文の2番目のパラメータは、最初のINSERT文の最初のパラメータと同じ値を使用します。

BEGIN
INSERT INTO tab1 VALUES(:a, :a);
INSERT INTO tab1 VALUES(:b, :a);
END

浮動小数点データに関する考慮事項

BINARY_DOUBLEおよびBINARY_FLOATデータ型は、IEEEの浮動小数点の値Inf、-InfおよびNaNを格納および取得します。アプリケーションでprintf、scanfまたはstrtodのような文字データへの変換を必要とするC言語機能を使用した場合、浮動小数点の値はINF、-INFおよびNANとして返されます。これらのキャラクタ文字列を浮動少数点の値に戻すことはできません。

ドライバ・マネージャを使用したSQL_WCHARおよびSQL_WVARCHARの使用

Windowsのドライバ・マネージャを使用するアプリケーションでは、SQL_WCHARまたはSQL_WVARCHARのfSqlType値を渡す際に、SQLBindParameterからSQL状態S1004(SQLデータ型が範囲外)エラーが発生する場合があります。この問題は、かわりにfSqlTypeに次のいずれかの値を渡すことで回避できます。

- SQL_WCHARではなくSQL_WCHAR_DM_SQLBINDPARAMETER_BYPASS

- SQL_WVARCHARではなくSQL_WVARCHAR_DM_SQLBINDPARAMETER_BYPASS

これらの値は、意味的にはSQL_WCHARおよびSQL_WVARCHARと同じですが、Windowsのドライバ・マネージャからのエラーを回避します。これらは、ドライバ・マネージャとリンクするアプリケーションまたはTimesTen ODBCの直接ドライバやODBCクライアント・ドライバと直接リンクするアプリケーションで使用できます。

ODBC関数の詳細は、「SQLBindParameter関数」を参照してください。

REF CURSORの使用

REF CURSORはPL/SQLの1つの概念で、SQL結果セット上のカーソルに対するハンドルであり、PL/SQLとアプリケーションの間で受渡しすることができます。TimesTenでは、PL/SQL内でカーソルをオープンでき、そのREF CURSORをアプリケーションに渡すことができます。結果は、アプリケーション内でODBCコールを使用して処理できます。これがOUT REF CURSOR(PL/SQLに対するOUTパラメータ)です。REF CURSORは文ハンドルにアタッチされ、アプリケーションは任意の結果セットと同じAPIを使用して結果セットを記述およびフェッチできます。

REF CURSORを使用するには、次の手順を実行します。REF CURSOR OUTパラメータを使用してカーソルを返すPL/SQL文を想定しています。REF CURSORでは、「問合せの準備および実行とカーソルの使用」のカーソルの例と同じ準備、バインド、実行およびフェッチの基本的な手順を使用します。

1. SQLPrepareを使用して、最初の文ハンドルと関連付けるPL/SQL文を準備します。

2. SQLBindParameterを使用して、文の各パラメータをバインドします。REF CURSOR出力パラメータをバインドする場合、割り当てられた2番目の文ハンドルをrgbValue(データ・バッファへのポインタ)として使用します。
pcbValue引数、ibScale引数、cbValueMax引数およびpcbValue引数は、REF CURSORに対しては無視されます。

SQLBindParameterのこれらの引数および他の引数の詳細は、「SQLBindParameter関数」および「出力パラメータのバインド」を参照してください。

3. SQLBindColをコールして、結果列をローカル変数の記憶域にバインドします。

4. SQLExecuteをコールして、文を実行します。

5. SQLFetchをコールして結果をフェッチします。PL/SQLからアプリケーションにREF CURSORが渡された後、アプリケーションは結果セットの場合と同様に、その結果を記述およびフェッチできます。

6. SQLFreeStmtを使用して文ハンドルを解放します。

これらの手順を、次の例で実際に行ってみます。これらの関数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。REF CURSORの詳細は、『Oracle TimesTen In-Memory Database PL/SQL開発者ガイド』のPL/SQL REF CURSORに関する説明を参照してください。

重要:
PL/SQLとアプリケーションの間のREF CURSORの受渡しについて、TimesTenでは、PL/SQLからアプリケーションへのOUT REF CURSORのみと、単一のREF CURSORのみを返す文がサポートされます。

例2-7 問合せの実行およびREF CURSORの使用

この例では、REF CURSORをループで使用して、問合せの準備、パラメータのバインド、問合せの実行、ローカル変数記憶域への結果のバインド、および結果のフェッチを行う基本的な手順を示します。わかりやすくするためにエラー処理は省略しています。以前に概要を示したODBC関数以外に、この例ではSQLAllocStmtを使用して文ハンドルにメモリーを割り当てます。

refcursor_example(SQLHDBC hdbc)
{
SQLCHAR*      stmt_text;
SQLHSTMT      plsql_hstmt;
SQLHSTMT      refcursor_hstmt;
SQLINTEGER    deptid;
SQLINTEGER    depts[3] = {10,30,40};
SQLINTEGER    empid;
SQLCHAR       lastname[30];
SQLINTEGER    i;

/* allocate 2 statement handles: one for the plsql statement and
* one for the ref cursor */
SQLAllocStmt(hdbc, &plsql_hstmt);
SQLAllocStmt(hdbc, &refcursor_hstmt);

/* prepare the plsql statement */
stmt_text = (SQLCHAR*)
"begin "
"open :refc for "
"select employee_id, last_name "
"from employees "
"where department_id = :dept; "
"end;";
SQLPrepare(plsql_hstmt, stmt_text, SQL_NTS);

/* bind parameter 1 (:refc) to refcursor_hstmt */
SQLBindParameter(plsql_hstmt, 1, SQL_PARAM_OUTPUT, SQL_C_REFCURSOR,
SQL_REFCURSOR, 0, 0, refcursor_hstmt, 0, 0);

/* bind parameter 2 (:deptid) to local variable deptid */
SQLBindParameter(plsql_hstmt, 2, SQL_PARAM_INPUT, SQL_C_SLONG,
SQL_INTEGER, 0, 0, &deptid, 0, 0);

/* loop through values for :deptid */
for (i=0; i<3; i++)
{
deptid = depts[i];

/* execute the plsql statement */
SQLExecute(plsql_hstmt);
/*
* The result set is now attached to refcursor_hstmt.
* Bind the result columns and fetch the result set.
*/

/* bind result column 1 to local variable empid */
SQLBindCol(refcursor_hstmt, 1, SQL_C_SLONG,
(SQLPOINTER)&empid, 0, 0);

/* bind result column 2 to local variable lastname */
SQLBindCol(refcursor_hstmt, 2, SQL_C_CHAR,
(SQLPOINTER)lastname, sizeof(lastname), 0);

/* fetch the result set */
while(SQLFetch(refcursor_hstmt) != SQL_NO_DATA_FOUND){
printf("%d, %s\n", empid, lastname);
}

/* close the ref cursor statement handle */
SQLFreeStmt(refcursor_hstmt, SQL_CLOSE);
}

/* drop both handles */
SQLFreeStmt(plsql_hstmt, SQL_DROP);
SQLFreeStmt(refcursor_hstmt, SQL_DROP);
}

DML RETURNING(RETURNING INTO句)の使用

DML RETURNINGと呼ばれるRETURNING INTO句をINSERT、UPDATEまたはDELETE文で使用すると、処理の影響を受けた行の特定の項目を返すことができます。これにより、処理の影響を受けた対象を確認する場合などに、後続のSELECT文および別個のラウンドトリップが不要になります。

ODBCの場合、DML RETURNINGは単一行処理から項目を返すことに限定されます。この句では、項目を出力パラメータのリストに返します。「パラメータのバインドおよび文の実行」の記述に従って、出力パラメータをバインドします。

TimesTenでのRETURNING INTO句のSQL構文および制限については、『Oracle TimesTen In-Memory Database SQLリファレンス』のINSERT、UPDATEおよびDELETEに関する説明を参照してください。

DML RETURNINGの詳細は、『Oracle Database PL/SQL言語リファレンス』のRETURNING INTO句に関する項を参照してください。

例2-8 DML RETURNING

この例は、例2-10を元に、主要な部分を太字で強調表示したものです。

void
update_example(SQLHDBC hdbc)
{
SQLCHAR*      stmt_text;
SQLHSTMT      hstmt;
SQLINTEGER    raise_pct;
char          hiredate_str[30];
char          last_name[30];
SQLLEN        hiredate_len;
SQLLEN        numrows;

/* allocate a statement handle */
SQLAllocStmt(hdbc, &hstmt);

/* prepare an update statement to give a raise to one employee hired
before a given date and return that employee's last name */
stmt_text = (SQLCHAR*)
"update employees "
"set salary = salary * ((100 + :raise_pct) / 100.0) "
"where hire_date < :hiredate and rownum = 1 returning last_name into "
":last_name";
SQLPrepare(hstmt, stmt_text, SQL_NTS);

/* bind parameter 1 (:raise_pct) to variable raise_pct */
SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_SLONG,
SQL_DECIMAL, 0, 0, (SQLPOINTER)&raise_pct, 0, 0);

/* bind parameter 2 (:hiredate) to variable hiredate_str */
SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR,
SQL_TIMESTAMP, 0, 0, (SQLPOINTER)hiredate_str,
sizeof(hiredate_str), &hiredate_len);
/* bind parameter 3 (:last_name) to variable last_name */
SQLBindParameter(hstmt, 3, SQL_PARAM_OUTPUT, SQL_C_CHAR,
SQL_VARCHAR, 30, 0, (SQLPOINTER)last_name,
sizeof(last_name), NULL);
/* set parameter values to give a 10% raise to an employee hired before
* January 1, 1996. */
raise_pct = 10;
strcpy(hiredate_str, "1996-01-01");
hiredate_len = SQL_NTS;

/* execute the update statement */
SQLExecute(hstmt);

/* tell us who the lucky person is */
printf("Gave raise to %s.\n", last_name );

/* drop the statement handle */
SQLFreeStmt(hstmt, SQL_DROP);

/* commit the changes */
SQLTransact(henv, hdbc, SQL_COMMIT);

}

この例では、昇給の対象者としてKingが返されます。

ROWIDの使用

データベース表の各行には、ROWIDと呼ばれる一意の識別子があります。アプリケーションでは、ROWID擬似列から行のROWIDを取得できます。ROWIDはバイナリまたは文字形式で表すことができます。

アプリケーションでは、SQL文のWHERE句などで、一重引用符で囲んだCHAR定数としてリテラルのROWID値を指定できます。

表2-2に示すとおり、ODBC SQLデータ型のSQL_ROWIDはSQLデータ型のROWIDに対応します。

パラメータおよび結果セット列では、ROWIDは、Cデータ型のSQL_C_BINARY、SQL_C_WCHARおよびSQL_C_CHARとの間で双方向に変換可能です。SQL_C_CHARは、ROWIDのデフォルトのCデータ型です。ROWIDのサイズは、SQL_C_BINARYとしては12バイト、SQL_C_CHARとしては18バイトおよびSQL_C_WCHARとしては36バイトです。

ROWIDおよびROWIDデータ型の使用方法および存続期間などの詳細は、『Oracle TimesTen In-Memory Database SQLリファレンス』のROWIDデータ型およびROWIDに関する説明を参照してください。

注意:
TimesTenでは、PL/SQL型UROWIDはサポートされていません。

LOBの作業

TimesTenではLOB(ラージ・オブジェクト)がサポートされています。これには、CLOB(Character LOB)、NCLOB(National Character LOB)およびBLOB(Binary LOB)が含まれます。

この項では、次の各項目で、LOBの概要とODBCでの使用について説明します。

- LOBの概要

- TimesTen LOBとOracle Database LOBの相違点

- LOBプログラミング・インタフェース

- ODBCでのLOBの簡易データ・インタフェースの使用

- ODBCでのLOBのピース単位のデータ・インタフェースの使用

- ODBCでのパススルーLOB

注意:
データベース・キャラクタ・セットがTIMESTEN8の場合、TimesTenではCLOBをサポートしません。

次の情報も参照できます。

- APIに固有の情報は、「TimesTen OCIでのLOB」および「TimesTen Pro*C/C++でのLOB」を参照してください。

- TimesTenでのLOBの詳細は、『Oracle TimesTen In-Memory Database SQLリファレンス』のLOBのデータ型に関する説明を参照してください。

- LOBによるプログラミングの一般的な情報(TimesTen機能に固有ではない)は、Oracle Database SecureFileおよびラージ・オブジェクト開発者ガイドを参照してください。

LOBの概要

LOBは、ラージ・バイナリ・オブジェクト(BLOB)またはキャラクタ・オブジェクト(CLOBまたはNCLOB)です。TimesTenでは、BLOBのサイズは最大16MBで、CLOBまたはNCLOBは最大4MBです。他に注記がなければ、TimesTenでのLOBには、Oracle Databaseと基本的に同じ機能があります。(次の項「TimesTen LOBとOracle Database LOBの相違点」を参照。)

LOBは、永続または一時のいずれかです。永続LOBは、データベースのLOB列に存在します。一時LOBは、アプリケーション内にのみ存在します。一時LOBがTimesTenによって暗黙的に作成される場合があります。たとえば、SELECT文で追加の文字列が連結されたLOBを指定した場合に、連結されたデータを含むためにTimesTenによって一時LOBが作成されます。TimesTen ODBCでは、すべての一時LOBは暗黙的に管理されます。

一時LOBは、TimesTenの一時データ領域に格納されます。

TimesTen LOBとOracle Database LOBの相違点

次のことに注意してください。

- TimesTen LOB実装とOracle Database実装の主な違いは、TimesTenでは、アプリケーションで使用されたLOBはトランザクションの終了後は有効ではないことです。アプリケーションで使用されたLOBはすべて(明示的、暗黙的のどちらの場合も)、コミットまたはロールバックの後に無効化されます。これには、TimesTen DDLCommitBehaviorが0(ゼロ)(デフォルト)に設定されている場合(Oracle Databaseの動作に対応)、すべてのDDL文の実行後が含まれます。

- TimesTenでは、BFILE、SecureFile、LOBに対する配列読取りおよび書込みまたはLOBに対するコールバック関数をサポートしていません。

- TimesTenでは、LOBに対する配列のバインドをサポートしていません。

- TimesTenでは、LOBに対するバッチ処理をサポートしていません。

- BLOBに関して、TimesTenでの16進リテラルの使用方法に違いがあります。『Oracle TimesTen In-Memory Database SQLリファレンス』の定数でHexadecimalLiteralに関する説明を参照してください。

LOBプログラミング・インタフェース

CまたはC++プログラムでのTimesTen LOBへのアクセスには、次の3つのプログラミング方法があります。

- 簡易データ・インタフェース(ODBC、OCI、Pro*C/C++、TTClasses): その他のスカラー型と同様に、バインドおよび定義を使用してLOBデータを1チャンクで転送します。

- ピース単位のデータ・インタフェース(ODBC): バインドおよび定義の拡張書式を使用して複数ピース単位でLOBデータを転送します。これは、ストリーミングまたはdata-at-execの使用(プログラムの実行時)と呼ばれることがあります。TimesTenでは、LOBデータをピース単位で探索するポーリング・ループを使用した、ピース単位のデータ・インタフェースをサポートしています。(ピース単位による別の方法であるコールバック関数の使用は、Oracle Databaseではサポートされていますが、TimesTenではサポートされていません。)

- LOBロケータ・インタフェース(OCI、Pro*C/C++): SQLでLOBロケータを選択し、ファイル・システムへのアクセスで使用するAPIと概念的に似ているAPIを介して、LOBデータにアクセスします。LOBロケータ・インタフェースを使用すると、LOBデータを分割してまたは単一チャンクで使用できます。(「TimesTen OCIでのLOB」および「TimesTen Pro*C/C++でのLOB」を参照。)

LOBロケータ・インタフェースは、使用できる場合は最適なユーティリティを提供します。

ODBCでのLOBの簡易データ・インタフェースの使用

簡易データ・インタフェースを使用すると、他のスカラー型と同様に、アプリケーションからバインドおよび定義によってLOBデータにアクセスできます。ODBCでの簡易データ・インタフェースでは、パラメータのバインドにSQLBindParameterを使用し、結果列の定義にSQLBindColを使用します。アプリケーションは、SQLデータ型を使用してバインドまたは定義することが可能で、このSQLデータ型は次に示すように対応する変数型と互換性があります。

- BLOBデータでは、SQL型SQL_LONGVARBINARYおよびC型SQL_C_BINARYを使用します。

- CLOBデータでは、SQL型SQL_LONGVARCHARおよびC型SQL_C_CHARを使用します。

- NCLOBデータでは、SQL型SQL_WLONGVARCHARおよびC型SQL_C_WCHARを使用します。

LOBデータに対するSQLBindParameterコールおよびSQLBindColコールは、この章で前述した他のデータ型に対するコールとよく似ています。

注意:
CLOBまたはNCLOBでC型のSQL_C_BINARYを使用したバインドは禁止されています。

ODBCでのLOBのピース単位のデータ・インタフェースの使用

ピース単位のインタフェースを使用すると、アプリケーションから、LOBデータの各部分に個別にアクセスできます。簡易データ・インタフェースで実行されるのと同様のアクションで、アプリケーションによってパラメータがバインドされ、結果が定義されますが、プログラム実行時(at exec)にデータが提供されたものか取得されたものであるかが示されます。TimesTenでは、すべてのLOBデータが読み取られるか書き込まれるまで継続されるポーリング・ループを介してピース単位のデータ・インタフェースを実装できます。

ODBCでのピース単位のデータ・インタフェースでは、SQLParamDataとSQLPutDataをポーリング・ループで使用してパラメータをバインドし(次の例2-9を参照)、SQLGetDataをポーリング・ループで使用して結果を取得します。BLOB、CLOBおよびNCLOBでサポートされるSQLおよびCのデータ型の詳細は、前述の項「ODBCでのLOBの簡易データ・インタフェースの使用」を参照してください。

注意:
様々なAPIに対する同様のピース単位のデータ・アクセスは、TimesTenの以前のリリースからサポートされています(varデータ型の場合)。

例2-9 SQLPutDataの使用、ODBCのピース単位のデータ・インタフェース

このプログラムの抜粋では、SQLPutDataとSQLParamDataをポーリング・ループで使用して、LOBデータをピース単位でデータベースに挿入します。コードが実行されるとき、CLOB列には"123ABC"の値が含まれています。

...
/* create a table */
create_stmt = "create table clobtable ( c clob )";
rc = SQLExecDirect(hstmt, (SQLCHAR *)create_stmt, SQL_NTS);
if(rc != SQL_SUCCESS){/* ...error handling... */}

/* initialize an insert statement */
insert_stmt = "insert into clobtable values(?)";
rc = SQLPrepare(hstmt, (SQLCHAR *)insert_stmt, SQL_NTS);
if(rc != SQL_SUCCESS){/* ...error handling... */}

/* bind the parameter and specify that we will be using
* SQLParamData/SQLPutData */
rc = SQLBindParameter
hstmt,            /* statement handle */
1,                /* colnum number */
SQL_PARAM_INPUT,  /* param type */
SQL_C_CHAR,       /* C type */
SQL_LONGVARCHAR,  /* SQL type (ignored) */
2,                /* precision (ignored) */
0,                /* scale (ignored) */
0,                /* putdata token */
0,                /* ignored */
&pcbvalue);       /* indicates use of SQLPutData */
if(rc != SQL_SUCCESS){/* ...error handling... */}

pcbvalue = SQL_DATA_AT_EXEC;

/* execute the statement -- this should return SQL_NEED_DATA */
rc = SQLExecute(hstmt);
if(rc != SQL_NEED_DATA){/* ...error handling... */}

/* while we still have parameters that need data... */
while((rc = SQLParamData(hstmt, &unused)) == SQL_NEED_DATA){

memcpy(char_buf, "123", 3);
rc = SQLPutData(hstmt, char_buf, 3);
if(rc !=  SQL_SUCCESS){/* ...error handling... */}

memcpy(char_buf, "ABC", 3);
rc = SQLPutData(hstmt, char_buf, 3);
if(rc !=  SQL_SUCCESS){/* ...error handling... */}

}
...

ODBCでのパススルーLOB

パススルーLOB(TimesTenを介してアクセスされるOracle DatabaseのLOB)は、TimesTen LOBとして公開され、TimesTenによってTimesTen LOBとほぼ同じようにサポートされますが、次の点に注意してください。

- TimesTen LOBのサイズ制限は、パススルーによるOracle DatabaseのLOBの格納には適用されません。

- TimesTenのローカルLOBと同様に、アプリケーションで使用されるパススルーLOBは、トランザクションの終了後は有効ではありません。

データベースに対する変更の実行とコミット

実行したDML変更(更新、挿入または削除)が自動的にコミットされるよう、自動コミットはデフォルトで有効になっています(ODBCの指定に従って)。ただし、この機能を無効にして、変更を明示的にコミット(またはロールバック)することをお薦めします。これを設定するには、次のようにSQLSetConnectOptionコールでSQL_AUTOCOMMITオプションを使用します。

rc = SQLSetConnectOption(hdbc, SQL_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF);

自動コミットが無効になっている場合は、次のコミットの例のように、SQLTransact ODBC関数を使用してトランザクションをコミットまたはロールバックできます。

rc = SQLTransact(henv, hdbc, SQL_COMMIT);

これらの関数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。

注意:

- 自動コミット・モードは、SQLExecuteまたはSQLExecDirectで実行されるトップレベルの文にのみ適用されます。文の内部での実行内容は認識されないため、ネストされた処理の中間自動コミットの機能はありません。

- 接続時のすべてのオープン・カーソルは、TimesTenでのトランザクションのコミットまたはロールバック時にクローズされます。

- SQLRowCount関数を使用すると、SQL処理に関する情報を返すことができます。UPDATE、INSERTおよびDELETE文の場合、出力の引数によって、影響を受けた行数が返されます。TimesTenの特別な機能については、「キャッシュ・グループの管理」を参照してください。SQLRowCountおよびその引数の全般的な情報については、ODBC APIのリファレンス・マニュアルを参照してください。

トランザクションの追加情報は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のトランザクションの概要に関する説明を参照してください。

例2-10 データベースの更新および変更のコミット

この例では、選択した従業員の昇給を行う文を準備して実行した後、手動で変更をコミットします。自動コミットが事前に無効にされていることを前提としています。

update_example(SQLHDBC hdbc)
{
SQLCHAR*      stmt_text;
SQLHSTMT      hstmt;
SQLINTEGER    raise_pct;
char          hiredate_str[30];
SQLLEN        hiredate_len;
SQLLEN        numrows;

/* allocate a statement handle */
SQLAllocStmt(hdbc, &hstmt);

/* prepare an update statement to give raises to employees hired before a
* given date */
stmt_text = (SQLCHAR*)
"update employees "
"set salary = salary * ((100 + :raise_pct) / 100.0) "
"where hire_date < :hiredate";
SQLPrepare(hstmt, stmt_text, SQL_NTS);

/* bind parameter 1 (:raise_pct) to variable raise_pct */
SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_SLONG,
SQL_DECIMAL, 0, 0, (SQLPOINTER)&raise_pct, 0, 0);

/* bind parameter 2 (:hiredate) to variable hiredate_str */
SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR,
SQL_TIMESTAMP, 0, 0, (SQLPOINTER)hiredate_str,
sizeof(hiredate_str), &hiredate_len);

/* set parameter values to give a 10% raise to employees hired before
* January 1, 1996. */
raise_pct = 10;
strcpy(hiredate_str, "1996-01-01");
hiredate_len = SQL_NTS;

/* execute the update statement */
SQLExecute(hstmt);

/* print the number of employees who got raises  */
SQLRowCount(hstmt, &numrows);
printf("Gave raises to %d employees.\n", numrows);

/* drop the statement handle */
SQLFreeStmt(hstmt, SQL_DROP);

/* commit the changes */
SQLTransact(henv, hdbc, SQL_COMMIT);

}

その他のTimesTenデータ管理機能の使用

前述の項では、TimesTenデータを管理するための主な機能について説明しました。この項では、次にリストするその他の機能について説明します。

- プロシージャおよび関数を実行するためのCALLの使用

- SQL文の実行に対するタイムアウトまたはしきい値の設定

- TimesTen Cacheで使用する機能

- グローバリゼーション・オプションの設定

- レプリケーションで使用する機能

- ODBC 3.0データ型

プロシージャおよび関数を実行するためのCALLの使用

TimesTenでは、スタンドアロンまたはパッケージの一部であるPL/SQLプロシージャ(procname)またはPL/SQLファンクション(funcname)をコールするため、またはTimesTenの組込みプロシージャ(procname)をコールするための、すべてのプログラミング・インタフェースの次の各構文書式がサポートされています。

CALL procname[(argumentlist)]

CALL funcname[(argumentlist)] INTO :returnparam

CALL funcname[(argumentlist)] INTO ?

TimesTen ODBCでは、次の各構文書式もサポートされています。

{ CALL procname[(argumentlist)] }

{ ? = [CALL] funcname[(argumentlist)] }

{ :returnparam = [CALL] funcname[(argumentlist)] }

次のODBCの例では、TimesTen ttCkpt組込みプロシージャをコールします。

rc = SQLExecDirect (hstmt, (SQLCHAR*) "call ttCkpt",SQL_NTS);

これらの例では、PL/SQLプロシージャmyprocを2つのパラメータでコールします。

rc = SQLExecDirect(hstmt, (SQLCHAR*) "{ call myproc(:param1, :param2) }",SQL_NTS);

rc = SQLExecDirect(hstmt, (SQLCHAR*) "{ call myproc(?, ?) }",SQL_NTS);

PL/SQLファンクションmyfuncをコールするいくつかの方法を次に示します。

rc = SQLExecDirect (hstmt, (SQLCHAR*) "CALL myfunc() INTO :retparam",SQL_NTS);

rc = SQLExecDirect (hstmt, (SQLCHAR*) "CALL myfunc() INTO ?",SQL_NTS);

rc = SQLExecDirect (hstmt, (SQLCHAR*) "{ :retparam = myfunc() }",SQL_NTS);

rc = SQLExecDirect (hstmt, (SQLCHAR*) "{ ? = myfunc() }",SQL_NTS);

CALL構文の詳細は、『Oracle TimesTen In-Memory Database SQLリファレンス』のCALLに関する説明を参照してください。

注意:

- ユーザー独自のプロシージャは、同じ名前のTimesTen組込みプロシージャより優先されますが、このようなネーミングの競合は避けることが最適です。

- TimesTenでは、CALL文に対するSQL_DEFAULT_PARAMとSQLBindParameterの使用はサポートされていません。

SQL文の実行に対するタイムアウトまたはしきい値の設定

TimesTenには、実行するSQL文またはプロシージャ・コールの時間を制限する方法が2つあり、SQLExecute、SQLExecDirectまたはSQLFetchコールに適用されます。

- SQL文のタイムアウト期間の設定

- SQL文のしきい値期間の設定

前者の場合、タイムアウト期間に達すると、文の実行が停止し、エラーがスローされます。後者の場合、しきい値に達すると、SNMPトラップがスローされますが実行は継続されます。

SQL文に対するタイムアウト期間の設定

タイムアウトまでのSQL文の実行時間を制御するには、SQLSetStmtOptionまたはSQLSetConnectOptionコールを使用してSQL_QUERY_TIMEOUTオプションを設定することで、タイムアウト値を秒単位で指定できます。値0はタイムアウトが発生しないことを示します。このような名前であるにもかかわらず、このタイムアウト値は問合せのみではなく、実行可能なすべてのSQL文に適用されます。

TimesTenでは、SqlQueryTimeout一般接続属性を使用することで、タイムアウト値を接続、つまり接続の任意の文に対して指定できます。(『Oracle TimesTen In-Memory Databaseリファレンス』のSqlQueryTimeoutに関する説明も参照してください。)SQL_QUERY_TIMEOUTオプションを指定したSQLSetConnectOptionのコールは、前の問合せタイムアウトの設定を上書きします。SQL_QUERY_TIMEOUTオプションを指定したSQLSetStmtOptionのコールは、特定の文の接続設定を上書きします。

問合せのタイムアウト制限は、SQL文がアクティブに実行されている場合にのみ有効です。コミット中またはロールバック中にはタイムアウトは発生しません。多数の行に対して更新、削除または挿入を行うトランザクションでは、コミットまたはロールバックが完了するまでに時間がかかる場合があります。その間、タイムアウト値は無視されます。

注意:
ロック・タイムアウト値およびSQL問合せタイムアウト値の両方が指定されている場合は、まず、2つの値の小さい方の値によってタイムアウトが発生します。ロック・タイムアウトについては、『Oracle TimesTen In-Memory Databaseリファレンス』のttLockWait(組込みプロシージャ)またはLockWait(一般接続属性)に関する説明、またはOracle TimesTen In-Memory Databaseトラブルシューティング・ガイドのデッドロックとタイムアウトの確認に関する説明を参照してください。

SQL文に対するしきい値期間の設定

SQL文の実行が指定期間(秒単位)を超えた場合に、サポート・ログに警告を書き込んでSNMPトラップをスローするように、TimesTenを構成できます。実行は継続され、しきい値による影響は受けません。

このSNMPトラップの名前はttQueryThresholdWarnTrapです。SNMPトラップの構成方法については、『Oracle TimesTen In-Memory Databaseエラー・メッセージおよびSNMPトラップ』参照してください。このような名前であるにもかかわらず、このしきい値は実行可能なすべてのSQL文に適用されます。

デフォルトでは、アプリケーションはしきい値をQueryThreshold一般接続属性設定から取得します(『Oracle TimesTen In-Memory Databaseリファレンス』のQueryThresholdに関する説明を参照)。SQLSetConnectOptionコールでTT_QUERY_THRESHOLDオプションを設定すると、現在の接続の接続属性の設定が上書きされます。

SQLSetConnectOptionでしきい値を設定するには、次のように入力します。

RETCODE SQLSetConnectOption(hdbc, TT_QUERY_THRESHOLD, seconds);

SQLSetStmtOptionコールでTT_QUERY_THRESHOLDオプションを設定すると、その文に対する接続属性の設定およびSQLSetConnectOptionによる設定が上書きされます。この設定は、ODBC文ハンドルを使用して実行されるSQL文に適用されます。

SQLSetStmtOptionでしきい値を設定するには、次のように入力します。

RETCODE SQLSetStmtOption(hstmt, TT_QUERY_THRESHOLD, seconds);

SQLGetConnectOptionまたはSQLGetStmtOption ODBC関数を使用して、TT_QUERY_THRESHOLDの現在の値を取得できます。

RETCODE SQLGetConnectOption(hdbc, TT_QUERY_THRESHOLD, paramvalue);

RETCODE SQLGetStmtOption(hstmt, TT_QUERY_THRESHOLD, paramvalue);

TimesTen Cacheで使用する機能

この項では、TimesTen Cacheの使用に関する機能について説明します。

- ttOptSetFlag組込みプロシージャを使用した一時的なパススルー・レベルの設定

- パススルー・ステータスの確認

- キャッシュ・グループの管理

TimesTen Cacheの詳細は、『Oracle TimesTen Application-Tier Database Cacheユーザーズ・ガイド』を参照してください。

一般接続属性の詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のパススルーに関する説明を参照してください。パススルー設定の詳細は、『Oracle TimesTen Application-Tier Database Cacheユーザーズ・ガイド』のパススルー・レベルの設定に関する説明を参照してください。

ttOptSetFlag組込みプロシージャを使用した一時的なパススルー・レベルの設定

TimesTenでは、パススルー・レベルを一時的に設定するためのPassThroughフラグを含む、様々なフラグを設定するためのttOptSetFlag組込みプロシージャが提供されています。次の例のとおり、ttOptSetFlagを使用して、CアプリケーションでPassThroughを設定できます(この例では、パススルー・レベルは1に設定されます)。この設定によって、トランザクションが終了するまで、準備されたすべての文に適用されます。

rc = SQLExecDirect (hstmt, "call ttOptSetFlag ('PassThrough', 1)",SQL_NTS);

この組込みプロシージャの詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttOptSetFlagに関する説明を参照してください。

パススルー・ステータスの確認

SQL文がTimesTenデータベースで実行されるか、またはOracle Databaseにパススルーされて実行されるかを確認するには、TT_STMT_PASSTHROUGH_TYPE文オプションを指定したODBC関数SQLGetStmtOptionをコールします。これは次の例のようになります。

rc = SQLGetStmtOption(hStmt, TT_STMT_PASSTHROUGH_TYPE, &passThroughType);

SQL文の準備の後に、このコールを実行できます。これは、PassThrough設定1、2、4または5の場合(文が実際にパススルーされるかどうかの確認がコンパイル時まで行われない)に有効です。TT_STMT_PASSTHROUGH_NONEが返された場合、文はTimesTenで実行されます。TT_STMT_PASSTHROUGH_ORACLEが返された場合、文はOracle Databaseにパススルーされて実行されます。

注意:
TT_STMT_PASSTHROUGH_TYPEは、SQLGetStmtOptionでのみサポートされていて、SQLSetStmtOptionではサポートされていません。

キャッシュ・グループの管理

TimesTen Cacheでは、FLUSH CACHE GROUP、LOAD CACHE GROUP、REFRESH CACHE GROUPまたはUNLOAD CACHE GROUP文の実行の後、ODBC関数SQLRowCountを使用するとフラッシュ、ロード、リフレッシュまたはアンロードされたキャッシュ・インスタンスの数が返されます。

詳細は、『Oracle TimesTen Application-Tier Database Cacheユーザーズ・ガイド』の処理の影響を受けるキャッシュ・インスタンスの数の確認に関する項を参照してください。

SQLRowCountの全般的な情報については、ODBC APIのリファレンス・マニュアルを参照してください。

グローバリゼーション・オプションの設定

TimesTenによるODBCの拡張によって、アプリケーションで言語ソート、文字列の長さセマンティクス、およびキャラクタ・セット変換中のエラー・レポートに関するオプションを設定できます。これらのオプションは、SQLSetConnectOptionへのコールで使用できます。オプションは、timesten.hファイル(「TimesTen includeファイル」を参照)で定義します。

言語ソート、長さセマンティクスおよびキャラクタ・セットの詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のグローバリゼーション・サポートに関する項を参照してください。

この項では、次のTimesTen ODBCグローバリゼーション・サポートについて説明します。

- TT_NLS_SORT

- TT_NLS_LENGTH_SEMANTICS

- TT_NLS_NCHAR_CONV_EXCP

TT_NLS_SORT

このオプションには、言語比較で使用する照合順番を指定します。サポートされている言語ソートについては、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』の単一言語ソートに関する説明および多言語ソートに関する説明を参照してください。

このオプションには、文字列値を指定します。デフォルトはBINARYです。

また、同じ機能を持つNLS_SORT一般接続属性の説明も参照してください(『Oracle TimesTen In-Memory Databaseリファレンス』のNLS_SORTに関する説明を参照)。実行時オプションのTT_NLS_SORTは、NLS_SORT接続属性より優先されることに注意してください。

TT_NLS_LENGTH_SEMANTICS

このオプションには、バイト・セマンティクスを使用するか、キャラクタ・セマンティクスを使用するかを指定します。指定できる値は次のとおりです。

- TT_NLS_LENGTH_SEMANTICS_BYTE (デフォルト)

- TT_NLS_LENGTH_SEMANTICS_CHAR

また、同じ機能を持つNLS_LENGTH_SEMANTICS一般接続属性の説明も参照してください(『Oracle TimesTen In-Memory Databaseリファレンス』のNLS_LENGTH_SEMANTICSに関する説明を参照)。実行時オプションのTT_NLS_LENGTH_SEMANTICSは、NLS_LENGTH_SEMANTICS接続属性より優先されることに注意してください。

TT_NLS_NCHAR_CONV_EXCP

このオプションでは、SQL処理中に、NCHARまたはNVARCHAR2データとCHARまたはVARCHAR2データの間の暗黙的または明示的なキャラクタ・タイプの変換中にデータが消失した場合に、エラーがレポートされるかどうかを指定します。このオプションは、バインドの結果としてのODBCによる変換には適用されません。

指定できる値は次のとおりです。

- TRUE: 変換中のエラーがレポートされます。

- FALSE: 変換中のエラーはレポートされません(デフォルト)。

また、同じ機能を持つNLS_NCHAR_CONV_EXCP一般接続属性の説明も参照してください(『Oracle TimesTen In-Memory Databaseリファレンス』のNLS_NCHAR_CONV_EXCPに関する説明を参照)。実行時オプションのTT_NLS_NCHAR_CONV_EXCPは、NLS_NCHAR_CONV_EXCP接続属性より優先されることに注意してください。

レプリケーションで使用する機能

レプリケーションを使用するアプリケーションの場合、parallel replicationを使用することでパフォーマンスを向上させることができます。これは、トランザクションの変更をレプリケーション・スキーム内のノードにレプリケートおよび適用するために並行して動作する複数のスレッドを使用します。TimesTenでは、次のタイプのパラレル・レプリケーションをサポートしています。

- 自動パラレル・レプリケーション(ReplicationApplyOrdering=0): トランザクションの依存性と、コミット順に適用されたすべての変更を自動的に適用する、複数のスレッドにおけるパラレル・レプリケーション。これはデフォルトです。

- コミット依存性を無効にした自動パラレル・レプリケーション(ReplicationApplyOrdering=2): トランザクションの依存性を自動的に強制するが、サブスクライバ・データベース上でマスター・データベース上と同じ順序でコミットされるトランザクションは強制しない、複数スレッドでのパラレル・レプリケーション。このモードでは、オプションでレプリケーション・トラックを指定できます。

- ユーザー定義のパラレル・レプリケーション(ReplicationApplyOrdering=1): クラシック・レプリケーション・スキームを使用し、トランザクションの依存性の予測性が高く、レシーバでのコミット順序が元のデータベース上のコミット順序と同じである必要がないアプリケーションの場合。トランザクションの追跡数を指定し、各追跡に特定のトランザクションを適用できます。すべての追跡の読取り、送信および適用はパラレルに行われます。

詳細および使用シナリオについては、『Oracle TimesTen In-Memory Database開発者および管理者ガイド』のパラレル・レプリケーションの構成に関する説明を参照してください。

注意:
ユーザー定義のパラレル・レプリケーションは通常、お薦めできません。レプリケーション・ノード間のデータの相違を回避するために注意する必要があるためです。

パラレル・レプリケーションを使用し、レプリケーション・トラックを指定するODBCアプリケーションでは、TT_REPLICATION_TRACK接続オプションを使用した接続時のトランザクションのトラック番号を指定できます(「SQLSetConnectOptionおよびSQLGetConnectOption用のオプションのサポート」を参照)。(または、一般接続属性ReplicationTrackまたはALTER SESSIONのパラメータREPLICATION_TRACKを使用します。)

ODBC 3.0データ型

ODBC 2.0以下のリリースで使用されていたデータ型は、ISO 92標準に準拠するために名前が変更されています。TimesTenに付属のサンプル・プログラムは、SQL 3.0データ型を使用して記述されています。次の表に、2.0データ型およびそれに対応する3.0データ型を示します。

TimesTenでは、ODBC 2.5、拡張レベル1がサポートされており、拡張レベル2用の追加機能もありますが、これらの機能については、第10章「TimesTen ODBC関数およびオプション」を参照してください。

ODBC 2.0データ型

ODBC 3.0データ型

HDBC

SQLHDBC

HENV

SQLHENV

HSTMT

SQLHSTMT

HWND

SQLHWND

LDOUBLE

SQLDOUBLE

RETCODE

SQLRETURN

SCHAR

SQLSCHAR

SDOUBLE

SQLFLOATS

SDWORD

SQLINTEGER

SFLOAT

SQLREAL

SWORD

SQLSMALLINT

UCHAR

SQLCHAR

UDWORD

SQLUINTEGER

UWORD

SQLUSMALLINT

いずれのバージョンのデータ型もTimesTenで制限なしに使用される場合があります。

また、ODBC 2.0のドキュメントに記載されているFAR修飾子は必要ないことにも注意してください。

アクセス制御に関するTimesTen機能の考慮事項

TimesTenには、表、ビュー、マテリアライズド・ビュー、順序、シノニムなどのデータベース・オブジェクトについて、オブジェクト・レベルの解決法でデータベース・アクセスを制御する機能が含まれています。これらの機能の概要は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のアクセス制御の管理に関する項を参照してください。

この項では、SQL処理、データベース接続、XLAおよびCユーティリティ関数に関連するアクセス制御について説明します。

このマニュアルで説明されている、または例で使用されている問合せ、SQL DMLまたはDDL文では、ユーザーは、その文の実行のために適切な権限を持っていることを前提としています。たとえば、表に対するSELECT文では、その表の所有権、その表に関して付与されているSELECT権限またはSELECT ANY TABLEシステム権限が必要です。同様に、DML文にはその表の所有権、その表に関して付与されている適切なDML権限(UPDATEなど)または適切なANY TABLE権限(UPDATE ANY TABLEなど)が必要です。

DDL文の場合、CREATE TABLEにはユーザー・スキーマのCREATE TABLE権限またはその他のスキーマのCREATE ANY TABLE権限が必要です。ALTER TABLEには、所有権またはALTER ANY TABLEシステム権限が必要です。DROP TABLEには、所有権またはDROP ANY TABLEシステム権限が必要です。オブジェクト・レベルのALTER権限またはDROP権限はありません。

特定のSQL文に必要な権限については、『Oracle TimesTen In-Memory Database SQLリファレンス・ガイド』のSQL文に関する項を参照してください。

権限は、SQLのGRANT文で付与され、REVOKE文で取り消されます。一部の権限は、各ユーザーがメンバーであるPUBLICロールを介して、すべてのユーザーに付与されます。このロールの詳細は、『Oracle TimesTen In-Memory Database SQLリファレンス・ガイド』のPUBLICロールに関する項を参照してください。

また、アクセス制御は、このマニュアルで説明している次の内容に関係します。

- データベースへの接続: 「接続のアクセス制御」を参照してください。

- 接続属性の設定: 「プログラムでの接続属性の設定」を参照してください。

- XLAの構成および管理とXLA関数の使用: 「アクセス制御がXLAに与える影響」を参照してください。第9章「XLAリファレンス」も参照してください。各XLA関数のドキュメントは、必要な権限を示しています。

- Cユーティリティ関数の実行: 第8章「TimesTenユーティリティAPI」を参照してください。各ユーティリティのドキュメントは、権限が必要かどうかを示しています。

注意:

- アクセス制御は無効にできません。

- アクセス制御の権限は、データベースでSQLが準備されるときと実行されるときの両方で確認され、パフォーマンス・コストの大部分は準備時に発生します。

エラー処理

この項の内容は次のとおりです。

- エラーのチェック

- エラーおよび警告のレベル

- 致命的なエラーからのリカバリ

エラーのチェック

アプリケーションでは、コールのたびにエラーおよび警告をチェックする必要があります。これによって、開発およびデバッグ時に時間および労力が大幅に節約されます。TimesTenに付属のデモ・プログラムには、エラー・チェックの例が含まれています。

エラーは、install_dir/include/tt_errCode.hファイルで定義されているTimesTenエラー・コード(エラー番号)またはエラー文字列のいずれかを使用してチェックできます。エントリの書式は次のとおりです。

#define tt_ErrMemoryLock             712

各メッセージについては、『Oracle TimesTen In-Memory Databaseエラー・メッセージおよびSNMPトラップ』のエラーおよび警告のリストに関する項を参照してください。

ODBC関数をコールした後、リターン・コードを確認します。リターン・コードがSQL_SUCCESSでない場合は、ODBC関数SQLErrorをコールするエラー処理ルーチンを使用して、関連するODBCハンドルのエラーを取得します。1回のODBCコールで、複数のエラーが返される場合もあります。アプリケーションは、すべてのエラーがエラー・スタックから読み取られるまでSQLError関数を繰り返しコールしてすべてのエラーを返すように記述されている必要があります。リターン・コードがSQL_NO_DATA_FOUNDになるまで、SQLErrorをコールし続けます。

SQLError関数およびその引数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。

一般的なODBCエラーを処理する関数の作成方法については、『Oracle TimesTen In-Memory Databaseエラー・メッセージおよびSNMPトラップ』のエラーおよび警告の取得に関する項を参照してください。

例2-11 ODBC関数コールでのエラーの確認

この例では、SQLAllocConnectをコールした後にエラー状況を確認できることを示しています。エラーが見つかった場合、エラー・メッセージが表示され、プログラムの実行は終了します。

rc = SQLAllocConnect(henv, &hdbc);

if (rc != SQL_SUCCESS) {
handleError(rc, henv, hdbc, hstmt, err_buf, &native_error);
fprintf(stderr,
"Unable to allocate a connection handle:\n%s\n",
err_buf);
exit(-1);
}

エラーおよび警告のレベル

操作が完全には成功しない場合、TimesTenは、致命的なエラー、致命的ではないエラーまたは警告を返すことができます。

致命的なエラー

致命的なエラーとは、エラー・リカバリが終わるまでデータベースにアクセスできなくなるエラーのことです。致命的なエラーが発生すると、すべてのデータベースの接続を切断する必要があります。それ以後の処理は完了されません。致命的なエラーは、TimesTenのエラー・コード846および994で示されます。これらのエラーの処理は、標準的なエラーの処理とは異なります。特に、アプリケーションのエラー処理コードは、現行のトランザクションをロールバックし、データベースから切断する必要があります。

「致命的なエラーからのリカバリ」も参照してください。

致命的ではないエラー

致命的ではないエラーには、一意制約に違反しているINSERT文などの単純なエラーが含まれます。また、一部のアプリケーション障害およびプロセス障害も、致命的ではないエラーに含まれます。

TimesTenは、通常のエラー処理プロセスを通して致命的ではないエラーを返します。アプリケーションはエラーがないか確認し、適切に処理する必要があります。

致命的ではないエラーによってデータベースに影響が出た場合、エラーが返されることがあり、アプリケーションで適切に対処する必要があります。

アプリケーションでは、その処理を変更するか、または障害が発生した1つ以上のトランザクションをロールバックすることによって、致命的ではないエラーに対処できます。

警告

予期しない状態が発生した場合、TimesTenは警告を返します。次のイベントが発生した場合、TimesTenは警告を発行します。

- チェックポイントの障害

- 非推奨TimesTen機能の使用

- 一部のデータの切捨て

- 接続時のリカバリ処理の実行

- レプリケーションがRETURN RECEIPTの場合のタイムアウト

アプリケーション開発者は、アプリケーションの問題を指摘することができるように、警告をチェックするコードを含める必要があります。

異常終了

プロセス障害などの場合、エラーは返されませんが、失敗したプロセスのトランザクションが自動的にロールバックされます。

致命的なエラーからのリカバリ

致命的なエラーが発生した場合、TimesTenは、次の完全なクリーンアップおよびリカバリ・プロシージャを実行します。

- データベースに対するすべての接続を無効化します。サーバーでのメモリー不足状態を回避するには、無効になったデータベースからアプリケーションを切断する必要があります。古いTimesTenインスタンスの共有メモリーは、エラー発生時にアクティブだったすべての接続が切断されるまで解放されません。古いTimesTenインスタンスに依然として接続されている非アクティブなアプリケーションは、手動で終了する必要があることがあります。

- その後の最初の初期接続時に、チェックポイント・ファイルおよびトランザクション・ログ・ファイルからデータベースをリカバリします。

- リカバリされたデータベースには、永続コミットされたすべてのトランザクションの状態が反映されます。また、非永続的にコミットされた一部のトランザクションも反映されます。

- コミットされていないトランザクションまたはロールバックされたトランザクションは反映されません。

アプリケーションでの自動クライアント・フェイルオーバーの使用

自動クライアント・フェイルオーバーは、TimesTenアクティブ・スタンバイ・ペア・レプリケーション構成での高可用性シナリオで使用されます。アクティブ・ノードに障害が発生した場合、新しいアクティブ(元のスタンバイ)・ノードへのフェイルオーバー(転送)が発生し、アプリケーションは新しいアクティブ・ノードに自動的に再接続されます。TimesTenは自動クライアント・フェイルオーバーが発生したときに、アプリケーションに警告を渡す機能を提供しているため、アプリケーションは適切な処理を行うことができます。

この項では、アプリケーション開発者に適用されるTimesTenでの自動クライアント・フェイルオーバーの実装を取り上げ、次のことについて説明します。

- 自動クライアント・フェイルオーバーの機能

- 自動クライアント・フェイルオーバーの構成

- フェイルオーバーのコールバック関数

この機能の詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』の自動クライアント・フェイルオーバーの使用に関する説明を参照してください。

自動クライアント・フェイルオーバーの機能

アプリケーションがまずアクティブ・ノードに接続すると、接続が登録され、この登録はスタンバイ・ノードにレプリケートされます。アクティブ・ノードで障害が発生すると、スタンバイ・ノードが新しいアクティブ・ノードになり、フェイルオーバーのことがクライアントに通知されます。この時点で、次の点に注意してください。

- クライアントは新しいアクティブ・ノードに対して新しく接続しますが、以前と同じODBC接続ハンドルを使用します。ハンドル自体以外は、元の接続の状態は保持されません。アプリケーションは、新しいODBC文ハンドルをオープンする必要があります。

- 関数が登録された場合に、アプリケーションに関連付けられたフェイルオーバー・イベント関数を起動するフェイルオーバー・リスナー・スレッドが各クライアントにあります。(「フェイルオーバーのコールバック関数」を参照してください。)

元の接続からのすべてのクライアント文ハンドルは、無効とマークされます。これらの文ハンドルに対してAPIコールを実行すると、通常は次のように、tt_errCode.hで定義されている個別のフェイルオーバー・エラー・コードがSQL_ERRORとともに返されます。

SQLSTATE = S1000 "General Error", native error = tt_ErrFailoverInvalidation

SQLErrorおよびSQLFreeStmtコールについては例外で、通常どおり動作します。

また、次の点にも注意してください。

- 元のアクティブ・ノードに対するソケットは閉じられます。SQLDisconnectのコールは試行されません。

- 新しいアクティブな(元のスタンバイ) TimesTenノードに接続する場合、新しいサーバーDSNを指定するときを除き、元の接続リクエストから返された同じ接続文字列が使用されます。

- 新しい文ハンドルをオープンして必要なSQLPrepareコールを再実行するかどうかは、アプリケーション次第です。

- フェイルオーバーがすでに発生し、クライアントがすでに新しいアクティブ・ノードに接続されている場合、次のフェイルオーバー・リクエストでは、元のアクティブ・ノードへの再接続が試みられます。再接続に失敗した場合、タイムアウトになるまで2つのサーバーへの接続の試行が交互に行われ、この間は接続はブロックされます。タイムアウト値は、TimesTenクライアント接続属性TTC_Timeout (デフォルトは60秒)に従いますが、TTC_Timeoutの設定にかかわらず、最小値は60秒です。(この属性の詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のTTC_Timeoutに関する説明を参照してください。)

- フェイルオーバー接続は、事前に作成されるのではなく、必要に応じてのみ作成されます。

フェイルオーバーの間、TimesTenは登録されているユーザー定義関数に対してコールバックを行います。この関数は、フェイルオーバーが発生している状況で実行する必要があるカスタム処理を行います。(「フェイルオーバーのコールバック関数」を参照してください。)

次に示すパブリック接続オプションは、新しい接続に伝播されます。該当する場合は、対応する一般接続属性をカッコ内に示しています。TT_REGISTER_FAILOVER_CALLBACKオプションは、コールバック関数を登録するために使用します。

SQL_ACCESS_MODE
SQL_AUTOCOMMIT
SQL_TXN_ISOLATION (Isolation)
SQL_OPT_TRACE
SQL_QUIET_MODE
TT_PREFETCH_CLOSE
TT_CLIENT_TIMEOUT (TTC_TIMEOUT)
TT_REGISTER_FAILOVER_CALLBACK

次に示すオプションは、接続属性またはSQLSetConnectOptionコールで設定されている場合には新しい接続に伝播されますが、TimesTen組込みプロシージャまたはALTER SESSIONで設定されている場合には新しい接続に伝播されません。

TT_NLS_SORT (NLS_SORT)
TT_NLS_LENGTH_SEMANTICS (NLS_LENGTH_SEMANTICS)
TT_NLS_NCHAR_CONV_EXCP (NLS_NCHAR_CONV_EXCP)
TT_DYNAMIC_LOAD_ENABLE (DynamicLoadEnable)
TT_DYNAMIC_LOAD_ERROR_MODE (DynamicLoadErrorMode)

次に示すオプションは、接続ハンドルで設定されている場合には新しい接続に伝播されます。

SQL_QUERY_TIMEOUT
TT_PREFETCH_COUNT

自動クライアント・フェイルオーバーの構成

詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』の自動クライアント・フェイルオーバーの構成に関する説明を参照してください。

注意:
TTC_Server2、TTC_Server_DSN2またはTCP_Port2のいずれかを設定することは、暗黙的に次のことを意味します。

- ユーザーは、自動クライアント・フェイルオーバーを使用するつもりである。

- ユーザーは、フェイルオーバー・メカニズムをサポートするためにアプリケーションに新しいスレッドが作成されることを理解している。

- アプリケーションをスレッド・ライブラリにリンクしました(UNIXシステムではpthread)。

フェイルオーバーのコールバック関数

フェイルオーバーが発生すると、TimesTenは目的の処理を行うためにユーザー定義関数に対してコールバックを行います。この関数は、新しいアクティブな(元のスタンバイ)ノードへの接続試行が開始されたときにコールされ、接続の試行が完了した後に再度コールされます。たとえば、文ハンドルを正常にリストアするために、この関数を使用できます。

関数APIの定義は次のとおりです。

typedef SQLRETURN (*ttFailoverCallbackFcn_t)
(SQLHDBC,      /* hdbc    */
SQLPOINTER,   /* foCtx   */
SQLUINTEGER,  /* foType  */
SQLUINTEGER); /* foEvent */

各要素の意味は次のとおりです。

- hdbcは、障害が発生した接続のODBC接続ハンドルです。

- foCtxは、アプリケーション定義のデータ構造体に対するポインタで、必要に応じて使用します。

- foTypeは、フェイルオーバーのタイプです。これに対して、TimesTenでサポートされている値はTT_FO_SESSIONのみであり、セッションが再確立されます。この場合、文の再準備は行われません。

- foEventは、サポートされている次の値を使用して、発生したイベントを示します。

- TT_FO_BEGIN: フェイルオーバーの開始。

- TT_FO_ABORT: フェイルオーバーの失敗。TTC_Timeoutで指定した時間(アクティブ・スタンバイ・フェイルオーバーの最小値である60秒)の間、再試行が実行されましたが成功しませんでした。

- TT_FO_END: フェイルオーバーの正常終了。

- TT_FO_ERROR: フェイルオーバー接続に失敗しましたが、再試行されます。

TT_FO_REAUTHはTimesTenクライアント・フェイルオーバーではサポートされないことに注意してください。

コールバック関数を登録するには、SQLSetConnectOptionコールを使用してTimesTen TT_REGISTER_FAILOVER_CALLBACKオプションを設定し、指定するオプション値はCデータ型の構造体ttFailoverCallback_tへのポインタで、この構造体はtimesten.hファイルに次のように定義されており、コールバック関数を参照します。

typedef struct{
SQLHDBC                 appHdbc;
ttFailoverCallbackFcn_t callbackFcn;
SQLPOINTER              foCtx;
} ttFailoverCallback_t;

各要素の意味は次のとおりです。

- appHdbcはODBC接続ハンドルであり、SQLSetConnectOptionコール・シーケンスのhdbcと同じ値である必要があります。(これは、ドライバ・マネージャを使用している場合のドライバ・マネージャの実装詳細のために、データ構造体で必要になります。)

- callbackFcnは、コールバック関数を指定します。(NULLに設定すると、指定した接続のコールバックが取り消されます。フェイルオーバーは変わらずに発生しますが、アプリケーションが通知を受けることはありません。)

- foCtxは、前述の関数で説明したように、アプリケーション定義のデータ構造体に対するポインタです。

コールバックを必要とする接続ごとに、TT_REGISTER_FAILOVER_CALLBACKを設定します。ttFailoverCallback_t構造体の値は、SQLSetConnectOptionコールが実行されるときにコピーされます。アプリケーションで構造体を保持する必要はありません。TT_REGISTER_FAILOVER_CALLBACKが接続に対して複数回設定されている場合、最後の設定が優先されます。

注意:

- コールバック関数はアプリケーションのメイン・スレッドに対して非同期で実行されるため、通常、アプリケーションによってポーリングされるフラグの設定などの簡単なタスクのみを実行させる必要があります。ただし、アプリケーションがマルチスレッド用に設計されている場合は、このような制限はありません。この場合、たとえば関数でODBCコールを実行することもできますが、foEvent値TT_FO_ENDを受け取っている場合にのみ安全に実行できます。

- foCtx設定が指すデータを管理するかどうかはアプリケーション次第です。

例2-12 フェイルオーバーのコールバック関数および登録

この例では次の機能を示しています。

- グローバルに定義されるユーザー構造体タイプFOINFO、およびタイプFOINFOの構造体変数foStatus

- フェイルオーバーが発生すると常にfoStatus構造体を更新するコールバック関数FailoverCallback()

- 登録関数RegisterCallback()。次の処理を行います。

- タイプttFailoverCallback_tの構造体failoverCallbackを宣言します。

- foStatus値を初期化します。

- 接続ハンドル、foStatusへのポインタおよびコールバック関数(FailoverCallback)で構成されるfailoverCallbackデータ値を設定します。

- SQLSetConnectOptionコールを使用してコールバック関数を登録し、TT_REGISTER_FAILOVER_CALLBACKをfailoverCallbackへのポインタとして設定します。

/* user defined structure */
struct FOINFO
{
int callCount;
SQLUINTEGER lastFoEvent;
};
/* global variable passed into the callback function */
struct FOINFO foStatus;

/* the callback function */
SQLRETURN FailoverCallback (SQLHDBC hdbc,
SQLPOINTER pCtx,
SQLUINTEGER FOType,
SQLUINTEGER FOEvent)
{
struct FOINFO* pFoInfo = (struct FOINFO*) pCtx;

/* update the user defined data */
if (pFoInfo != NULL)
{
pFoInfo->callCount ++;
pFoInfo->lastFoEvent = FOEvent;

printf ("Failover Call #%d\n", pFoInfo->callCount);
}

/* the ODBC connection handle */
printf ("Failover HDBC : %p\n", hdbc);

/* pointer to user data */
printf ("Failover Data : %p\n", pCtx);

/* the type */
switch (FOType)
{
case TT_FO_SESSION:
printf ("Failover Type : TT_FO_SESSION\n");
break;

default:
printf ("Failover Type : (unknown)\n");
}

/* the event */
switch (FOEvent)
{
case TT_FO_BEGIN:
printf ("Failover Event: TT_FO_BEGIN\n");
break;

case TT_FO_END:
printf ("Failover Event: TT_FO_END\n");
break;

case TT_FO_ABORT:
printf ("Failover Event: TT_FO_ABORT\n");
break;

case TT_FO_REAUTH:
printf ("Failover Event: TT_FO_REAUTH\n");
break;

case TT_FO_ERROR:
printf ("Failover Event: TT_FO_ERROR\n");
break;

default:
printf ("Failover Event: (unknown)\n");
}

return SQL_SUCCESS;
}

/* function to register the callback with the failover connection */
SQLRETURN RegisterCallback (SQLHDBC hdbc)
{
SQLRETURN rc;
ttFailoverCallback_t failoverCallback;

/* initialize the global user defined structure */
foStatus.callCount = 0;
foStatus.lastFoEvent = -1;

/* register the connection handle, callback and the user defined structure */
failoverCallback.appHdbc = hdbc;
failoverCallback.foCtx = &foStatus;
failoverCallback.callbackFcn = FailoverCallback;

rc = SQLSetConnectOption (hdbc, TT_REGISTER_FAILOVER_CALLBACK,
(SQLULEN)&failoverCallback);

return rc;
}

フェイルオーバーが発生すると、コールバック関数は次のような出力を生成します。

Failover Call #1
Failover HDBC : 0x8198f50
Failover Data : 0x818f8ac
Failover Type : TT_FO_SESSION
Failover Event: TT_FO_BEGIN

3 TimesTenでのOCIのサポート

TimesTenおよびTimesTen Cacheでは、CまたはC++プログラム用のOracle Call Interface (OCI)がサポートされます。

この章では、OCIに関する概要およびTimesTen固有の情報について説明し、特にTimesTenでのOCIの使用とOracle DatabaseでのOCIの使用の違いについて強調します。OCIの詳細は、Oracle Databaseライブラリの『Oracle Call Interfaceプログラマーズ・ガイド』を参照してください。

第2章「ODBCでのTimesTenデータベースの使用」も参照してください。TimesTenの機能について興味深いと思われる情報が記載されています。

内容は次のとおりです。

- OCIの概要

- TimesTen OCIサポートの概要

- TimesTen OCIの使用

- TimesTen OCIでの追加機能の使用

- TimesTen OCI サポートのリファレンス

OCIの概要

OCIとは、データベースにアクセスしてSQL実行を制御するために使用可能な機能を備えたAPIのことです。OCIでは、CおよびC++プログラミング言語のデータ型、コール規則、構文およびセマンティックがサポートされています。すべてのCまたはC++プログラムと同様にOCIプログラムをコンパイルおよびリンクします。前処理またはプリコンパイルの手順はありません。

データベース・アクセスおよび検索機能のOCIライブラリは、実行時にアプリケーションにリンクできる動的なランタイム・ライブラリの形式になっています。OCIライブラリには、次の機能領域が含まれます。

- SQLアクセス機能

- データ型マッピングおよび操作機能

次に、OCIに用意されている、またはOCIでサポートされている多数の役立つ機能の一部を示します。

- 文のキャッシュ

- 動的SQL

- トランザクション制御文、セッション制御文およびシステム制御文(DML文のような)を処理する機能

- サーバー・メタデータのレイヤーを公開する記述機能

- コミット・リクエストを文の実行と関連付けてラウンドトリップを減らす機能

- ラウンドトリップを減らす透過的プリフェッチ・バッファを使用した問合せの最適化

- OCIハンドルの相互排他ロックを不要にするスレッド・セーフティ

OCIの一般的な詳細は、Oracle Databaseドキュメント・セットに含まれている『Oracle Call Interfaceプログラマーズ・ガイド』を参照してください。

TimesTen OCIサポートの概要

この章では、TimesTenおよびTimesTen CacheでのOCIの使用に固有の情報を示します。サポートされている機能、TimesTen OCIの構文および使用方法は、Oracle Databaseと同じです。

この項の内容は次のとおりです。

- OCIのライブラリおよびアーキテクチャ

- グローバリゼーション・サポート

- TimesTenの制限および相違点

- ttSrcScanユーティリティ

OCIのライブラリおよびアーキテクチャ

TimesTen OCIサポートによって、既存の数多くのOCIアプリケーションをTimesTen直接接続またはクライアント/サーバー接続で実行できます。また、OCIをデータベース・インタフェースとして使用するPro*C/C++やODP.NETなどのその他の機能を使用することもできます。(OCI、Pro*C/C++およびODP.NETアプリケーションからPL/SQLをコールすることもできます。)図3-1に、TimesTenアーキテクチャにおけるOCIサポートの位置付けを示します。

TimesTenは、OCIクライアント・ライブラリとしてOracle Instant Clientを備えています。これは、『Oracle TimesTen In-Memory Databaseインストレーション･ガイド』の環境変数に関する項で説明する、適切なttenvスクリプトを使用して構成します。

図3-1 TimesTenアーキテクチャにおけるOCI

TimesTen 11gリリース2(11.2.2)OCIはOracle Databaseリリース11.2.0.2 OCIに基づいており、現在のOCI 8スタイルのAPIをサポートしています。たとえば、OCIStmtExecute()関数はサポートされますが、これより古いoexec()関数はサポートされません。Oracle Databaseドキュメントの『Oracle Call Interfaceプログラマーズ・ガイド』の廃止されたOCIルーチンに関する説明を参照してください。

グローバリゼーション・サポート

この項では、グローバリゼーションのTimesTen OCIサポートについて説明します。

キャラクタ・セット

接続用のキャラクタ・セットを指定するには、OCIプログラムでNLS_LANG環境変数を設定するか、またはOCIEnvNlsCreate()をコールできます。NLS_LANGまたはOCIEnvNlsCreate()によって上書きされない場合、sys.odbc.iniまたはユーザーodbc.iniファイルの設定がデフォルトで使用されます。キャラクタ・セットを明示的に設定することをお薦めします。通常、デフォルトはAMERICAN_AMERICA.US7ASCIIです。

TimesTen OCIでは言語またはロケール(地域)設定はサポートされていないため、前述のAMERICAN_AMERICAなどのNLS_LANGの言語および地域コンポーネントは無視されます。ただし、言語およびロケールを指定しない場合にも、NLS_LANGの設定時にキャラクタ・セットの前にピリオドを付ける必要があります。たとえば、AMERICAN_AMERICAは無視されますが、次の設定はいずれも有効です。

NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

または

NLS_LANG=.WE8ISO8859P1

注意:

- TimesTenのキャラクタ・セットはOracle Databaseと互換性があります。

- NLS_LANG環境設定は、TimesTenのデフォルトのキャラクタ・セットよりも優先されます。

- Windowsでは、NLS_LANG設定が環境にない場合、レジストリで設定が検索されます。OCIまたはPro*C/C++プログラムによるTimesTenへの接続に問題がある場合、HKEY_LOCAL_MACHINE\Software\ORACLE\配下にあるNLS_LANGの設定が(そのキーが存在する場合は)有効であること、およびTimesTenでサポートされているキャラクタ・セットを示していることを確認します。

- NLS_LANGの詳細は、Oracle Databaseグローバリゼーション・サポート・ガイドのNLS_LANG環境変数でのロケールの選択に関する説明を参照してください。

- TimesTenのデフォルトのキャラクタ・セットはAMERICAN_AMERICA.US7ASCIIです。TIMESTEN8キャラクタ・セットはサポートされていません。『Oracle TimesTen In-Memory Databaseリファレンス』のサポートされているキャラクタ・セットに関する説明を参照してください。

- OCIコールの詳細は、『Oracle Call Interfaceプログラマーズ・ガイド』のOCIEnvNlsCreate()に関する項を参照してください。

その他のグローバリゼーション機能

TimesTen OCIでは、他に、次のグローバリゼーション機能もサポートされます。これらの機能は、環境変数、TimesTenの一般接続属性またはTimesTen ODBC接続オプションとして設定できます。接続オプションの場合、ここでは名前の先頭に「TT_」が追加されます。環境変数の設定は、対応する接続属性または接続オプションの設定よりも優先されます。接続オプションの設定は、対応する接続属性の設定よりも優先されます。

- NLS_LENGTH_SEMANTICS: デフォルトで、文字データ型CHARおよびVARCHAR2の長さは、文字数ではなくバイト数で指定します。シングルバイト文字エンコードの場合は、バイトでの指定は正しく機能します。マルチバイト文字エンコードの場合は、NLS_LENGTH_SEMANTICSを使用して、かわりに文字長セマンティクスによってCHAR列およびVARCHAR2列を作成できます。サポートされている設定は、BYTE(デフォルト)およびCHARです。(NCHAR列およびNVARCHAR2列は、常に文字ベースです。既存の列は影響を受けません。)

- NLS_SORT: 文字データのソートの種類を指定します。NLS_LANGのデフォルト値よりも優先されます。有効な値は、BINARYまたはTimesTenでサポートされているすべての言語ソート名です。たとえば、ドイツ語の言語ソート順序を指定するには、NLS_SORT=Germanと設定します。

- NLS_NCHAR_CONV_EXCP: NCHARまたはNVARCHARデータとCHARまたはVARCHAR2データの間の暗黙的または明示的なキャラクタ・タイプの変換中にデータが消失した場合に、エラーがレポートされるかどうかを指定します。有効な設定は、TRUEおよびFALSEです。デフォルト値はFALSEで、エラーはレポートされません。

これらの環境変数および関連機能の詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のグローバリゼーションのサポートに関する説明および『Oracle Databaseグローバリゼーション・サポート・ガイド』のグローバリゼーション・サポート環境の設定に関する説明を参照してください。TimesTen接続オプションのサポートについては、「SQLSetConnectOptionおよびSQLGetConnectOptionのオプションのサポート」を参照してください。

TimesTenの制限および相違点

この項では、Oracle DatabaseでのOCIとTimesTenでのOCIを比較した場合の制限事項および違いを、次の各項目について説明します。

- サポートされていないOracle Databaseの機能

- TimesTen OCIのその他の制限事項

- TimesTen OCIのその他の相違点

サポートされていないOracle Databaseの機能

TimesTenでは、TimesTenまたはTimesTen Cacheに存在しない機能に関連するOCIコールはサポートされていません。たとえば、TimesTenおよびTimesTen Cacheでは、次のOracle Database機能はサポートされていません。

- アドバンスト・キューイング

- ANYDATA

- オブジェクトのサポート

- コレクション

- カートリッジ・サービス

- ダイレクト・パス・ロード

- 日付/時間間隔

- イテレータ

- BFILE

- 暗号ツールキット

- XML DBサポート

- Spatialサービス

- イベント処理

- セッションの切替え

- スクロール可能カーソル

TimesTen OCIのその他の制限事項

TimesTen OCIには、次の制限があります。

- TypeModeデータ・ストア属性は、Oracle Databaseの動作に対応する0に設定する必要があります。

- DuplicateBindMode一般接続属性は、Oracle Databaseの動作に対応する0に設定する必要があります。

- DDLCommitBehavior一般接続属性は、Oracle Databaseの動作に対応する0に設定する必要があります。

- 非同期コールはサポートされていません。

- 接続プーリングおよびセッション・プーリングはサポートされていません。

- OCIDescribeAny()でのオブジェクトの記述は、名前による記述のみがサポートされます。PL/SQLオブジェクトの記述はサポートされていません。(「サポートされているOCIコール」に記載されているこの関数のエントリも参照してください。)

- TimesTenクライアント/サーバー自動クライアント・フェイルオーバーはサポートされていません。

- TNSPINGユーティリティでは、TimesTenへの接続は認識されていません。

- INSERT、UPDATEおよびDELETE文からの暗黙的ROWID値の取得はサポートされていません。(ただし、SELECT FOR UPDATE文ではサポートされています。)

- 結果セットを返すTimesTen組込みプロシージャは、直接にはサポートされていません。ただし、この目的にPL/SQLを使用することはできます。「OCIでPL/SQLを使用してTimesTen組込みプロシージャをコール」を参照してください。

- PL/SQLブロック、プロシージャ・コールまたは関数コールから単一のREF CURSORのみが返されます。

- OCIBindArrayOfStruct()およびOCIDefineArrayOfStruct()による構造体のバインドおよび定義は、SQL文についてはサポートされていますが、PL/SQLについてはサポートされていません。(「サポートされているOCIコール」に記載されているこれらの関数のエントリも参照してください。)

- SQL*PlusやSQL*LoaderなどのOracle Databaseユーティリティはサポートされていません。(TimesTenでは、SQL*PlusのかわりにttIsqlを、SQL*LoaderのかわりにttBulkCpを使用できます。『Oracle TimesTen In-Memory Databaseリファレンス』のユーティリティに関する説明を参照してください。)

- 配列バインド(PL/SQL文に配列をバインドする機能)は、連想配列(索引付き表またはPL/SQL表)についてはサポートされていますが、VARRAY(変数サイズ配列)やネストされた表はサポートされていません。(「TimesTen OCIでの連想配列バインド」を参照してください。)

TimesTen OCIのその他の相違点

次の点に注意してください。

- TimesTenとOracle DatabaseはどちらもXAをサポートしていますが、TimesTenではOCIを介したXAはサポートしていません。

- OCIを使用すると、TimesTenでは、DML文に対する自動コミットが自動的に無効化されます。終了時に、トランザクションを明示的にコミットするか、ロールバックする必要があります。

- TimesTenでは16進リテラルの使用方法に違いがあります。詳細は、『Oracle TimesTen In-Memory Database SQLリファレンス』の定数でHexadecimalLiteralに関する説明を参照してください。

ttSrcScanユーティリティ

既存のOCIプログラムがあり、そのプログラムでTimesTenではサポートされていないOCI機能が使用されているかどうかを確認する場合は、ttSrcScanコマンドライン・ユーティリティを使用すると、サポートされていない関数、型、型コード、属性、モードおよび定数に関してプログラムをスキャンできます。このユーティリティは、TimesTenまたはOracle Databaseがインストールされていない場合でも実行可能なスタンドアロン・ユーティリティであり、TimesTenでサポートされているどのプラットフォームでも動作します。入力としてソース・コード・ファイルを読み取り、出力としてHTMLおよびテキスト・ファイルを作成します。サポートされていない項目が検出されると、それらの項目はログに記録され、代替が示されます。ttSrcScan実行可能ファイルは、TimesTenのインストール先のquickstart/sample_utilディレクトリにあります。

入力ファイルまたはスキャン対象のプログラムのディレクトリ、およびttSrcScanレポートの出力ディレクトリを指定します。その他のオプションも使用できます。詳細は、sample_utilディレクトリにあるREADMEファイルを参照してください。

TimesTen OCIの使用

この項では、TimesTen OCIアプリケーションの開始に関する次の内容について説明します。

- TimesTen OCIの環境変数

- OCIアプリケーションのコンパイルおよびリンク

- OCIからTimesTenデータベースへの接続

- OCIエラー・レポート

- シグナル処理および診断フレームワークの考慮事項

- OCIのデモ・プログラム

TimesTen OCIの環境変数

表3-1に、TimesTen OCIアプリケーションを実行するための環境変数を示します。設定は、特に記述のないかぎり、直接接続とクライアント/サーバー接続の両方に適用されます。

環境変数は、インストール後に必要に応じて、使用オペレーティング・システムに適用可能なTimesTenのinstall_dir/bin/ttenvスクリプトまたはquickstart/ttquickstartenvスクリプトを使用して変更できます。ttenvの詳細は、『Oracle TimesTen In-Memory Databaseインストレーション・ガイド』の環境変数に関する説明を参照してください。

クイック・スタート・デモに付属のTimesTen OCIファイルおよびPro*C/C++ Makeファイルを使用して、適切な環境設定を実行することもできます。これらのファイルは次の場所にあります。

quickstart/sample_code/oci/
quickstart/sample_code/proc/

注意:
TimesTenで動作するOCIプログラムが適切に生成されるためには、OCIコンパイルにORACLE_HOMEを設定しないでください(以前に設定されていた場合は設定解除してください)。

表3-1 TimesTen OCIの環境変数

変数

必須またはオプション

設定

LD_LIBRARY_PATH (UNIX)

PATH (Windows)

必須

パス内で、TimesTen Instant ClientディレクトリがOracle Databaseライブラリより前になるように設定する必要があります。パスは、install_dirの次のいずれかのスクリプトを使用すると適切に設定されます。(2番目のパスは、標準のクイック・スタートの場所を想定しています)。

bin/ttenv
quickstart/ttquickstartenv

ttenvの詳細は、『Oracle TimesTen In-Memory Databaseインストレーション・ガイド』の環境変数に関する説明を参照してください。

TNS_ADMIN

tnsnamesネーミング・メソッドを使用する場合は必須

tnsnames.oraファイルを保存するディレクトリを指定します。これは、TimesTenがsqlnet.oraファイルを検索するディレクトリでもあります。

TWO_TASK (UNIX)

LOCAL (Windows)

オプション

OCIログオン・コールでdbname引数を指定するかわりに、この環境変数(使用プラットフォームに適したほう)を使用できます。設定は、有効なTNS名または簡易接続文字列で構成されます。

詳細は、「OCIからTimesTenデータベースへの接続」を参照してください。

NLS_LANG

オプション

「キャラクタ・セット」を参照してください。キャラクタ・セット・コンポーネントのみが適用され、TimesTenでサポートされているキャラクタ・セットを示している必要があります。言語および地域の値は無視されます。

この環境変数は、TimesTenのデフォルトのキャラクタ・セットよりも優先されます。

NLS_SORT

オプション

「その他のグローバリゼーション機能」を参照してください。ソート順序は、TimesTenでサポートされている値である必要があります。

この環境変数は、TimesTenのNLS_SORT一般接続属性よりも優先されます。

NLS_LENGTH_SEMANTICS

オプション

「その他のグローバリゼーション機能」を参照してください。

この環境変数は、TimesTenのNLS_LENGTH_SEMANTICS一般接続属性よりも優先されます。

NLS_NCHAR_CONV_EXCP

オプション

「その他のグローバリゼーション機能」を参照してください。

この環境変数は、TimesTenのNLS_NCHAR_CONV_EXCP一般接続属性よりも優先されます。

注意:
表に記載されているNLS接続属性の詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のNLS一般接続属性に関する説明を参照してください。

OCIアプリケーションのコンパイルおよびリンク

OCIアプリケーションをコンパイルおよびリンクする手順について、Oracle DatabaseとTimesTenの間に変更は必要ありません。

Oracle Client 11.2.0.2ライブラリを使用するOCIプログラムは、TimesTenで実行するために再コンパイルまたは再リンクする必要はありません。

OCIからTimesTenデータベースへの接続

TimesTen OCIでは、Oracle Instant Clientを使用してTimesTenデータベースに接続します。Oracle Databaseに接続する場合と同様に、tnsnamesまたはeasy connectのいずれかのネーミング・メソッドを使用してデータベースに接続できます。

この項の内容は次のとおりです。

- tnsnamesネーミング・メソッドを使用した接続

- 簡易接続文字列を使用した接続

- 使用する接続方法の設定(tnsnames.oraまたは簡易接続)

- OCIでの外部で識別されたユーザーとしての接続

tnsnames、簡易接続およびtnsnames.oraファイルの詳細は、『Oracle Database Net Services管理者ガイド』のネーミング・メソッドの構成に関する項を参照してください。

注意:

- sqlnetメカニズムはTimesTen OCI接続に使用されますが、接続はOracle Databasesqlnetドライバではなく、TimesTen ODBCドライバを介して行われます。

- データベースに接続する権限は、TimesTenに接続するインスタンス管理者以外の各ユーザーに、CREATE SESSION権限を使用して明示的に付与する必要があります。「接続のアクセス制御」を参照してください。

tnsnamesネーミング・メソッドを使用した接続

TimesTenでは、tnsnames構文がサポートされています。TimesTenのtnsnames.oraエントリは、Oracle Databaseのtnsnames.oraエントリを使用する場合と同じ方法で使用できます。

次に、tnsnames.oraでのTimesTenエントリの構文を示します。

tns_entry = (DESCRIPTION =
(CONNECT_DATA =
(SERVICE_NAME = dsn)
(SERVER = timesten_direct | timesten_client)))

ここで、tns_entryは、エントリに割り当てる任意のTNS名です。これは、OCILogon()、OCILogon2()およびOCIServerAttach()コールでdbname引数として使用できます。

ここで示されているように、DESCRIPTIONおよびCONNECT_DATAは必要です。

SERVICE_NAMEでは、dsnは、OCIアプリケーションを実行しているユーザーに見えるsys.odbc.iniまたはユーザーodbc.iniファイルで構成されているTimesTen DSNである必要があります。Windowsでは、DSNはODBC Data Source Administratorを使用して指定できます。『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のTimesTenデータベースの管理に関する説明を参照してください。

SERVERの場合は、timesten_directでTimesTenへの直接接続を指定するか、timesten_clientでクライアント/サーバー接続を指定します。timesten_clientを選択した場合、DSNをクライアント/サーバー・データベースとして構成する必要があります。

通常どおり、TimesTenサーバーのホストおよびポートは、sys.ttconnect.iniファイルのエントリからDSNに基づいて決定されます。『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のTimesTen ClientおよびTimesTen Serverの使用に関する項を参照してください。

次に、直接接続のtnsnames.oraエントリの例を示します。

my_tnsname = (DESCRIPTION =
(CONNECT_DATA =
(SERVICE_NAME = my_dsn)
(SERVER = timesten_direct)))

TNS名my_tnsnameは、次のいずれかの方法で使用できます。

- OCIログオン・コールでmy_tnsnameをdbname引数に指定します。

- dbnameに空の文字列を指定し、TWO_TASKまたはLOCALをmy_tnsnameに設定します。

次に例を示します。

OCILogon2(envhp, errhp, &svchp,
(text *)"user1", (ub4)strlen("user1"),
(text *)"pwd1", (ub4)strlen("pwd1"),
(text *)"my_tnsname", (ub4)strlen((char*)"my_tnsname"), OCI_DEFAULT));

OCIログオンのコール・シーケンスの詳細は、『Oracle Call Interfaceプログラマーズ・ガイド』の接続関数、認証関数および初期化関数に関する項を参照してください。

またはUNIXシステムでは、たとえば、my_tnsnameにTWO_TASKを設定し、dbnameに空の文字列を指定してOCIログオン・コールを使用します。

OCILogon2(envhp, errhp, &svchp,
(text *)"user1", (ub4)strlen("user1"),
(text *)"pwd1", (ub4)strlen("pwd1"),
(text *)"", (ub4)0, OCI_DEFAULT));

簡易接続文字列を使用した接続

TimesTenでは簡易接続構文がサポートされており、tnsnames.oraを構成しなくても接続できるため、Instant Clientパッケージがさらに便利になります。簡易接続文字列は、URLに似た次の形式の構文を使用します。

[//]host[:port]/service_name:server[/instance]

先頭のダブルスラッシュは任意です。ホスト名は、簡易接続構文を満たすように指定する必要があり、そうでない場合、TimesTenでは無視されます。慣例的に、名前localhostがよく使用されます。ポートに指定した値も無視されます。クライアント/サーバー接続では、TimesTenサーバーのホストおよびポートは、TimesTen DSNに基づいてsys.ttconnect.iniファイルのエントリから決定されます。

service_nameにDSNを指定します。必要に応じて、serverにtimesten_clientまたはtimesten_directを指定します。

TimesTenでは、instanceフィールドは無視されます。指定する必要はありません。

たとえば、次の簡易接続文字列では、クライアント/サーバー・ライブラリを使用してTimesTenサーバーに接続します。sys.odbc.iniファイルのDSN ttclientがクライアント/サーバー・データ・ソースとして解決され、sys.ttconnect.iniファイルで指定された対応するホストおよびポートに接続することを想定しています。

"localhost/ttclient:timesten_client"

次の簡易接続文字列は、TimesTenへの直接接続の場合のものです。DSN ttdirectがsys.odbc.iniで定義されることを想定しています。

"localhost/ttdirect:timesten_direct"

簡易接続文字列は次のいずれかの方法で使用できます。

- OCIログオン・コールでdbname引数に指定します。

- dbnameに空の文字列を指定し、TWO_TASKまたはLOCALに簡易接続文字列を一重引用符で囲んで設定します。

次に例を示します。

OCILogon2(envhp, errhp, &svchp,
(text *)"user1", (ub4)strlen("user1"),
(text *)"pwd1", (ub4)strlen("pwd1"),
(text *)"localhost/ttclient:timesten_client",
(ub4)strlen((char*)"localhost/ttclient:timesten_client"), OCI_DEFAULT));

OCIログオンのコール・シーケンスの詳細は、『Oracle Call Interfaceプログラマーズ・ガイド』の接続関数、認証関数および初期化関数に関する項を参照してください。

またはUNIXシステムでは、たとえば次のように、localhost/ttclient:timesten_clientにTWO_TASKを設定し、dbnameに空の文字列を指定してOCIログオン・コールを使用します。

OCILogon2(envhp, errhp, &svchp,
(text *)"user1", (ub4)strlen("user1"),
(text *)"pwd1", (ub4)strlen("pwd1"),
(text *)"", (ub4)0, OCI_DEFAULT));

使用する接続方法の設定(tnsnames.oraまたは簡易接続)

sqlnet.oraファイルが存在する場合、このファイルは、試行するネーミング・メソッドおよびその試行順序を指定します。Instant Clientは、TNS_ADMINの場所でsqlnet.oraファイルを検索します(該当する場合)。TNS_ADMINではなくORACLE_HOMEが設定されている場合(以前のInstant Clientをインストールしていた場合など)、デフォルトのsqlnet.oraの場所は、Oracle Databaseのデフォルトの場所になります(Oracle Database Net Servicesリファレンスのsqlnet.oraファイルのパラメータに関する説明を参照)。

sqlnet.oraが存在していても、特定のネーミング・メソッドを指定していない場合、そのメソッドは使用できません。sqlnet.oraが存在しない場合は、いずれのメソッドも使用できます。

TimesTenでは、tnsnames.oraおよびsqlnet.oraのサンプル・コピーはinstall_dir/network/admin/samplesディレクトリにあります。次に、TimesTenに用意されているsqlnet.oraファイルを示しますが、このファイルでは、tnsnamesと簡易接続(EZCONNECT)の両方がサポートされます。

# To use ezconnect syntax or tnsnames, the following entries must be
# included in the sqlnet.ora configuration.
#
NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)

TimesTenでは、このファイルによって、最初にOCIログオン・コール内のtnsnames構文が検索されます。tnsnames構文を検出できなかった場合、簡易接続構文が検索されます。

OCIでの外部で識別されたユーザーとしての接続

[myadmin]のようにユーザー名を大カッコ内に指定し、パスワードを空の文字列("")として指定することで、OCIを介して外部で識別されたユーザー(外部ユーザー)として接続できます。

特に、TimesTenでは常に外部ユーザーであるインスタンス管理者として接続する場合に有効です。

外部で識別されたユーザーは、直接モードまたはローカル･ホスト上のデータベースへのクライアント/サーバー接続に使用できますが、リモート・ホスト上のデータベースへのクライアント/サーバー接続には使用できません。

前述の例を次のように変更します。

OCILogon2(envhp, errhp, &svchp,
(text *)"[myadmin]", (ub4)strlen("[myadmin]"),
(text *)"", (ub4)strlen(""),
(text *)"my_tnsname", (ub4)strlen((char*)"my_tnsname"), OCI_DEFAULT));

この機能はOCIプロキシ構文を使用します。『Oracle Call Interfaceプログラマーズ・ガイド』のプロキシを介したクライアント・アクセスに関する説明を参照してください。

OCI エラー・レポート

TimesTen OCIアプリケーションのエラーでは、Oracle Databaseのエラー・コードが返されます。TimesTenでは、同様の状況でOracleがレポートするOracle Databaseエラー・コードと同じエラー・コードをレポートしようとします。エラー・メッセージは、TimesTenカタログまたはOracle Databaseカタログのいずれかから取得されます。エラー・メッセージによっては、TimesTenエラー・コードを伴う場合もあります(該当する場合)。

致命的なエラーとは、エラー・リカバリが終わるまでデータベースにアクセスできなくなるエラーのことです。致命的なエラーが発生すると、メモリー不足状態を回避するために、すべてのデータベースの接続を切断する必要があります。それ以後の処理は完了されません。古いTimesTenインスタンスの共有メモリーは、エラー発生時にアクティブだったすべての接続が切断されるまで解放されません。

OCIでの致命的なエラーは、Oracle Databaseエラー・コードORA-03135またはORA-00600で示されます。これらのエラーの処理は、標準的なエラーの処理とは異なります。特に、アプリケーションのエラー処理コードにデータベースとの接続を切断するコードを含める必要があります。

シグナル処理および診断フレームワークの考慮事項

OCIの診断フレームワークでは、アプリケーションで使用しているすべてのシグナル処理に影響する可能性のあるシグナル・ハンドラがインストールされます。OCIのシグナル処理は、sqlnet.oraファイルにDIAG_SIGHANDLER_ENABLED=FALSEを設定することで無効化できます。詳細は、『Oracle Call Interfaceプログラマーズ・ガイド』のOCIの障害診断に関する説明を参照してください。

OCIのデモ・プログラム

TimesTenにはOCIデモ・プログラムが付属しています。これらのプログラムはquickstart/sample_code/ociディレクトリにあります。このディレクトリのREADMEファイルに、デモのコンパイル方法および実行方法が記載されています。

詳細は、クイック・スタートのようこそページ(install_dir/quickstart.html)を参照してください。

TimesTen OCIでの追加機能の使用

この項では、TimesTen OCIを使用する開発者向けに次の内容について説明します。

- TimesTenの遅延準備

- TimesTen OCIでのパラメータのバインド機能

- TimesTen OCIでのTimesTen Cache

- TimesTen OCIでのLOB

- OCIでPL/SQLを使用してTimesTen組込みプロシージャをコール

TimesTenの遅延準備

OCIでは、準備コールはクライアントで実行される軽量処理であることが期待されています。TimesTenでこの期待との一貫性を実現し、クライアントとサーバー間の不要なラウンドトリップを回避するため、TimesTenクライアント・ライブラリに実装されたSQLPrepareでは、遅延準備と呼ばれる処理が実行されますが、この処理では、リクエストは要求されるまでサーバーに送信されません。詳細は、「TimesTenの遅延準備」を参照してください。

TimesTen OCIでのパラメータのバインド機能

この項では、OCIアプリケーションからSQLまたはPL/SQLへのパラメータのバインドに関連する機能について説明します。

- TimesTen OCIでの重複したパラメータのバインド

- TimesTen OCIでの連想配列バインド

TimesTen OCIでの重複したパラメータのバインド

SQL文で重複したパラメータをバインドするための、2つのサポートされているモード(Oracleモードまたは従来のTimesTenモード)については、「SQL文での重複したパラメータのバインド」を参照してください。その項と同様に、次の問合せについて検討します。TimesTen OCIでは、Oracleモードのみがサポートされていることに注意してください。

SELECT * FROM employees
WHERE employee_id < :a AND manager_id > :a AND salary < :b;

OCIでは、通常、Oracleモードの場合と同様に、パラメータaが2回出現すると別のパラメータとみなされます。ただし、OCIでは、aを両方ともOCIBindByPos()への1つのコールとバインドすることができます。

OCIBindByPos(..., 1, ...); /* both occurrences of :a */
OCIBindByPos(..., 3, ...); /* occurrence of :b */

また、OCIでは2つのaを別々にバインドすることもできます。

OCIBindByPos(..., 1, ...); /* first occurrence of :a */
OCIBindByPos(..., 2, ...); /* second occurrence of :a */
OCIBindByPos(..., 3, ...); /* occurrence of :b */

両方の場合で、パラメータbは位置3に存在するとみなされていることに注意してください。

注意:
また、OCIでは、OCIBindByName()を使用して位置ではなく、名前でバインドすることもできます。

TimesTen OCIでの連想配列バインド

連想配列(以前の索引付き表またはPL/SQL表)は、TimesTen PL/SQLでは、(たとえばOCIアプリケーションからの)IN、OUTまたはIN OUTバインド・パラメータとしてサポートされます。これにより、アプリケーションとデータベース間で効率的に配列データを渡すことができます。

連想配列は、キー/値のペアのセットです。TimesTenでは、連想配列バインド(PL/SQL内でのみの連想配列の使用を除く)、キーまたは索引は、整数(BINARY_INTEGERまたはPLS_INTEGER)である必要があります。値は、同じデータ型を持つ単純なスカラー値である必要があります。たとえば、部門番号で索引付けされた部門マネージャの配列になります。索引は、作成された順序ではなく、ソートされた順序で格納されます。

次の例のように、PL/SQLから連想配列の型を宣言し、次に連想配列を宣言できます(INDEX BYに注意)。

declare
TYPE VARCHARARRTYP IS TABLE OF VARCHAR2(30) INDEX BY BINARY_INTEGER;
x VARCHARARRTYP;
...

Pro*C/C++の場合は、「TimesTen Pro*C/C++での連想配列バインド」を参照してください。

詳細は、Oracle TimesTen In-Memory Database PL/SQL開発者ガイドのアプリケーションからの連想配列の使用に関する説明を参照してください。

注意:
次のTimesTenでの制限事項に注意してください。

- 連想配列のバインドでは、LOB、REF CURSOR、TIMESTAMP、ROWIDはサポートされていません。

- パススルー文では連想配列バインドは許可されていません。

- TimesTen OCIでは、配列の一般的なバルク・バインドはサポートされていません。VARRAYおよびネストした表は、バインド・パラメータとしてはサポートされていません。

TimesTenでは、OCIBindByName()およびOCIBindByPos()関数のmaxarr_lenおよび*curelepパラメータをサポートすることによって、OCIでの連想配列バインドがサポートされています。これらのパラメータは、バインドが連想配列であることを示すために使用されます。

これらの関数の完全なコール・シーケンスは次のとおりです。

sword OCIBindByName ( OCIStmt *stmtp,
OCIBind **bindpp,
OCIError *errhp,
const OraText *placeholder,
sb4 placeh_len,
void *valuep,
sb4 value_sz,
ub2 dty,
void *indp,
ub2 *alenp,
ub2 *rcodep,
ub4 maxarr_len,
ub4 *curelep,
ub4 mode );

sword OCIBindByPos ( OCIStmt *stmtp,
OCIBind **bindpp,
OCIError *errhp,
ub4 position,
void *valuep,
sb4 value_sz,
ub2 dty,
void *indp,
ub2 *alenp,
ub2 *rcodep,
ub4 maxarr_len,
ub4 *curelep,
ub4 mode );

maxarr_lenおよび*curelepパラメータで連想配列をバインドする場合、次のように使用されます。(連想配列をバインドしない場合は、0(ゼロ)に設定してください。)

- maxarr_len: これは、配列の最大長を示す入力パラメータです。これは、連想配列が対応できる要素の最大数です。

- *curelep: これは、現在の配列の長さを示す入力/出力パラメータです。文の実行前後の連想配列での実際の要素の数へのポインタです。

これらの関数の詳細は、『Oracle Call Interfaceプログラマーズ・ガイド』のOCIBindByName()およびOCIBindByPos()に関する説明を参照してください。

注意:
TimesTenでは、OCIBindDynamic()関数およびOCIBindByName()とOCIBindByPos()に対するOCI_DATA_AT_EXECモード設定はサポートされていません。(Oracle Databaseでは、OCIBindDynamic()を使用して、データをat execモードで提供または受信し、実行時に追加のバインド属性を設定するためのユーザー定義のコールバック関数を登録できます。)

例3-1では、OCIアプリケーションは、PL/SQLプロシージャで、整数配列および文字配列を対応するOUT連想配列にバインドします。

例3-1 OCIからの連想配列へのバインド

次のSQL設定を前提とします。

DROP TABLE FOO;

CREATE TABLE FOO (CNUM INTEGER,
CVC2 VARCHAR2(20));

INSERT INTO FOO VALUES ( null,
'VARCHAR  1');
INSERT INTO FOO VALUES (-102,
null);
INSERT INTO FOO VALUES ( 103,
'VARCHAR  3');
INSERT INTO FOO VALUES (-104,
'VARCHAR  4');
INSERT INTO FOO VALUES ( 105,
'VARCHAR  5');
INSERT INTO FOO VALUES ( 106,
'VARCHAR  6');
INSERT INTO FOO VALUES ( 107,
'VARCHAR  7');
INSERT INTO FOO VALUES ( 108,
'VARCHAR  8');

COMMIT;

次のPL/SQLパッケージ定義を前提とします。これには、プロシージャP1の定義内の出力連想配列c1およびc2のそれぞれに使用される、INTEGER連想配列タイプNUMARRTYPおよびVARCHAR2連想配列タイプVCHARRTYPがあります。

CREATE OR REPLACE PACKAGE PKG1 AS
TYPE NUMARRTYP IS TABLE OF INTEGER INDEX BY BINARY_INTEGER;
TYPE VCHARRTYP IS TABLE OF VARCHAR2(20) INDEX BY BINARY_INTEGER;

PROCEDURE P1(c1 OUT NUMARRTYP,c2 OUT VCHARRTYP);

END PKG1;
/

CREATE OR REPLACE PACKAGE BODY PKG1 AS

CURSOR CUR1 IS SELECT CNUM, CVC2 FROM FOO;

PROCEDURE P1(c1 OUT NUMARRTYP,c2 OUT VCHARRTYP) IS
BEGIN
IF NOT CUR1%ISOPEN  THEN
OPEN CUR1;
END IF;
FOR i IN 1..8 LOOP
FETCH CUR1 INTO c1(i), c2(i);
IF CUR1%NOTFOUND THEN
CLOSE CUR1;
EXIT;
END IF;
END LOOP;
END P1;

END PKG1;

次のOCIプログラムは、PKG1.P1をコールし、配列をP1出力連想配列にバインドし、バインドした連想配列の内容を出力します。特にOCIBindByName()関数は、バインドを行うためにコールすることに注意してください。

static OCIEnv *envhp;
static OCIServer *srvhp;
static OCISvcCtx *svchp;
static OCIError *errhp;
static OCISession *authp;
static OCIStmt *stmthp;
static OCIBind *bndhp[MAXCOLS];
static OCIBind *dfnhp[MAXCOLS];

STATICF VOID outbnd_1()
{
int   i;
int   num[MAXROWS];
char*   vch[MAXROWS][20];

unsigned int    numcnt   = 5;
unsigned int    vchcnt = 5;

unsigned short    alen_num[MAXROWS];
unsigned short    alen_vch[MAXROWS];
unsigned short    rc_num[MAXROWS];
unsigned short    rc_vch[MAXROWS];

short    indp_num[MAXROWS];
short    indp_vch[MAXROWS];

/* Assume the process is connected and srvhp, svchp, errhp, authp, and stmthp
are all allocated/initialized/etc. */

char  *sqlstmt = (char *)"BEGIN PKG1.P1(:c1, :c2); END; ";

for (i = 0; i < MAXROWS; i++)
{
alen_num[i] = 0;
alen_vch[i] = 0;
rc_num[i] = 0;
rc_vch[i] = 0;
indp_num[i] = 0;
indp_vch[i] = 0;
}

DISCARD printf("Running outbnd_1.\n");
DISCARD printf("\n----> %s\n", sqlstmt);
checkerr(errhp, OCIStmtPrepare(stmthp, errhp, sqlstmt,
(unsigned int)strlen((char *)sqlstmt),
(unsigned int) OCI_NTV_SYNTAX, (unsigned int) OCI_DEFAULT));

bndhp[0] = 0;
bndhp[1] = 0;

checkerr(errhp, OCIBindByName(stmthp, &bndhp[0], errhp,
(char *) ":c1", (sb4) strlen((char *) ":c1"),
(dvoid *) &num[0], (sb4) sizeof(num[0]), SQLT_INT,
(dvoid *) &indp_num[0], (unsigned short *) &alen_num[0],
(unsigned short *) &rc_num[0],
(unsigned int) MAXROWS, (unsigned int *) &numcnt,
(unsigned int) OCI_DEFAULT));

checkerr(errhp, OCIBindByName(stmthp, &bndhp[1], errhp,
(char *) ":c2", (sb4) strlen((char *) ":c2"),
(dvoid *) vch[0], (sb4) sizeof(vch[0]), SQLT_CHR,
(dvoid *) &indp_vch[0], (unsigned short *) &alen_vch[0],
(unsigned short *) &rc_vch[0],
(unsigned int) MAXROWS, (unsigned int *) &vchcnt,
(unsigned int) OCI_DEFAULT));

DISCARD printf("\nTo execute the PL/SQL statement.\n");

checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (unsigned int) 1,
(unsigned int) 0, (const OCISnapshot*) 0,
(OCISnapshot*) 0,  (unsigned int) OCI_DEFAULT));

DISCARD printf("\nHere are the results:\n\n");

DISCARD printf("Column 1, INTEGER: \n");
for (i = 0; i < numcnt; i++)
{
if (indp_num[i] == -1)
DISCARD printf("-NULL- ");
else
DISCARD printf("%5d, ", num[i]);
DISCARD printf("ind = %d,  len = %d, rc = %d\n",
indp_num[i], alen_num[i], rc_num[i]);
}

DISCARD printf("\nColumn 2, VARCHAR2(20): \n");
for (i = 0; i < vchcnt; i++)
{
if (indp_vch[i] == -1)
DISCARD printf("-NULL-      ");
else
DISCARD printf("%.*s, ", alen_vch[i], vch[i]);
DISCARD printf("ind = %d,  len = %d, rc = %d\n",
indp_vch[i], alen_vch[i], rc_vch[i]);
}

DISCARD printf("\nDone\n");
return;
}

注意:
alen_*配列は長さの配列、rc_*配列はリターン・コードの配列、indp_*配列はインジケータの配列です。

TimesTen OCIでのTimesTen Cache

この項では、TimesTen Cacheの使用に関するTimesTen OCI機能について説明します。

- OCIでのTimesTen Cache用Oracle Databaseパスワードの指定

- アクションの影響を受けるキャッシュ・グループの数の確認

OCIでのTimesTen Cache用Oracle Databaseパスワードの指定

TimesTen Cacheを使用するには、キャッシュされたOracle Database表からの選択およびその更新が可能なOracle Databaseユーザーと同じ名前を持つキャッシュ・ユーザーがTimesTenデータベースに存在している必要があります。たとえば、このOracle Databaseユーザーは、キャッシュ管理ユーザーまたはスキーマ・ユーザーになります。TimesTenキャッシュ・ユーザーのパスワードは、同じ名前を持つOracle Databaseユーザーと別のパスワードにすることができます。詳細は、『Oracle TimesTen Application-Tier Database Cacheユーザーズ・ガイド』のキャッシュ・インフラストラクチャの設定に関する説明を参照してください。

OCIをTimesTen Cacheで使用する場合、TimesTenでは、TimesTenへのログイン時にOCILogon()またはOCILogon2()コールのパスワード・フィールドにOracle Databaseユーザーのパスワードを追加することで、OCIを介してOracle Databaseユーザーのパスワードを渡すことができます。次の例のように、接続文字列で属性OraclePWDを使用します。

text *cacheuser = (text *)"cacheuser1";
text *cachepwds = (text *)"ttpwd;OraclePWD=orclpwd";
text *ttdbname = (text *)"tt_tnsname";
....
OCILogon2(envhp, errhp, &svchp,
(text *)cacheuser, (ub4)strlen(cacheuser),
(text *)cachepwds, (ub4)strlen(cachepwds),
(text *)ttdbname, (ub4)strlen(ttdbname), OCI_DEFAULT));

Oracle DatabaseユーザーのパスワードがTimesTenユーザーのパスワードと同じ場合でも、常にOraclePWDを指定する必要があります。

この例での指定内容は次のとおりです。

- TimesTenキャッシュ・ユーザーの名前(キャッシュされたOracle Database表にアクセスできるOracle Databaseユーザーの名前)は、cacheuser1です。

- TimesTenキャッシュ・ユーザーのパスワードはttpwdです。

- Oracle Databaseユーザーのパスワードは、orclpwdです。

- 接続するTimesTenデータベースのTNS名は、tt_tnsnameです。

Oracle Databaseは、sys.odbc.iniファイルまたはユーザーodbc.iniファイルのTimesTen OracleNetServiceName一般接続属性を使用して指定します。

あるいは、TNS名を使用するかわりに、簡易接続構文またはTWO_TASK環境変数かLOCAL環境変数を使用することもできます(前述の項を参照)。

アクションの影響を受けるキャッシュ・グループの数の確認

TimesTen OCIでは、FLUSH CACHE GROUP、LOAD CACHE GROUP、REFRESH CACHE GROUPまたはUNLOAD CACHE GROUP文の実行の後、OCI_ATTR_ROW_COUNT引数を指定したOCI関数OCIAttrGet()を使用すると、フラッシュ、ロード、リフレッシュまたはアンロードされたキャッシュ・インスタンスの数が返されます。

詳細は、『Oracle TimesTen Application-Tier Database Cacheユーザーズ・ガイド』の処理の影響を受けるキャッシュ・インスタンスの数の確認に関する説明を参照してください。

TimesTen OCIでのLOB

TimesTenではLOB(ラージ・オブジェクト)がサポートされています。これには、CLOB(Character LOB)、NCLOB(National Character LOB)およびBLOB(Binary LOB)が含まれます。

「LOBの使用」を参照してください。この項はODBC向けですが、LOBの概要、TimesTenとOracle Database LOBの違いおよびLOBのプログラミング・インタフェースについて説明しています。

この項では、LOBロケータ、一時LOBおよびOCI LOBのAPIおよび機能に重点を置いています。

TimesTenでのLOBの追加情報は、『Oracle TimesTen In-Memory Database SQLリファレンス』のLOBのデータ型に関する説明を参照してください。

TimesTenでは、BFILE、SecureFile、LOBに対する配列読取りおよび書込みまたはLOBのコールバック関数をサポートしていないことに注意し、LOBの詳細情報およびOCIでの使用方法は、『Oracle Call Interfaceプログラマーズ・ガイド』のLOBおよびBFILEの操作に関する説明を参照してください。

OCIに関して、次の内容について説明します。

- OCIでのLOBロケータ

- OCIでの一時LOB

- OCIでのTimesTen LOBとOracle Database LOBの相違点

- OCIでのLOBの簡易データ・インタフェースの使用

- OCIでのLOBロケータ・インタフェースの使用

- OCIクライアント側のバッファリング

- OCIでのLOBのプリフェッチ

- OCIでのパススルーLOB

注意:
LOBのピース単位のデータ・インタフェースは、TimesTenでのOCIアプリケーションには適用されません。(ただし、LOBロケータ・インタフェースの機能を介して、LOBデータを分割して操作することはできます。)

OCIでのLOBロケータ

OCIでは、LOBロケータ・インタフェースが提供されており、インタフェースでは、LOBロケータとLOB値でLOBが構成されます。ロケータは値に対するハンドルとして機能します。アプリケーションがデータベースからLOBを選択すると、ロケータを受信ます。LOBの更新はロケータを介して行われます。LOBをパラメータとして渡す場合、実際の値ではなくロケータが渡されます。「OCIでのLOBロケータ・インタフェースの使用」を参照してください。(OCIでは、ロケータが関与しない簡易データ・インタフェースも使用できます。「OCIでのLOBの簡易データ・インタフェースの使用」を参照してください。)

LOBを更新するには、トランザクションでLOBが含まれる行に対する排他ロックが必要です。この操作を行うには、SELECT ... FOR UPDATE文でLOBを選択します。これを行うと、ロケータが書込み可能になります。単純なSELECT文では、ロケータは読取り専用です。読取り専用ロケータおよび書込み可能なロケータの動作は、次のとおりです。

- 読取り専用ロケータは読取り一貫性で、これは、有効期間を通して選択された時点のLOBの内容のみが確認されるという意味です。これには、LOBが選択されるより前の同じトランザクション内でLOBに対して行われた、コミットされていない更新も含まれることに注意してください。

- 書込み可能なロケータは、ロケータを介して書込みが行われるたびに、データベースからの最新データで更新されます。そのため、各書込みは最新のLOBのデータに対して行われ、他のロケータに対して行われた更新も含まれます。

次の例は、同じLOBに対する2つの書込み可能なロケータの動作を示します。

1. LOB列に「XY」が含まれています。

2. ロケータL1を選択して更新します。

3. ロケータL2を選択して更新します。

4. L1を介してオフセット1に「Z」を書き込みます。

5. ロケータL1を介して読み取ります。「ZY」が戻されます。

6. ロケータL2を介して読み取ります。L2は書込みに使用されるまで読取り一貫性を維持するため、「XY」が戻されます。

7. L2を介してオフセット2に「W」を書き込みます。

8. ロケータL2を介して読み取ります。「ZW」が戻されます。前述の手順の書込みの前に、ロケータが最新データ(「ZY」)で更新されました。

OCIでの一時LOB

一時LOBはアプリケーション内にのみ存在し、TimesTen OCIでは、存続期間は作成されたトランザクションを超えません(TimesTenでのすべてのLOBロケータの存続期間と同様)。一時LOBをLOBデータのスクラッチ領域と考えることができます。

OCIアプリケーションは、アプリケーション内で使用するために、適切なAPIを介して、一時LOBをインスタンス化できます。(「OCIでのLOBロケータ・インタフェースの使用」を参照してください。)一時LOBは、TimesTenによって暗黙的に作成されることもあります。たとえば、SELECT文で追加の文字列が連結されたLOBを選択した場合に、連結されたデータを含むためにTimesTenによって一時LOBが作成され、OCIアプリケーションは、その一時LOBのロケータを受信します。

一時LOBは、TimesTenの一時データ領域に格納されます。

OCIでのTimesTen LOBとOracle Database LOBの相違点

TimesTen LOB実装とOracle Database実装の主な違いは、TimesTenでは、LOBロケータはトランザクションの終了後は有効ではないことです。すべてのLOBロケータは、(明示的、暗黙的のどちらの場合も)コミットまたはロールバックの後は無効化されます。これには、TimesTen DDLCommitBehaviorが0(ゼロ)(デフォルト)に設定されている場合(Oracle Databaseの動作に対応)、すべてのDDL文の実行後が含まれます。

「TimesTen LOBとOracle Database LOBの相違点」も参照してください。

OCIでのLOBの簡易データ・インタフェースの使用

簡易データ・インタフェースでは、その他のスカラー・データ型と同様に、バインドおよび定義することによって、アプリケーションによるLOBデータへのアクセスが可能です。アプリケーションでは、対応する変数タイプと互換性のあるLOB型を使用できます。OCIStmtPrepare()を使用して、文を準備します。パラメータのバインドには、OCIBindByName()またはOCIBindByPos()を使用します。結果列の定義には、OCIDefineByPos()を使用します。

たとえば、OCIアプリケーションは、データ型がSQLT_CHRのOCIBindByName()をコールすることによって、CLOBパラメータをバインドできます。OCIStmtExecute()を使用して文を実行します。NCLOBパラメータの場合は、データ型SQLT_CHRを使用し、OCIのcsform属性(OCI_ATTR_CHARSET_FORM)をSQLCS_NCHARに設定します。BLOBパラメータの場合は、データ型SQLT_BINを使用できます。

OCIを介した簡易データ・インタフェースの使用例を次に示します。

注意:
簡易データ・インタフェース(OCIBindByName()、OCIBindByPos()またはOCIDefineByPos())のバインドのサイズは64KBに制限されます。

例3-2 表および変数の例

以降の例では、ここに表示されている表および変数を前提にします。

person(ssn number, resume clob)

OCIEnv *envhp;
OCIServer *srvhp;
OCISvcCtx *svchp;
OCIError *errhp;
OCISession *authp;
OCIStmt *stmthp;

/* Bind Handles */
OCIBind *bndp1 = (OCIBind *) NULL;
OCIBind *bndp2 = (OCIBind *) NULL;

/* Define Handles */
OCIDefine *defnp1 = (OCIDefine *) NULL;
OCIDefine *defnp2 = (OCIDefine *) NULL;

#define DATA_SIZE 50
#define PIECE_SIZE 10
#define NPIECE (DATA_SIZE/PIECE_SIZE)

char col2[DATA_SIZE];
char col2Res[DATA_SIZE];
ub2 col2len = DATA_SIZE;
sb4 ssn = 123456;
...

text *ins_stmt = (text *)"INSERT INTO PERSON VALUES (:1, :2)";
text *sel_stmt = (text *)"SELECT * FROM PERSON_1 ORDER BY SSN";
...

表3-3 簡易データ・インタフェースを使用したLOBデータの挿入

この例では、OCIでの簡易データ・インタフェースを使用してINSERT文を実行します。この例では、変数ins_stmtで定義したINSERT文を含む、前述の例3-2の表および変数を使用します。

for (i=0;i<DATA_SIZE;i++)
col2[i] = 'A';

/* prepare SQL insert statement */
OCIStmtPrepare (stmthp, errhp, ins_stmt, strlen(ins_stmt), OCI_NTV_SYNTAX,
OCI_DEFAULT);

/* bind parameters 1 and 2 using OCI_DEFAULT (not data-at-exec) */
OCIBindByPos (stmthp, &bndp1, errhp, 1, (dvoid *) &ssn, sizeof(ssn),
SQLT_INT, 0, 0, 0, 0, 0, OCI_DEFAULT);
OCIBindByPos (stmthp, &bndp2, errhp, 2, (dvoid *) col2, col2len,
SQLT_CHR, 0, 0, 0, 0, 0, OCI_DEFAULT);

/* execute insert statement */
OCIStmtExecute (svchp, stmthp, errhp, 1, 0, 0, 0, OCI_DEFAULT);

表3-4 簡易データ・インタフェースを使用したLOBデータの選択

この例では、OCIでの簡易データ・インタフェースを使用してSELECT文を実行します。この例では、変数sel_stmtで定義したSELECT文を含む、前述の例3-2の表および変数を使用します。

/* prepare select statement */
OCIStmtPrepare (stmthp, errhp, sel_stmt, strlen(sel_stmt), OCI_NTV_SYNTAX,
OCI_DEFAULT);

/* define result columns 1 and 2 using OCI_DEFAULT (not data-at-exec) */
OCIDefineByPos (stmthp, &defnp1, errhp, 1, (dvoid*) &ssn, sizeof(ssn),
SQLT_INT, 0, 0, 0, OCI_DEFAULT);
OCIDefineByPos (stmthp, &defnp2, errhp, 2, (dvoid *) col2Res, sizeof(col2),
SQLT_CHR, 0, &col2len, 0, OCI_DEFAULT);

/* execute select statement */
OCIStmtExecute (svchp, stmthp, errhp, (ub4)1, (ub4)0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT));

/* col2Res should now have a DATA_SIZE sized string of 'A's. */

OCIでのLOBロケータ・インタフェースの使用

OCI LOBロケータ・インタフェースは、データベースまたは一時LOB(ピース単位またはチャンク全体)のどちらとも使用できます。

LOBロケータ・インタフェースを使用するには、アプリケーションに有効なLOBロケータが必要です。一時LOBの場合、これは、OCILobCreateTemporary()コールにより明示的に、または一時LOBを作成するSQL文(たとえば、SELECT c1 || c2 FROM myclob)により暗黙的に取得できます。永続LOBの場合は、SQL文を使用してデータベースからLOBロケータを取得します。(例はこの項で後述します。)

バインド・タイプは、CLOBではSQLT_CLOB、BLOBではSQLT_BLOBです。NCLOBの場合は、SQLT_CLOBを使用し、OCIのcsform属性(OCI_ATTR_CHARSET_FORM)をSQLCS_NCHARに設定します。

TimesTenでは、特にBFILE、SecureFile、LOBに対する配列の読取りおよび書込みまたはLOBのコールバック関数を対象とした機能がサポートされていないことに注意し、詳細情報とOCI LOB関数のその他の例は、『Oracle Call Interfaceプログラマーズ・ガイド』のLOBの関数に関する説明を参照してください。

重要:
LOBロケータを使用してAPIを介してLOBを操作すると、TimesTenの一時領域を使用することになります。このような操作を多数行うことで、TimesTenの一時データ領域のサイズ増加が必要となる場合があります。『Oracle TimesTen In-Memory Databaseリファレンス』のTempSizeに関する説明を参照してください。

注意:

- 無効のLOBロケータが、OCILobLocatorAssign()を使用して、別のLOBロケータに割り当てられている場合、割当て先も解放され、無効のマークが設定されます。

- OCILobLocatorAssign()は一時LOBに対して使用できますが、OCILobAssign()は使用できません。

OCIでの一時LOBの作成

OCIアプリケーションは、ロケータを割り当てるためのOCIDescriptorAlloc()の最初のコール後に、LOBロケータの入力/出力パラメータを含むOCILobCreateTemporary()関数を使用して一時LOBを作成できます。終了後に、OCIDescriptorFree()を使用してロケータの割当てを解放し、OCILobFreeTemporary()を使用して一時LOB自身を解放します。

重要:
TimesTenでは、一時LOBを作成すると、データベース・トランザクションがまだ進行していない場合は、データベース・トランザクションが作成されます。エラーとなる状況を回避するには、コミットまたはロールバックを実行してトランザクションをクローズする必要があります。

TimesTenでは、Oracle Databaseによってサポートされるすべての期間(OCI_DURATION_SESSION、 OCI_DURATION_TRANSACTIONまたはOCI_DURATION_CALL)は、OCILobCreateTemporary()で許容されますが、TimesTenでは、一時LOBの存続期間はトランザクション存続期間を超えることはありません。

次のシナリオでは、一時LOBの存続期間はトランザクション存続期間より短くなることに注意してください。

- OCI_DURATION_CALLが指定されている場合

- トランザクションの終了前に、アプリケーションが、ロケータでOCILobFreeTemporary()をコールした場合

- アプリケーションで、一時LOBのユーザーが指定した期間を開始するためにOCIDurationBegin()をコールし、トランザクションの終了前にOCIDurationEnd()をコールした場合

前述したOCI LOB関数の一部の例を次に示します。一時LOBの使用の詳細と完全な例は、『Oracle Call Interfaceプログラマーズ・ガイド』の一時LOBのサポートに関する説明を参照してください。

if (OCIDescriptorAlloc((void*)envhp, (void **)&tblob,(ub4)OCI_DTYPE_LOB,
(size_t)0, (void**)0))
{
printf("failed in OCIDescriptor Alloc in select_and_createtemp \n");
return OCI_ERROR;
}

...

if (OCILobCreateTemporary(svchp, errhp, tblob, (ub2)0, SQLCS_IMPLICIT,
OCI_TEMP_BLOB, OCI_ATTR_NOCACHE, OCI_DURATION_TRANSACTION))
{
(void) printf("FAILED: OCILobCreateTemporary() \n");
return OCI_ERROR;
}

...

if(OCILobFreeTemporary(svchp,errhp,tblob))
{
printf ("FAILED: OCILobFreeTemporary() call \n");
return OCI_ERROR;
}

OCIでの永続LOBのロケータへのアクセス

アプリケーションでは通常、SQL文を使用してLOBロケータを取得またはロケータにアクセスし、次に、適切なAPI関数をロケータに渡すことによって、データベースからLOBにアクセスします。

EMPTY_CLOB()またはEMPTY_BLOB() SQL関数を使用して作成されたLOBには、有効なロケータがあり、アプリケーションはこのロケータを使用し、選択することでLOBにデータを挿入します。

次の表定義を想定します。

CREATE TABLE clobtable (x NUMBER, y DATE, z VARCHAR2(30), lobcol CLOB);

1. INSERT文を準備します。次に例を示します。

INSERT INTO clobtable ( x, y, z, lobcol )
VALUES ( 81, sysdate, 'giants', EMPTY_CLOB() )
RETURNING lobcol INTO :a;

または、データを使用してLOBを初期化します。

INSERT INTO clobtable ( x, y, z, lobcol )
VALUES ( 81, sysdate, 'giants', 'The Giants finally won a World Series' )
RETURNING lobcol INTO :a;

2. 記載されているとおり、LOBロケータを:aにバインドします。

3. 文を実行します。実行後、ロケータは新しく作成されたLOBを参照します。

アプリケーションは、LOBロケータ・インタフェースを使用して、ロケータを介してLOBデータの読取りまたは書込みが可能です。

または、アプリケーションはSELECT文を使用して、既存LOBのロケータにアクセスできます。

例3-5 LOBロケータ・インタフェースを使用したLOBロケータの選択

この例では、次の表を使用します。

person(ssn number, resume clob)

PERSON表のLOB列用のロケータを選択します。

text *ins_stmt = (text *)"INSERT INTO PERSON VALUES (:1, :2)";
text *sel_stmt = (text *)"SELECT * FROM PERSON WHERE SSN = 123456";
text *ins_empty = (text *)"INSERT INTO PERSON VALUES ( 1, EMPTY_CLOB())";

OCILobLocator *lobp;

ub4   amtp = DATA_SIZE;
ub4   remainder = DATA_SIZE;
ub4    nbytes = PIECE_SIZE;

/* Allocate lob locator */
OCIDescriptorAlloc (envhp, &lobp, OCI_DTYPE_LOB, 0, 0);

/* Insert an empty locator */
OCIStmtPrepare (stmhp, errhp, ins_empty, strlen(ins_empty), OCI_NTV_SYNTAX,
OCI_DEFAULT);
OCIStmtExecute (svchp, stmhp, errhp, 1, 0, 0, 0, OCI_DEFAULT);

/* Now select the locator */

OCIStmtPrepare (stmhp, errhp, sel_stmt, strlen(sel_stmt), OCI_NTV_SYNTAX,
OCI_DEFAULT);

/* Call define for the lob column */
OCIDefineByPos (stmthp, &defnp2, errhp, 1, &lobp, 0 , SQLT_CLOB, 0, 0, 0,
OCI_DEFAULT);

OCIStmtExecute (svchp, stmhp, errhp, 1, 0, 0, 0, OCI_DEFAULT);

OCI LOBロケータ・インタフェースを使用したLOBデータの読取りおよび書込み

OCIアプリケーションはOCILobOpen()およびOCILobClose()を使用して、LOBをオープンおよびクローズできます。LOBを明示的にオープンまたはクローズしない場合は、読取りまたは書込みの前に暗黙的にオープンされ、トランザクションの終了時に暗黙的にクローズされます。

アプリケーションでは、OCILobRead()またはOCILobRead2()を使用してLOBデータを読み取り、OCILobWrite()またはOCILobWrite2()を使用してLOBデータを書き込み、OCILobWriteAppend()またはOCILobWriteAppend2()を使用してLOBデータに追加し、OCILobErase()またはOCILobErase2()を使用してLOBデータを消去し、その他の様々なOCI関数を使用してその他の様々なアクションを実行します。

たとえば、「Hello World!」という内容のCLOBについて考えてみます。OCILobWrite()をコールして、オフセット7に「I am a new string」と書き込むようにデータを上書きおよび追加できます。この結果、CLOBの内容が「Hello I am a new string」に更新されます。または、元の「Hello World!」からデータを消去する場合、オフセット7、量(文字数)5などを指定してOCILobErase()をコールすると、CLOBを「Hello !」(空白が6つ)に更新できます。

OCI LOBロケータ・インタフェースのすべての関数については、『Oracle Call Interfaceプログラマーズ・ガイド』のLOB関数に関する説明を参照してください。

注意:

- Oracle DatabaseではLOBに対するOCIの読取りおよび書込み関数で、2のバージョンを重視しています(2のバージョン以外はOracle Database 11.2リリースで非推奨になりました)が、現在、TimesTenでは、OCILobRead2()、OCILobWrite2()およびOCILobWriteAppend2()(TimesTenでサポートするサイズより大きいLOBを対象)を使用することによる技術的なメリットはありません。

- LOBの読取りまたは書込み関数を使用する場合、TimesTenではLOB操作に対するコールバック関数をサポートしていないため、コールバック関数のパラメータがNULLまたは0(ゼロ)に設定されている必要があります。

- TimesTenではLOBに対する配列のバインドがサポートされていないため、OCILobArrayRead()およびOCILobArrayWrite()関数はサポートされません。

例3-6 LOBロケータ・インタフェースを使用したLOBデータの読取りおよび書込み

この例では、OCI LOB関数OCILobWrite()を使用したLOBデータの書込み方法およびOCILobRead()を使用したデータの読取り方法を示します。前述の例3-5の表および変数を使用します。

for (i=0;i<DATA_SIZE;i++)
col2[i] = 'A';

/*************** Writing to the LOB *****************/

amt = DATA_SIZE;
offset = 1;

/* Write contents of col2 buffer into the LOB in a single chunk via locator lobp */
OCILobWrite (svchp, errhp, lobp, &amt, offset, col2, DATA_SIZE, OCI_ONE_PIECE,
0, 0, 0, SQLCS_IMPLICIT);

/*************** Reading from the LOB *****************/

/* Get the length of the LOB */
OCILobGetLength (svchp, errhp, lobp, &len);
amt = len;

/* Read the LOB data in col2Res in a single chunk */
OCILobRead (svchp, errhp, lobp, &amt, offset, col2Res, DATA_SIZE, 0, 0, 0,
SQLCS_IMPLICIT);

OCIクライアント側のバッファリング

OCIでは、LOBごとにクライアント側のバッファリング用の機能が提供されています。この機能は、LOBでOCILobEnableBuffering()をコールすることで有効化され、OCILobDisableBuffering()をコールすること無効化されます。

LOBロケータに対するバッファリングを有効化することで、512KBの書込みバッファが作成されます。このサイズは設定できません。アプリケーションによってLOBロケータを介して書き込まれたデータはバッファされます。可能な場合、クライアント・ライブラリは、LOBの読取りリクエストにバッファからも対応します。アプリケーションは、OCILobFlushBuffer()をコールすることによってバッファをフラッシュできます。バッファが一杯になっても自動的にはフラッシュされないため、バッファが一杯のときにロケータを介してLOBに書込みを試みると、エラーが発生することに注意してください。

次の制限事項は、クライアント側のバッファリングを使用している場合に適用されます。

- バッファリングは、OCILobAppend()、OCILobCopy()、OCILobCopy2()、OCILobErase()、OCILobGetLength()、OCILobTrim()、OCILobWriteAppend()およびOCILobWriteAppend2()の各関数とは互換性がありません。

- アプリケーションでは、LOBの最後に追加する場合にのみOCILobWrite()またはOCILobWrite2()を使用できます。

- LOBデータは、アプリケーションがバッファをフラッシュした後にのみ、SQLおよびPL/SQL(サーバー側)操作に表示されます。

- フラッシュされていないクライアント側の書込みがバッファにあるときにLOBが選択されると、そのフラッシュされていないデータは選択に含まれません。

OCIでのLOBのプリフェッチ

クライアント/サーバー接続でサーバーへのラウンドトリップを減らすには、データベースからLOBデータをプリフェッチし、フェッチ操作中にクライアント側にキャッシュできます。OCIでのLOBのプリフェッチには、Oracle Databaseと同じ機能がTimesTenにあります。

次のOCI属性を使用してLOBのプリフェッチを構成します。サイズは、BLOBの場合はバイトで、CLOBまたはNCLOBの場合は文字数で表すことに注意してください。

- OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE: これを使用してプリフェッチを有効化し、デフォルトのプリフェッチ・サイズを指定します。値0(ゼロ)(デフォルト)はプリフェッチを無効化します。

- OCI_ATTR_LOBPREFETCH_SIZE: この属性を列定義ハンドルに設定し、特定のLOB列に対するプリフェッチ・サイズを指定します。

- OCI_ATTR_LOBPREFETCH_LENGTH: この属性はTRUEまたはFALSE(デフォルト)に設定でき、LOBの長さやチャンクのサイズなどのLOBのメタデータをプリフェッチします。

OCI_ATTR_DEFAULT_LOBPREFETCH_SIZEとOCI_ATTR_LOBPREFETCH_LENGTHの設定は互いに独立しています。LOBデータのプリフェッチは、LOBメタデータのプリフェッチから切り離して使用できます。

詳細および例は、『Oracle Call Interfaceプログラマーズ・ガイド』のLOBデータのプリフェッチ、長さおよびチャンクのサイズに関する説明を参照してください。

注意:
前述の属性設定は、TimesTenの直接接続では無視されます。

OCIでのパススルーLOB

パススルーLOB(TimesTenを介してアクセスされるOracle DatabaseのLOB)は、TimesTen LOBとして公開され、TimesTenによってTimesTen LOBとほぼ同じようにサポートされますが、次の点に注意してください。

- パススルーLOBの作成に、OCILobCreateTemporary()は使用できません。

- 1つのTimesTen LOBを別のTimesTen LOBにコピーすること(OCILobCopy()、OCILobCopy2()、OCILobAppend()などを使用して)に加えて、TimesTen LOBをパススルーLOBに、パススルーLOBからTimesTen LOBに、1つのパススルーLOBから別のパススルーLOBにコピーできます。これらのコピーでは、LOBの値をターゲットの宛先にコピーします。たとえば、パススルーLOBのTimesTen LOBへのコピーでは、LOBの値がTimesTenデータベースにコピーされます。
パススルーLOBのサイズがTimesTen LOBのサイズ制限より大きい場合、パススルーLOBをTimesTen LOBにコピーしようとするとエラーが発生します。

- TimesTen LOBのサイズ制限は、パススルーによるOracle DatabaseのLOBの格納には適用されません。パススルーLOBがTimesTen LOBにコピーされた場合、サイズ制限はコピーにも適用されます。

- TimesTenのローカルLOBと同様に、パススルーLOBのロケータは、トランザクションの終了後は有効ではありません。

例3-7 TimesTen LOBとパススルーLOB間のコピー

この例では、TimesTen LOBとOracle Database上のパススルーLOB間のコピーでの重要な機能を強調しています。表およびデータの設定後に、最初の例では、OCILobAppend()を使用してLOBデータをOracle DatabaseからTimesTenにコピーし、2番目目の例では、OCILobCopy()を使用してLOBデータをTimesTenからOracle Databaseにコピーしています。(どちらのコールも、どちらの場合にも使用できます。)次に、対比のために、3番目の例では、UPDATE文を使用してLOBデータをOracle DatabaseからTimesTenにコピーし、4番目の例では、INSERT文を使用してLOBデータをTimesTenからOracle Databaseにコピーしています。

/* Table and data setup */
call ttoptsetflag(''passthrough'', 3)';
DROP TABLE oratab';
CREATE TABLE oratab (i INT, c CLOB)';
INSERT INTO oratab VALUES (1, ''Copy from Oracle to TimesTen'')';
INSERT INTO oratab VALUES (2, EMPTY_CLOB())';
COMMIT;

call ttoptsetflag(''passthrough'', 0)';
DROP TABLE tttab';
CREATE TABLE tttab (i INT, c CLOB)';
INSERT INTO tttab VALUES (1, ''Copy from TimesTen to Oracle'')';
INSERT INTO tttab VALUES (2, EMPTY_CLOB())';
INSERT INTO tttab VALUES (3, NULL)';
COMMIT;
/* Table and data setup end */

/*
* Below are four OCI pseudocode examples, for copying LOBs between
* TimesTen and Oracle using OCI API and INSERT/UPDATE statements.
*/

/* Init OCI Env */

/* Set the passthrough level to 1 */
OCIStmtPrepare (..., "call ttoptsetflag(''passthrough'', 1)'", ...);
OCIStmtExecute (...);

/*
* 1. Copy a passthrough LOB on Oracle to a TimesTen LOB
*/

/* Select a passthrough locator on Oracle */
OCIStmtPrepare (..., "SELECT c FROM oratab WHERE i = 1", ...);
OCIDefineByPos (..., (dvoid *)&ora_loc_1, 0 , SQLT_CLOB, ...);
OCIStmtExecute (...);

/* Select a locator on TimesTen for update */
OCIStmtPrepare (..., "SELECT c FROM tttab WHERE i = 2 FOR UPDATE", ...);
OCIDefineByPos (..., (dvoid *)&tt_loc_2, 0 , SQLT_CLOB, ...);
OCIStmtExecute (...);

/* Copy a passthrough LOB on Oracle to a TimesTen LOB */
OCILobAppend(..., tt_loc_2, ora_loc_1);

/*
* 2. Copy a TimesTen LOB to a passthrough LOB on Oracle
*/

/* Select a passthrough locator on Oracle for update */
OCIStmtPrepare (..., "SELECT c FROM oratab WHERE i = 2 FOR UPDATE", ...);
OCIDefineByPos (..., (dvoid *)&ora_loc_2, 0 , SQLT_CLOB, ...);
OCIStmtExecute (...);

/* Select a locator on TimesTen */
OCIStmtPrepare (..., "SELECT c FROM tttab WHERE i = 1", ...);
OCIDefineByPos (..., (dvoid *)&tt_loc_1, 0 , SQLT_CLOB, ...);
OCIStmtExecute (...);

/* Copy a passthrough LOB on Oracle to a TimesTen LOB */
OCILobCopy(..., ora_loc_2, tt_loc_1, 28, 1, 1);

/*
* 3. UPDATE a TimesTen LOB with a passthrough LOB on Oracle
*/

/* A passthrough LOB, (selected above in case 1) is bound to an UPDATE statement
* on TimesTen table */
OCIStmtPrepare (..., "UPDATE tttab SET c = :1 WHERE i = 3", ...);
OCIBindByPos (..., (dvoid *)&ora_loc_1, 0 , SQLT_CLOB, ...);
OCIStmtExecute (...);

/*
* 4. INSERT a passthrough table on Oracle with a TimesTen LOB
*/

/* A TimesTen LOB, (selected above in case 2) is bound to an INSERT statement
* on a passthough table on Oracle */
OCIStmtPrepare (..., "INSERT INTO oratab VALUES (3, :1)", ...);
OCIBindByPos (..., (dvoid *)&tt_loc_1, 0 , SQLT_CLOB, ...);
OCIStmtExecute (...);

OCITransCommit (...);

/* Cleanup OCI Env */

OCIでPL/SQLを使用してTimesTen組込みプロシージャをコール

この章で前述したように、結果セットを返すTimesTen組込みプロシージャは、OCIを通じて直接にはサポートされていません。ただし、例3-8のように、この目的にPL/SQLを使用することはできます。

例3-8 OCIでPL/SQLを使用してTimesTen組込みプロシージャをコール

plsql_resultset_example(OCIEnv *envhp, OCIError *errhp, OCISvcCtx *svchp)
{
OCIStmt   *stmhp;
OCIBind   *bindp;

sb4        passThruValue = -1;
char       v_name[255];
text      *stmt_text;

/* prepare the plsql statement */
stmt_text = (text *)
"declare v_name varchar2(255); "
"begin execute immediate "
"'call ttOptGetFlag(''passthrough'')' into v_name, :rc1; "
"end;";
OCIStmtPrepare2(svchp, &stmhp, errhp, (text *)stmt_text,
(ub4)strlen((char *)stmt_text),
(text *)0, (ub4)0,
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);

/* bind parameter 1 (:v_name) to varchar2 out-parameter */
OCIBindByPos(stmhp, &bindp, errhp, 1,
(dvoid*)&v_name, sizeof(v_name), SQLT_CHR,
(dvoid*)0, (ub2*)0, (ub2*)0, (ub4)0, (ub4*)0,
OCI_DEFAULT);

/* execute the plsql statement */
OCIStmtExecute(svchp, stmhp, errhp, (ub4)1, (ub4)0,
(OCISnapshot *)0, (OCISnapshot *)0, (ub4)OCI_DEFAULT);

/* convert the passthrough string value to an integer */
passThruValue = (sb4)atoi((const char *)v_name);
printf("Value of the passthrough flag is %d\n", passThruValue);

/* drop the statement handle */
OCIStmtRelease(stmhp, errhp, (text *)0, (ub4)0, (ub4)OCI_DEFAULT);
}

TimesTen OCI サポートのリファレンス

この項では、OCI機能のTimesTenによるサポートのリファレンスに関して、次の項目について説明します。

- サポートされているOCIコール

- サポートされているハンドルおよび属性

- サポートされている記述子

- サポートされているSQLデータ型

- サポートされているパラメータ属性

サポートされているOCIコール

表3-2に、Oracle Databaseリリース11.2.0.2に関して記述されている、OCIコールに対するTimesTenサポートを示します。

一部のコールのグループは、名前にアスタリスクを付けて示しています。たとえば、TimesTenでサポートされていないアドバンスト・キューイングに関連するコールは、OCIAQで始まる名前を持ち、表ではOCIAQ*()と示されています。TimesTenでサポートされているOCI日付関数は、OCIDate*()と示されています。

表3-2 TimesTen OCIでサポートされているコール

OCIコール

サポート

注意

OCIAQ*()

なし

TimesTenでは、アドバンスト・キューイングはサポートされていません。

OCIAnyData*()

なし

TimesTenではANYDATAはサポートされていません。

OCIAppCtxClearAll()

あり

OCIAppCtxSet()

あり

OCIArrayDescriptorAlloc()

あり

OCIArrayDescriptorFree()

あり

OCIAttrGet()

あり

TimesTenサポートには、キャッシュ・グループでの特別な使用方法が含まれています。「TimesTen OCIでのTimesTen Cache」を参照してください。

OCIAttrSet()

あり

OCIBinXml*()

なし

TimesTenでは、XML DBはサポートされていません。

OCIBindArrayOfStruct()

あり

SQL文ではサポートされていますが、PL/SQLではサポートされていません。

OCIBindByName()

あり

次の値はmodeパラメータではサポートされていません。

- OCI_DATA_AT_EXEC

- OCI_IOV

OCIBindByPos()

あり

次の値はmodeパラメータではサポートされていません。

- OCI_DATA_AT_EXEC

- OCI_IOV

OCIBindDynamic()

なし

OCIBindObject()

なし

TimesTenでは、ユーザー定義オブジェクトはサポートされていません。

OCIBreak()

なし

OCICache*()

なし

TimesTenでは、ユーザー定義オブジェクトはサポートされていません。

OCICharSetConversionIsReplacementUsed()

あり

OCICharSetToUnicode()

あり

OCIClientVersion()

あり

OCIColl*()

なし

TimesTenでは、コレクションはサポートされていません。

OCIConnectionPoolCreate()

なし

OCIConnectionPoolDestroy()

なし

OCIContext*()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIDBShutdown()

なし

OCIDBStartup()

なし

OCIDate*()

あり

記述子のサポートの詳細は、表3-4を参照してください。

OCIDefineArrayOfStruct()

あり

SQL文ではサポートされていますが、PL/SQLではサポートされていません。

OCIDefineByPos()

あり

次の値はmodeパラメータではサポートされていません。

- OCI_DATA_AT_EXEC

- OCI_IOV

OCIDefineDynamic()

なし

OCIDefineObject()

なし

OCIDescribeAny()

あり

PL/SQLオブジェクトはサポートされていません。

オブジェクトの記述は名前でのみサポートされます。

objptr_typパラメータでは、次の値はサポートされていません。

- OCI_OTYPE_REF

- OCI_OTYPE_PTR

objtypパラメータでは、次の値はサポートされていません。

- OCI_PTYPE_PKG

- OCI_PTYPE_FUNC

- OCI_PTYPE_PROC

- OCI_PTYPE_SYN

- OCI_PTYPE_TYPE

objtypパラメータの設定OCI_PTYPE_DATABASEを使用する場合は、事前定義済名$TT_DB_NAME$を、*objptrパラメータのデータベース名として使用します。

OCIDescriptorAlloc()

あり

OCIDescriptorFree()

あり

OCIDirPath*()

なし

TimesTenではダイレクト・パス・ロードはサポートされていません。

OCIDurationBegin()

あり

LOBではサポートされています。期間の設定にかかわらず、期間はトランザクション存続期間を超えることはできません。

OCIDurationEnd()

あり

LOBではサポートされています。期間の設定にかかわらず、期間はトランザクション存続期間を超えることはできません。

OCIDuration*()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIEnvCreate()

あり

次の値はmodeパラメータではサポートされていません。

- OCI_EVENTS

- OCI_NEW_LENGTH_SEMANTICS

- OCI_NCHAR_LITERAL_REPLACE_ON

- OCI_NCHAR_LITERAL_REPLACE_OFF

- OCI_NO_MUTEX(かわりにOCI_ENV_NO_MUTEXを使用します。)

OCIEnvInit()

あり

次の値はmodeパラメータではサポートされていません。

- OCI_NO_MUTEX

- OCI_ENV_NO_MUTEX

注意: OCIEnvInit()のかわりにOCIEnvCreate()を使用します。OCIEnvInit()は下位互換性を保つためにサポートされています。

OCIEnvNlsCreate()

あり

次の値はmodeパラメータではサポートされていません。

- OCI_EVENTS

- OCI_NCHAR_LITERAL_REPLACE_ON

- OCI_NCHAR_LITERAL_REPLACE_OFF

- OCI_NO_MUTEX(かわりにOCI_ENV_NO_MUTEXを使用します。)

OCIErrorGet()

あり

OCIExtProc*()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIExtract*()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIFile*()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIFormatInit()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIFormatString()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIFormatTerm()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIHandleAlloc()

あり

OCIHandleFree()

あり

OCIInitialize()

あり

次の値はmodeパラメータではサポートされていません。

- OCI_NO_MUTEX

- OCI_ENV_NO_MUTEX

注意: OCIInitialize()のかわりにOCIEnvCreate()を使用します。OCIInitialize()は下位互換性を保つためにサポートされています。

OCIInterval*()

あり

記述子のサポートの詳細は、表3-4を参照してください。

OCIIter*()

なし

TimesTenでは、コレクションはサポートされていません。

OCILdaToSvcCtx()

なし

OCILob*()

あり

TimesTenでは、次を除くOCILob*()関数がサポートされています。

- 特に配列の読取りおよび書込みを対象とした関数

- 特にBFILEを対象とした関数

- 特にSecureFileを対象とした関数

注意:

- OCILobCreateTemporary()コールでの期間の設定にかかわらず、LOBの存続期間はトランザクション存続期間を超えることはできません。

- OCILobRead2()、OCILobWrite2()およびOCILobWriteAppend2()については、「OCI LOBロケータ・インタフェースを使用したLOBデータの読取りおよび書込み」を参照してください。

OCILogoff()

あり

OCILogon()

あり

OCILogon2()

あり

modeパラメータでは、OCI_DEFAULT値のみがサポートされています。

OCIMemory*()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIMessage*()

なし

TimesTenでは、データ・カートリッジはサポートされていません。

OCIMultiByte*()

あり

OCINls*()

あり

OCINumber*()

あり

OCIObject*()

なし

TimesTenでは、ユーザー定義オブジェクトはサポートされていません。

OCIParamGet()

あり

OCIParamSet()

あり

OCIPasswordChange()

なし

OCIPing()

あり

OCIRaw*()

あり

OCIRef*()

なし

OCIReset()

なし

OCIRowidToChar()

あり

OCIServer*()

あり

OCIServerAttachのmodeパラメータでは、OCI_DEFAULT値のみがサポートされています。

OCISessionBegin()

あり

credtパラメータでは、OCI_CRED_RDBMS値のみがサポートされています。

modeパラメータでは、OCI_DEFAULT値のみがサポートされています。

OCISessionEnd()

あり

OCISessionGet()

あり

TimesTenでは、セッション間の切り替えはサポートされていません。

OCISessionPoolCreate()

なし

OCISessionPoolDestroy()

なし

OCISessionRelease()

あり

OCISharedLibInit()

なし

OCIStmtExecute()

あり

次の値はmodeパラメータではサポートされていません。

- OCI_BATCH_ERRORS

- OCI_STMT_SCROLLABLE_READONLY

注意: OCI_COMMIT_ON_SUCCESSを使用すると、トランザクションをコミットするためのサーバーへの余分なラウンドトリップが回避され、パフォーマンスが向上します。

OCIStmtFetch()

あり

OCIStmtFetch2()

あり

orientationパラメータでサポートされる値は、OCI_DEFAULTおよびOCI_FETCH_NEXTのみです。

OCIStmtGetBindInfo()

あり

OCIStmtGetPieceInfo()

なし

OCIStmtPrepare()

あり

languageパラメータでサポートされる値は、OCI_NTV_SYNTAXのみです。

OCIStmtPrepare2()

あり

modeパラメータでサポートされる値は、OCI_DEFAULTのみです。

文のキャッシュについては、TimesTenでは、OCIStmtPrepare2()またはOCIStmtRelease()への将来のコール用に、文にタグを付けるためのkey引数がサポートされています。

OCIStmtRelease()

あり

modeパラメータでサポートされる値は、OCI_DEFAULTのみです。

文のキャッシングについては、TimesTenでは、文にタグを付けるためのkey引数がサポートされています。これには、OCIStmtPrepare2()から返されたキーを指定できます。

OCIStmtSetPieceInfo()

なし

OCIString*()

あり

OCISubscription*()

なし

TimesTenでは、アドバンスト・キューイングはサポートされていません。

OCISvcCtxToLda()

なし

OCITable*()

なし

OCITerminate()

なし

OCIThread*()

あり

OCITransCommit()

あり

modeパラメータでサポートされる値は、OCI_DEFAULTのみです。

OCITransDetach()

なし

OCITransForget()

なし

OCITransMultiPrepare()

なし

OCITransPrepare()

なし

OCITransRollback()

あり

OCITransStart()

なし

OCIType*()

なし

OCIUnicodeToCharSet()

あり

OCIUserCallbackGet()

あり

OCIUserCallbackRegister()

あり

OCIWideChar*()

あり

OCIXmlDbFreeXmlCtx()

なし

TimesTenでは、XML DBはサポートされていません。

OCIXmlDbInitXmlCtx()

なし

TimesTenでは、XML DBはサポートされていません。

サポートされているハンドルおよび属性

表3-3に、TimesTen OCIでサポートされているハンドルおよび属性を示します。

表3-3 TimesTen OCIでサポートされているハンドルおよび属性

ハンドル

Cオブジェクト

サポートされる属性

環境

OCIEnv

OCI_ATTR_ENV_CHARSET_ID

OCI_ATTR_ENV_NCHARSET_ID

OCI_ATTR_ENV_UTF16

OCI_ATTR_EVTCTX

OCI_ATTR_OBJECT

エラー

OCIError

OCI_ATTR_DML_ROW_OFFSET

サービス・コンテキスト

OCISvcCtx

OCI_ATTR_ENV

OCI_ATTR_IN_V8_MODE

OCI_ATTR_SERVER

OCI_ATTR_SESSION

OCI_ATTR_TRANS

文

OCIStmt

OCI_ATTR_BIND_COUNT

OCI_ATTR_CURRENT_POSITION

OCI_ATTR_ENV

OCI_ATTR_FETCH_ROWID

OCI_ATTR_NUM_DML_ERRORS

OCI_ATTR_PARAM_COUNT

OCI_ATTR_PREFETCH_MEMORY

OCI_ATTR_PREFETCH_ROWS

OCI_ATTR_ROW_COUNT

OCI_ATTR_ROWID

OCI_ATTR_ROWS_FETCHED

OCI_ATTR_SQLFNCODE

OCI_ATTR_STATEMENT

OCI_ATTR_STMT_TYPE

バインド

OCIBind

OCI_ATTR_CHARSET_FORM

OCI_ATTR_CHARSET_ID

OCI_ATTR_MAXCHAR_SIZE

OCI_ATTR_MAXDATA_SIZE

定義

OCIDefine

OCI_ATTR_CHARSET_FORM

OCI_ATTR_CHARSET_ID

OCI_ATTR_MAXCHAR_SIZE

記述

OCIDescribe

OCI_ATTR_PARAM

OCI_ATTR_PARAM_COUNT

サーバー

OCIServer

OCI_ATTR_ENV

OCI_ATTR_IN_V8_MODE

OCI_ATTR_SERVER_GROUP

OCI_ATTR_SERVER_STATUS

ユーザー・セッション

OCISession

OCI_ATTR_CLIENT_IDENTIFER

OCI_ATTR_CLIENT_INFO

OCI_ATTR_CURRENT_SCHEMA

OCI_ATTR_DRIVER_NAME

OCI_ATTR_INITIAL_CLIENT_ROLES

OCI_ATTR_MODULE

OCI_ATTR_PROXY_CREDENTIALS

OCI_ATTR_USERNAME

認証

OCIAuthInfo

ユーザー・セッション・ハンドルの場合と同じです。

トランザクション

OCITrans

OCI_ATTR_TRANS_NAME

OCI_ATTR_TRANS_TIMEOUT

スレッド

OCIThreadHandle

サポートされている記述子

表3-4に、TimesTen OCIでサポートされている記述子を示します。

表3-4 TimesTen OCIでサポートされている記述子

記述子

Cオブジェクト

パラメータ(読取り専用)

OCIParam

ROWID

OCIRowid

ANSI DATE

OCIDateTime

TIMESTAMP

OCIDateTime

TIMESTAMP WITH TIME ZONE

OCIDateTime

TIMESTAMP WITH LOCAL TIME ZONE

OCIDateTime

INTERVAL YEAR TO MONTH

OCIInterval

INTERVAL DAY TO SECOND

OCIInterval

ユーザー・コールバック

OCIUcb

サポートされているSQLデータ型

表3-5に、TimesTen OCIでサポートされているSQLデータ型を示します。

表3-5 TimesTen OCIでサポートされているSQLデータ型

SQLデータ型

注意

SQLT_AFC

SQLT_AVC

SQLT_BDOUBLE

SQLT_BFLOAT

SQLT_BIN

SQLT_BLOB

SQLT_CHR

SQLT_CLOB

NCLOBに対する書込みおよび読取りを行うには、アプリケーション関数コールに対してキャラクタ・セット・フォーム(csfrm)パラメータをSQLCS_NCHARに設定します。

SQLT_DAT

SQLT_DATE

SQLT_FLT

SQLT_IBDOUBLE

SQLT_IBFLOAT

SQLT_INT

SQLT_INTERVAL_DS

TimesTenには格納されていません。

SQLT_INTERVAL_YM

TimesTenには格納されていません。

SQLT_LBI

SQLT_LNG

SQLT_LVB

TimesTenに格納されるときに4MBで切り捨てられます。

SQLT_LVC

TimesTenに格納されるときに4MBで切り捨てられます。

SQLT_NUM

SQLT_ODT

SQLT_RDD

ROWIDはOracle Database形式で返されます。

SQLT_RSET

1文につき1つの結果セット・パラメータのみが許可されます。

SQLT_STR

SQLT_TIME

SQLT_TIME_TZ

TimesTenに格納されるときにタイムゾーンは無視されます。

SQLT_TIMESTAMP

SQLT_TIMESTAMP_LTZ

TimesTenに格納されるときにタイムゾーンは無視されます。

SQLT_TIMESTAMP_TZ

TimesTenに格納されるときにタイムゾーンは無視されます。

SQLT_UIN

SQLT_VBI

SQLT_VCS

SQLT_VNU

SQLT_VST

サポートされているパラメータ属性

次の表3-6に、サポートされているパラメータ属性を示します。

表3-6 TimesTen OCIでサポートされているパラメータ属性

パラメータ

サポートされる属性

すべてのパラメータ

OCI_ATTR_NUM_PARAMS

OCI_ATTR_OBJ_NAME

OCI_ATTR_OBJ_SCHEMA

OCI_ATTR_PTYPE

表およびビュー・パラメータ

OCI_ATTR_NUM_COLS

OCI_ATTR_LIST_COLUMNS

PL/SQLプロシージャおよび関数パラメータ

OCI_ATTR_LIST_ARGUMENTS

PL/SQLサブプログラム・パラメータ

OCI_ATTR_LIST_ARGUMENTS

OCI_ATTR_NAME

PL/SQLパッケージ・パラメータ

OCI_ATTR_LIST_SUBPROGRAMS

順序パラメータ

OCI_ATTR_OBJID

OCI_ATTR_MIN

OCI_ATTR_MAX

OCI_ATTR_INCR

OCI_ATTR_CACHE

OCI_ATTR_ORDER

OCI_ATTR_HW_MARK

列パラメータ

OCI_ATTR_CHAR_USED

OCI_ATTR_CHAR_SIZE

OCI_ATTR_DATA_SIZE

OCI_ATTR_DATA_TYPE

OCI_ATTR_NAME

OCI_ATTR_PRECISION

OCI_ATTR_SCALE

OCI_ATTR_IS_NULL

OCI_ATTR_TYPE_NAME

OCI_ATTR_SCHEMA_NAME

OCI_ATTR_CHARSET_ID

OCI_ATTR_CHARSET_FORM

引数および結果パラメータ

OCI_ATTR_NAME

OCI_ATTR_POSITION

OCI_ATTR_DATA_TYPE

OCI_ATTR_DATA_SIZE

OCI_ATTR_PRECISION

OCI_ATTR_SCALE

OCI_ATTR_LEVEL

OCI_ATTR_IS_NULL

OCI_ATTR_CHARSET_ID

OCI_ATTR_CHARSET_FORM

リスト・パラメータ

OCI_LTYPE_COLUMN

OCI_LTYPE_SCH_OBJ

OCI_LTYPE_DB_SCH

データベース・パラメータ

OCI_ATTR_VERSION

OCI_ATTR_CHARSET_ID

OCI_ATTR_NCHARSET_ID

OCI_ATTR_LIST_SCHEMAS

OCI_ATTR_MAX_PROC_LEN

OCI_ATTR_MAX_COLUMN_LEN

OCI_ATTR_ATTR_CURSOR_COMMIT_BEHAVIOR

OCI_ATTR_MAX_CATALOG_NAMELEN

OCI_ATTR_CATALOG_LOCATION

OCI_ATTR_SAVEPOINT_SUPPORT

OCI_ATTR_NOWAIT_SUPPORT

OCI_ATTR_AUTOCOMMIT_DDL

OCI_ATTR_LOCKING_MODE

4 TimesTenでのPro*C/C++のサポート

TimesTenおよびTimesTen Cacheでは、CおよびC++アプリケーションのOracle Pro*C/C++プリコンパイラがサポートされています。プリコンパイラは、TimesTenデータベースにアクセスする埋込みSQLおよびPL/SQLアプリケーションで使用できます。

この章では、Pro*C/C++に関する概要およびTimesTen固有の情報について説明し、特にTimesTenでのPro*C/C++の使用とOracle DatabaseでのPro*C/C++の使用の違いについて強調します。Pro*C/C++の詳細は、Oracle Databaseライブラリの『Pro*C/C++プログラマーズ・ガイド』を参照してください。

第2章「ODBCでのTimesTenデータベースの使用」も参照してください。TimesTenの機能について興味深いと思われる情報が記載されています。

この章の内容は次のとおりです。

- Oracle Pro*C/C++プリコンパイラの概要

- TimesTenでのPro*C/C++のサポートの概要

- TimesTen Pro*C/C++の開始

- TimesTen Pro*C/C++のその他の機能

- TimesTenのPro*C/C++プリコンパイラ・オプション

Oracle Pro*C/C++プリコンパイラの概要

Oracle Pro*C/C++プリコンパイラを使用すると、SQL文またはPL/SQLブロックを直接CコードまたはC++コードに埋め込むことができます。さらに、CまたはC/C++プログラム・ホスト変数を埋込みSQLまたはPL/SQLで使用できます。

プリコンパイル手順を使用して、Pro*C/C++ソース・ファイルをCまたはC++のソース・ファイルに変換します。プリコンパイラはPro*C/C++ファイルを入力として受け入れ、埋込みSQL文を標準Oracleランタイム・ライブラリ・コールに変換し、後でコンパイルおよびリンクが可能な変更されたソース・コード・ファイルを生成します。Pro*C/C++のコードは、Oracle Instant Clientの一部としてTimesTenに付属する、Oracle DatabaseプリコンパイラSQLLIBライブラリとリンクされます。

TimesTenでのPro*C/C++のサポートの概要

TimesTenでのOracle Pro*C/C++プリコンパイラのサポートは、TimesTen OCIに依存します。TimesTen OCIは、Oracleクライアント・ライブラリおよびTimesTen ODBCライブラリに依存します。TimesTenアーキテクチャにおけるOCIおよびPro*C/C++の位置付けを確認するには、図3-1を参照してください。

この章では、TimesTenでのOracle Pro*C/C++プリコンパイラの使用に固有の情報を示します。TimesTenでのOracle Pro*C/C++プリコンパイラの構文および使用方法は、基本的にOracle Databaseの場合と同じです。

この項の以降の内容は次のとおりです。

- TimesTen OCIサポート

- 埋込みSQLのサポートおよび制限

- セマンティック・チェックの制限

- 埋込みPL/SQLの制限

- トランザクションの制限

- 接続の制限

- サポートされていないか制限されている実行可能コマンドおよび句の概要

- ttSrcScanユーティリティ

TimesTen OCIサポート

TimesTenでのOracle Pro*C/C++プリコンパイラのサポートは、TimesTen OCIサポートに依存しているため、TimesTen OCIの制限がPro*C/C++アプリケーションに適用されます。

また、TimesTenでは、TimesTenに存在しない機能に関連するOCIコールはサポートされていません。

TimesTen OCIサポートの詳細は、第3章「TimesTenでのOCIのサポート」を参照してください。ここの情報のほとんどは、Pro*C/C++アプリケーションにも該当することがあります。

埋込みSQLのサポートおよび制限

TimesTen Pro*C/C++プリコンパイラでは、TimesTenおよびTimesTen Cacheでサポートされていない機能の埋込みSQLはサポートされていません。「TimesTenの制限および相違点」を参照してください。

TimesTenではSQLLIB機能について、次のようなサポートが提供されています。

- SQLErrorGetText(sqlglmt)がサポートされています。

- SQLRowidGet()は、SELECT FOR UPDATE文に続く場合にのみサポートされます。

また、TimesTenでのOracle Pro*C/C++プリコンパイラのサポートには、次の制限があります。

- REGISTER CONNECTはサポートされていません。

- ストアドJavaサブプログラムはサポートされていません。

セマンティック・チェックの制限

TimesTenでのOracle Pro*C/C++プリコンパイラのサポートには、プリコンパイル時のセマンティック・チェックは含まれません。セマンティック・チェックを指定するSQLCHECKプリコンパイラ・オプション設定は可能ですが、実行されません。

ただし、SEMANTICSを設定した場合、プリコンパイルのセマンティック・チェックは実行されませんが、データベース接続が行われることを認識することが重要です。このため、SEMANTICSを設定する場合は、プリコンパイル時に次の要件があります。

- データベースが稼働している必要があります。

- コマンドラインまたはpcscfg.cfg構成ファイルのいずれかでUSERIDプリコンパイラ・オプションを設定する必要があります。既存のTimesTenユーザーのユーザー名とパスワード、およびデータベースを指すTNS名を入力する必要があります。次の例では、パスワードの入力が求められます。

USERID=user1@my_tnsname

または、USERID=user1/mypassword@my_tnsnameと入力することもできます。ただし、セキュリティ上の理由から、コマンドラインまたは構成ファイルでパスワードを指定することはお薦めしません。

TNS名の使用方法および構文については、「Pro*C/C++からTimesTenデータベースへの接続」を参照してください。

PL/SQLを使用するPro*C/C++プログラムの詳細は、次の項の「埋込みPL/SQLの制限」を参照してください。

埋込みPL/SQLの制限

TimesTenでは、Pro*C/C++アプリケーションにPL/SQLブロックが含まれている場合、Pro*C/C++はSQLCHECK設定がSEMANTICSであるかのように動作します。この場合、プリコンパイルのセマンティック・チェックは実行されませんが、データベース接続が行われることを認識することが重要です。このため、PL/SQLをPro*C/C++アプリケーションで使用する場合は、プリコンパイル時に次の要件があります。

- データベースが稼働している必要があります。

- 既存のTimesTenユーザーを指定して、USERIDプリコンパイラ・オプションを設定する必要があります。このオプションの設定の詳細は、前の項の「セマンティック・チェックの制限」を参照してください。

トランザクションの制限

トランザクションに関して、TimesTenでのOracle Pro*C/C++プリコンパイラのサポートには次のものは含まれません。

- SAVEPOINT SQL文

- SET TRANSACTION SQL文
トランザクションのコミットおよびロールバックは実行できますが、SET TRANSACTION SQL文は使用できません。

- 複数コミットにまたがるフェッチ

- 分散トランザクション

接続の制限

接続に関して、TimesTenでのOracle Pro*C/C++プリコンパイラのサポートには次のものは含まれません。

- ALTER AUTHORIZATION句

- データベースへの自動接続

- SYSDBA権限またはSYSOPER権限がTimesTenに存在しない場合、これらの権限を使用したデータベースへの接続。

- TimesTenまたはOracle Databaseへの暗黙的接続(dblinks)

サポートされている接続構文の詳細は、「Pro*C/C++からTimesTenデータベースへの接続」を参照してください。

サポートされていないか制限されている実行可能コマンドおよび句の概要

前の項で示した制限を前提として、この項では、Pro*C/C++ EXEC SQL実行可能コマンド、コマンドのカテゴリおよびTimesTenでサポートされていないか、一部のみサポートされているコマンド句の概要を示します。

- ALTER AUTHORIZATION

- CACHE FREE ALL

- CALL
これはPL/SQLのコールでのみサポートされます。TimesTen組込みプロシージャをコールするには、動的SQL文を使用します。

- すべてのCOLLECTION...コマンド

- COMMIT FORCE '任意のテキスト'

- COMMIT WORK COMMENT '任意のテキスト' RELEASE
COMMENT句はサポートされていません。

- CONNECT BY

- CONTEXT OBJECT OPTION GET

- CONTEXT OBJECT OPTION SET

- DECLARE CURSOR
WITH HOLD句はサポートされていません。

- DECLARE TABLE
Oracle Databaseデータ型のみサポートされています。

- DECLARE TYPE

- EXPLAIN PLAN

- IN SYSDBA MODE

- IN SYSOPER MODE

- LOCK TABLE

- すべてのOBJECT...コマンド

- PARTITION

- REGISTER CONNECT

- RETURN

- RETURNING

- SAVEPOINT

- SET DESCRIPTOR
CHARACTER_SET_NAMEは設定できません。

- SET TRANSACTION

- START WITH

- TO SAVEPOINT

ttSrcScanユーティリティ

既存のPro*C/C++プログラムがあり、そのプログラムでTimesTenでサポートされていないPro*C/C++機能が使用されているかどうかを確認する場合は、ttSrcScanコマンドライン・ユーティリティを使用すると、サポートされていない埋込みSQL関数および型に関してプログラムをスキャンできます。このユーティリティは、TimesTenまたはOracle Databaseがインストールされていない場合でも実行可能なスタンドアロン・ユーティリティであり、TimesTenでサポートされているどのプラットフォームでも動作します。入力としてソース・コード・ファイルを読み取り、出力としてHTMLおよびテキスト・ファイルを作成します。サポートされていない項目が検出されると、それらの項目はログに記録され、代替が示されます。ttSrcScan実行可能ファイルは、TimesTenのインストール先のquickstart/sample_utilディレクトリにあります。

入力ファイルまたはスキャン対象のプログラムのディレクトリ、およびttSrcScanレポートの出力ディレクトリを指定します。その他のオプションも使用できます。詳細は、sample_utilディレクトリにあるREADMEファイルを参照してください。

TimesTen Pro*C/C++の使用

この項では、TimesTenのPro*C/C++アプリケーションの使用に関する次の内容について説明します。

- TimesTen Pro*C/C++の環境および構成

- Pro*C/C++アプリケーションの作成

- Pro*C/C++からTimesTenデータベースへの接続

- エラー・レポートおよび処理

- Pro*C/C++のデモ・プログラム

TimesTen Pro*C/C++の環境および構成

Pro*C/C++のシステム構成ファイルpcscfg.cfgには、Pro*C/C++ソース・コードをプリコンパイルするためのプリコンパイラ・オプションが含まれています。TimesTenでは、TimesTenによって提供されるこのファイルのバージョンを使用する必要があります。通常、これは、TimesTen ttenvスクリプトによりTimesTenが適切に構成されると、自動的にこのバージョンになります。ttenvの詳細は、『Oracle TimesTen In-Memory Databaseインストレーション・ガイド』の環境変数に関する説明を参照してください。

注意:
TimesTenで動作するOCIおよびPro*C/C++プログラムが適切に生成されるためには、OCIおよびPro*C/C++コンパイルにORACLE_HOMEを設定しないでください(以前に設定されていた場合は設定解除してください)。

Pro*C/C++アプリケーションの作成

Pro*C/C++アプリケーションを作成する前に、環境を設定する必要があります。

1. クイック・スタート・デモに付属のTimesTen OCIファイルおよびPro*C/C++ Makeファイルを使用して、適切な環境設定を実行できます。これらのファイルは次の場所にあります(標準のクイック・スタートの場所を想定しています)。

install_dir/quickstart/sample_code/oci/
install_dir/quickstart/sample_code/proc/

2. パス内でOracle Instant ClientディレクトリがOracle Databaseライブラリより前になるように、LD_LIBRARY_PATHまたはPATHが設定されていることを確認します。install_dir/bin/ttenvスクリプトまたはquickstart/ttquickstartenvスクリプトを使用すると、パスは適切に設定されます。環境変数およびttenvの詳細は、『Oracle TimesTen In-Memory Databaseインストレーション・ガイド』の環境変数に関する項を参照してください。

次に、次のような手順を使用して、Pro*C/C++アプリケーションを作成します。ここで示す手順は、UNIXシステムの基本的な例を表し、プログラムに他のインクルード(#include)または他のライブラリへのリンクが含まれていないことを想定しています。instant_clientの指定は、Oracle Instant Clientがインストールされているディレクトリを表します。

詳細なプラットフォーム固有の例は、quickstart/sample_code/procディレクトリのクイック・スタートPro*C/C++ Makeファイルを参照してください。

1. システム・プロンプトからprocコマンドを使用して、Pro*C/C++ソース・ファイルをプリコンパイルします。次に例を示します。

% proc iname=sample.pc

procユーティリティは.pcソース・ファイルを入力として受け取り、.cファイルを生成します。

2. 生成されたCコード・ファイルをコンパイルします。Linuxプラットフォームでは、次のようなコマンドを入力します。

% gcc -c sample.c -I(instant_client)/sdk/

3. 生成されたオブジェクト・モジュールをSQLLIBのモジュールにリンクします。次に例を示します。

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

Pro*C/C++からTimesTenデータベースへの接続

この項では、Pro*C/C++アプリケーションからTimesTenへの接続について説明します。TimesTen Pro*C/C++およびOCIでは、Oracle Instant Clientを使用してTimesTenデータベースに接続します。tnsnamesネーミング・メソッドまたは簡易接続ネーミング・メソッドを使用してデータベースに接続するための追加の構成手順については、「OCIからTimesTenデータベースへの接続」を参照してください。

この項には、次の項目が含まれます。

- 接続の構文およびパラメータ

- tnsnamesまたは簡易接続の使用

- Pro*C/C++でのTimesTen Cache用Oracle Databaseパスワードの指定

- Pro*C/C++での外部で識別されたユーザーとしての接続

注意:
TimesTen接続は、親プロセスから継承することはできません。プロセスが子プロセスを作成(分岐)する前にデータベース接続をオープンした場合、子プロセスではそのデータベース接続を使用しないでください。Pro*C/C++では、子プロセスが誤って親プロセスから接続を継承するのを回避するため、子プロセスを作成する前に親プロセスでEXEC SQL COMMIT RELEASEを使用します。

接続の構文およびパラメータ

TimesTenでは、次の接続構文がサポートされます。

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

パラメータについては、表4-1を参照してください。

表4-1 接続パラメータ

パラメータ

説明

user

ユーザー名

pwd

パスワード

user_string

別々のuserエントリとpwdエントリの代替

これは、user1/pwd1のようにスラッシュで区切られたユーザー名とパスワードです。@記号の後に、dbnameを使用するかわりにデータベース識別子を含めたり、connect_stringを使用するかわりにTNS名または簡易接続文字列を含めることもできます。次の項「tnsnamesまたは簡易接続の使用」の例を参照してください。

dbname

DECLARE DATABASE文を使用してすでに宣言されているデータベース識別子

host_variable

値にデータベース識別子をとる変数

connect_string

TimesTenデータベースの有効なTNS名または簡易接続文字列

tnsnamesまたは簡易接続の使用

Pro*C/C++アプリケーションからTimesTenに接続するには、TimesTenデータベースのTNS名または簡易接続文字列を構成する必要があります。「OCIからTimesTenデータベースへの接続」で説明するtnsnamesまたは簡易接続の手順を実行してください。

Pro*C/C++から、ホスト変数を使用して、ユーザー名、パスワードおよびTNS名を指定することができます。次に例を示します。

EXEC SQL CONNECT :dbstring

ここで、dbstringはuser1/pwd1@my_tnsnameに設定されています。

あるいは、ホスト変数にユーザー名、パスワードおよび簡易接続文字列を指定することもできます。たとえば、dbstringにuser1/pwd1@localhost/ttclient:timesten_clientを設定できます。

あるいは、TWO_TASKまたはLOCAL環境変数(使用オペレーティング・システムに適したほう)が、my_tnsnameまたはlocalhost/ttclient:timesten_clientに設定されている場合は、次の例のように接続できます。

EXEC SQL CONNECT :user1 IDENTIFIED BY :pwd1

Pro*C/C++でのTimesTen Cache用Oracle Databaseパスワードの指定

TimesTen Cacheを使用するには、キャッシュされたOracle Database表からの選択およびその更新が可能なOracle Databaseユーザーと同じ名前を持つキャッシュ・ユーザーがTimesTenデータベースに存在している必要があります。たとえば、このOracle Databaseユーザーは、キャッシュ管理ユーザーまたはスキーマ・ユーザーになります。TimesTenキャッシュ・ユーザーのパスワードは、同じ名前を持つOracle Databaseユーザーと別のパスワードにすることができます。詳細は、『Oracle TimesTen Application-Tier Database Cacheユーザーズ・ガイド』のキャッシュ・インフラストラクチャの設定に関する説明を参照してください。

TimesTen CacheでPro*C/C++を使用する場合、TimesTenでは、TimesTenへのログイン時にEXEC SQL CONNECTコールのパスワード・フィールドにOracle Databaseユーザーのパスワードを追加することで、Pro*C/C++を介してOracle Databaseユーザーのパスワードを渡すことができます。次の例のように、接続文字列で属性OraclePWDを使用します。

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

Oracle DatabaseユーザーのパスワードがTimesTenユーザーのパスワードと同じ場合でも、常にOraclePWDを指定する必要があります。また、TimesTen CacheのOracle Databaseパスワードを指定する場合は、パスワードを別個のホスト変数として指定するEXEC SQL CONNECTの形式を使用する必要があります。この例のcacheuser1は、TimesTenキャッシュ・ユーザーの名前であると同時に、キャッシュされたOracle Database表にアクセスできるOracle Databaseユーザーの名前で、ttpwdは、TimesTenキャッシュ・ユーザーのパスワードで、orclpwdは、Oracle Databaseユーザーのパスワードで、tt_tnsnameは、接続するTimesTenデータベースのTNS名です。Oracle Databaseは、sys.odbc.iniファイルまたはユーザーodbc.iniファイルのTimesTen OracleNetServiceName一般接続属性を使用して指定します。

または、TNS名とともにAT句を使用するかわりに、TWO_TASKまたはLOCAL環境変数を使用できます(「OCIからTimesTenデータベースへの接続」を参照)。

Pro*C/C++での外部で識別されたユーザーとしての接続

[myadmin]のようにユーザー名を大カッコ内に指定し、パスワードを空の文字列""として指定することで、Pro*C/C++を介して外部で識別されたユーザー(外部ユーザー)として接続できます。

特に、TimesTenでは常に外部ユーザーであるインスタンス管理者として接続する場合に有効です。

外部で識別されたユーザーは、直接モードまたはローカル･ホスト上のデータベースへのクライアント/サーバー接続に使用できますが、リモート・ホスト上のデータベースへのクライアント/サーバー接続には使用できません。

次の例を想定してください。

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

この機能はOCIプロキシ構文を使用します。『Oracle Call Interfaceプログラマーズ・ガイド』のプロキシを介したクライアント・アクセスに関する説明を参照してください。

エラー・レポートおよび処理

エラー状態およびエラー・レポートに関して、次のことに注意してください。

- TimesTen Pro*C/C++アプリケーションのエラーでは、Oracle Databaseエラー・コードが返されます。TimesTenでは、同様の状況でOracleがレポートするOracle Databaseエラー・コードと同じエラー・コードをレポートしようとします。エラー・メッセージは、TimesTenカタログまたはOracle Databaseカタログのいずれかから取得されます。エラー・メッセージによっては、TimesTenエラー・コードを伴う場合もあります(該当する場合)。解析エラー・コードに依存するPro*C/C++アプリケーションは、チェックする必要があります。

- TimesTenでは、エラーが発生した場合にエラー・ハンドラへ移動するためのWHENEVER SQLERRORディレクティブ、およびデータが見つからない状況が発生した場合に処理セクションヘ移動するためのWHENEVER NOT FOUNDディレクティブがサポートされています。TimesTenでは、WHENEVER SQLWARNINGディレクティブはサポートされていません。
例:

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

Pro*C/C++のデモ・プログラム

TimesTenには、Pro*C/C++のデモ・プログラムが付属しています。これらのプログラムはquickstart/sample_code/procディレクトリにあります。このディレクトリのREADMEファイルに、デモのコンパイル方法および実行方法が記載されています。

詳細は、クイック・スタートのようこそページ(install_dir/quickstart.html)を参照してください。

TimesTen Pro*C/C++のその他の機能

この項では、TimesTen Pro*C/C++で使用できるその他の機能について説明します。

- TimesTen Pro*C/C++での連想配列バインド

- TimesTen Pro*C/C++でのLOB

TimesTen Pro*C/C++での連想配列バインド

「TimesTen OCIでの連想配列バインド」の説明のとおり、TimesTen PL/SQLでの連想配列(以前の索引付き表またはPL/SQL表)は、IN、OUTまたはIN OUTバインド・パラメータとしてサポートされます。詳細および制限事項は、該当する項を参照してください。

連想配列は、PL/SQLブロックとPro*C/C++アプリケーション間だけでなく、OCIアプリケーション間でも渡すことができます。これらには、BINARY_INTEGER型またはPLS_INTEGER型のPL/SQL変数によって索引付けができます。

通常は、ホスト配列全体がPL/SQLに渡されますが、Pro*C/C++ ARRAYLEN文を使用すれば、より小さい配列サイズを指定できます。

詳細は、『Pro*C/C++プログラマーズ・ガイド』の埋込みPL/SQLに関する説明のPL/SQL表、ホスト配列およびARRAYLEN文に関する各説明を参照してください。

例4-1 Pro*C/C++の連想配列へのバインド

このコードの抜粋は、Pro*C/C++からPL/SQLの連想配列num_tabにバインドされる配列salary[]を示します。

...
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;
...

TimesTen Pro*C/C++でのLOB

TimesTenではLOB(ラージ・オブジェクト)がサポートされています。これには、CLOB(Character LOB)、NCLOB(National Character LOB)およびBLOB(Binary LOB)が含まれます。

「LOBの使用」を参照してください。この項はODBC向けですが、LOBの概要、TimesTenとOracle Database LOBの違いおよびLOBのプログラミング・インタフェースについても説明しています。LOBロケータ、一時LOB、OCIでの簡易データ・インタフェースまたはLOBロケータの使用方法およびOCI LOBのその他の機能については、「TimesTen OCIでのLOB」も参照してください。

この項では、主要なPro*C/C++ LOBの機能およびTimesTen固有のサポートおよび制限に重点を置いています。

TimesTenでのLOBの追加情報は、『Oracle TimesTen In-Memory Database SQLリファレンス』のLOBのデータ型に関する説明を参照してください。

TimesTenでは、BFILE、SecureFile、LOBに対する配列読取りおよび書込みまたはLOBのコールバック関数をサポートしていないことに注意し、LOBの詳細情報およびPro*C/C++での使用方法は、『Pro*C/C++プログラマーズ・ガイド』のLOBに関する説明を参照してください。特に、その章にある、プログラムでのLOBの使用に関する説明を参照してください。

Pro*C/C++に関して、次の内容について説明します。

- Pro*C/C++でのLOBの簡易データ・インタフェースの使用

- Pro*C/C++でのLOBロケータ・インタフェースの使用

重要:
OCIについての章で説明するとおり、TimesTenでは、アプリケーションで使用したLOBは、トランザクションの終了後は有効ではありません。

注意:
TimesTenでは、LOBのピース単位のデータ・インタフェースはOCIまたはPro*C/C++アプリケーションには適用されません。(ただし、LOBロケータ・インタフェースの機能を介して、LOBデータを分割して操作することはできます。)

Pro*C/C++でのLOBの簡易データ・インタフェースの使用

簡易データ・インタフェースでは、その他のスカラー・データ型の操作(EXEC SQL INSERTやEXEC SQL SELECTの使用など)と同様の方法で、アプリケーションによるLOBデータの操作が可能です。アプリケーションでは、対応する変数タイプと互換性のあるLOB型を使用できます。

アプリケーションでは、必要に応じてEMPTY_BLOB()関数またはEMPTY_CLOB()関数を使用して、永続LOBを初期化できます。これは、次に説明する、LOBロケータ・インタフェースでALLOCATEを使用することとほぼ同じです。次のような表について考えてみます。

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 );

次の例では、data_tableから選択したLOBデータをmyblobおよびmyclobに代入し、次に、代入したLOBデータを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);

NCLOBを使用するには、次のように変数を宣言します。

OCIClobLocator CHARACTER SET IS NCHAR_CS *mynclob;

注意:
OCIまたはPro*C/C++を介した簡易データ・インタフェースでは、バインドのサイズが64KBに制限されます。

Pro*C/C++でのLOBロケータ・インタフェースの使用

Pro*C/C++ LOBロケータ・インタフェースは、データベースまたは一時LOB(ピース単位またはチャンク全体)のどちらとも使用できます。

TimesTenでは、特にBFILE、SecureFile、LOBに対する配列の読取りおよび書込みまたはLOBのコールバック関数を対象とした機能がサポートされていないことに注意し、LOBのPro*C/C++文の詳細情報は、『Pro*C/C++プログラマーズ・ガイド』のLOB文に関する説明を参照してください。

エンドツーエンドの例は、『Pro*C/C++プログラマーズ・ガイド』のLOBに関する説明にあるlobdemo1.pcの例を参照してください。

関連情報および使用上の注意は、「OCIでのLOBロケータ・インタフェースの使用」を参照してください。

注意:
Pro*C/C++構文で、機能性が十分でないために操作を完了するための指定を完全に行えない場合は、対応するOCI関数を代替として使用できます。

Pro*C/C++に一時LOBを作成

Pro*C/C++アプリケーションでは、最初にALLOCATEを使用してロケータを割り当ててから、CREATE TEMPORARY埋込みSQL機能を使用して一時LOBを作成できます。FREEを使用してロケータへの割当てを解放し、FREE TEMPORARYを使用して一時LOB自身を解放します。次に例を示します。

「OCIでの一時LOBの作成」も参照してください。

重要:
TimesTenでは、一時LOBを作成すると、データベース・トランザクションがまだ進行していない場合は、データベース・トランザクションが作成されます。エラーとなる状況を回避するには、コミットまたはロールバックを実行してトランザクションをクローズする必要があります。

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;

または、LOBキャラクタ・セット(ここではNCHAR)を指定する場合は、対応するOCI関数を使用できます。

status = OCILobCreateTemporary(svc, err, tempclob, OCI_DEFAULT, SQLCS_NCHAR,
OCI_TEMP_CLOB, TRUE, OCI_DURATION_TRANSACTION);

Pro*C/C++での永続LOBのロケータへのアクセス

アプリケーションでは通常、SQL文を使用してLOBロケータを取得し、適切なAPI関数をロケータに渡すことで、データベースからLOBにアクセスします。

「OCIでの永続LOBのロケータへのアクセス」も参照してください。

前述した『Pro*C/C++プログラマーズ・ガイド』のLOBに関する項で説明しているlobdemo1.pcの例を次に抜粋します。この例では、CLOB license_txtおよび社会保険番号、氏名、および交通違反を集計したテキストが含まれる列(CLOB列)で構成される表license_tableを使用します。

OCIClobLocator *license_txt;
...
EXEC SQL ALLOCATE :license_txt;
...
EXEC SQL SELECT name, txt_summary INTO :name, :license_txt FROM license_table
WHERE sss = :sss;

Pro*C/C++ LOBロケータ・インタフェースを使用したLOBデータの読取りおよび書込み

Pro*C/C++アプリケーションでは、LOB OPENおよびLOB CLOSEを使用してLOBをオープンおよびクローズし、LOB READを使用してLOBデータを読み取り、LOB WRITEまたはLOB WRITE APPENDを使用してLOBデータに書き込みまたは追加し、LOB DESCRIBEを使用してLOBに関する情報を取得し、その他の各種Pro*C/C++機能を使用して様々なその他操作を行うことができます。Pro*C/C++ LOBロケータ・インタフェースのすべての機能については、『Pro*C/C++プログラマーズ・ガイド』のLOBに関する説明を参照してください。

データを書き込むには、LOB WRITE ONEを使用して、1チャンクでデータを書き込みます。TimesTenでは、LOB WRITE FIRST、LOB WRITE NEXTまたはLOB WRITE LAST(ピース単位のデータ・インタフェースの機能)はサポートしていません。

「OCI LOBロケータ・インタフェースを使用したLOBデータの読取りおよび書込み」も参照してください。

EXEC SQL LOB READ文の例を次に示します。

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

詳細は、『Pro*C/C++プログラマーズ・ガイド』の「LOB」にある、ファイルの読取り、BLOBのWRITEの例に関する説明を参照してください。

EXEC SQL LOB WRITE文の例(LOBデータの1チャンクでの書込み)を次に示します。

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

詳細は、『Pro*C/C++プログラマーズ・ガイド』の「LOB」にある、BLOBのREAD、ファイルの書込みの例に関する説明を参照してください。

EXEC SQL LOB WRITE APPEND文の例を次に示します。

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

注意:
LOBをオープンすることは、概念的にはファイルを開くことに似ていますが、技術的には異なります。LOBをオープンすることは、必要となるリソースに関するヒントのようなものです。
OCILobRead()、OCILobWrite()または同等の機能によってアクセスされているLOBは、必要に応じて自動的にオープンされます。

例4-2 Pro*C/C++ LOBロケータ・インタフェースを使用したLOBの書込み

前述した『Pro*C/C++プログラマーズ・ガイド』のLOBに関する項で説明しているlobdemo1.pcの例を次に抜粋します。

...
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;
...

例4-3 Pro*C/C++ LOBロケータ・インタフェースを使用したLOBへの書込みおよび追加

この例では、前述の例と同様に、LOB WRITE ONEを使用します。次にLOB WRITE APPENDも使用して、その他のデータを追加します。ここでは、MAX_CHUNKSに達するまで、1KずつのチャンクでBLOBに書込みまたは追加を行います。

...
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++プリコンパイラ・オプション

この項では、TimesTenでサポートされているPro*C/C++プリコンパイラ・オプションについて説明します。

プリコンパイラ・オプションのサポート

表4-2に、TimesTenのPro*C/C++プリコンパイラ・オプションのサポートを示します。

表4-2 TimesTenのPro*C/C++プリコンパイラ・オプションのサポート

オプション

注意

AUTO_CONNECT

サポートされる値: NO(デフォルト)

CHAR_MAP

サポート

CINCR

適用なし

TimesTenではCPOOL=NOのみサポートされているため、設定は無効になります。

CLOSE_ON_COMMIT

サポートされる値: YES

Oracle Databaseデフォルト値のNOは、TimesTenによって上書きされます。

CMAX

適用なし

TimesTenではCPOOL=NOのみサポートされているため、設定は無効になります。

CMIN

適用なし

TimesTenではCPOOL=NOのみサポートされているため、設定は無効になります。

CNOWAIT

適用なし

TimesTenではCPOOL=NOのみサポートされているため、設定は無効になります。

CODE

サポート

COMP_CHARSET

サポート

config

サポート

CPOOL

サポートされる値: NO(デフォルト)

CPP_SUFFIX

サポート

CTIMEOUT

適用なし

TimesTenではCPOOL=NOのみサポートされているため、設定は無効になります。

DB2_ARRAY

サポート

DBMS

サポートされる値: NATIVE(デフォルト)

DEF_SQLCODE

サポート

DEFINE

サポート

DURATION

適用なし

TimesTenではオブジェクトはサポートされていないため、設定は無効になります。

DYNAMIC

サポート

ERRORS

サポート

ERRTYPE

サポートされていません。

EVENTS

適用なし

両方の値を指定できますが、TimesTen OCIではアドバンスト・キューイングはサポートされていません。

FIPS

サポート

HEADER

サポート

HOLD_CURSOR

サポート

IMPLICIT_SVPT

サポートされる値: NO(デフォルト)

INAME

サポート

INCLUDE

サポート

INTYPE

サポート

LINES

サポート

LNAME

サポート

LTYPE

サポート

MAX_ROW_INSERT

サポート

MAXLITERAL

サポート

MAXOPENCURSORS

サポート

MODE

サポート

NATIVE_TYPES

サポート

NLS_CHAR

サポート

NLS_LOCAL

サポートされる値: NO(デフォルト)

OBJECTS

適用なし

TimesTenではオブジェクトはサポートされていないため、設定は無効になります。

ONAME

サポート

ORACA

サポート

OUTLINE

適用なし

すべての値を指定できますが、TimesTenではOracle Database最適化はサポートされていません。

OUTLNPREFIX

適用なし

両方の値を指定できますが、TimesTenではOracle Database最適化はサポートされていません。

PAGELEN

サポート

PARSE

サポート

PREFETCH

サポート

RELEASE_CURSOR

サポート

RUNOUTLINE

適用なし

両方の値(yes|no)を指定できますが、無視されます。

SELECT_ERROR

サポート

SQLCHECK

適用なし

すべてのSQLCHECK設定を指定できますが、TimesTenではプリコンパイル時のセマンティック・チェックはサポートされていません。

Pro*C/C++アプリケーションでPL/SQLが使用される場合は、常にPro*C/C++はSQLCHECK設定がSEMANTICSである場合と同様に動作します。

重要: SEMANTICS(または同義のFULL)の設定では、プリコンパイルのセマンティック・チェックが実行されない場合にも、常にデータベースへの接続が行われます。

「セマンティック・チェックの制限」を参照してください。

STMT_CACHE

サポート

SYS_INCLUDE

サポート

THREADS

サポート

TYPE_CODE

サポート

UNSAFE_NULL

サポート

USERID

サポート

UTF16_CHARSET

サポートされる値: NCHAR_CHARSET

VARCHAR

サポート

VERSION

適用なし

TimesTenではオブジェクトはサポートされていないため、設定は無効になります。

注意:
TimesTenでは、CLOSE_ON_COMMITのデフォルト値はサポートされていません。TimesTenでは、CLOSE_ON_COMMIT=YESのみサポートされています。

プリコンパイラ・オプションの設定

プリコンパイラ・オプションは次の方法で設定できます。

- コンパイル時に、構成ファイルpcscfg.cfgまたはPro*C/C++コマンドラインで設定
コマンドラインでの設定は、構成ファイルでの設定よりも優先されます。

- 実行時に、EXEC ORACLE OPTIONコマンドで設定
実行時の設定は、コンパイル時の設定よりも優先されます。

たとえば、TimesTenに付属の構成ファイルの一部を次に示します。

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

次のコマンドラインは、構成ファイルでのltype=short設定よりも優先されます。

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

次の実行時コマンドは、コマンドラインからのltype=long設定よりも優先されます。

EXEC ORACLE OPTION LTYPE=NONE;

5 XLAおよびTimesTenイベント管理

TimesTenトランザクション・ログAPI(XLA)はC言語関数のセットで、この関数によって、次の処理を実行するアプリケーションを実装できます。

- ローカル・データベースの指定した表への変更に関してTimesTenを監視するアプリケーション。

- これらの変更の通知をリアルタイムで受信するアプリケーション。

XLAの主な目的は、トリガーにかわる高パフォーマンスで非同期の機能です。

注意:
『Oracle TimesTen In-Memory Database開発者および管理者ガイド』で説明するTimesTenレプリケーション・ソリューションではニーズが満たされない場合、XLA関数を使用してカスタム・データ・レプリケーション・ソリューションを構築できます。

この章の内容は次のとおりです。

- XLAの概念

- XLAイベント・ハンドラ・アプリケーションの作成

- レプリケーション・メカニズムとしてのXLAの使用

- その他のXLA機能

各XLA関数の詳細は、第9章「XLAリファレンス」を参照してください。

XLAの概念

この項の内容は次のとおりです。

- XLAの基本

- XLAでレコードをトランザクション・ログから読み取る方法

- XLAおよびマテリアライズド・ビューについて

- XLAブックマークについて

- XLAデータ型について

- アクセス制御がXLAに与える影響

- XLAの制限事項

- XLAのデモ

ここで説明するXLA関数については、第9章「XLAリファレンス」を参照してください。

XLAの基本

TimesTen XLAによって更新レコードがトランザクション・ログ・バッファまたはトランザクション・ログ・ファイルから直接取得されるため、それらの更新レコードは、必要とされるかぎり使用可能です。また、ロギング・モデルによって、複数のリーダーでトランザクション・ログの更新を同時に読み取ることができます。

ttXlaPersistOpen XLA関数は、でデータベースへの接続をオープンします。

TimesTenは、初期作成時に、アプリケーションがリンクされているTimesTenリリースと同じバージョンに、トランザクション・ログ・ハンドルを構成します。また、ttXlaGetVersionおよびttXlaSetVersion XLA関数を使用して、以前のXLAバージョンと相互運用することもできます。

XLAでレコードをトランザクション・ログから読み取る方法

アプリケーションによってデータベースが変更されると、TimesTenは、データの変更およびトランザクション・コミットなどの他のイベントを示すトランザクション・ログ・レコードを生成します。

新しいトランザクション・ログ・レコードは、生成されると常にログ・バッファの最後に書き込まれます。

トランザクション・ログ・レコードは、メモリ内のログ・バッファからディスク上のトランザクション・ログ・ファイルへ定期的に一括でフラッシュされます。XLAが初期化されている場合、XLAアプリケーションでは、トランザクション・ログのどの部分がディスクまたはメモリーに存在するかについて考慮する必要はありません。したがって、この章で使用するトランザクション・ログという用語は、トランザクション更新レコードの仮想ソースを指し、これらのレコードが物理的にメモリーまたはディスクに保存されているかどうかは関係ありません。

アプリケーションで、XLAを使用し、データベースへの変更に関してトランザクション・ログを監視できます。XLAは、トランザクション・ログ全体を読み取り、ログ・レコードをフィルタ処理し、目的の表および列への変更が含まれているトランザクション・レコードのリストをXLAアプリケーションに配信します。

XLAは、レコードをディスクリート・トランザクションにソートします。複数のアプリケーションが同時にデータベースを更新している場合、異なるアプリケーションのトランザクション・ログ・レコードがトランザクション・ログに交互配置されます。

XLAは、特定のトランザクションに関連するすべてのトランザクション・ログ・レコードを透過的に抽出し、それらを連続するリストにしてアプリケーションに配信します。

コミット済のトランザクションのレコードのみが返されます。コミット済のレコードは、最後のコミット・レコードがトランザクション・ログに書き込まれる順序で返されます。コミットされていないデータベースへの変更に関連するレコードは、XLAによってフィルタ処理されます。

変更が行われ、その後にロールバックされた場合、XLAは強制終了されたトランザクションのレコードをアプリケーションに配信しません。

これらのXLAの基本概念のほぼすべてを次の例5-1に示し、次にそれぞれの内容を箇条書きで示します。

図5-1に示すトランザクション・ログを例として考えてみます。

図5-1 トランザクション・ログから抽出されるレコード

例5-1 トランザクション・ログ・レコードの読取り

この例では、トランザクション・ログに次のレコードが含まれています。

CT1 - アプリケーションCは、表Wの行1を値7.7で更新。
BT1 - アプリケーションBは、表Xの行3を値2で更新。
CT2 - アプリケーションCは、表Wの行9を値5.6で更新。
BT2 - アプリケーションBは、表Yの行2を値XYZで更新。
AT1 - アプリケーションAは、表Zの行1を値3で更新。
AT2 - アプリケーションAは、表Zの行3を値4で更新。
BT3 - アプリケーションBがトランザクションをコミット。
AT3 - アプリケーションAがトランザクションをロールバック。
CT3 - アプリケーションCがトランザクションをコミット。

表W、YおよびZへの変更を検出するように設定されているXLAアプリケーションでは次のようになります。

BT2およびBT3 - 表Yの行2を値XYZで更新し、コミット。
CT1 - 表Wの行1を値7.7で更新。
CT2およびCT3 - 表Wの行9を値5.6で更新し、コミット。

この例では、次のことが示されています。

- アプリケーションBおよびCのすべてのトランザクション・レコードが同時に書き込まれます。

- トランザクション・ログでは、アプリケーションCのレコードがアプリケーションBのレコードより前に書き込まれますが、アプリケーションBのコミット(BT3)はアプリケーションCのコミット(CT3)より前に書き込まれます。その結果、アプリケーションBのレコードはアプリケーションCのレコードより先にXLAアプリケーションに返されます。

- XLAは表Xへの変更を検出するように設定されていないため、アプリケーションBによる表Xへの更新(BT1)は示されません。

- アプリケーションAによる表Zへの更新(AT1およびAT2)が示されないのは、コミットされずにロールバックされたためです(AT3)。

XLAおよびマテリアライズド・ビューについて

XLAを使用すると、表およびマテリアライズド・ビューの両方への変更を追跡できます。マテリアライズド・ビューによって、複数のディテール表内の選択した行および列への変更を追跡できる単一のソースが提供されます。マテリアライズド・ビューがない場合は、XLAアプリケーションで、すべてのディテール表の更新レコード(アプリケーションにとって重要ではない行および列への更新が反映されているレコードを含む)に対して監視およびフィルタ処理を行う必要があります。

一般に、表またはマテリアライズド・ビューへの変更を追跡するために使用するXLAメカニズムの間に処理上の違いはありません。ただし、非同期のマテリアライズド・ビューの場合、非同期のマテリアライズド・ビューのXLA通知の順序は、関連付けられているディテール表での順序または同期のマテリアライズド・ビューでの順序と同じとはかぎらないことに注意してください。たとえば、ディテール表に2つの挿入が行われる場合、非同期のマテリアライズド・ビューでは逆の順序で挿入が行われることがあります。さらに、マテリアライズド・ビューのディテール表への更新は、削除とその後に続く挿入としてXLAによって扱われることがあります。また、複数の挿入や複数の削除などの複数の操作を組み合せて1つの操作にすることもできます。正確な順序に依存するアプリケーションでは、非同期のマテリアライズド・ビューを使用しないでください。

マテリアライズド・ビューの詳細は、次を参照してください。

- 『Oracle TimesTen In-Memory Database SQLリファレンス・ガイド』のCREATE MATERIALIZED VIEWに関する項

- 『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のマテリアライズド・ビューの理解に関する項

XLAブックマークについて

各XLAリーダーは、ブックマークを使用して更新ログ・ストリーム内での位置を維持します。各ブックマークは、ログ・レコード識別子を使用してトランザクション・ログ内の更新レコードを追跡する2つのポインタで構成されています。

- 初期読取りログ・レコード識別子は、最後に確認されたトランザクション・ログ・レコードを指します。初期読取りログ・レコード識別子はデータベースに保存されるため、データベースの接続、停止および障害が発生しても永続的に維持されます。

- 現行読取りログ・レコード識別子は、トランザクション・ログから現在読み取られているレコードを指します。

この項の以降の内容は次のとおりです。

- ブックマークの作成または再利用

- ブックマークの動作

- レプリケートされたブックマーク

- XLAブックマークおよびトランザクション・ログの保留

ブックマークの作成または再利用

「XLAの初期化およびXLAハンドルの取得」で説明するとおり、ttXlaPersistOpen関数をコールしてXLAハンドルを初期化する場合、tagパラメータを使用して新しいブックマークまたはシステムに既存のブックマークのいずれかを指定し、optionsパラメータを使用してそのブックマークが新しいレプリケートされていないブックマーク、新しいレプリケートされたブックマーク、または既存(再利用)のブックマークのいずれであるかを指定します。この時点で、ブックマークに関連付けられている初期読取りログ・レコード識別子は、データベースから読み取られ、XLAハンドル(ttXlaHandle_h)にキャッシュされます。この識別子は、トランザクション・ログ内のリーダーの開始位置を示します。

詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttLogHoldsに関する説明を参照してください。TimesTen組込みプロシージャは、トランザクション・ログの保留に関する情報を返します。

ブックマークの動作

アプリケーションが最初にXLAを初期化し、XLAハンドルを取得した時点では、現行読取りログ・レコード識別子と初期読取りログ・レコード識別子は、この後の図5-2に示すように、両方ともデータベースに最後に書き込まれたレコードを指しています。

図5-2 XLAハンドルを初期化した時点でのログ・レコード識別子の位置

ttXlaNextUpdateまたはttXlaNextUpdateWait関数を使用すると、一連のコミット済トランザクションのレコードが、コミットされた順序でトランザクション・ログから返されます(「トランザクション・ログからの更新レコードの取得」を参照)。図5-3に示すように、ttXlaNextUpdateをコールするたびに、ブックマークの現行読取りログ・レコード識別子は、最後に読み取られたレコードに再設定されます。現行読取りログ・レコード識別子によって、次にttXlaNextUpdateをコールする場合の開始位置がマークされます。

図5-3 ttXlaNextUpdateによって取得されるレコード

ttXlaGetLSNおよびttXlaSetLSN関数を使用すると、レコードを再度読み取ることができます(「ブックマークの位置の変更」を参照)。ただし、図5-4に示すように、ttXlaAcknowledge関数をコールすると、ブックマークの初期読取りログ・レコード識別子が現行読取りログ・レコード識別子に永続的に再設定されます。ttXlaAcknowledge関数をコールして初期読取りログ・レコード識別子を再設定すると、以前に読み取られたすべてのトランザクション・レコードにパージのフラグが設定されます。初期読取りログ・レコード識別子を再設定すると、ttXlaSetLSN関数を使用して元に戻し、以前に読み取ったトランザクションを再度読み取ることはできません。

図5-4 ttXlaAcknowledgeによるブックマークの再設定

注意:
ttXlaAcknowledgeをコールすると、確認する関連更新レコードがない場合でもブックマークが再設定されます。これは、トランザクション・ログ領域の管理に役立ちますが、処理コストとのバランスを保つ必要があります。XLAでは、トランザクション・ログが一度に1ファイルずつパージされる点に注意してください。処理の詳細は、「ttXlaAcknowledge」を参照してください。

データベースで作成されるブックマークの数は64に制限されています。各ブックマークに一度に関連付けることができるアクティブな接続は1つのみです。ただし、ブックマークは、存続期間中に多数の接続と関連付けることができます。アプリケーションによって、接続をオープンし、新しいブックマークを作成し、そのブックマークを接続と関連付け、ブックマークを使用してレコードを読み取り、接続をデータベースから切断し、データベースに再接続して、新しい接続を作成し、この新しい接続を既存のブックマークと関連付け、以前の接続が停止されたトランザクション・ログ・レコードから読取りを続行することができます。

レプリケートされたブックマーク

アクティブ・スタンバイ・ペアのレプリケーション・スキームを使用する場合は、ttXlaPersistOpenコールのoptionsの設定に従ってレプリケートされたブックマークを使用できます。レプリケートされたブックマークの場合、ブックマークに対する処理は必要に応じてスタンバイ・データベースにレプリケートされます。これにより、フェイルオーバーが発生した場合、より効率的にブックマークの位置をリカバリできます。読取りは、新しいアクティブ・ストアへのスイッチオーバー前に読取りが中断された位置に近いXLAレコードのストリームから再開されます。レプリケートされたブックマークがない場合、古いアクティブ・ストアに返されている多数の重複レコードを読み取る必要があります。

レプリケートされたブックマークを使用する際には、次の順に手順を実行する必要があります。

1. アクティブ・スタンバイ・ペアのレプリケーション・スキームを作成します。(これは、create active standby pair操作、またはクラスタウェア管理環境のttCWAdmin -createコマンドによって行われます。)

2. ブックマークを作成します。

3. ブックマークをサブスクライブします。

4. アクティブ・スタンバイ・ペアを起動します(このとき、スタンバイへの複製が発生し、レプリケーションが始まります)。(これはttRepAdmin -duplicateコマンド、またはクラスタウェア管理環境のttCWAdmin -startコマンドによって行われます。)

使用に関しては、次の点に注意してください。

- スタンバイ・データベースでのブックマークの位置は、アクティブ・データベースでのブックマークの位置に非常に近くなります。ただし、確認処理のレプリケーションは非同期に行われるため、確認処理の実行頻度によっては、フェイルオーバーの発生時に更新の重複を示す小さなウィンドウが表示されることがあります。

- データベースがスタンバイ・ステータスからアクティブ・ステータスに変わった後に、ttXlaClose関数とttXlaPersistOpen関数を使用して、そのデータベース上のすべてのブックマークを閉じ、再度開く必要があります。ブックマークは、レプリケーション・エージェントによってスタンバイ・データベース上で必要に応じて自動的に再配置されるため、スタンバイ・データベース上のレプリケートされたブックマークの状態は、通常のXLA処理中に変化します。データベースがアクティブ・ステータスに変更される前に開いていたブックマークを使用しようとすると、ブックマークの状態がリセットされたこととブックマークが再配置されたことを示すエラーが表示されます。この場合でも再配置されたブックマークから読取りを続行できますが、ブックマークを閉じて再度開くと、エラーを回避できます。

- レプリケートされたブックマークが存在する間に、アクティブ・スタンバイ・ペアのスキームを削除できます。ブックマークは当然その時点でレプリケートされなくなりますが、削除はされません。続けてアクティブ・スタンバイ・ペア・スキームを再び有効にすると、これらのブックマークは自動的にスキームに追加されます。

- レプリケーション・エージェントの実行中は、レプリケートされたブックマークを削除できません。

- アクティブ・データベース内のレプリケートされたブックマークのみを読み取って確認できます。レプリケートされたブックマークを確認するたびに、確認処理がスタンバイ・データベースに非同期にレプリケートされます。

XLAブックマークおよびトランザクション・ログの保留

XLAが使用中の場合、TimesTenのトランザクション・ログ・ファイルは、XLAのブックマークが進むまで保留されることに注意してください。保留によって、XLAで必要でないことが確認されるまで、トランザクション・ログ・ファイルはパージされません。XLAアプリケーションが予期せず終了したり、そのブックマークの削除や変更トラッキングの無効化を行わずに切断した場合などに、ブックマークが固まってしまうと、ログは保持されたままになり、トランザクション・ログ・ファイルが過度に蓄積される場合があります。この蓄積の結果、ディスク領域が一杯になる場合があります。

この状況を監視し、対処するための情報は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のトランザクション・ログ・ファイルの蓄積の監視に関する説明を参照してください。

XLAデータ型について

表5-1に、内部SQLデータ型と、リリース7.0より前およびリリース7.0以上のXLAデータ型のマッピングを示します。TimesTenデータ型の詳細は、『Oracle TimesTen In-Memory Database SQLリファレンス・ガイド』のデータ型に関する項を参照してください。

表5-1 XLAデータ型のマッピング

内部SQLデータ型

リリース7.0より前のXLAデータ型

リリース7.0以上のXLAデータ型

TT_CHAR

SQL_CHAR

TTXLA_CHAR_TT

TT_VARCHAR

SQL_VARCHAR

TTXLA_VARCHAR_TT

TT_NCHAR

SQL_WCHAR

TTXLA_NCHAR_TT

TT_NVARCHAR

SQL_WVARCHAR

TTXLA_NVARCHAR_TT

CHAR

-

TTXLA_CHAR

NCHAR

-

TTXLA_NCHAR

VARCHAR2

-

TTXLA_VARCHAR

NVARCHAR2

-

TTXLA_NVARCHAR

TT_TINYINT

SQL_TINYINT

TTXLA_TINYINT

TT_SMALLINT

SQL_SMALLINT

TTXLA_SMALLINT

TT_INTEGER

SQL_INTEGER

TTXLA_INTEGER

TT_BIGINT

SQL_BIGINT

TTXLA_BIGINT

BINARY_FLOAT

SQL_REAL

TTXLA_BINARY_FLOAT

BINARY_DOUBLE

SQL_DOUBLE

TTXLA_BINARY_DOUBLE

TT_DECIMAL

SQL_DECIMAL

TTXLA_DECIMAL_TT

NUMBER

-

TTXLA_NUMBER

NUMBER(p,s)

-

TTXLA_NUMBER

FLOAT

-

TTXLA_NUMBER

TT_TIME

SQL_TIME

TTXLA_TIME

TT_DATE

SQL_DATE

TTXLA_DATE_TT

TT_TIMESTAMP

SQL_TIMESTAMP

TTXLA_TIMESTAMP_TT

DATE

-

TTXLA_DATE

TIMESTAMP

-

TTXLA_TIMESTAMP

TT_BINARY

SQL_BINARY

TTXLA_BINARY

TT_VARBINARY

SQL_VARBINARY

TTXLA_VARBINARY

ROWID

-

TTXLA_ROWID

BLOB

-

TTXLA_BLOB

CLOB

-

TTXLA_CLOB

NCLOB

-

TTXLA_NCLOB

XLAでは、内部SQLデータ型と外部プログラム・データ型を変換する関数が提供されます。たとえば、ttXlaNumberToCStringを使用すると、NUMBER列を文字列に変換できます。TimesTenは、次のXLAデータ型変換関数を備えています。

- ttXlaDateToODBCCType

- ttXlaDecimalToCString

- ttXlaNumberToCString

- ttXlaNumberToDouble

- ttXlaNumberToBigInt

- ttXlaNumberToInt

- ttXlaNumberToSmallInt

- ttXlaNumberToTinyInt

- ttXlaNumberToUInt

- ttXlaOraDateToODBCTimeStamp

- ttXlaOraTimeStampToODBCTimeStamp

- ttXlaRowidToCString

- ttXlaTimeToODBCCType

- ttXlaTimeStampToODBCCType

アクセス制御がXLAに与える影響

データベース内の処理に与えるTimesTenアクセス制御の影響の概要については、「アクセス制御に関するTimesTen機能の考慮事項」を参照してください。アクセス制御は、次のようにXLAに影響を与えます。

- 次のようなXLA機能の実行には、システム権限XLAが必要です。

- ttXlaPersistOpen C関数を使用するなど、XLAリーダーとしてのTimesTenへの接続(CREATE SESSION権限も必要)

- その他のXLA関連のTimesTen C関数の実行(第9章「XLAリファレンス」を参照)

- XLA関連のTimesTen組込みプロシージャの実行
プロシージャttXlaBookmarkCreate、ttXlaBookmarkDelete、ttXlaSubscribeおよびttXlaUnsubscribeについては、『Oracle TimesTen In-Memory Databaseリファレンス』の組込みプロシージャに関する説明を参照してください。

- XLA権限を持つユーザーには、SELECT ANY TABLE、SELECT ANY VIEWおよびSELECT ANY SEQUENCEシステム権限と同等の権限があり、データベースで発生するDDL文レコードを取得できます。その結果、このユーザーは、XLA権限を持たない場合にはアクセスが許可されていないデータベース・オブジェクトに関する情報を取得できる点に注意してください。

XLAの制限事項

TimesTen XLAの使用時は、次の制限事項に注意してください。

- XLAは、TimesTenでサポートされているすべてのプラットフォームで使用できます。ただし、異なるプラットフォーム間、または同じプラットフォームの32ビットと64ビットとの間でのデータの転送はXLAではサポートされていません。

- LOBに対するXLAのサポートは限定されています。詳細は、「更新を監視する表の指定」を参照してください。

- XLAでは、ドライバ・マネージャ・ライブラリまたはクライアント/サーバー・ライブラリにリンクされたアプリケーションはサポートされていません。(クイック・スタート・アプリケーションで提供されるTimesTenドライバ・マネージャではXLAをサポートしていますが、ドライバ・マネージャ自体が完全にサポートされているわけではありません。「ODBCドライバ・マネージャとのリンク」のこのドライバ・マネージャについての注意を参照してください。)

- XLAリーダーは、インメモリー列圧縮を使用する表をサブスクライブできません。

- Oracle Databaseに対する変更トラッキング・トリガーでは、自動リフレッシュ・キャッシュ・グループの列レベルでの解決は行いません。(これには非常に費用がかかります。)そのため、自動リフレッシュ機能では、実際にはすべての列のデータが変更されていない場合でも、行のすべての列が更新され、XLAではすべての列が変更されたということのみがレポートされます。

XLAのデモ

TimesTenには、この章で説明する多数のXLA関数の使用方法を示すxlaSimpleデモが用意されています。このデモはquickstart/sample_code/odbc/xlaディレクトリにあります。

C開発者向けのTimesTenデモ・プログラムの概要は、「TimesTen Cのデモについて」を参照してください。詳細は、install_dir/quickstart.htmlを参照してください。odbcディレクトリのREADMEファイルには、xlaSimpleのビルドおよび実行の手順が記載されています。

次の項「XLAイベント・ハンドラ・アプリケーションの作成」に示すサンプル・コードなど、この章の大部分の内容は、このxlaSimpleデモに基づいています。このデモでは、表MYDATAがAPPUSERスキーマに作成されています。APPUSERとしてログインしている間は、その表を更新することになります。XLAUSERとしてログインしている間は、xlaSimpleデモが更新についてレポートします。

デモを実行するには、コマンド・プロンプトでxlaSimpleを実行します。サンプル・データベースの作成時に指定したXLAUSERのパスワードを入力するように求められます。別のコマンド・プロンプトでttIsqlを開始して、APPUSERとしてTimesTenサンプル・データベースに接続します。再度、サンプル・データベースの作成時に指定したパスワードの入力を求められます。

ttIsqlコマンド・プロンプトで、DML文を入力して表を変更できます。その後、xlaSimpleウィンドウでXLA出力を表示できます。

XLAイベント・ハンドラ・アプリケーションの作成

この項では、データベース内の選択した表への変更を検出およびレポートするXLAアプリケーションの一般的な作成手順について説明します。「列データの確認」のような例外もありますが、この項で説明する手順は、ほぼすべてのXLAアプリケーションに適用できます。

この項で説明する手順は次のとおりです。

- データベース接続ハンドルの取得

- XLAの初期化およびXLAハンドルの取得

- 更新を監視する表の指定

- トランザクション・ログからの更新レコードの取得

- レコード・ヘッダーの確認および行アドレスの検出

- 列データの確認

- XLAエラーの処理

- XLAブックマークを使用する表の削除

- ブックマークの削除

- XLAアプリケーションの終了

この項のコード例は、xlaSimpleデモ・アプリケーションに基づいています。

ここで説明するXLA関数については、第9章「XLAリファレンス」を参照してください。

重要:
「TimesTen includeファイル」で説明したファイル以外に、XLAアプリケーションにはtt_xla.hを含める必要があります。

注意:
コード例をわかりやすくするために、各関数コールのルーチン・エラー・チェック・コードは省略されています。エラーの処理方法については、「XLAエラーの処理」を参照してください。

データベース接続ハンドルの取得

すべてのODBCアプリケーションと同様に、XLAアプリケーションは、ODBCを初期化し、環境ハンドル(henv)を取得し、接続ハンドル(hdbc)を取得して、特定のデータベースと通信する必要があります。

環境ハンドルおよび接続ハンドルを初期化します。

SQLHENV henv = SQL_NULL_HENV;
SQLHDBC hdbc = SQL_NULL_HDBC;

henvのアドレスをSQLAllocEnv ODBC関数に渡して環境ハンドルを割り当てます。

rc = SQLAllocEnv(&henv);

hdbcのアドレスをSQLAllocConnect ODBC関数に渡して、データベース用の接続ハンドルを割り当てます。

rc = SQLAllocConnect(henv, &hdbc);

SQLDriverConnect ODBC関数をコールして、接続文字列(connStr)で指定されたデータベースに接続しますが、この接続文字列は、この例ではコマンドラインから渡されます。

static char connstr[CONN_STR_LEN];
...
rc = SQLDriverConnect(hdbc, NULL, (SQLCHAR*)connstr, SQL_NTS, NULL, 0,
NULL, SQL_DRIVER_COMPLETE);

注意:
XLAアプリケーションで使用するためにODBC接続ハンドルをオープンすると、ttXlaCloseをコールして対応するXLAハンドルをクローズするまで、ODBCハンドルをODBC処理に使用できません。

SQLSetConnectOption ODBC関数をコールして、自動コミットをオフにします。

rc = SQLSetConnectOption(hdbc, SQL_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF);

XLAの初期化およびXLAハンドルの取得

前述の項「データベース接続ハンドルの取得」の説明に従ってODBCを初期化し、環境ハンドルおよび接続ハンドルを取得した後、XLAを初期化し、XLAハンドルを取得して、トランザクション・ログにアクセスできます。1つのODBC接続に対して1つのみのXLAハンドルを作成します。アプリケーションで複数のXLAリーダー・スレッドを使用する(それぞれが独自のXLAブックマークに接続されている)場合は、スレッドごとに個別のXLAハンドルおよびODBC接続を作成します。

この項では、XLAを初期化する方法について説明します。XLAを初期化する前に、ブックマークを初期化します。その後、XLAハンドルをttXlaHandle_h型として初期化します。

unsigned char bookmarkName [32];
...
strcpy((char*)bookmarkName, "xlaSimple");
...
ttXlaHandle_h xla_handle = NULL;

bookmarkNameおよびxla_handleのアドレスをttXlaPersistOpen関数に渡してXLAハンドルを取得します。

rc = ttXlaPersistOpen(hdbc, bookmarkName, XLACREAT, &xla_handle);

XLACREATオプションは、新しいレプリケートされていないブックマークの作成に使用します。または、XLAREPLオプションを使用して、レプリケートされたブックマークを作成します。どちらの場合も、ブックマークがすでに存在する場合は処理に失敗します。

すでに存在するブックマークを使用するには、次の例で示すように、XLAREUSEオプションを指定してttXlaPersistOpenをコールします。

#include <tt_errCode.h>      /* TimesTen Native Error codes */
...
if ( native_error == 907 ) { /* tt_ErrKeyExists */
rc = ttXlaPersistOpen(hdbc, bookmarkName, XLAREUSE, &xla_handle);
...
}

ttXlaPersistOpenに無効なパラメータが指定されている場合、またはアプリケーションでハンドル用のメモリーを割り当てることができなかった場合は、SQL_INVALID_HANDLEというコードが返されます。この場合、このエラーまたはこれ以降のエラーの検出にttXlaErrorは使用できません。

ttXlaPersistOpenが失敗しても、まだハンドルを作成する場合は、メモリー・リークを防ぐためにハンドルを閉じる必要があります。

更新を監視する表の指定

前述の項「XLAの初期化およびXLAハンドルの取得」の説明に従ってXLAを初期化し、XLAハンドルを取得した後、更新イベントを監視する表またはマテリアライズド・ビューを指定できます。

SYS.XLASUBSCRIPTIONS表を問い合せることによって、ブックマークをサブスクライブする表を確認できます。また、SYS.XLASUBSCRIPTIONSを使用すると、特定の表にサブスクライブしたブックマークを確認することもできます。

ttXlaNextUpdateおよびttXlaNextUpdateWait関数は、DDLイベントに関連するXLAレコードを取得します。DDL XLAレコードはどのXLAブックマークでも使用できます。DDLイベントには、CREATAB、DROPTAB、CREAIND、DROPIND、CREATVIEW、DROPVIEW、CREATSEQ、DROPSEQ、CREATSYN、DROPSYN、ADDCOLS、DRPCOLSおよびTRUNCATEトランザクションが含まれています。これらのイベント・タイプの詳細は、「ttXlaUpdateDesc_t」を参照してください。

ttXlaTableStatus関数は、現行のブックマークを指定した表に更新するためにサブスクライブします。または、現在のブックマークが表に関連するDMLレコードをすでに監視しているかどうかを判別します。

ttXlaTableByName関数をコールして、指定した表またはマテリアライズド・ビューのシステム識別子およびユーザー識別子の両方を取得します。次に、ttXlaTableStatus関数をコールして、表またはマテリアライズド・ビューへの変更を監視するためにXLAを有効にします。

注意:
XLAでのLOBのサポートは、次のように制限されています。

- LOB列を含む表にサブスクライブできますが、LOB値自体についての情報は使用できません。

- ttXlaGetColumnInfoでは、LOB列に関する情報が返されます。

- LOBを含む列は、空(長さがゼロ)またはNULL(実際に値がNULLの場合)としてレポートされます。このようにして、NULL列と非NULL列を区別できます。

例5-2 更新を監視する表の指定

この例では、MYDATA表への変更を追跡します。

#define TABLE_OWNER "APPUSER"
#define TABLE_NAME "MYDATA"
...
SQLUBIGINT SYSTEM_TABLE_ID = 0;
...
SQLUBIGINT userID;

rc = ttXlaTableByName(xla_handle, TABLE_OWNER, TABLE_NAME,
&SYSTEM_TABLE_ID, &userID);

表の識別子を取得すると、ttXlaTableStatus関数を使用して、MYDATA表への変更を検出するためのXLA更新追跡を有効にできます。newstatusパラメータを0(ゼロ)以外の値に設定すると、指定した表に行われた変更がXLAによって追跡されます。

SQLINTEGER oldstatus;
SQLINTEGER newstatus = 1;
...
rc = ttXlaTableStatus(xla_handle, SYSTEM_TABLE_ID, 0,
&oldstatus, &newstatus);

oldstatusパラメータは、コール時の表のステータスを示す出力です。

ttXlaTableStatusでnewstatusをNULLにし、oldstatusのみを返すことによって、表の現行のXLAステータスを返すことができます。次に例を示します。

rc = ttXlaTableStatus(xla_handle, SYSTEM_TABLE_ID, 0,
&oldstatus, NULL);
...
if (oldstatus != 0)
printf("XLA is currently tracking changes to table %s.%s\n",
TABLE_OWNER, TABLE_NAME);
else
printf("XLA is not tracking changes to table %s.%s\n",
TABLE_OWNER, TABLE_NAME);

トランザクション・ログからの更新レコードの取得

更新を監視する表を指定した後、ttXlaNextUpdateまたはttXlaNextUpdateWait関数をコールして、トランザクション・ログから一連のレコードを返すことができます。コミット済のトランザクションのレコードのみが返されます。レコードはコミットされた順序で返されます。不要になり、トランザクション・ログからパージ可能なレコードをXLAが判別できるように、ttXlaAcknowledge関数を定期的にコールして、トランザクションの受信を確認する必要があります。これらの関数は、トランザクション・ログ内のアプリケーションのブックマークの位置に影響を与えます(「ブックマークの動作」を参照)。詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttLogHoldsに関する説明も参照してください。TimesTen組込みプロシージャは、トランザクション・ログの保留に関する情報を返します。

注意:
ttXlaAcknowledgeは、必要な場合にのみ使用する必要がある高コストの処理です。

ttXlaNextUpdateによって返されたトランザクション内の各更新レコードは、ttXlaUpdateDesc_t構造体で記述される更新ヘッダーで始まります。この更新ヘッダーには、レコードがトランザクションの最初のレコード(TT_UPDFIRST)か、最後のコミット・レコード(TT_UPDCOMMIT)かを示すフラグが格納されています。また、更新ヘッダーは、更新によって影響を受ける表も識別します。更新ヘッダーの後には、データベース内の表に対して行われた変更について記述する0(ゼロ)から2行の行データが続きます。

次の図5-5に、4つの更新レコードで構成されているトランザクションをトランザクション・ログから返すttXlaNextUpdateへのコールを示します。返されたトランザクションの受信は、ttXlaAcknowledgeをコールすることで確認され、ブックマークが再設定されます。

注意:
この例は、説明を明確にするために簡略化されています。実際のXLAアプリケーションでは、ttXlaAcknowledgeをコールする前に、複数のトランザクションのレコードを読み取る可能性があります。

図5-5 更新レコード

例5-3 トランザクション・ログからの更新レコードの取得

xlaSimpleデモでは、表の更新に対する監視は、ユーザーが停止するまで続行されます。

この例では、ttXlaNextUpdateWaitをコールする前に、返されるttXlaUpdateDesc_tレコードを保持するバッファへのポインタ(arry)と実際に返されるレコード数を保持する変数(records)を初期化します。この例ではttXlaNextUpdateWaitをコールするため、トランザクション・ログ・バッファでレコードが見つからない場合に待機する秒数(FETCH_WAIT_SECS)も指定します。

次に、ttXlaNextUpdateWaitをコールし、これらの値を渡してarry内の一連のttXlaUpdateDesc_tレコードを取得します。例5-4に示すように、arry内の各レコードは、HandleChange()関数に渡すことによって処理されます。すべてのレコードの処理後、ttXlaAcknowledgeをコールして、ブックマークの位置を再設定します。

#define FETCH_WAIT_SECS 5
...
SQLINTEGER records;
ttXlaUpdateDesc_t** arry;
int j;

while (!StopRequested()) {

/* Get a batch of update records */
rc = ttXlaNextUpdateWait(xla_handle, &arry, 100,
&records, FETCH_WAIT_SECS);
if (rc != SQL_SUCCESS {
/* See "Handling XLA errors" */
}

/* Process the records */
for(j=0; j < records; j++){
ttXlaUpdateDesc_t* p;
p = arry[j];
HandleChange(p); /* Described in the next section */
}

/* After each batch, Acknowledge updates to reset bookmark.*/
rc = ttXlaAcknowledge(xla_handle);
if (rc != SQL_SUCCESS {
/* See "Handling XLA errors" */
}
} /* end while !StopRequested() */

ttXlaNextUpdateまたはttXlaNextUpdateWaitによって返されるレコードの実際の数は、これらの関数のnreturned出力パラメータで示されるように、maxrecordsパラメータの値より小さい場合があります。図5-6に示す例では、maxrecordsが10で、7つのレコードで構成されているトランザクションATおよび3つのレコードで構成されているトランザクションBTがトランザクション・ログに含まれています。この場合、両方のトランザクションが同じバッチで返され、maxrecordsおよびnreturnedの両方の値が10になります。ただし、ログ内のその次の3つのトランザクションは、11個のレコードで構成されているCT、2つのレコードで構成されているDTおよび2つのレコードで構成されているETになります。CTのコミット・レコードの前にDTトランザクションのコミット・レコードが書き込まれるため、次にttXlaNextUpdateをコールすると、DTトランザクションの2つのレコードが返され、nreturnedの値は2になります。その次にttXlaNextUpdateをコールすると、XLAによって、CTトランザクションの合計レコード数がmaxrecordsを超えていることが検出され、このトランザクションのレコードが2つのバッチで返されます。最初のバッチには、CTの最初の10個のレコード(nreturned = 10)が含まれます。2番目のバッチには、CTの最後のレコードおよびETトランザクションの2つのレコード(ETの後のトランザクションのコミット・レコードが次の7つのレコード内で検出されないと想定)が含まれます。

これらの関数のパラメータの詳細は、「ttXlaNextUpdate」および「ttXlaNextUpdateWait」を参照してください。

図5-6 maxrecords=10の場合に取得されるレコード

XLAは、レコードをメモリー・バッファまたはディスク上のトランザクション・ログ・ファイルから読み取ります(「XLAでレコードをトランザクション・ログから読み取る方法」を参照)。待機時間を最小にするために、メモリー・バッファからのレコードは使用可能になるとすぐに返されますが、バッファにないレコードはバッファが空の場合にのみ返されます。この設計によって、XLAアプリケーションでは、行われた変更を最小の待機時間ですぐに表示できます。トレードオフとして、ttXlaNextUpdateまたはttXlaNextUpdateWaitのmaxrecordsパラメータでリクエストした数より少ない数の変更が返される場合があります。

注意:
スループットを最適化するために、XLAアプリケーションでは、フェッチおよびレコード処理の手順を非同期にする必要があります。たとえば、1つのスレッドを作成してレコードのフェッチおよび保存を行ったり、1つ以上のスレッドを作成して保存したレコードを処理することができます。

レコード・ヘッダーの確認および行アドレスの検出

更新レコードの配列が存在し、その各レコードが示す処理のタイプがわかるため、返された行データを確認できます。

ttXlaNextUpdateまたはttXlaNextUpdateWait関数によって返される各レコードは、ttXlaUpdateDesc_tヘッダーで始まり、このヘッダーには次の情報が記述されています。

- 処理が実行された表

- レコードがトランザクションの最初のレコードであるか、または最後の(コミット)レコードであるか

- レコードが示す処理のタイプ

- 返された行データの長さ(行データがある場合)

- 行内の更新された列(該当する列がある場合)

図5-7に、トランザクション・ログ内の更新レコードの例を示します。

図5-7 XLA更新レコードに返される行データのアドレス

ttXlaUpdateDesc_tヘッダーは固定長で、処理のタイプに応じて、データベースから0(ゼロ)から2行の行(タプル)が続きます。ttXlaUpdateDesc_tヘッダーのアドレスを取得し、それにsizeof(ttXlaUpdateDesc_t)を追加することによって、最初に返された行のアドレスを特定できます。

tup1 = (void*) ((char*) ttXlaUpdateDesc_t + sizeof(ttXlaUpdateDesc_t));

これを次の例5-4に示します。

ttXlaUpdateDesc_t ->typeフィールドは、更新を生成したSQL処理のタイプについての記述です。UPDATETTUP型のトランザクション・レコードは、UPDATE処理についての記述であるため、更新の前後の行データをレポートするために2行の行を返します。更新後の値が含まれている2番目に返された行のアドレスは、レコード内の1つ目の行のアドレスにその長さに追加することで特定できます。

if (ttXlaUpdateDesc_t->type == UPDATETUP) {
tup2 = (void*) ((char*) tup1 + ttXlaUpdateDesc_t->tuple1);
}

これも例5-4に示します。

例5-4 レコード・ヘッダーでのSQL処理タイプの確認

この例では、ttXlaNextUpdateWait関数によって返された各レコードをHandleChange()関数に渡し、この関数では、そのレコードがINSERT、UPDATEまたはCREATE VIEW処理に関連しているかを判別します。この例では、わかりやすくするために、その他の処理はすべて無視されています。

HandleChange()関数は、PrintColValues()関数(例5-13を参照)をコールする前に各タイプのSQL処理を異なる方法で処理します。

void HandleChange(ttXlaUpdateDesc_t* xlaP)
{
void*  tup1;
void*  tup2;

/* First confirm that the XLA update is for the table we care about. */
if (xlaP->sysTableID != SYSTEM_TABLE_ID)
return ;

/* OK, it's for the table we're monitoring. */

/* The last record in the ttXlaUpdateDesc_t record is the "tuple2"
* field.  Immediately following this field is the first XLA record "row". */

tup1 = (void*) ((char*) xlaP + sizeof(ttXlaUpdateDesc_t));

switch(xlaP->type) {

case INSERTTUP:
printf("Inserted new row:\n");
PrintColValues(tup1);
break;

case UPDATETUP:

/* If this is an update ttXlaUpdateDesc_t, then following that is
* the second XLA record "row".
*/

tup2 = (void*) ((char*) tup1 + xlaP->tuple1);
printf("Updated row:\n");
PrintColValues(tup1);
printf("To:\n");
PrintColValues(tup2);
break;

case DELETETUP:
printf("Deleted row:\n");
PrintColValues(tup1);
break;

default:
/* Ignore any XLA records that are not for inserts/update/delete SQL ops. */
break;

} /* switch (xlaP->type) */
}

列データの確認

更新レコードでは、0(ゼロ)から2行のデータがttXlaUpdateDesc_t構造体の後に返される場合があります(「レコード・ヘッダーの確認および行アドレスの検出」を参照)。図5-8に示すように、各行のデータの最初の部分は固定長で、その後に可変長データが続きます。

図5-8 XLA更新レコードに返される行内の列オフセット

列データを確認する手順は次のとおりです。

- 列記述の取得

- 固定長列データの読取り

- NOT INLINE可変長列データの読取り

- 返された文字列の空文字での終了

- 複合データ型の変換

- NULL値の検出

- すべての列確認コードの組合せ: PrintColValues()関数

列記述の取得

返された行から列値を読み取るには、まず、その行の各列のオフセットを判別する必要があります。列オフセットおよびその他の列メタデータは、特定の表に対してttXlaGetColumnInfo関数をコールすると取得でき、この関数は表の列ごとに個別のttXlaColDesc_t構造体を返します。ttXlaGetColumnInfo関数は、初期化プロシージャの一部としてコールする必要があります。「XLAの初期化およびXLAハンドルの取得」の説明では、わかりやすくするためにこのコールは省略されています。

ttXlaGetColumnInfoをコールする場合は、colinfoパラメータを指定して、返されるttXlaColDesc_t構造体のリストを保持するバッファへのポインタを作成します。maxcolsパラメータを使用して、バッファのサイズを定義します。

例5-5 列記述の使用

次に示すxlaSimpleデモのコード例では、返される列の最大数(MAX_XLA_COLUMNS)を推測し、返されるttXlaColDesc_t構造体を保持するバッファ(xla_column_defs)のサイズを設定します。maxcolsパラメータを設定する場合のもう1つのより正確な方法として、ttXlaGetTableInfo関数をコールし、ttXlaColDesc_t ->columnsに返された値を使用する方法があります。

#define MAX_XLA_COLUMNS 128
...
SQLINTEGER ncols;
...
ttXlaColDesc_t xla_column_defs[MAX_XLA_COLUMNS];
...
rc = ttXlaGetColumnInfo(xla_handle, SYSTEM_TABLE_ID, userID,
xla_column_defs, MAX_XLA_COLUMNS, &ncols);
if (rc != SQL_SUCCESS {
/* See "Handling XLA errors" */
}

図5-9に示すように、ttXlaGetColumnInfo関数は次の情報を出力します。

- ttXlaGetColumnInfo colinfoパラメータが指すバッファに格納されるttXlaColDesc_t構造体のリスト(xla_column_defs)

- xla_column_defsバッファに実際に返される列数を保持するnreturnedの値(ncols)

図5-9 ttXlaGetColumnInfoによって返されるttXlaColDesc_t構造体

ttXlaGetColumnInfoによって返される各ttXlaColDesc_t構造体には、その列のオフセット位置を記述するoffset値が含まれます。列データを読み込む際にこのoffset値をどのように使用するかは、列が固定長データ(CHAR、NCHAR、INTEGER、BINARY、DOUBLE、FLOAT、DATE、TIME、TIMESTAMPなど)を含んでいるか、可変長データ(VARCHAR、NVARCHAR、VARBINARYなど)を含んでいるかによって異なります。

固定長列データの読取り

固定長列データの場合、列のアドレスは、ttXlaColDesc_t構造体のoffset値に行のアドレスを追加したものです。

図5-10 行内の固定長データの検出

例5-6 固定長列データの読取り

ここに示すような計算の完全な動作例については、例5-13を参照してください。

MYDATA表の最初の列はCHAR型です。HandleChange()関数(例5-4)で前に取得したtup1行のアドレスと、ttXlaGetColumnInfo関数(例5-5)によって返された最初のttXlaColDesc_t構造体のoffsetを使用する場合は、次のように計算して最初の列の値を取得できます。

char*  Column1;

Column1 = ((unsigned char*) tup1 + xla_column_defs[0].offset);

MYDATA表の3番目の列はINTEGER型のため、3番目のttXlaColDesc_t構造体のoffsetを使用して値を検出し、次のように計算して、整数として再キャストできます。データは適切に配置されます。

int Column3;

Column3 = *((int*) ((unsigned char*) tup +
xla_column_defs[2].offset));

MYDATA表の4番目の列はNCHAR型のため、4番目のttXlaColDesc_t構造体のoffsetを使用して値を検出し、次のように計算して、SQLWCHAR型として再キャストできます。

SQLWCHAR*  Column4;

Column4 = (SQLWCHAR*) ((unsigned char*) tup +
xla_column_defs[3].offset);

前述の例で取得した列値とは異なり、Column4は2バイトのUnicode文字の配列を指します。文字列を取得するには、例5-13のSQL_WCHARの場合のように、この配列内の各要素に対して繰り返し実行する必要があります。

その他の固定長データ型は、対応するCの型にキャストできます。複合固定長データ型(DATE、TIME、DECIMAL値など)は、TimesTenの内部形式で格納されますが、アプリケーションでXLA変換関数を使用して、対応するODBC C値に変換できます(「複合データ型の変換」を参照)。

注意:
XLAによって返される文字列は空文字では終了しません。「返された文字列の空文字での終了」を参照してください。

NOT INLINE可変長列データの読取り

NOT INLINE可変長データ(VARCHAR、NVARCHARおよびVARBINARY)の場合、ttXlaColDesc_t ->offsetにあるデータは、返された行の可変長部分でのデータの場所を指す4バイトのオフセット値です。オフセット・アドレスをオフセット値に追加すると、行の可変長部分の列データのアドレスを取得できます。この場所の最初のnバイトはデータの長さで、その後に実際のデータが続きます(nは、32ビットのプラットフォームでは4、64ビットのプラットフォームでは8です)。可変長データの場合、ttXlaColDesc_t ->size値は列の許容最大サイズです。図5-11に、行内のNOT INLINE可変長データを検出する方法を示します。

図5-11 行内のNOT INLINE可変長データの検出

例5-7 NOT INLINE可変長列データの読取り

ここに示すような計算の完全な動作例については、例5-13「完全なPrintColValues()関数」を参照してください。

引き続きこの例では、返された行(tup1)の2番目の列はVARCHAR型です。行内の可変長データを検出するには、まず前述の図5-11に示すように、行の固定長部分で列のttXlaColDesc_t ->offsetの値を検出します。このアドレスの値は、行の可変長部分のデータの4バイトのオフセットです(VarOffset)。次に、VarOffsetのアドレスにVarOffsetオフセット値を追加して、可変長列データの先頭へのポインタを取得します(DataLength)。32ビット・プラットフォームで処理が行われると想定すると、DataLength位置の最初の4バイトがデータの長さです。DataLengthの後の次のバイトが、実際のデータの先頭です(Column2)。

このコード例では、32ビット・プラットフォームで処理が行われると想定しているため、DataLengthは32ビット・タイプとして初期化されます。64ビット・プラットフォームでは、DataLengthを64ビット・タイプとして初期化する必要があり、Column2データはオフセット・アドレスDataLengthの後に64ビット+1で書き込まれます。

void*  VarOffset; /* offset of data */
long*  DataLength; /* length of data */
char*  Column2; /* pointer to data */

VarOffset = (void*) ((unsigned char*) tup1 +
xla_column_defs[1].offset);
/*
* If column is out-of-line, pColVal points to an offset
* else column is inline so pColVal points directly to the string length.
*/

if (xla_column_defs[1].flags & TT_COLOUTOFLINE)
DataLength = (long*)((char*)VarOffset + *((int*)VarOffset));
else
DataLength = (long*)VarOffset;
Column2 = (char*)(DataLength+1);

VARBINARY型は、VARCHAR型での方法とほぼ同じ方法で処理されます。Column2がNVARCHAR型の場合、SQLWCHARとして初期化し、前述のVARCHARの場合と同様に値を取得し、次に例5-13のNCHAR値CharBufの場合と同様にColumn2配列に対して繰り返し実行できます。

注意:
前述の例では、DataLengthはデータ型longで、64-bitのシステムでは64ビット(8バイト)型で、32-bitのシステムでは32ビット(4バイト)型として記載されています。ほとんどのUNIXシステムに当てはまりますが、Windowsの64-bitシステムのlongは4バイト型です。

返された文字列の空文字での終了

レコードの行データから返される文字列は空文字では終了していません。文字列をバッファにコピーし、その文字列の最後の文字の後に\0などの空文字を追加すると、文字列を空文字で終了できます。

文字列を空文字で終了する手順は、文字列が固定長の場合と可変長の場合で少し異なります。例5-8に、固定長文字列を空文字で終了する手順を示します。その後の例5-9には、サイズがわかっている可変長文字列を空文字で終了する手順を示します。例5-10には、サイズがわかっていない文字列の場合の手順を示します。

例5-8 固定長文字列の空文字での終了

ここに示すような計算の完全な動作例については、例5-13を参照してください。

例5-6で返された固定長CHAR(10) Column1文字列を空文字で終了するには、文字列と空文字を保持できる十分な大きさのバッファを設定します。次に、ttXlaColDesc_t ->sizeから文字列のサイズを取得し、文字列をバッファにコピーして、次のような計算で文字列の末尾を空文字で終了します。これで、バッファの内容を使用できます。この例では、その文字列を出力します。

char buffer[10+1];
int size;

size = xla_column_defs[0].size;
memcpy(buffer, Column1, size);
buffer[size] = '\0';

printf(" Row %s is %s\n", ((unsigned char*) xla_column_defs[0].colName), buffer);

可変長文字列を空文字で終了する手順は、固定長文字列の手順とほぼ同じです。可変長データのオフセットの先頭にある値は、文字列のサイズのみです(「NOT INLINE可変長列データの読取り」を参照)。

例5-9 サイズがわかっている可変長文字列の空文字での終了

(ここに示すような計算の完全な動作例については、例5-13を参照してください。)

例5-7で取得したColumn2文字列がVARCHAR(32)の場合、文字列と空文字を保持できる十分な大きさのバッファを設定します。DataLengthオフセットにある値を使用して、次のような計算で文字列のサイズを設定します。

char buffer[32+1];

memcpy(buffer, Column2, *DataLength);
buffer[*DataLength] = '\0';

printf(" Row %s is %s\n", ((unsigned char*) xla_column_defs[1].colName), buffer);

すべてのデータ型を読み取るための汎用コードを記述する場合は、返される文字列のサイズを想定できません。サイズがわからない文字列に対しては、返された文字列の大部分を保持できる十分な大きさのバッファを静的に割り当てます。返された文字列がバッファより大きい場合は、例5-10に示すように、正しいサイズのバッファを動的に割り当てます。

例5-10 サイズがわかっていない可変長文字列の空文字での終了

例5-7で取得したColumn2文字列のサイズがわからない場合は、最大10000文字の文字列を保持できる十分な大きさのバッファを静的に割り当てます。その後、可変長データ・オフセットの先頭で取得したDataLength値が、バッファのサイズより小さいことを確認します。文字列がバッファより大きい場合は、malloc()を使用してバッファを動的に正しいサイズに割り当てます。

#define STACKBUFSIZE 10000
char VarStackBuf[STACKBUFSIZE];
char*  buffer;

buffer = (*DataLength+1 <= STACKBUFSIZE) ? VarStackBuf :
malloc(*DataLength+1);

memcpy(buffer,Column2,*DataLength);
buffer[*DataLength] = '\0';

printf(" Row %s is %s\n", ((unsigned char*) xla_column_defs[1].colName), buffer);
if (buffer != VarStackBuf) /* buffer was allocated */
free(buffer);

複合データ型の変換

TT_DATE、TT_TIME、TT_DECIMALなどの複合データ型の値は、TimesTenの内部形式で保存され、これらはXLA型変換関数を使用して、対応するODBC C型に変換できます。表5-2に、これらの変換関数の説明を示します。

表5-2 XLAデータ型変換関数

関数

変換

ttXlaDateToODBCCType

内部TT_DATE値をODBC C値に

ttXlaTimeToODBCCType

内部TT_TIME値をODBC C値に

ttXlaTimeStampToODBCCType

内部TT_TIMESTAMP値をODBC C値に

ttXlaDecimalToCString

内部TT_DECIMAL値を文字列値に

ttXlaDateToODBCCType

内部TTXLA_DATE_TT値をODBC C値に

ttXlaDecimalToCString

内部TTXLA_DECIMAL_TT値を文字列に

ttXlaNumberToBigInt

内部TTXLA_NUMBER値をTT_BIGINT値に

ttXlaNumberToCString

内部TTXLA_NUMBER値を文字列に

ttXlaNumberToDouble

内部TTXLA_NUMBER値を長い浮動小数点数値に

ttXlaNumberToInt

内部TTXLA_NUMBER値を整数に

ttXlaNumberToSmallInt

内部TTXLA_NUMBER値をTT_SMALLINT値に

ttXlaNumberToTinyInt

内部TTXLA_NUMBER値をTT_TINYINT値に

ttXlaNumberToUInt

内部TTXLA_NUMBER値を符号なし整数に

ttXlaOraDateToODBCTimeStamp

内部TTXLA_DATE値をODBCタイムスタンプに

ttXlaOraTimeStampToODBCTimeStamp

内部TTXLA_TIMESTAMP値をODBCタイムスタンプに

ttXlaTimeToODBCCType

内部TTXLA_TIME値をODBC C値に

ttXlaTimeStampToODBCCType

内部TTXLA_TIMESTAMP_TT値をODBC C値に

これらの変換関数は、ttXlaUpdateDesc_t型(UPDATETUP、INSERTTUPおよびDELETETUP)に含まれる行データで使用できます。

例5-11 複合データ型の変換

(ここに示すような計算の完全な動作例については、例5-13を参照してください。)

前にHandleChange()関数(例5-4)で取得したtup1行のアドレス、およびttXlaGetColumnInfo関数(例5-5)によって返された5番目のttXlaColDesc_t構造体のoffsetを使用すると、TIMESTAMP型の列値を検出できます。ttXlaTimeStampToODBCCType関数を使用し、TimesTen形式から列データを変換し、変換されたTIME値をODBC TIMESTAMP_STRUCTに保存します。次のようなコードを使用すると値を出力できます。

void*  Column5;
TIMESTAMP_STRUCT timestamp;

Column5 = (void*) ((unsigned char*) tup1 +
xla_column_defs[4].offset);

rc = ttXlaTimeStampToODBCCType(Column5, &timestamp);
if (rc != SQL_SUCCESS) {
/* See "Handling XLA errors" */
}
printf(" %s: %04d-%02d-%02d %02d:%02d:%02d.%06d\n",
((unsigned char*) xla_column_defs[i].colName),
timestamp.year,timestamp.month, timestamp.day,
timestamp.hour,timestamp.minute,timestamp.second,
timestamp.fraction);

前にHandleChange()関数(例5-4)で取得したtup1行のアドレス、およびttXlaGetColumnInfo関数(例5-5)によって返された6番目のttXlaColDesc_t構造体のoffsetを使用すると、DECIMAL型の列値を検出できます。ttXlaDecimalToCString関数を使用して、TimesTenのDECIMAL形式から文字列に列データを変換します。次のようなコードを使用すると値を出力できます。

char decimalData[50];

Column6 = (float*) ((unsigned char*) tup +
xla_column_defs[5].offset);
precision = (short) (xla_column_defs[5].precision);
scale = (short) (xla_column_defs[5].scale);

rc = ttXlaDecimalToCString(Column6, (char*)&decimalData,
precision, scale);
if (rc != SQL_SUCCESS) {
/* See "Handling XLA errors" */
}

printf(" %s: %s\n", ((unsigned char*) xla_column_defs[5].colName), decimalData);

NULL値の検出

NULL値可能な表の列の場合、ttXlaColDesc_t ->nullOffsetは、レコードの列のNULLバイトを指します。列にNULLを指定できない場合、このフィールドは0(ゼロ)で、列にNULLを指定できる場合、このフィールドは0より大きくなります。

NULL値可能な列の場合(ttXlaColDesc_t ->nullOffset > 0)、列がNULLであるかどうかを確認するには、NULLオフセットをttXlaUpdate_t*のアドレスに追加し、(unsigned char)バイトをチェックして1 (NULL)または0 (NOT NULL)のいずれであるかを確認します。

例5-12 NULL値の検出

Column6がNULLかどうかを次のように確認します。

if (xla_column_defs[5].nullOffset != 0) {
if (*((unsigned char*) tup +
xla_column_defs[5].nullOffset) == 1) {
printf("Column6 is NULL\n");
}
}

すべての列確認コードの組合せ: PrintColValues()関数

例5-13に、各列のttXlaColDesc_t ->dataTypeを確認して、データ型がCHAR、NCHAR、INTEGER、TIMESTAMP、DECIMALおよびVARCHARである列を検出し、その値を出力する関数を示します。これは、考えられる1つの方法にすぎません。たとえば、別の方法として、ttXlaColDesc_t ->ColNameの値を確認して、名前で特定の列を検出する方法もあります。

PrintColValues()関数は、長さが最大50バイトのCHARおよびVARCHARの文字列を処理します。NCHAR文字は、ASCIIキャラクタ・セットに属している必要があります。

例5-13 完全なPrintColValues()関数

この例では、関数はまずttXlaColDesc_t ->nullOffsetを調べて列がNULLかどうかを確認します。次に、ttXlaColDesc_t ->dataTypeのフィールドを調べて列のデータ型を確認します。単純な固定長データ(CHAR、NCHARおよびINTEGER)の場合は、ttXlaColDesc_t ->offsetにある値を適切なCの型にキャストします。複合データ型(TIMESTAMPおよびDECIMAL)は、ttXlaTimeStampToODBCCType関数およびttXlaDecimalToCString関数を使用して、TimesTen形式からODBC C値に変換されます。

可変長データ(VARCHAR)の場合、関数は行の可変長部分でデータを検出します(「XLAエラーの処理」を参照)。

void PrintColValues(void* tup)
{

SQLRETURN rc ;
SQLINTEGER native_error;

void* pColVal;
char buffer[50+1]; /* No strings over 50 bytes */
int i;

for (i = 0; i < ncols; i++)
{

if (xla_column_defs[i].nullOffset != 0) {  /* See if column is NULL */
/* this means col could be NULL */
if (*((unsigned char*) tup + xla_column_defs[i].nullOffset) == 1) {
/* this means that value is SQL NULL */
printf("  %s: NULL\n",
((unsigned char*) xla_column_defs[i].colName));
continue; /* Skip rest and re-loop */
}
}

/* Fixed-length data types: */
/* For INTEGER, recast as int */

if (xla_column_defs[i].dataType == TTXLA_INTEGER) {

printf("  %s: %d\n",
((unsigned char*) xla_column_defs[i].colName),
*((int*) ((unsigned char*) tup + xla_column_defs[i].offset)));
}

/* For CHAR, just get value and null-terminate string */

else if (   xla_column_defs[i].dataType == TTXLA_CHAR_TT
|| xla_column_defs[i].dataType == TTXLA_CHAR) {

pColVal = (void*) ((unsigned char*) tup + xla_column_defs[i].offset);

memcpy(buffer, pColVal, xla_column_defs[i].size);
buffer[xla_column_defs[i].size] = '\0';

printf("  %s: %s\n", ((unsigned char*) xla_column_defs[i].colName), buffer);
}

/* For NCHAR, recast as SQLWCHAR.
NCHAR strings must be parsed one character at a time */

else if (   xla_column_defs[i].dataType == TTXLA_NCHAR_TT
|| xla_column_defs[i].dataType == TTXLA_NCHAR ) {
SQLUINTEGER j;
SQLWCHAR* CharBuf;

CharBuf = (SQLWCHAR*) ((unsigned char*) tup + xla_column_defs[i].offset);

printf("  %s: ", ((unsigned char*) xla_column_defs[i].colName));

for (j = 0; j < xla_column_defs[i].size / 2; j++)
{
printf("%c", CharBuf[j]);
}
printf("\n");
}
/* Variable-length data types:
For VARCHAR, locate value at its variable-length offset and null-terminate.
VARBINARY types are handled in a similar manner.
For NVARCHARs, initialize 'var_data' as a SQLWCHAR, get the value as shown
below, then iterate through 'var_len' as shown for NCHAR above */

else if (   xla_column_defs[i].dataType == TTXLA_VARCHAR
|| xla_column_defs[i].dataType == TTXLA_VARCHAR_TT) {

long*  var_len;
char* var_data;
pColVal = (void*) ((unsigned char*) tup + xla_column_defs[i].offset);
/*
* If column is out-of-line, pColVal points to an offset
* else column is inline so pColVal points directly to the string length.
*/
if (xla_column_defs[i].flags & TT_COLOUTOFLINE)
var_len = (long*)((char*)pColVal + *((int*)pColVal));
else
var_len = (long*)pColVal;

var_data = (char*)(var_len+1);

memcpy(buffer,var_data,*var_len);
buffer[*var_len] = '\0';

printf("  %s: %s\n", ((unsigned char*) xla_column_defs[i].colName), buffer);
}
/* Complex data types require conversion by the XLA conversion methods
Read and convert a TimesTen TIMESTAMP value.
DATE and TIME types are handled in a similar manner  */

else if (   xla_column_defs[i].dataType == TTXLA_TIMESTAMP
|| xla_column_defs[i].dataType == TTXLA_TIMESTAMP_TT) {

TIMESTAMP_STRUCT timestamp;
char* convFunc;

pColVal = (void*) ((unsigned char*) tup + xla_column_defs[i].offset);

if (xla_column_defs[i].dataType == TTXLA_TIMESTAMP_TT) {
rc = ttXlaTimeStampToODBCCType(pColVal, &timestamp);
convFunc="ttXlaTimeStampToODBCCType";
}
else {
rc = ttXlaOraTimeStampToODBCTimeStamp(pColVal, &timestamp);
convFunc="ttXlaOraTimeStampToODBCTimeStamp";
}

if (rc != SQL_SUCCESS) {
handleXLAerror (rc, xla_handle, err_buf, &native_error);
fprintf(stderr, "%s() returns an error <%d>: %s",
convFunc, rc, err_buf);
TerminateGracefully(1);
}

printf("  %s: %04d-%02d-%02d %02d:%02d:%02d.%06d\n",
((unsigned char*) xla_column_defs[i].colName),
timestamp.year,timestamp.month, timestamp.day,
timestamp.hour,timestamp.minute,timestamp.second,
timestamp.fraction);
}

/* Read and convert a TimesTen DECIMAL value to a string. */

else if (xla_column_defs[i].dataType == TTXLA_DECIMAL_TT) {

char decimalData[50];
short precision, scale;
pColVal = (float*) ((unsigned char*) tup + xla_column_defs[i].offset);
precision = (short) (xla_column_defs[i].precision);
scale = (short) (xla_column_defs[i].scale);

rc = ttXlaDecimalToCString(pColVal, (char*)&decimalData, precision, scale);
if (rc != SQL_SUCCESS) {
handleXLAerror (rc, xla_handle, err_buf, &native_error);
fprintf(stderr, "ttXlaDecimalToCString() returns an error <%d>: %s",
rc, err_buf);
TerminateGracefully(1);
}

printf("  %s: %s\n", ((unsigned char*) xla_column_defs[i].colName),
decimalData);
}
else if (xla_column_defs[i].dataType == TTXLA_NUMBER) {
char numbuf[32];
pColVal = (void*) ((unsigned char*) tup + xla_column_defs[i].offset);

rc=ttXlaNumberToCString(xla_handle, pColVal, numbuf, sizeof(numbuf));
if (rc != SQL_SUCCESS) {
handleXLAerror (rc, xla_handle, err_buf, &native_error);
fprintf(stderr, "ttXlaNumberToDouble() returns an error <%d>: %s",
rc, err_buf);
TerminateGracefully(1);
}
printf("  %s: %s\n", ((unsigned char*) xla_column_defs[i].colName), numbuf);
}

} /* End FOR loop */
}

注意:

- 前述の例では、var_lenはデータ型longで、64-bitのシステムでは64ビット(8バイト)型で、32-bitのシステムでは32ビット(4バイト)型と想定しています。ほとんどのUNIXシステムに当てはまりますが、Windowsの64-bitシステムのlongは4バイト型です。

- TerminateGracefully()メソッドのサンプルは、「XLAアプリケーションの終了」を参照してください。

XLAエラーの処理

ODBCまたはXLA関数をコールするたびに、エラーのリターン・コードを確認する必要があります。エラーが致命的である場合は、「XLAアプリケーションの終了」の説明に従ってプログラムを終了します。

エラーは、エラー・コード(エラー番号)またはtt_Err文字列のいずれかを使用して確認できます。TimesTenエラー・コードとエラー文字列の完全なリストは、install_dir/include/tt_errCode.hファイルを参照してください。各メッセージについては、『Oracle TimesTen In-Memory Databaseエラー・メッセージおよびSNMPトラップ』のエラーおよび警告のリストに関する項を参照してください。

XLA関数のリターン・コードがSQL_SUCCESSでない場合は、ttXlaError関数を使用して、XLAハンドルでXLA固有のエラーを取得します。

「エラーのチェック」も参照してください。

例5-14 リターン・コードの確認とエラー処理関数のコール

この例では、XLA関数ttXlaTableByNameをコールした後、リターン・コードがSQL_SUCCESSであるかどうかを確認します。そうでない場合は、XLAエラー処理関数をコールし、その後アプリケーションを終了する関数をコールします。「XLAアプリケーションの終了」も参照してください。

rc = ttXlaTableByName(xla_handle, TABLE_OWNER, TABLE_NAME,
&SYSTEM_TABLE_ID, &userID);
if (rc != SQL_SUCCESS) {
handleXLAerror (rc, xla_handle, err_buf, &native_error);
fprintf(stderr,
"ttXlaTableByName() returns an error <%d>: %s", rc, err_buf);
TerminateGracefully(1);
}

XLAエラー処理関数は、エラー・スタックからすべてのXLAエラーが読み取られまで繰り返しttXlaErrorをコールする必要があり、ttXlaErrorからのリターン・コードがSQL_NO_DATA_FOUNDになるまで続行します。エラーを再度読み取る必要がある場合は、ttXlaErrorRestart関数をコールしてエラー・スタックのポインタを最初のエラーに再設定します。

エラー・スタックは、ttXlaErrorまたはttXlaErrorRestart以外のすべてのXLA関数へのコール後に消去されます。

注意:
ttXlaPersistOpenがXLAハンドルを作成できない場合は、エラー・コードSQL_INVALID_HANDLEを返します。XLAハンドルが作成されていないため、ttXlaErrorを使用してこのエラーを検出することはできません。SQL_INVALID_HANDLEは、メモリーが割り当てることができない場合または指定したパラメータが無効である場合にのみ返されます。

アプリケーションによっては、表5-3に示すような特定のXLAエラーに対処する必要がある場合があります。

表5-3 XLAエラーとコード

エラー

コード

tt_ErrDbAllocFailed

802(一時的)

tt_ErrCondLockConflict

6001(一時的)

tt_ErrDeadlockVictim

6002(一時的)

tt_ErrTimeoutVictim

6003(一時的)

tt_ErrPermSpaceExhausted

6220(一時的)

tt_ErrTempSpaceExhausted

6221(一時的)

tt_ErrBadXlaRecord

8024

tt_ErrXlaBookmarkUsed

8029

tt_ErrXlaLsnBad

8031

tt_ErrXlaNoSQL

8034

tt_ErrXlaNoLogging

8035

tt_ErrXlaParameter

8036

tt_ErrXlaTableDiff

8037

tt_ErrXlaTableSystem

8038

tt_ErrXlaTupleMismatch

8046

tt_ErrXlaDedicatedConnection

8047

例5-15 handleXLAerror()関数のコール

この例では、xlaSimpleデモ・プログラムのエラー関数であるhandleXLAerror()を示します。

void handleXLAerror(SQLRETURN rc, ttXlaHandle_h xlaHandle,
SQLCHAR* err_msg, SQLINTEGER* native_error)
{
SQLINTEGER retLen;
SQLINTEGER code;
char* err_msg_ptr;

/* initialize return codes */
rc = SQL_ERROR;
*native_error = -1;
err_msg[0] = '\0';

err_msg_ptr = (char*)err_msg;

while (1)
{
int rc = ttXlaError(xlaHandle, &code, err_msg_ptr,
ERR_BUF_LEN - (err_msg_ptr - (char*)err_msg), &retLen);
if (rc == SQL_NO_DATA_FOUND)
{
break;
}
if (rc != SQL_SUCCESS && rc != SQL_SUCCESS_WITH_INFO) {
sprintf(err_msg_ptr,
"*** Error fetching error message via ttXlaError(); rc=<%d>.",rc) ;
break;
}
rc = SQL_ERROR;
*native_error = code ;
/* append any other error messages */
err_msg_ptr += retLen;
}
}

XLAブックマークを使用する表の削除

XLAブックマークがサブスクライブされている表を削除するには、ブックマークから表をサブスクライブ解除する必要があります。ブックマークから表をサブスクライブ解除するには、アプリケーションがブックマークに接続されているかどうかに応じて、いくつかの方法があります。

XLAアプリケーションが接続されており、削除する表を追跡しているブックマークを使用している場合は、次のタスクを実行します。

1. 各XLAアプリケーションでttXlaTableStatus関数をコールし、newstatusパラメータを0に設定します。これにより、アプリケーションで使用中のXLAブックマークから表がサブスクライブ解除されます。

2. 表を削除します。

XLAアプリケーションが接続されておらず、削除する表に関連付けられているブックマークを使用している場合は、次のタスクを実行します。

1. SYS.XLASUBSCRIPTIONSシステム表を問い合せて、削除する表にサブスクライブされているブックマークを確認します。

2. ttXlaUnsubscribe組込みプロシージャを使用して、表にサブスクライブされている各XLAブックマークから表をサブスクライブ解除します。

3. 表を削除します。

ブックマークを削除すると、XLAブックマークからも表がサブスクライブ解除されます。次の項「ブックマークの削除」を参照してください。

ブックマークの削除

アプリケーションを終了する場合や表を削除する場合に、ブックマークを削除することがあります。アプリケーションが接続されており、ブックマークを使用している場合は、ttXlaDeleteBookmark関数を使用してXLAブックマークを削除します。

ブックマークは、前の接続がクローズされた後に新しい接続で再利用される可能性があります(「XLAブックマークについて」を参照)。新しい接続は、前の接続が停止した場所からトランザクション・ログの読取りを再開します。次の点に注意してください。

- ブックマークを削除すると、後続のチェックポイント処理(組込みプロシージャttCkpt、ttCkptBlockingなど)によって、トランザクション・ログ内の未読の更新レコードに関連するディスク領域が解放されます。

- ブックマークを削除しない場合、XLAアプリケーションは、接続してブックマークを再利用する際に、プログラムの終了以降累積していたすべての未読の更新レコードを読み取ります。これは、更新レコードがTimesTenトランザクション・ログで永続的であるためです。ただし、これらの未読のレコードがトランザクション・ログ・ファイルに累積し、大量のディスク領域を使用すると危険です。

注意:

- レプリケーション・エージェントの実行中は、レプリケートされたブックマークを削除できません。

- ブックマークを再利用する場合は、トランザクション・ログ・ファイル内の初期読取りログ・レコード識別子から開始します。ブックマークを再利用する接続で、前回、接続を切断した場所から読取りが開始されるようにするには、接続を切断する前にttXlaAcknowledgeをコールして、ブックマークの位置を現在アクセスしているレコードに再設定する必要があります。

- 詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttLogHoldsに関する説明を参照してください。TimesTen組込みプロシージャは、トランザクション・ログの保留に関する情報を返します。

- ttCkptとttCkptBlockingにはADMIN権限が必要です。TimesTenの組込みプロシージャと必要な権限については、『Oracle TimesTen In-Memory Databaseリファレンス』の組込みプロシージャに関する項を参照してください。

例5-16 ブックマークの削除

次の例に示すように、xlaSimpleデモのInitHandler()関数は、終了時にXLAブックマークを削除します。

if (deleteBookmark) {
ttXlaDeleteBookmark(xla_handle);
if (rc != SQL_SUCCESS) {
/* See "Handling XLA errors" */
}
xla_handle = NULL; /* Deleting the bookmark has the */
/* effect of disconnecting from XLA. */
}
/* Close the XLA connection as described in the next section,
"Terminating an XLA application". */

アプリケーションが接続されておらず、XLAブックマークを使用している場合、次のいずれかの方法でブックマークを削除できます。

- ブックマークをクローズしてttXlaBookmarkDelete組込みプロシージャをコールします。

- ブックマークをクローズしてttIsqlのxladeletebookmarkコマンドを使用します。

XLAアプリケーションの終了

XLAアプリケーションでトランザクション・ログの読取りを終了したら、コミットされていないトランザクションをロールバックし、すべてのハンドルを解放して、正常に終了する必要があります。これには次の2つの方法があります。

- すべての表およびマテリアライズド・ビューのサブスクライブを解除し、XLAブックマークを削除し、データベースから切断します。

または

- データベースからは切断しますが、XLAブックマークは維持します。後で再接続する際に、ブックマークからレコードの読取りを再開できます。

最初の方法では、次の手順を実行します。

1. ttXlaTableStatusをコールして各表およびマテリアライズド・ビューをサブスクライブ解除します(newstatusパラメータを0(ゼロ)に設定します)。

2. ttXlaDeleteBookmarkをコールして、ブックマークを削除します。「ブックマークの削除」を参照してください。

3. ttXlaCloseをコールして、XLAハンドルを切断します。

4. SQL_ROLLBACKを指定してODBC関数SQLTransactをコールし、コミットされていないトランザクションをすべてロールバックします。

5. ODBC関数SQLDisconnectをコールして、TimesTenデータベースから切断します。

6. ODBC関数SQLFreeConnectをコールして、ODBC接続ハンドルに割り当てられているメモリーを解放します。

7. ODBC関数SQLFreeEnvをコールして、ODBC環境ハンドルを解放します。

2番目の方法では、ブックマークを維持するため、最初の2つの手順を省略し残りの手順を完了します。

割当てとは反対の順序でリソースが解放されることに注意してください。たとえば、ODBC環境ハンドルはODBC接続ハンドルより先に割り当てられているため、クリーンアップでは、接続ハンドルを環境ハンドルより先に解放します。

例5-17 XLAアプリケーションの終了

この例では、xlaSimpleクイック・スタート・デモの終了関数であるTerminateGracefully()を示します。

void TerminateGracefully(int status)
{

SQLRETURN     rc;
SQLINTEGER    native_error ;
SQLINTEGER    oldstatus;
SQLINTEGER    newstatus = 0;

/* If the table has been subscribed to through XLA, unsubscribe it. */

if (SYSTEM_TABLE_ID != 0) {
rc = ttXlaTableStatus(xla_handle, SYSTEM_TABLE_ID, 0,
&oldstatus, &newstatus);
if (rc != SQL_SUCCESS) {
handleXLAerror (rc, xla_handle, err_buf, &native_error);
fprintf(stderr, "Error when unsubscribing from "TABLE_OWNER"."TABLE_NAME
" table <%d>: %s", rc, err_buf);
}
SYSTEM_TABLE_ID = 0;
}

/* Close the XLA connection. */

if (xla_handle != NULL) {
rc = ttXlaClose(xla_handle);
if (rc != SQL_SUCCESS) {
fprintf(stderr, "Error when disconnecting from XLA:<%d>", rc);
}
xla_handle = NULL;
}

if (hstmt != SQL_NULL_HSTMT) {
rc = SQLFreeStmt(hstmt, SQL_DROP);
if (rc != SQL_SUCCESS) {
handleError(rc, henv, hdbc, hstmt, err_buf, &native_error);
fprintf(stderr, "Error when freeing statement handle:\n%s\n", err_buf);
}
hstmt = SQL_NULL_HSTMT;
}

/* Disconnect from TimesTen entirely. */

if (hdbc != SQL_NULL_HDBC) {
rc = SQLTransact(henv, hdbc, SQL_ROLLBACK);
if (rc != SQL_SUCCESS) {
handleError(rc, henv, hdbc, hstmt, err_buf, &native_error);
fprintf(stderr, "Error when rolling back transaction:\n%s\n", err_buf);
}

rc = SQLDisconnect(hdbc);
if (rc != SQL_SUCCESS) {
handleError(rc, henv, hdbc, hstmt, err_buf, &native_error);
fprintf(stderr, "Error when disconnecting from TimesTen:\n%s\n", err_buf);
}

rc = SQLFreeConnect(hdbc);
if (rc != SQL_SUCCESS) {
handleError(rc, henv, hdbc, hstmt, err_buf, &native_error);
fprintf(stderr, "Error when freeing connection handle:\n%s\n", err_buf);
}
hdbc = SQL_NULL_HDBC;
}

if (henv != SQL_NULL_HENV) {
rc = SQLFreeEnv(henv);
if (rc != SQL_SUCCESS && rc != SQL_SUCCESS_WITH_INFO) {
handleError(rc, henv, hdbc, hstmt, err_buf, &native_error);
fprintf(stderr, "Error when freeing environment handle:\n%s\n", err_buf);
}
henv = SQL_NULL_HENV;
}
exit(status);
}

レプリケーション・メカニズムとしてのXLAの使用

『Oracle TimesTen In-Memory Database開発者および管理者ガイド』に記載されているとおり、TimesTenのレプリケーションは、ほとんどの顧客要件を満たすには十分ですが、XLA関数を使用して、1つのデータベースから別のデータベースに更新をレプリケートすることもできます。この方法で独自のレプリケーション・スキームをXLAの上に実装することはかなり困難ですが、TimesTenのレプリケーションがなんらかの理由で実行できない場合には検討できます。

注意:
異なるプラットフォーム間または同じプラットフォームの32ビットと64ビットのバージョン間では、XLAを使用して更新をレプリケートできません。

この項では、送信側のデータベースをマスター、受信側のデータベースをサブスクライバと呼びます。XLAを使用してデータベース間で変更をレプリケートするには、まずttXlaPersistOpen関数を使用してXLAハンドルを初期化します(「XLAの初期化およびXLAハンドルの取得」を参照)。

XLAハンドルをデータベースに対して初期化した後、次の項の手順を実行します。

- データベース間での表の互換性の確認

- データベース間での更新のレプリケート

- タイムアウトおよびデッドロックのエラーの処理

- 更新競合の確認

ここで説明するXLA関数については、第9章「XLAリファレンス」を参照してください。

データベース間での表の互換性の確認

データベース間で更新レコードを送信する場合は、マスター・データベースとサブスクライバ・データベースの表に互換性があることを確認します。

- ttXlaTableByName、ttXlaGetTableInfoおよびttXlaGetColumnInfo関数を使用して、表とその列の記述を確認できます。次の項「表および列の記述の確認」を参照してください。

- ttXlaVersionTableInfoおよびttXlaVersionColumnInfo関数を使用して、特定のXLAレコードの表および列のバージョンを確認できます。次の「表および列のバージョンの確認」を参照してください。

表および列の記述の確認

ttXlaTableByName、ttXlaGetTableInfoおよびttXlaGetColumnInfo関数を使用すると、レプリケートする各表のttXlaTblDesc_tおよびttXlaColDesc_t記述が返されます。これらの処理については、「更新を監視する表の指定」および「列の記述の取得」を参照してください。次に、これらの記述をttXlaTableCheck関数に渡すことができます。出力パラメータcompatは、表に互換性があるかどうかを指定します。値が1の場合は互換性があり、値が0(ゼロ)の場合は互換性がないことを示します。次の例でこれを説明します。

例5-18 表および列の記述の互換性の確認

SQLINTEGER compat;
ttXlaTblDesc_t table;
ttXlaColDesc_t columns[20];

rc = ttXlaTableCheck(xla_handle, &table, columns, &compat);
if (compat) {
/* Go ahead and start replicating */
}
else {
/* Not compatible or some other error occurred */
}

表および列のバージョンの確認

ttXlaVersionTableInfoおよびttXlaVersionColumnInfo関数を使用して、レコードの生成時に更新レコードの表構造の情報を取得します。

次の例では、pCmdソースのpXlaRecord更新レコードに関係付けられている表がhXlaTargetターゲットと互換性があることを確認します。

例5-19 表および列のバージョンの互換性の確認

BOOL CUTLCheckXlaTable (SCOMMAND* pCmd,
ttXlaHandle_h hXlaTarget,
const ttXlaUpdateDesc_t* pXlaRecord)
{
/* locals */
ttXlaTblVerDesc_t tblVerDescSource;
ttXlaColDesc_t colDescSource [255];
SQLINTEGER iColsReturned = 0;
SQLINTEGER iCompatible = 0;
SQLRETURN rc;

/* only certain update record types should be checked */
if (pXlaRecord->type == INSERTTUP ||
pXlaRecord->type == UPDATETUP ||
pXlaRecord->type == DELETETUP)
{
/* Get source table description associated with this record */
/* from the time it was generated. */
rc = ttXlaVersionTableInfo (pCmd->pCtx->con->hXla,
(ttXlaUpdateDesc_t*) pXlaRecord, &tblVerDescSource);

if (rc == SQL_SUCCESS)
{
/* Get the source column descriptors for this table */
/* at the time the record was generated. */
rc = ttXlaVersionColumnInfo (pCmd->pCtx->con->hXla,
(ttXlaUpdateDesc_t*) pXlaRecord,
colDescSource, 255, &iColsReturned);

if (rc == SQL_SUCCESS)
{
/* Check compatibility. */
rc = ttXlaTableCheck (hXlaTarget,
&tblVerDescSource.tblDesc, colDescSource,
&iCompatible);
}
}
}
}

データベース間での更新のレプリケート

レプリケートを開始する準備の完了後、ttXlaNextUpdateまたはttXlaNextUpdateWait関数を使用してマスター・データベースから更新レコードのバッチを取得し、ttXlaApplyを使用してサブスクライバ・データベースにレコードを書き込みます。この例を次に示します。

例5-20 データベース間での更新のレプリケート

int j;
ttXlaHandle_h h;
SQLINTEGER records;
ttXlaUpdateDesc_t** arry;

do {
/* get up to 15 updates */
rc = ttXlaNextUpdate(h,&arry,15,&records);
if (rc != SQL_SUCCESS) {
/* See "Handling XLA errors" */
}

/* print number of updates returned */
printf("Records returned by ttXlaNextUpdate : %d\n",records);

/* apply the received updates */
for (j=0;j < records;j++) {
ttXlaUpdateDesc_t* p;

p = arry[j];
rc = ttXlaApply(h, p, 0);
if (rc != SQL_SUCCESS){
/* See "Handling XLA errors" and */
/* "Handling timeout and deadlock errors" below */
}
}

/* print number of updates applied */
printf("Records applied successfully : %d\n",records);

} while (records != 0);

重要:
ネットワーク上、または同じメモリー領域を使用しないプロセス間の任意の場所でレプリケートするデータをパッケージ化する場合は、ttXlaUpdateDesc_tデータ構造体を完全に含める必要があります。その長さはttXlaUpdateDesc_t ->header.lengthで示され、header要素はttXlaNodeHdr_t構造体で、この構造体はlength要素を持ちます。「ttXlaUpdateDesc_t」および「ttXlaNodeHdr_t」も参照してください。

タイムアウトおよびデッドロックのエラーの処理

ttXlaApplyからのリターン・コードは、更新が正常に行われたかどうかを示します。リターン・コードがSQL_SUCCESSでない場合は、更新で一時的な問題(デッドロック、タイムアウトなど)または永続的な問題が発生した可能性があります。ttXlaErrorを使用して、tt_ErrDeadlockVictim、tt_ErrTimeoutVictimなどのエラーを確認できます。一時的なエラーは、レプリケートしたトランザクションをロールバックし、再実行することでリカバリできます。その他のエラーは、重複キー違反、キーが見つからないなどの永続的エラーである可能性があります。このようなエラーは、トランザクションを再実行しても、繰り返し発生する可能性があります。

ttXlaApplyが、トランザクションのコミット・レコード(ttXlaUpdateDesc_t ->flags = TT_UPDCOMMIT)をサブスクライバ・データベースに適用する前にタイムアウトまたはデッドロック・エラーを返した場合は、次のいずれかの処理を実行できます。

- ttXlaRollbackを使用してトランザクションをロールバックします。

- ttXlaCommitを使用して、レコードで、サブスクライバ・データベースに適用済の変更をコミットします。

一時的なエラーからのリカバリを有効にするには、マスター・データベースのトランザクション境界を追跡し、サブスクライバに現在適用中のトランザクションに関連付けられているレコードをユーザー・バッファに保存することで、必要に応じてそれらのレコードを再適用できます。トランザクション境界は、ttXlaUpdateDesc_t構造体のflagsメンバーを確認することで検出できます。次の例を想定してください。この条件がtrueの場合、レコードはコミットされています。

(pXlaRecords [iRecordIndex]->flags & TT_UPDCOMMIT)

トランザクションをロールバックする必要があるエラーが発生した場合は、ttXlaRollbackをコールして、サブスクライバ・データベースに適用済のレコードをロールバックします。その後、ttXlaApplyをコールして、バッファに保存されているすべてのロールバック・レコードを再適用します。

注意:
トランザクション・レコードをユーザー・バッファに保存するかわりに、ttXlaGetLSNをコールしてトランザクション・ログ内の各コミット・レコードのトランザクション・ログ・レコード識別子を取得する方法があります(「ブックマークの位置の変更」を参照)。トランザクションをロールバックする必要があるエラーが発生した場合は、ttXlaSetLSNをコールして、ブックマークをトランザクション・ログ内のトランザクションの先頭に再設定し、レコードを再適用します。ただし、この方法は、ttXlaGetLSN関数関連の追加のオーバーヘッドが発生するため、効率が悪くなる場合があります。

更新競合の確認

アプリケーションで、マスター・データベースおよびサブスクライバ・データベースの両方に対して同時に更新を行うと、更新競合が発生する場合があります。更新競合の詳細は、『Oracle TimesTen In-Memory Database開発者および管理者ガイド』のレプリケーション競合の解消に関する説明を参照してください。

XLAで更新競合を確認するには、ttXlaApplyのtestパラメータを設定して、UPDATETUP型の各レコードのold row値(ttXlaUpdateDesc_t ->tuple1)を、サブスクライバ・データベースの既存の行と比較します。更新記述のold row値がサブスクライバ・データベースの対応する行と一致しない場合は、原因はおそらく更新競合です。この場合、ttXlaApplyはサブスクライバへの更新を適用せず、sb_ErrXlaTupleMismatchエラーを返します。

TimesTen以外のデータベースへの更新のレプリケート

TimesTen以外のデータベースへの変更をレプリケートする場合は、ttXlaGenerateSQL関数を使用して、レコード・データをTimesTen以外のサブスクライバで読取りが可能なSQL文に変換します。更新および削除のレコードの場合、正しいSQLを生成するために、ttXlaGenerateSQLには、NULL値可能でない列に対する主キー索引または一意索引が必要です。

ttXlaGenerateSQL関数は、パラメータとしてttXlaUpdateDesc_tレコードを受け入れ、それと同等のSQLをバッファに出力します。

重要:
ttXlaGenerateSQLによって返されるSQLでは、TimesTen SQL構文を使用します。2つのシステム間でSQL構文に互換性がない場合、TimesTen以外のサブスクライバではSQL文が失敗することがあります。さらに、SQL文は、XLAハンドルに関連付けられている接続キャラクタ・セットでエンコードされます。

例5-21 TimesTen以外のデータベースへの更新のレプリケート

この例では、レコード(record)を変換し、その結果のSQL出力を200文字のバッファ(buffer)に保存します。バッファの実際のサイズはactualLengthパラメータによって返されます。

ttXlaUpdateDesc_t record;
char buffer[200];
SQLINTEGER actualLength;

rc = ttXlaGenerateSQL(xla_handle, &record, buffer, 200, &actualLength);

if (rc != SQL_SUCCESS) {
handleXLAerror (rc, xla_handle, err_buf, &native_error);
if ( native_error == 8034 ) { // tt_ErrXlaNoSQL
printf("Unable to translate to SQL\n");
}
}

その他のXLA機能

その他のXLA機能の使用方法について説明します。内容は次のとおりです。

- ブックマークの位置の変更

- アプリケーション・コンテキストの受渡し

ブックマークの位置の変更

接続中は、随時ttXlaGetLSN関数をコールして現行読取りログ・レコード識別子に関してシステムに問い合せることができます。一連の更新を繰り返し実行する必要がある場合は、ttXlaSetLSN関数を使用して、現行読取りログ・レコード識別子を最後のttXlaAcknowledgeコールによって設定された初期読取りログ・レコード識別子より大きい有効な値に再設定できます。ここで、「大きい」とは、比較対象のログ・レコード識別子が同じトランザクション内のレコードのものである場合にのみ意味を持ちます。そうでない場合、ログ・レコード識別子の数値が大きいとしても、別のトランザクションより前にコミットされたトランザクションのログ・レコード識別子は「より小さい」ログ・レコード識別子になります。初期読取りログ・レコード識別子を現行読取りログ・レコード識別子まで進める方法は、ttXlaAcknowledge関数をコールする方法のみで、この関数によって、現行読取りログ・レコード識別子までのすべてのトランザクション・ログ・レコードを取得および処理したということが示されます。特定のブックマークに対してttXlaAcknowledgeをコールすると、現行読取りログ・レコード識別子より小さいログ・レコード識別子を持つトランザクション・ログ・レコードにアクセスできなくなります。

アプリケーション・コンテキストの受渡し

XLA関数ではありませんが、トランザクション・ログに対するライターでttApplicationContext組込みプロシージャをコールして、アプリケーションに関連付けられているバイナリ・データをXLAリーダーに渡すことができます。このプロシージャは、現在のトランザクションが生成する次の更新レコードに返す1つのVARBINARY値を指定します。XLAリーダーでは、「NOT INLINE可変長列データの読取り」で説明されている方法で、この値へのポインタを取得できます。

注意:
コンテキスト値は、1つの更新レコードにのみ適用されます。適用後に値が再設定されます。同じコンテキスト値を複数の更新に適用する場合は、各更新の前に再設定する必要があります。

コンテキストを設定するには、次の手順を実行します。

1. ttApplicationContextプロシージャを起動するために2つのプログラム変数を宣言します。変数contextBufferは、最も長いアプリケーション・コンテキストを格納できる十分な大きさを持つように宣言されたCHAR配列です。contextBufferLenは、INTEGER型の変数で、ttApplicationContextへの各コールでコンテキストの実際の長さを伝えるために使用されます。

2. ttApplicationContext組込みプロシージャのコンパイル済の起動によって文ハンドルを初期化します。

rc = SQLPrepare(hstmt, "call ttApplicationContext(?)", SQL_NTS);
rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_BINARY,
SQL_VARBINARY, 0, 0, &contextBuffer,
sizeof contextBuffer, &contextBufferLen);

3. アプリケーション・コンテキストを後で設定する必要がある場合は、コンテキスト値をcontextBufferにコピーし、コンテキストの長さをcontextBufferLenに割り当て、次のコールを使用してttApplicationContextを起動します。

rc = SQLExecute(hstmt);

トランザクションは、SQLTransactへの通常のコールでコミットされます。

rc = SQLTransact(NULL, hdbc, SQL_COMMIT);

注意:
ttApplicationContextをコールした後にSQL処理に失敗すると、コンテキストが次のSQL処理に渡されず、失われる可能性があります。このような問題が発生した場合は、アプリケーションで、次のSQL処理の前にttApplicationContextを再度コールできます。

6 分散トランザクション処理: XA

この章では、TimesTenでのX/Open XA標準の実装について説明します。

TimesTenでのXAインタフェースの実装は、トランザクション・マネージャが分散トランザクション処理(DTP)環境で使用することを目的としています。これらのインタフェースを使用して、TimesTenリソース・マネージャとともに動作するように、新しいトランザクション・マネージャを作成するか、Oracle Tuxedoなどの既存のトランザクション・マネージャを改良できます。

この章では、TimesTenでのXAの実装に固有の情報を示します。また、必要に応じて、次のドキュメントも参照してください。

- X/Open CAE仕様の『Distributed Transaction Processing: The XA Specification』(The Open Group(http://www.opengroup.org)発行)

- Tuxedoのマニュアル。次の場所から入手できます。

http://www.oracle.com/technetwork/middleware/weblogic/documentation

この章の内容は次のとおりです。

- XAの概要

- TimesTenでのXAの使用

- Windows ODBCドライバ・マネージャを介したXAサポート

- TimesTen XAを使用するためのTuxedoの構成

重要:

- TimesTen XA実装は、TimesTen Cacheでは動作しません。キャッシュ・エージェントが実行されている場合、XAトランザクションの開始に失敗します。

- レプリケーションが有効になっている場合、XAトランザクションは実行できません。

- DDL文をXAトランザクション内で実行しないでください。

XAの概要

この項では、次のXA概念について概要について簡単に説明します。

- X/Open DTPモデル

- 2フェーズ・コミット

X/Open DTPモデル

次の図6-1に、X/Open DTPモデルによって定義されるインタフェースを示します。

図6-1 分散トランザクション処理モデル

TXインタフェースは、アプリケーションがトランザクション・マネージャとの通信に使用するインタフェースです。図は、グローバル・トランザクションをトランザクション・マネージャに送信するアプリケーションを示しています。DTPモデルでは、トランザクション・マネージャが、各グローバル・トランザクションを複数のブランチに分割し、それらを別々のリソース・マネージャに分散して処理します。トランザクション・マネージャは、XAインタフェースを使用して、各トランザクション・ブランチと適切なリソース・マネージャを組み合せます。

TimesTen XAでは、リソース・マネージャは、TimesTenデータベースで構成するか、またはXAをサポートする他の商用データベースとデータベースを組み合せて構成することができます。

TXおよびXAインタフェースによって提供されるグローバル・トランザクションの制御は、ネイティブのODBCインタフェースによって提供されるローカル・トランザクションの制御とは異なります。通常は、ローカル・トランザクションとグローバル・トランザクションで別々の接続を維持することをお薦めします。アプリケーションは、TimesTenリソース・マネージャに対する接続ハンドルを取得して、同じ接続上でローカル・トランザクションおよびグローバル・トランザクションの両方を開始できます。詳細は、「XA接続からODBCハンドルを取得するTimesTen tt_xa_context関数」を参照してください。

2フェーズ・コミット

XAの実装では、トランザクション・マネージャは、2フェーズ・コミットのプロトコルを使用して、分散されたグローバル・トランザクションのブランチをコミットします。

1. 第1フェーズでは、トランザクション・マネージャは、各リソース・マネージャに対してコミットを準備するように命令しますが、これは、グローバル・トランザクションの各ブランチがコミット可能であることを確認し、保証するためです。リソース・マネージャでブランチをコミットできない場合、トランザクション・マネージャは第2フェーズでトランザクション全体をロールバックします。

2. 第2フェーズでは、トランザクション・マネージャは、各リソース・マネージャにブランチをコミットするように命令します。また、第1フェーズでコミットできなかったことがリソース・マネージャにレポートされている場合は、グローバル・トランザクションをロールバックします。

次の最適化に注意してください。

- トランザクション・マネージャは、グローバル・トランザクションに1つのブランチのみが含まれるように指定した場合、第1フェーズをスキップして、第2フェーズでトランザクションをコミットします。

- グローバル・トランザクション・ブランチが読取り専用で、トランザクション・ログ・レコードが生成されない場合、トランザクション・マネージャは第1フェーズでそのブランチをコミットし、ブランチの第2フェーズをスキップします。

注意:
トランザクション・マネージャでは、すべてのブランチが正常にコミットされた場合にのみ、グローバル・トランザクションがコミットされたと認識されます。

TimesTenでのXAの使用

TimesTenでのXAの実装によって、『Distributed Transaction Processing: The XA Specification』で指定されているAPIと同じAPIが提供されます。この項で説明する、TimesTenでのXAの実装を使用する際に必要な前提知識についての内容は次のとおりです。

- XAのTimesTenデータベース要件

- TimesTenでのグローバル・トランザクション・リカバリ

- 標準のXA関数をTimesTenで使用する場合の考慮事項

- XA接続からODBCハンドルを取得するTimesTen tt_xa_context関数

- TimesTenでのXA接続に対するODBC関数のコールに関する考慮事項

- XAリソース・マネージャ・スイッチ

- TimesTenでのXAエラー処理

XAのTimesTenデータベース要件

グローバル・トランザクションの一貫性を保証するには、TimesTen XAのトランザクション・ブランチが永続的である必要があります。xa_prepare()、xa_rollback()およびxa_commit()関数のTimesTenの実装では、DurableCommits一般接続属性の設定値またはttDurableCommit組込みプロシージャを使用したかどうかに関係なく、実行された処理をディスクに記録します。(動作はDurableCommits=1を設定した場合と同じです。詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のDurableCommitsに関する説明を参照してください。)障害からのリカバリが必要な場合は、リソース・マネージャおよびTimesTenトランザクション・マネージャの両方に、障害発生時にアクティブ(準備された状態)であったトランザクション・ブランチに関する一貫性のあるビューが含まれます。

TimesTenでのグローバル・トランザクション・リカバリ

障害発生または予期しない終了の後にデータベースがディスクからロードされてリカバリが行われると、準備されたもののコミットされていないグローバル・トランザクションが保留中(インダウト)の状態のままになります。通常の処理は、すべてのインダウト・トランザクションの処理が解決されるまで有効になりません。

接続およびリカバリが完了すると、TimesTenは、インダウト・トランザクションを確認します。インダウト・トランザクションがない場合は、処理を通常どおり続行します。インダウト・トランザクションがある場合は、他の接続が作成されることもありますが、インダウト・トランザクションが解決されるまで、これらの接続でのすべての処理が事実上禁止されます。他のすべてのODBCまたはJDBCのコールは、次のようなエラーになります。

Error 11035 - "In-doubt transactions awaiting resolution in recovery must be
resolved first"

インダウト・トランザクションのリストは、xa_recover()のXA実装を介して取得した後、XAコールのxa_commit()、xa_rollback()またはxa_forget()を必要に応じて使用して処理できます。インダウト・トランザクションがすべて消去されると、通常どおりに処理が続行されます。

この方法は、トランザクション・マネージャで厳密に制御された状態で動作するシステムに適しています。トランザクション・マネージャは、接続後にまずxa_recover()をコールするためです。

トランザクション・マネージャを使用できない場合、またはインダウト・トランザクションを解決できない場合は、ttXactAdminユーティリティの-HCommitまたは-HAbortオプションを使用して、個々のトランザクション・ブランチを個別にコミットまたは強制終了できます。ただし、これらのttXactAdminオプションにはADMIN権限が必要であることに注意してください。詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttXactAdminに関する項を参照してください。

標準のXA関数をTimesTenで使用する場合の考慮事項

この項では、TimesTen XA関数の使用に関するいくつかの問題について説明しますが、これらは、独自のトランザクション・マネージャを作成する場合に必要となる情報です。

xa_open()

xa_open()で使用されるxa_info文字列は、次のようなSQLDriverConnectで指定される文字列と同じ接続文字列である必要があります。

"DSN=DataStoreResource;UID=MyName"

XAでは、文字列の長さは256文字に制限されます。xa.hヘッダー・ファイルのMAXINFOSIZEを参照してください。

xa_open()関数は、XA接続をオープンするときに、自動コミットを自動的に無効にします。

xa_open()でオープンされている接続は、xa_close()をコールしてクローズする必要があります。

注意:
TimesTenに接続する、インスタンス管理者以外の任意のユーザーには、CREATE SESSION権限を付与する必要があります。「接続のアクセス制御」を参照してください。

xa_close()

xa_close()で使用されるxa_info文字列は、空である必要があります。

トランザクションID(XID)パラメータ

XAでは、XIDと呼ばれるトランザクションIDを使用してグローバル・トランザクションを一意に識別します。XIDは、トランザクションを処理するXA関数に必要なパラメータです。内部的に、TimesTenはXIDを独自のトランザクション識別子にマップします。

XA標準で定義されたXIDは、long型として定義されたメンバー(formatID、gtrid_length、bqual_lengthなど)の一部を持ちます。このため、32ビットのクライアント・アプリケーションで64ビットのサーバーに接続したり、64ビットのクライアント・アプリケーションで32ビットのサーバーに接続する場合に、問題が発生する可能性があることに注意してください。これは、longが32ビットのプラットフォームでは32ビットの整数になり、64ビットのプラットフォーム(64ビットのWindows以外)では64ビットの整数となるためです。したがって、TimesTenは、クライアントまたはサーバーのプラットフォームのタイプに関係なく、これらのXIDメンバーの最小有効32ビットのみを内部的に使用します。TimesTenでは、32ビットの整数に適合しないXIDメンバーの値はサポートされません。

XA接続からODBCハンドルを取得するTimesTen tt_xa_context関数

TimesTenには関数tt_xa_context()があり、この関数を使用すると、xa_open()でオープンされるXA接続に関連付けられているODBC接続ハンドルを取得できます。

構文

#include <tt_xa.h>
int tt_xa_context(int* rmid, SQLHENV* henv, SQLHDBC* hdbc);

パラメータ

パラメータ

型

説明

rmid

int

指定したリソース・マネージャID
これがNULL以外の場合、そのrmidの値に関連付けられているハンドルが関数によって返されます。

指定したrmidがNULLの場合、このスレッドの最初の接続に関連付けられているハンドルが関数によって返されます。たとえば、ユーザーが記述したコードの範囲外で接続がオープンされていて、rmidが不明な場合には、NULL値を指定します。この設定では、アプリケーション環境でコンテキストが確立されます。

henv

out SQLHENV

現在のxa_open()コンテキストに関連付けられている環境ハンドル

hdbc

out SQLHDBC

現在のxa_open()コンテキストに関連付けられている接続ハンドル

戻り値

0: 成功

1: rmidが見つかりません

-1: 無効なパラメータです

例

次の例では、Tuxedoによってxa_open()およびxa_start()が使用され、データベースへの接続がオープンし、トランザクションが開始していると仮定します。さらに接続のODBC処理を続行するために、tt_xa_context()関数を使用して、xa_open()で割り当てられているSQLHENVおよびSQLHDBCハンドルを検出します。

例6-1 tt_xa_context()を使用したハンドルの検出

do_insert()
{

SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;

/* retrieve the handles for the current connection */
tt_xa_context(NULL, &henv, &hdbc);

/* now we can do our ODBC programming as usual */
SQLAllocStmt(hdbc, &hstmt);

SQLExecDirect(hstmt, "insert into t1 values (1)", SQL_NTS);

SQLFreeStmt(hstmt, SQL_DROP);
}

TimesTenでのXA接続に対するODBC関数のコールに関する考慮事項

この項では、xa_open()でオープンされるXA接続に関連付けられているODBCハンドルを使用してODBC関数をコールする際に注意する必要があるTimesTenの問題について、いくつか説明します。

Autocommit

処理を簡素化し、矛盾の発生を回避するために、xa_open()は、XA接続をオープンするときに、自動コミットを自動的に無効にします。

その後、ローカル・トランザクション処理の実行中に、自動コミットを有効または無効にする場合がありますが、xa_start()をコールしてグローバル・トランザクション・ブランチでの処理を開始する前には、無効にする必要があります。自動コミットが有効の場合、xa_start()をコールすると次のエラーが返されます。

Error 11030 - "Autocommit must be turned off when working on global (XA) transactions"

xa_start()をコールしてグローバル・トランザクション・ブランチでの処理を開始した後、xa_end()をコールしてその処理を完了するまで、自動コミットを有効にできない場合があります。この場合、自動コミットを有効にしようとすると、前述と同じエラーが発生します。

ローカル・トランザクションのCOMMITおよびROLLBACK

xa_start()をコールしてグローバル・トランザクション・ブランチでの処理を開始した後、SQLTransactを使用してローカル・コミットまたはロールバックを実行しようとすると、次のエラーが発生します。

Error 11031 - "Illegal combination of local transaction and global (XA) transaction"

オープンしているカーソルのクローズ

xa_end()をコールしてグローバル・トランザクション・ブランチでの処理を終了する前に、SQLFreeStmtをSQL_CLOSEの値とともに使用して、オープンしているすべての文カーソルをクローズする必要があります。このようにしなかった場合、次のエラーが返されます。

Error 11032 - "XA request failed due to open cursors"

XAリソース・マネージャ・スイッチ

各リソース・マネージャは、xa.hヘッダー・ファイルにスイッチを定義し、これよって、トランザクション・マネージャはリソース・マネージャ内のXA関数にアクセスできます。トランザクション・マネージャでは、XAインタフェース関数を直接コールしません。かわりに、スイッチ表の関数をコールし、スイッチ表は、リソース・マネージャ内の該当する関数を指します。これにより、アプリケーションを再コンパイルしなくても、リソース・マネージャを追加および削除できます。

TimesTenでのXAの実装では、XAスイッチxa_switch_tの関数は、TimesTenスイッチtt_xa_switchで定義されているそれぞれの関数を指します。

xa_switch_t

XA仕様によって定義されているxa_switch_t構造体は次のとおりです。

/* XA Switch Data Structure */
#define RMNAMESZ       32         /* length of resource manager name, */
/* including the null terminator */
#define MAXINFOSIZE    256        /* maximum size in bytes of xa_info strings, */
/* including the null terminator */

struct xa_switch_t
{

char name[RMNAMESZ];                /* name of resource manager */
long flags;                         /* resource manager specific options */
long version;                       /* must be 0 */

int (*xa_open_entry)(char*, int, long);        /* xa_open function pointer */
int (*xa_close_entry)(char*, int, long);       /* xa_close function pointer*/
int (*xa_start_entry)(XID*, int, long);        /* xa_start function pointer */
int (*xa_end_entry)(XID*, int, long);          /* xa_end function pointer */
int (*xa_rollback_entry)(XID*, int, long);     /* xa_rollback function pointer */
int (*xa_prepare_entry)(XID*, int, long);      /* xa_prepare function pointer */
int (*xa_commit_entry)(XID*, int, long);       /* xa_commit function pointer */
int (*xa_recover_entry)(XID*, long, int, long); /* xa_recover function pointer*/
int (*xa_forget_entry)(XID*, int, long);        /* xa_forget function pointer */
int (*xa_complete_entry)(int*, int*, int, long); /* xa_complete function pointer */
};

typedef struct xa_switch_t xa_switch_t;
/*
* Flag definitions for the RM switch
*/
#define TMNOFLAGS 0x00000000L     /* no resource manager features selected */
#define TMREGISTER 0x00000001L    /* resource manager dynamically registers */
#define TMNOMIGRATE 0x00000002L   /* RM does not support association migration */
#define TMUSEASYNC 0x00000004L    /* RM supports asynchronous operations */

tt_xa_switch

tt_xa_switchでは、TimesTenリソース・マネージャで実装されている実際の関数に名前を付けます。また、関連移行がサポートされていないことを明示的に示します。なお、動的な登録と非同期の処理もサポートされません。

struct xa_switch_t
tt_xa_switch =
{
"TimesTen", /* name of resource manager */
TMNOMIGRATE, /* RM does not support association migration */
0,
tt_xa_open,
tt_xa_close,
tt_xa_start,
tt_xa_end,
tt_xa_rollback,
tt_xa_prepare,
tt_xa_commit,
tt_xa_recover,
tt_xa_forget,
tt_xa_complete
};

TimesTenでのXAエラー処理

XA仕様では、XAインタフェース・コールから返される可能性がある一定のエラーが厳密に定義されています。ODBC SQLError関数は、XAで定義されたエラーを追加情報ととともに返します。

TimesTen XA関連のエラーは11000番から始まります。11002から11020のエラーは、XA標準で定義されたエラーと対応しています。

エラーの完全なリストは、『Oracle TimesTen In-Memory Databaseエラー・メッセージおよびSNMPトラップ』の「警告およびエラー」を参照してください。

Windows ODBCドライバ・マネージャを介したXAサポート

この項では、XAをWindows ODBCドライバ・マネージャとともに使用する場合の問題点および手順について説明します。(UNIX ODBCドライバ・マネージャについては対象としていません。)

考慮事項

ODBCドライバ・マネージャを介したXAサポートには特別な処理が必要です。次の2つの基本的な問題があります。

- XAインタフェースは、定義済のODBCインタフェースには含まれていません。アプリケーションでXA記号が直接参照される場合は、すべての外部参照を解決するために、ドライバ・マネージャ・ライブラリのみとリンクすることはできません。

- 設計では、SQLConnectまたはSQLDriverConnectをコールすると、接続時にドライバ・マネージャがロードするドライバ.dllファイルを決定します。XAは、xa_open()を介して接続をオープンする必要があることを命令します。ただし、接続処理中に.dllがロードされるまで、適切なxa_open()エントリ・ポイントを指定することはできません。

基本的に各XAの実装は独自のものであるため、通常、データベースの移植性というドライバ・マネージャの目的はここでは適用できないことに注意してください。ドライバ・マネージャでXA対応のアプリケーションをサポートする主な利点は、TimesTen固有のアプリケーションをTimesTenの直接ドライバまたはTimesTenのClient/Serverドライバを使用して透過的に実行できることです。

TimesTen ODBC XAドライバ・マネージャの拡張ライブラリへのリンク

Windowsインストールでは、TimesTenによってXA関数用に、ドライバ・マネージャの拡張ライブラリttxadm1122.dllが提供されます。アプリケーションは、XAを直接コールすることができますが、拡張ライブラリにリンクする必要があります。

ttxadm1122.dllライブラリとリンクするには、リンク行のodbc32.libの前にttxadm1122.libを含める必要があります。次に例を示します。

# Link with the ODBC driver manager
appldm.exe:appl.obj
$(CC) /Feappldm.exe appl.obj ttxadm1122.lib odbc32.lib

注意:
XAドライバ・マネージャの拡張機能は、32-bitのWindowsアプリケーションでのみ実装されます。

TimesTen XAを使用するためのTuxedoの構成

TimesTenリソース・マネージャを使用するようにTuxedoを構成するには、次のタスクを実行します。

- $TUXDIR/udataobj/RMファイルの更新

- Tuxedoトランザクション・マネージャ・サーバーの構築

- UBBCONFIGファイルのGROUPSセクションの更新

- サーバーのコンパイル

重要:
TimesTen XAはOracle Tuxedoトランザクション・マネージャと連携して動作することが実証されていますが、TimesTenでのXAの実装範囲を超えるDTPソフトウェアの動作は保証されていません。

注意:

- この項の例では、直接ドライバを使用します。また、クライアント/サーバー・ライブラリまたはドライバ・マネージャ・ライブラリをXA拡張ライブラリとともに使用することもできます。

- オブジェクトリレーショナル・マッピング・フレームワークおよびアプリケーション・サーバー(Oracle WebLogic Application Serverなど)用にTimesTenを構成する詳細は、TimesTenクイック・スタートを参照してください。「Configuration and Setup」の「Java EE and OR Mapping」をクリックしてください。

$TUXDIR/udataobj/RMファイルの更新

TimesTen XAリソース・マネージャをOracle Tuxedoシステムに統合するには、TimesTenリソース・マネージャ、TimesTenリソース・マネージャ・スイッチの名前(tt_xa_switch)およびリソース・マネージャのライブラリの名前を示すように$TUXDIR/udataobj/RMファイルを更新します。

UNIXプラットフォームで、次の行を追加します。

TimesTen:tt_xa_switch:-Linstall_dir/lib -ltten

次に例を示します。

TimesTen:tt_xa_switch:-L/opt/TimesTen/giraffe/lib -ltten

Windowsプラットフォームで、次の行を追加します。

TimesTen;tt_xa_switch;install_dir\lib\ttdv1122.lib

次に例を示します。

TimesTen;tt_xa_switch;C:\TimesTen\giraffe\lib\ttdv1122.lib

注意:
install_dirは、TimesTenホーム・ディレクトリのパスです。

Tuxedoトランザクション・マネージャ・サーバーの構築

buildtmsコマンドを使用して、TimesTenリソース・マネージャ用のトランザクション・マネージャ・サーバーを構築します。その後、buildtmsで作成したTMS_TTファイルを$TUXDIR/binディレクトリにコピーします。

UNIXプラットフォームでは、コマンドは次のようになります。

buildtms -o TMS_TT -r TimesTen -v
cp TMS_TT $TUXDIR/bin

Windowsプラットフォームでは、コマンドは次のようになります。

buildtms -o TMS_TT -r TimesTen -v
copy TMS_TT.exe %TUXDIR%\bin

UBBCONFIGファイルのGROUPSセクションの更新

TMSNAMEにbuildtmsコマンドで作成したTMS_TTファイルを指定します(前述の項を参照)。

TMSNAME=TMS_TT

各TimesTenリソース・マネージャについて、グループ名の後にLMID、GRPNOおよびOPENINFOパラメータが続く行を入力します。OPENINFO文字列は、次のようになります。

OPENINFO="TimesTen:DSN=DSNname"

DSNnameは、データベースの名前です。

Windowsでは、TuxedoサーバーはユーザーSYSTEMとして実行されることに注意してください。OPENINFO文字列にUID一般接続属性を追加して、SYSTEM以外のユーザーを指定します。

OPENINFO="TimesTen:DSN=DSNname;UID=user"

どのTimesTenリソース・マネージャにもCLOSEINFOパラメータを指定しないでください。

例6-2に、GROUP1とGROUP2という2つのTimesTenリソース・マネージャの構成に使用するUBBCONFIGファイルの一部を示します。

例6-2 TimesTenリソース・マネージャの構成

*RESOURCES
...
*MACHINES
...
ENGSERV LMID=simple
*GROUPS
DEFAULT: TMSNAME=TMS_TT TMSCOUNT=2
GROUP1
LMID=simple GRPNO=1 OPENINFO="TimesTen:DSN=MyDSN1;UID=MyName"
GROUP2
LMID=simple GRPNO=2 OPENINFO="TimesTen:DSN=MyDSN2;UID=MyName"
*SERVERS
DEFAULT:
CLOPT="-A"
simpserv1 SRVGRP=GROUP1 SRVID=1
simpserv2 SRVGRP=GROUP2 SRVID=2

*SERVICES
TOUPPER
TOLOWER

サーバーのコンパイル

TimesTen includeファイルを含んでいるinstall_dir/includeディレクトリを含むように、CFLAGS環境変数を設定します。その後、buildserverコマンドを使用して、Oracle Tuxedo ATMIサーバー・ロード・モジュールを構成します。

UNIXプラットフォームで、次の行を入力します。

export CFLAGS=-Iinstall_dir/
buildserver -o server -f server.c -r TimesTen -s SERVICE

Windowsプラットフォームで、次の行を入力します。

set CFLAGS=-Iinstall_dir\
buildserver -o server -f server.c -r TimesTen -s SERVICE

注意:
install_dirは、TimesTenホーム・ディレクトリのパスです。

例6-3に、buildclientコマンドを使用してクライアント・モジュール(simpcl)を構成する方法と、buildserverコマンドを使用して前述の例6-2のUBBCONFIGファイルに記述されている2つのサーバー・モジュールを構成する方法の例を示します。

例6-3 サーバー・モジュールの構成

set CFLAGS=-IC:\TimesTen\giraffe\
buildclient -o simpcl -f simpcl.c
buildserver -v -t -o simpserv1 -f simpserv1.c -r TimesTen -s TOUPPER
buildserver -v -t -o simpserv2 -f simpserv2.c -r TimesTen -s TOLOWER

7 ODBCアプリケーションのチューニング

この章では、TimesTenデータベース上で最適に実行されるようにODBCアプリケーションをチューニングする方法について説明します。チューニングの一般的な詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のTimesTen Databaseのパフォーマンス・チューニングに関する項を参照してください。

この章の内容は次のとおりです。

- ドライバ・マネージャの回避(必要な場合)

- バッチ実行用パラメータ配列の使用

- 過剰なバインドの回避

- SQLGetDataの回避

- データ型の変換の回避

- TimesTenデータ行のバルク・フェッチ

ドライバ・マネージャの回避(必要な場合)

ドライバ・マネージャで提供される一部の機能を必要としないODBCアプリケーションは、ドライバ・マネージャを使用しないでTimesTenにリンクできます。特に、TimesTen以外のデータ・ベース・システムへのODBCアクセスを必要としないアプリケーションでは、ドライバ・マネージャを省略する必要があります。これは、アプリケーションをTimesTenの直接ドライバまたはクライアント・ドライバに直接リンクすることによって行います(「リンク・オプション」を参照)。パフォーマンスが大幅に向上します。

注意:
データベースに接続している一部のアプリケーションは、ドライバ・マネージャを使用してリンクできますが、同じデータベースに接続している他のアプリケーションは、直接リンクされます。

バッチ実行用パラメータ配列の使用

アプリケーションで、バッチと呼ばれる文の実行のグループを使用して、パフォーマンスを向上できます。

SQLParamOptions ODBC関数では、アプリケーションによってSQLBindParameterで割り当てられるパラメータのセットに複数の値を指定できます。これは、同じSQL文を様々なパラメータ値を使用して複数回処理する場合に有効です。たとえば、アプリケーションで、INSERT文に関連付けられているパラメータのセットに複数の値のセットを指定すると、INSERT文を1回実行してその挿入処理をすべて実行できます。

TimesTenでは、SQLParamOptionsをINSERT、UPDATE、DELETEおよびMERGE文とともに使用できますが、SELECT文とともに使用することはできません。TimesTen 11gリリース2(11.2.2)では、次のバッチ・サイズをお薦めします。

- INSERT文に256

- UPDATE文に31

- DELETE文に31

- MERGE文に31

表7-1に、SQLParamOptions引数の概要を示します。詳細は、ODBC APIのリファレンス・マニュアルを参照してください。

表7-1 SQLParamOptions引数

引数

型

説明

hstmt

SQLHSTMT

文ハンドル

crow

SQLROWSETSIZE

各パラメータの値の数

pirow

SQLROWSETSIZE

現在の行番号の記憶域へのポインタ

crow値が1より大きく、SQLBindParameterのrgbValue引数がパラメータ値の配列を指し、pcbValue引数が長さの配列を指すことを想定しています。(「SQLBindParameter関数」も参照してください。)

バッチ処理の完全な動作例は、TimesTenクイック・スタート・デモのソース・ファイルbulkinsert.cを参照してください。(TTClassesを使用したC++でのプログラミングについては、bulktest.cppも参照してください。)

注意:
SQLParamOptionsをTimesTen Client/Serverドライバとともに使用する場合、実行時データ・パラメータはサポートされません。(アプリケーションは、SQLBindParameter rgbValueバッファで、またはSQLPutDataに対する1つ以上のコールとともにパラメータの値を渡すことができます。SQLPutDataとともにデータが渡されるパラメータは、実行時データ・パラメータといいます。これらは一般に、SQL_LONGVARBINARYおよびSQL_LONGVARCHARパラメータのデータを送信するために使用され、その他のパラメータと混在することができます。)

過剰なバインドの回避

SQLBindColまたはSQLBindParameterは、型変換およびプログラム・バッファをデータ列またはパラメータと関連付けるためにコールします。特定のSQL文で、文を繰り返し実行する間に特定のデータ列またはパラメータに対する型変換またはメモリー・バッファが変更されない場合は、SQLBindColまたはSQLBindParameterを繰り返しコールしないことをお薦めします。1回準備し、1回バインドして、何回も実行します。

注意:
SQL_UNBINDオプションを指定してSQLFreeStmtをコールすると、すべての列がアンバインドされます。

SQLGetDataの回避

SQLGetDataを使用すると、列をバインドせずにデータをフェッチできます。この場合、アプリケーションでフェッチ対象のすべての行のすべての列に対してSQLGetData ODBCコールを発行する必要があるため、パフォーマンスに悪影響を及ぼす可能性があります。一方、バインドされた列を使用する場合は、フェッチされる列ごとに1回のみのODBCコールが必要となります。また、TimesTen ODBCドライバには、バインドされた列でデータをフェッチする方法が適しています。

ただし、SQLGetDataは、長い文字列またはバイナリ列からデータをピース単位でフェッチする場合に非常に有効です。(「ODBCでのLOBのピース単位のデータ・インタフェースの使用」のLOBに関する説明を参照してください。)

データ型の変換の回避

TimesTenの命令パスは非常に短いため、データ変換による短時間の遅れでさえ、トランザクション時間の大幅な増加の原因となる可能性があります。データ型の変換を回避するには、次の手順を実行します。

- 入力引数の型と式の型を一致させます。

- 出力バッファの型とフェッチされた値の型を一致させます。

- 接続キャラクタ・セットとデータベース・キャラクタ・セットを一致させます。

TimesTenデータ行のバルク・フェッチ

TimesTenは、TT_PREFETCH_COUNTオプションを備えています。これは、SQLSetStmtOptionを使用して設定でき、これによってアプリケーションは複数のデータ行をフェッチできます。この機能は、コミット読取り分離レベルを使用しているアプリケーションで使用できます。大量のTimesTenデータを取得するアプリケーションの場合、複数行のフェッチによってパフォーマンスを大幅に向上させることができます。ただし、アプリケーションですべてのデータが取得されるまで、取得されるすべての行にロックが設定されるため、同時実行性は低下します。TT_PREFETCH_COUNTの使用方法の詳細は、「複数のデータ行のプリフェッチ」を参照してください。

8 TimesTenユーティリティAPI

この章で説明するTimesTenユーティリティ・ライブラリのC言語関数は、『Oracle TimesTen In-Memory Databaseリファレンス』のユーティリティに関する項で説明されているコマンドライン・ユーティリティの一部に対して、プログラム可能なインタフェースを提供します。

このC言語関数のセットを使用するアプリケーションでは、ttutillib.hをインクルードし、TimesTenドライバ・ライブラリ(UNIXではlibtten、Windowsではttdv1122.libおよびtten1122.lib)およびTimesTenユーティリティ・ライブラリ(UNIXではlibttutil、Windowsではttutil1122.lib)の両方をリンクする必要があります。

重要:
アプリケーションでは、他のすべてのTimesTenユーティリティ・ライブラリ関数をコールする前に、ttUtilAllocEnv C関数をコールする必要があります。また、TimesTenユーティリティ・ライブラリ・インタフェースを使用して処理を行う場合、アプリケーションは、ttUtilFreeEnv C関数をコールする必要があります。

これらの関数はTimesTen ClientまたはJavaアプリケーションではサポートされていません。それらは、直接ドライバを使用するTimesTen ODBCアプリケーションでサポートされます。(クイック・スタート・アプリケーションで提供されるTimesTenドライバ・マネージャではこれらの関数をサポートしていますが、ドライバ・マネージャ自体が完全にはサポートされているわけではありません。「ODBCドライバ・マネージャとのリンク」のこのドライバ・マネージャについての注意を参照してください。)

リターン・コード

特に指定されていないかぎり、ユーティリティ関数は、ttutillib.hで定義されている次のコードを返します。

コード

説明

TTUTIL_SUCCESS

成功を示します。

TTUTIL_ERROR

エラーが発生したことを示します。

TTUTIL_WARNING

成功時に、警告が生成されたことを示します。

TTUTIL_INVALID_HANDLE

無効なユーティリティ・ライブラリ・ハンドルが指定されていることを示します。

注意:
アプリケーションでは、ttUtilGetError C関数をコールして、実際のエラー情報または警告情報をすべて取得する必要があります。

ttBackup

説明

connStrで指定したデータベースの全体バックアップまたは増分バックアップのコピーを作成します。データベースは、一連のファイルまたはストリームのいずれかにバックアップできます。ttRestore関数またはttRestoreユーティリティを使用して、後でデータベースをリストアできます。

TimesTenのバックアップとリストア機能の概要は、『Oracle TimesTen In-Memory Databaseインストレーション・ガイド』の移行、バックアップおよびリストアに関する説明を参照してください。

必要な権限

ADMIN

構文

ttBackup (ttUtilHandle handle, const char* connStr,
ttBackUpType type, ttBooleanType atomic,
const char* backupDir, const char* baseName,
ttUtFileHandle stream)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

connStr

const char*

これは、バックアップするデータベースについて記述する接続文字列を指定する、空文字で終了する文字列です。

type

ttBackupType

実行するバックアップの種類を指定します。有効な値は次のとおりです。

- TT_BACKUP_FILE_FULL: backupDirおよびbaseNameパラメータで指定されたバックアップ・パスにファイルの全体バックアップを実行します。作成されたバックアップは、増分バックアップでは使用できません。

- TT_BACKUP_FILE_FULL_ENABLE: backupDirおよびbaseNameパラメータで指定されたバックアップ・パスにファイルの全体バックアップを実行します。作成されたバックアップは、増分バックアップで使用できます。

- TT_BACKUP_FILE_INCREMENTAL: backupDirおよびbaseNameパラメータで指定されたバックアップ・パスにデータベースの増分可能バックアップが含まれている場合は、そのバックアップ・パスでファイルの増分バックアップを実行します。それ以外の場合は、エラーが返されます。

- TT_BACKUP_FILE_INCR_OR_FULL: backupDirおよびbaseNameパラメータで指定されたバックアップ・パスにデータベースの増分可能バックアップが含まれている場合は、そのバックアップ・パスでファイルの増分バックアップを実行します。それ以外の場合は、データベースのファイルの完全バックアップを実行し、増分可能のマークを付けます。

- TT_BACKUP_STREAM_FULL: streamパラメータで指定したストリームでストリーム・バックアップを実行します。

- TT_BACKUP__INCREMENTAL_STOP: バックアップを実行しません。backupDirおよびbaseNameパラメータで指定されたバックアップ・パスの増分バックアップを無効にします。これにより、増分バックアップでトランザクション・ログ・ファイルが蓄積することを回避します。

atomic

ttBooleanType

新しいバックアップが作成されている間、同じbaseNameおよびbackupDirを持つ既存のバックアップの処理を指定します。
このパラメータは、同じbaseNameおよびbackupDirを持つ既存のバックアップがある場合に、ファイルの全体バックアップでのみ有効です。増分バックアップの場合、既存のバックアップを置き換えるのではなく増補するため、このパラメータは無視されます。ストリーム・バックアップの場合は、baseNameおよびbackupDirパラメータを無視して、指定したストリームに書き込まれるため、このパラメータは無視されます。

有効な値は、次のとおりです。

- TT_FALSE: 新しいバックアップを開始する前に、既存のバックアップが破棄されます。新しいバックアップが正常に完了しなかった場合、新しい不完全なバックアップも既存のバックアップもデータベースのリストアに使用できません。このオプションは、データベースのバックアップを初めて行う場合、異なるbaseNameまたはbackupDirを使用するデータベースの別のバックアップがある場合、またはデータベースのバックアップが存在しない時間帯(通常、大規模なデータベースで数十分)をアプリケーションが許容できる場合にのみ使用する必要があります。

- TT_TRUE: 既存のバックアップは、新しいバックアップが正常に完了した後にのみ破棄されます。新しいバックアップが正常に完了しなかった場合、古いバックアップは保持されていて、データベースのリストアに使用できます。同じbaseNameおよびbackupDirを持つ既存のバックアップがある場合にこのオプションを使用すると、既存のバックアップも新しいバックアップもデータベースのリストアに使用できない時間帯はなくなり、既存のバックアップは、新しいバックアップによって正常に置き換えられた場合にのみ破棄されます。ただし、既存のバックアップと新しいバックアップの両方がbackupDirに同時に存在するには、十分なディスク領域が必要です。

backupDir

const char*

ファイル・バックアップのバックアップ・ディレクトリを指定します。このパラメータは、ストリーム・バックアップでは無視されます。それ以外の場合はNULL以外になります。
TT_BACKUP_INCREMENTAL_STOPの場合は、無効にするバックアップ・パスのディレクトリ部分を指定します。

TT_BACKUP_INCREMENTAL_STOPまたはファイル・バックアップの場合は、NULLを指定すると、エラーが返されます。

baseName

const char*

ファイル・バックアップのbackupDirパラメータで指定されたバックアップ・ディレクトリ内のバックアップ・ファイルのファイル接頭辞を指定します。
このパラメータは、ストリーム・バックアップでは無視されます。

このパラメータにNULLを指定すると、バックアップ・ファイルのファイル接頭辞には、データベースのODBC定義に設定されたDataStore属性のファイル名部分が適用されます。

TT_BACKUP_INCREMENTAL_STOPの場合、このパラメータは無効にするバックアップ・パスのベース名部分を指定します。

stream

ttUtFileHandle

ストリーム・バックアップの場合、このパラメータはバックアップが書き込まれるストリームを指定します。
UNIXの場合は、write(2)を使用して書き込むことができる整数ファイル記述子です。1を渡すと、stdoutにバックアップが書き込まれます。

Windowsの場合は、WriteFileを使用して書き込むことができるハンドルです。GetStdHandle(STD_OUTPUT_HANDLE)の結果を渡すと、標準出力にバックアップが書き込まれます。

このパラメータは、ファイル・バックアップでは無視されます。

アプリケーションで、このパラメータに対してTTUTIL_INVALID_FILE_HANDLEを渡すことができます。

例

この例では、payrollというDSNのデータベースアをC:\backupにバックアップします。

ttUtilHandle  utilHandle;
int           rc;
rc = ttBackup (utilHandle,  "DSN=payroll", TT_BACKUP_FILE_FULL,
TT_TRUE, "c:\\backup", NULL, TTUTIL_INVALID_FILE_HANDLE);

バックアップが正常に行われると、すべてのファイルがC:\backupディレクトリに作成されます。

注意

各データベースで、8つの増分可能バックアップのみがサポートされます。

関連項目

ttRestore
『Oracle TimesTen In-Memory Databaseリファレンス』の「ttBackup」および「ttRestore」ユーティリティ

ttDestroyDataStore

説明

接続文字列で指定したデータベースに対応する、すべてのチェックポイント・ファイル、トランザクション・ログおよびデーモン・カタログ・エントリを含むデータベースを破棄します。サポートされているUNIXプラットフォームのsys.odbc.iniまたはユーザーodbc.iniファイル内、またはサポートされているWindowsプラットフォームのWindowsレジストリ内に定義されているDSN自体は削除されません。

必要な権限

インスタンス管理者

構文

ttDestroyDataStore (ttUtilHandle handle, const char* connStr,
unsigned int timeout)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

connStr

const char*

これは、破棄するデータベースについて記述する接続文字列を指定する、空文字で終了する文字列です。DSNおよびDataStore属性を除く、この接続文字列内のすべての属性が無視されます。

timeout

unsigned int

コール元に返される前に再試行する回数を指定します。ttDestroyDataStoreは、正常に実行されるかタイムアウトに達するまで、破棄処理を1秒ごとに繰り返し再試行します。これは、データベースの使用中などの一時的な状態が原因で破棄が失敗する場合に有効です。
このパラメータ値が0(ゼロ)の場合、再試行は実行されません。

例

この例では、ファイルC:\dsns\payroll.ds0、C:\dsns\payroll.ds1およびいくつかのトランザクション・ログ・ファイルC:\dsns\payroll.lognで構成されるpayrollというDSNで定義されているデータベースを破棄します。

char            errBuff [256];
int             rc;
unsigned int    retCode;
ttUtilErrType   retType;
ttUtilHandle    utilHandle;
...
...
rc = ttDestroyDataStore (utilHandle, "DSN=payroll", 30);
if (rc == TTUTIL_SUCCESS)
printf ("Datastore payroll successfully destroyed.\n");
else if (rc == TTUTIL_INVALID_HANDLE)
printf ("TimesTen utility library handle is invalid.\n");
else
while ((rc = ttUtilGetError (utilHandle, 0, &retCode,
&retType, errBuff, sizeof (errBuff), NULL)) !=
TTUTIL_NODATA)
{
...
...
}

ttDestroyDataStoreForce

説明

接続文字列で指定したデータベースに対応する、すべてのチェックポイント・ファイル、トランザクション・ログおよびデーモン・カタログ・エントリを含むデータベースを破棄します。サポートされているUNIXプラットフォームのsys.odbc.iniまたはユーザーodbc.iniファイル内、またはサポートされているWindowsプラットフォームのWindowsレジストリ内に定義されているDSN自体は削除されません。

必要な権限

インスタンス管理者

構文

ttDestroyDataStoreForce (ttUtilHandle handle, const char* connstr,
unsigned int timeout)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

connStr

const char*

これは、破棄するデータベースについて記述する接続文字列を指定する、空文字で終了する文字列です。DSNおよびDataStore属性を除く、この接続文字列内のすべての属性が無視されます。

timeout

unsigned int

コール元に返される前に再試行する秒数を指定します。ttDestroyDataStoreForceユーティリティは、正常に実行されるかタイムアウトに達するまで、破棄処理を1秒ごとに繰り返し再試行します。これは、データベースの使用中などの一時的な状態が原因で破棄が失敗する場合に有効です。
このパラメータ値が0(ゼロ)の場合、再試行は実行されません。

例

この例では、ファイルC:\dsns\payroll.ds0、C:\dsns\payroll.ds1およびいくつかのトランザクション・ログ・ファイルC:\dsns\payroll.lognで構成されるpayrollというDSNで定義されているデータベースを破棄します。

char              errBuff [256];
int               rc;
unsigned int      retCode;
ttUtilErrType     retType;
ttUtilHandle      utilHandle;
...
...
rc = ttDestroyDataStoreForce (utilHandle, "DSN=payroll", 30);
if (rc == TTUTIL_SUCCESS)
printf ("Datastore payroll successfully destroyed.\n");
else if (rc == TTUTIL_INVALID_HANDLE)
printf ("TimesTen utility library handle is invalid.\n");
else
while ((rc = ttUtilGetError (utilHandle, 0, &retCode,
&retType, errBuff, sizeof (errBuff), NULL)) !=
TTUTIL_NODATA)
{
...
...
}

ttRamGrace

説明

最後のアプリケーションがデータベースから接続を切断した後、接続文字列で指定したデータベースがTimesTenによってRAMに保持される秒数を指定します。その後、TimesTenはデータベースをアンロードします。この猶予期間は随時設定または再設定が可能ですが、RAMポリシーがTT_RAMPOL_INUSEに設定されている場合のみです。

必要な権限

インスタンス管理者

構文

ttRamGrace (ttUtilHandle handle, const char* connStr, unsigned int seconds)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

connStr

const char*

これは、RAM猶予期間を設定するデータベースについて記述する接続文字列を指定する、空文字で終了する文字列です。

seconds

unsigned int

最後のアプリケーションがデータベースから接続を切断した後、TimesTenがデータベースをRAMに保持する秒数を指定します。その後、TimesTenはデータベースをアンロードします。

例

この例では、payrollというDSNに10秒のRAM猶予期間を設定します。

ttUtilHandle   utilHandle;
int            rc;
rc = ttRamGrace (utilHandle, "DSN=payroll", 10);

関連項目

「ttRamLoad」
「ttRamPolicy」
「ttRamUnload」

ttRamLoad

説明

接続文字列で指定したデータベースをシステムのRAMにロードするようにTimesTenに指示します。永続データベースでは、ttRamLoadへのコールはRamPolicyがTT_RAMPOL_MANUALに設定されている場合にのみ有効です。一時データベースでは、ttRamLoadへのコールによってデータベースがRAMにロードされます。

関連の詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttRamPolicySetに関する説明、またはttRamPolicyを参照してください。

必要な権限

インスタンス管理者

構文

ttRamLoad (ttUtilHandle handle, const char* connStr)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

connStr

const char*

これは、RAMにロードするデータベースについて記述する接続文字列を指定する、空文字で終了する文字列です。

例

この例では、payrollというDSNのデータベースをロードします。

ttUtilHandle   utilHandle;
int            rc;
rc = ttRamLoad (utilHandle, "DSN=payroll");

関連項目

「ttRamGrace」
「ttRamPolicy」
「ttRamUnload」

ttRamPolicy

説明

接続文字列で指定したデータベースをTimesTenがシステムRAMにロードするタイミングを決定するためのポリシーを定義します。

必要な権限

インスタンス管理者

構文

ttRamPolicy (ttUtilHandle handle, const char* connStr,
ttRamPolicyType policy)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

connStr

const char*

これは、RAMポリシーを設定するデータベースについて記述する接続文字列を指定する、空文字で終了する文字列です。

policy

ttRamPolicyType

指定したデータベースをTimesTenがシステムRAMにロードするタイミングを決定するためのポリシーを指定します。有効な値は、次のとおりです。

- TT_RAMPOL_ALWAYS: データベースが常時RAMに存在するように指定します。

- TT_RAMPOL_MANUAL: ttRamLoad C関数またはttAdmin -ramLoadコマンドのいずれかを使用して、データベースが明示的にRAMにロードされるように指定します。同様に、データベースは、ttRamUnload C関数またはttAdmin -ramUnloadコマンドを使用して明示的にRAMからアンロードできます。

- TT_RAMPOL_INUSE: アプリケーションでデータベースに接続する場合にデータベースがRAMにロードされるように指定します。このRAMポリシーは、ttRamGrace C関数またはttAdmin -ramGraceコマンドを使用して、さらに変更できます。

指定したデータベースに対して明示的にRAMポリシーを設定しない場合、デフォルトのRAMポリシーはTT_RAMPOL_INUSEとなります。

例

この例では、payrollというDSNのRAMポリシーをmanualに設定します。

ttUtilHandle   utilHandle;
int            rc;
rc = ttRamPolicy (utilHandle, "DSN=payroll", TT_RAMPOL_MANUAL);

注意

一時データベースにポリシーは設定できません。

関連項目

「ttRamGrace」
「ttRamLoad」
「ttRamUnload」

ttRamUnload

説明

TimesTen RAMポリシーがmanualに設定されている場合に、接続文字列で指定したデータベースをシステムのRAMからアンロードするようにTimesTenに指示します。永続データベースでは、このコールはRAMポリシーがTT_RAMPOL_MANUALに設定されている場合にのみ有効です。一時データベースでは、RAMポリシーを設定できないため、ttRamUnloadをコールすると、RAMからのデータベースのアンロードが常に試行されます。

関連の詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttRamPolicySetに関する説明、またはttRamPolicyを参照してください。

必要な権限

インスタンス管理者

構文

ttRamUnload (ttUtilHandle handle, const char* connStr)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

connStr

const char*

これは、RAMからアンロードするデータベースの接続文字列を指定する、空文字で終了する文字列です。

例

この例では、payrollというDSNのデータベースをRAMからアンロードします。

ttUtilHandle   utilHandle;
int            rc;
rc = ttRamUnload (utilHandle, "DSN=payroll");

注意

この関数を一時データベースに対して使用すると、TimesTenはデータベースのアンロードを常に試行します。

関連項目

「ttRamGrace」
「ttRamLoad」
「ttRamPolicy」

ttRepDuplicateEx

説明

リモート・データベースのレプリカをローカル・システムに作成します。このプロセスは、受信側のローカル・システムから開始されます。受信側のローカル・システムからリモートのソース・データベースに接続され、複製処理が実行されます。

注意:

- このユーティリティには、サイトの障害からリカバリするために、アクティブ・スタンバイ・ペアのレプリケーション・スキームの一部として、障害時リカバリ(DR)読取り専用サブスクライバを作成する機能があります。詳細は、『Oracle TimesTen In-Memory Database開発者および管理者ガイド』のアクティブ・スタンバイ・ペアでの障害時リカバリ・サブスクライバの使用方法に関する説明を参照してください。

- データベースでキャッシュ・グループが使用されない場合、以降で説明する、cacheuidおよびcachepwdデータ構造体要素、TT_REPDUP_NOKEEPCG、TT_REPDUP_RECOVERINGNODE、TT_REPDUP_INITCACHEDRおよびTT_REPDUP_DEFERCACHEUPDATEの各フラグ値は関連しません。

- このユーティリティのパラメータであるttRepDuplicateExArg構造体にあるlocalIPおよびremoteIPという要素を使用すると、使用するローカル・ネットワーク・インタフェース、使用するリモート・ネットワーク・インタフェース、またはこの両方をオプションで指定できます。

必要な権限

ttRepDuplicateExがコールされる受信側ローカル・データベースのインスタンス管理者、およびリモートのソース・データベースのADMIN権限を持つユーザーが必要です。必要に応じて、リモートのソース・ストアに内部ユーザーを作成します。

また、ttRepDuplicateExを実行するには、次の要件に注意してください。

- 受信側ローカル・データベースのインスタンス管理者のオペレーティング・システム・ユーザー名は、リモートのソース・データベースのインスタンス管理者のオペレーティング・システム・ユーザー名と同じである必要があります。

- ttRepDuplicateExが呼び出される場合、uidおよびpwdデータ構造体要素で、リモートのソース・データベースでADMIN権限を持つユーザーのユーザー名とパスワードを指定する必要があります。このユーザー名は、複製処理を実行するためにリモートのソース・データベースに接続する場合に使用されます。

構文

ttRepDuplicateEx (ttUtilHandle handle,
const char* destConnStr,
const char* srcDatabase,
const char* remoteHost,
ttRepDuplicateExArg* arg
)
typedef struct
{
unsigned int size; /*set to size of(ttRepDuplicateExArg) */
unsigned int flags;
const char* uid;
const char* pwd;
const char* pwdcrypt;
const char* cacheuid;
const char* cachepwd;
const char* localHost;
int truncListLen;
const char** truncList;
int dropListLen;
const char** dropList;
int maxkbytesPerSec;
int remoteDaemonPort;
int nThreads4initDR;
const char* localIP
const char* remoteIP
int crsManaged;
/*new struct elements can only be added here at the end */
} ttRepDuplicateExArg

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

destConnStr

const char*

これは、リモート・データベースのレプリカとして作成するローカル・データベースの接続文字列を指定する、空文字で終了する文字列です。

srcDatabase

const char*

これは、リモートのソース・データベース名を指定する、空文字で終了する文字列です。この名前は、データベース・パス名の最後の部分です。

remoteHost

const char*

これは、リモートのソース・データベースが配置されているシステムのTCP/IPホスト名を指定する、空文字で終了する文字列です。

arg

ttRepDuplicateExArg*

これは、必要なttRepDuplicateEx引数が含まれている構造体のアドレスです。NULLがargに対して渡される場合、またはarg ->sizeの値が無効な場合は、TimesTenによってエラー12230(「invalid argument value」)およびTTUTIL_ERRORが返されます。

構造体要素

ttRepDuplicateExArg構造体には、次の要素があります。

要素

型

説明

size

unsigned int

サイズ
これは、最大(ttRepDuplicateExArg)のサイズまで設定する必要があります。

フラグ

unsigned int

フラグ値の表のリストから選択される値のビット単位の共用体

uid

const char*

リモートのソース・データベースでADMIN権限を持つユーザーのユーザー名
このユーザー名は、複製処理を実行するためにリモートのソース・データベースに接続する場合に使用されます。

pwd

const char*

ユーザーIDに関連付けられているパスワード

pwdcrypt

const char*

ユーザーIDに関連付けられている暗号化されたパスワード

cacheuid

const char*

TimesTen Cache管理ユーザーID

cachepwd

const char*

TimesTen Cache管理ユーザー・パスワード

localHost

const char*

ローカル・システムのTCP/IPホスト名を指定する、空文字で終了する文字列
remoteRepStartがTT_FALSEの場合、この要素は無視されます。これによってローカル・ホストは明示的に識別されます。このパラメータはNULLにでき、IPアドレスなどの標準でない名前をローカル・ホストに使用する場合に有効です。

truncListLen

int

truncListの要素の数

truncList

const char**

複製後に切り捨てるレプリケーションされていない表のリスト

dropListLen

int

dropListの要素の数

dropList

const char**

複製処理後に削除するレプリケーションされていない表のリスト

maxkbytesPerSec

int

最大キロバイト数/秒
これを0(ゼロ)以外の値に設定すると、複製処理でデータがmaxkbytesPerSec(KB/秒)を超えてネットワークに送信されないように指定されます。0(ゼロ)または負の値に設定すると、複製処理で帯域幅の制限が試行されないように指定されます。

remoteDaemonPort

int

リモート・デーモン・ポート
これを0に設定すると、ターゲット・データベースのデーモン・ポート番号には、ソース・データベース上のデーモンに使用されたポート番号が設定されます。

このオプションは、自動ポート構成を使用したデータベースの複製処理では使用できません。

nThreads4initDR

int

初期化のスレッドの数
障害時リカバリ・サブスクライバの場合、これによって障害時リカバリ・サイトでOracle Databaseの初期化に使用されるスレッドの数が決定します。

TimesTenデータベースが障害時リカバリ・システムにコピーされた後、Oracle Database表が切り捨てられ、TimesTenキャッシュ・グループのデータが障害時リカバリ・システム上のOracle Databaseにコピーされます。

次のTT_REPDUP_INITCACHEDRフラグも参照してください。

localIP

const char*

複製操作に使用するローカル・ネットワーク・インタフェースのエイリアスまたはIPアドレス(IPv4またはIPv6)を指定する、NULLで終わる文字列。ローカル・ネットワーク・インタフェースを指定しない場合は、これをNULLに設定します。この場合、互換性のあるインタフェースは使用できます。

remoteIP

const char*

複製操作のために使用するリモート・ネットワーク・インタフェースのエイリアスまたはIPアドレス(IPv4またはIPv6)を指定する、NULLで終わる文字列。リモート・ネットワーク・インタフェースを指定しない場合は、これをNULLに設定します。この場合、互換性のあるインタフェースは使用できます。
注意: localIPとremoteIPの両方を指定することも、いずれかを使用することも、またはいずれも指定しないこともできます。

crsManaged

int

内部で使用
0(ゼロ)(デフォルト)に設定する必要があります。

ttRepDuplicateExArg flags要素は、次の値で構成されています。

値

説明

TT_REPDUP_NOFLAGS

フラグがないことを示します。

TT_REPDUP_COMPRESS

複製処理に対して、ネットワークを介して送信されるデータの圧縮を有効にします。

TT_REPDUP_REPSTART

ttRepDuplicateExに対して、リモート・データベースがネットワークを介してコピーされる前に、リモート・データベースの(ローカル・データベースに対する)レプリケーションの状態をstartに設定するように指示します。これによって、複製処理の後で行われたすべての更新が、リモート・データベースから新しく作成またはリストアされたローカル・データベースにレプリケートされます。

TT_REPDUP_RAMLOAD

複製処理の完了時に、メモリー内にデータベースを保持します。データベースのRAMポリシーがmanualに変更されます。

TT_REPDUP_DELXLA

ttRepDuplicateExに対して、すべてのXLAブックマークを複製処理の一部として削除するように指示します。

TT_REPDUP_NOKEEPCG

キャッシュ・グループ定義を保持しないため、ttRepDuplicateExは、すべてのキャッシュ・グループ表を通常の表に変換します。
デフォルトでは、キャッシュ・グループ定義は保持されます。

TT_REPDUP_RECOVERINGNODE

AWTまたは自動リフレッシュ・キャッシュ・グループを含むレプリケーション・スキームの障害ノードのリカバリにttRepDuplicateExを使用すること指定します。新しいレプリケーション・スキームまたは変更したレプリケーション・スキームをノードに適用する場合、TT_REPDUP_RECOVERINGNODEは指定しないでください。ttRepDuplicateExでOracle Databaseに格納されているメタデータを更新できず、すべての増分自動リフレッシュ・キャッシュ・グループがレプリケートされる場合、メタデータへの更新は、キャッシュおよびレプリケーション・エージェントが開始されるまで、自動的に延期されます。

TT_REPDUP_DEFERCACHEUPDATE

キャッシュおよびレプリケーション・エージェントが開始され、エージェントがOracle Databaseに接続できるまで、Oracle Databaseに格納されているメタデータの更新を強制的に延期します。このオプションを使用すると、増分キャッシュ・グループの一部がレプリケートされない場合、またはttRepDuplicateExを使用して新しいレプリケーション・スキームまたは変更したレプリケーション・スキームをノードに適用する場合に、完全な自動リフレッシュが行われます。

TT_REPDUP_INITCACHEDR

障害時リカバリを初期化します。データ構造体でcacheuidおよびcachepwdも指定する必要があります。データ構造体で、nThreads4initDRも参照してください。

例

この例では、データベース・パス名がC:\dsns\payrollであるremote_payrollというリモートのTimesTen DSNのレプリカをlocal_payrollというローカルDSNに作成します。

ttUtilHandle utilHandle;
int rc;
ttRepDuplicateExArg arg;

memset(&arg, 0, sizeof(arg));
arg.size = sizeof(ttRepDuplicateExArg);
arg.flags = TT_REPDUP_REPSTART | TT_REPDUP_DELXLA;
arg.localHost = "mylocalhost";
arg.uid="myuid";
arg.pwd="mypwd";
rc=ttRepDuplicateEx(utilHandle,"DSN=local_payroll","payroll","remotehost", &arg);

関連項目

詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttRepAdmin -duplicateに関する説明を参照してください。

次の組込みプロシージャの詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』の組込みプロシージャに関する説明を参照してください。

「ttReplicationStatus」
「ttRepPolicySet」
「ttRepStop」
「ttRepSubscriberStateSet」
「ttRepSyncGet」
「ttRepSyncSet」

ttRestore

説明

ttBackup C関数またはttBackupユーティリティを使用して作成したバックアップから、接続文字列で指定したデータベースをリストアします。データベースがすでに存在している場合、ttRestoreはデータベースを上書きしません。

TimesTenのバックアップとリストア機能の概要は、『Oracle TimesTen In-Memory Databaseインストレーション・ガイド』の移行、バックアップおよびリストアに関する説明を参照してください。

必要な権限

インスタンス管理者

構文

ttRestore (ttUtilHandle handle, const char* connStr,
ttRestoreType type, const char* backupDir,
const char* baseName, ttUtFileHandle stream,
unsigned intflags)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

connStr

const char*

これは、リストアするデータベースについて記述する接続文字列を指定する、空文字で終了する文字列です。

type

ttRestoreType

ファイル・バックアップまたはストリーム・バックアップのどちらからデータベースをリストアするかを指定します。有効な値は、次のとおりです。

- TT_RESTORE_FILE: backupDirおよびbaseNameパラメータで指定されたバックアップ・パスにあるファイル・バックアップから、データベースをリストアします。

- TT_RESTORE_STREAM: 指定したストリームから読み取られたストリーム・バックアップから、データベースをリストアします。

backupDir

const char*

TT_RESTORE_FILEの場合、バックアップ・ファイルが保存されるディレクトリを指定します。
TT_RESTORE_STREAMの場合、このパラメータは無視されます。

baseName

const char*

TT_RESTORE_FILEの場合、backupDirパラメータで指定されたバックアップ・ディレクトリにあるバックアップ・ファイルのファイル接頭辞を指定します。
NULLを指定すると、バックアップ・ファイルのファイル接頭辞には、データベースのODBC定義に設定されたDataStore属性のファイル名部分が適用されます。

TT_RESTORE_STREAMの場合、このパラメータは無視されます。

stream

ttUtFileHandle

TT_RESTORE_STREAMの場合、バックアップを読み取るストリームを指定します。
UNIXの場合は、read(2)を使用して読み込むことができる整数ファイル記述子です。0(ゼロ)を渡すと、stdinからバックアップが読み取られます。

Windowsの場合は、ReadFileを使用して読み込むことができるハンドルです。GetStdHandle(STD_INPUT_HANDLE)の結果を渡すと、標準入力から読み取られます。

TT_RESTORE_FILEの場合、このパラメータは無視されます。アプリケーションで、このパラメータに対してTTUTIL_INVALID_FILE_HANDLEを渡すことができます。

フラグ

unsigned int

これは、将来使用するために予約されています。0(ゼロ)に設定します。

例

この例では、payrollというDSNのデータベースをC:\backupからリストアします。

ttUtilHandle   utilHandle;
int            rc;

rc = ttRestore (utilHandle, "DSN=payroll", TT_RESTORE_FILE,
"c:\\backup", NULL, TTUTIL_INVALID_FILE_HANDLE, 0);

関連項目

ttBackup
『Oracle TimesTen In-Memory Databaseリファレンス』のttBackupおよびttRestoreユーティリティに関する説明

ttUtilAllocEnv

説明

TimesTenユーティリティ・ライブラリ環境ハンドルにメモリーを割り当て、アプリケーションで使用されるTimesTenユーティリティ・ライブラリ・インタフェースを初期化します。アプリケーションでは、他のすべてのTimesTenユーティリティ・ライブラリ関数より前に、ttUtilAllocEnvをコールする必要があります。また、TimesTenユーティリティ・ライブラリ・インタフェースを使用して処理を行う場合、アプリケーションは、ttUtilFreeEnvをコールする必要があります。

必要な権限

ありません。

構文

ttUtilAllocEnv (ttUtilHandle* handle_ptr, char* errBuff,
unsigned int buffLen, unsigned int* errLen)

パラメータ

パラメータ

型

説明

handle_ptr

ttUtilHandle*

TimesTenユーティリティ・ライブラリ環境ハンドルが返される記憶域へのポインタを指定します。

errBuff

char*

これは、エラー・メッセージがある場合に返される、ユーザーが割り当てるバッファです。返されるエラー・メッセージは、空文字で終了する文字列です。エラー・メッセージは、その長さがbuffLen-1を超えると、buffLen-1に切り捨てられます。このパラメータがNULLの場合、buffLenは無視され、TimesTenはコール元のアプリケーションにエラー・メッセージを返しません。

buffLen

unsigned int

バッファerrBuffのサイズを指定します。このパラメータが0(ゼロ)の場合、TimesTenはコール元のアプリケーションにエラー・メッセージを返しません。

errLen

unsigned int*

これは、エラー・メッセージの実際の長さが返される、符号なし整数へのポインタです。NULLの場合、このパラメータは無視されます。

リターン・コード

このユーティリティは、ttutillib.hで定義されている次のコードを返します。

コード

説明

TTUTIL_SUCCESS

成功時に返します。

これ以外の場合、tt_errCode.hに定義されているTimesTen固有のエラー・メッセージおよび対応するエラー・メッセージが、コール元によって提供されるバッファに返されます。

例

この例では、utilHandleという名前を使用して、TimesTenユーティリティ・ライブラリ環境ハンドルを割り当てて初期化します。

char           errBuff [256];
int            rc;
ttUtilHandle   utilHandle;

rc = ttUtilAllocEnv (&utilHandle, errBuff, sizeof(errBuff), NULL);

関連項目

「ttUtilFreeEnv」
「ttUtilGetError」
「ttUtilGetErrorCount」

ttUtilFreeEnv

説明

TimesTenユーティリティ・ライブラリ環境ハンドルに関連付けられているメモリーを解放します。

アプリケーションでは、他のすべてのTimesTenユーティリティ・ライブラリ関数より前に、ttUtilAllocEnvをコールする必要があります。また、TimesTenユーティリティ・ライブラリ・インタフェースを使用して処理を行う場合、アプリケーションは、ttUtilFreeEnvをコールする必要があります。

必要な権限

ありません。

構文

ttUtilFreeEnv (ttUtilHandle handle, char* errBuff,
unsigned int buffLen, unsigned int* errLen)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

errBuff

char*

これは、エラー・メッセージが返される、ユーザーが割り当てるバッファです。返されるエラー・メッセージは、空文字で終了する文字列です。エラー・メッセージは、その長さがbuffLen-1を超えると、buffLen-1に切り捨てられます。このパラメータがNULLの場合、buffLenは無視され、TimesTenはコール元のアプリケーションにエラー・メッセージを返しません。

buffLen

unsigned int

バッファerrBuffのサイズを指定します。このパラメータが0(ゼロ)の場合、TimesTenはコール元のアプリケーションにエラー・メッセージを返しません。

errLen

unsigned int*

これは、エラー・メッセージの実際の長さが返される、符号なし整数へのポインタです。NULLの場合、このパラメータは無視されます。

リターン・コード

このユーティリティは、ttutillib.hで定義されている次のコードを返します。

コード

説明

TTUTIL_SUCCESS

成功時に返します。

TTUTIL_INVALID_HANDLE

無効なユーティリティ・ライブラリ・ハンドルが指定されている場合に返します。

これ以外の場合、tt_errCode.hに定義されているTimesTen固有のエラー・メッセージおよび対応するエラー・メッセージが、コール元によって提供されるバッファに返されます。

例

この例では、utilHandleというTimesTenユーティリティ・ライブラリ環境ハンドルを解放します。

char           errBuff [256];
int            rc;
ttUtilHandle   utilHandle;

rc = ttUtilFreeEnv (utilHandle, errBuff, sizeof(errBuff), NULL);

関連項目

「ttUtilAllocEnv」
「ttUtilGetError」
「ttUtilGetErrorCount」

ttUtilGetError

説明

TimesTen Cユーティリティ・ライブラリ関数(ttUtilAllocEnvおよびttUtilFreeEnvを除く)への最後のコールによって生成されたエラーおよび警告を取得します。

必要な権限

ありません。

構文

ttUtilGetError (ttUtilHandle handle, unsigned int errIndex,
unsigned int* retCode, ttUtilErrType* retType,
char* errbuff, unsigned int buffLen,
unsigned int* errLen)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

errIndex

unsigned int

TimesTenユーティリティ・ライブラリ・エラー配列から取得するエラーまたは警告レコードを指定します。有効な値は次のとおりです。

- 0: ユーティリティ・ライブラリ・エラー配列から次のレコードを取得します。

- 1...n: ユーティリティ・ライブラリ・エラー配列から特定のレコードを取得しますが、ここで、nはttUtilGetErrorCountコールによって返されるエラー・カウントです。

retCode

unsigned int*

tt_errCode.hで定義されているTimesTen固有のエラー・コードまたは警告コードを返します。

retType

ttUtilErrType*

返されたメッセージがエラーまたは警告のいずれであるかを示します。有効な戻り値は、次のとおりです。

- TTUTIL_ERROR

- TTUTIL_WARNING

errBuff

char*

これは、エラー・メッセージがある場合に返される、ユーザーが割り当てるバッファです。返されるエラー・メッセージは、空文字で終了する文字列です。エラー・メッセージは、その長さがbuffLen-1を超えると、buffLen-1に切り捨てられます。このパラメータがNULLの場合、buffLenは無視され、TimesTenはコール元のアプリケーションにエラー・メッセージを返しません。

buffLen

unsigned int

バッファerrBuffのサイズを指定します。このパラメータが0(ゼロ)の場合、TimesTenはコール元のアプリケーションにエラー・メッセージを返しません。

errLen

unsigned int*

エラー・メッセージの実際の長さが返される、符号なし整数へのポインタ。NULLの場合、TimesTenではこのパラメータは無視されます。

リターン・コード

このユーティリティは、ttutillib.hで定義されている次のコードを返します。

コード

説明

TTUTIL_SUCCESS

成功時に返します。

TTUTIL_INVALID_HANDLE

無効なユーティリティ・ライブラリ・ハンドルが指定されている場合に返します。

TTUTIL_NODATA

エラー情報も警告情報も取得されない場合に返します。

例

この例では、payrollというDSNに対して、ttDestroyDataStoreをコールした後にすべてのエラー情報または警告情報を取得します。

char            errBuff[256];
int             rc;
unsigned int    retCode;
ttUtilErrType   retType;
ttUtilHandle    utilHandle;

rc = ttDestroyDataStore (utilHandle, "DSN=PAYROLL", 30);
if ((rc == TTUTIL_SUCCESS)
printf ("Datastore payroll successfully destroyed.\n");
else if (rc == TTUTIL_INVALID_HANDLE)
printf ("TimesTen utility library handle is invalid.\n");
else
while ((rc = ttUtilGetError (utilHandle, 0,
&retCode, &retType, errBuff, sizeof (errBuff),
NULL)) != TTUTIL_NODATA)
{
...
...
}

注意

各TimesTen C関数は、アプリケーションからの1回のコールで、複数のエラーおよび警告を生成する可能性があります。これらのエラーおよび警告のすべてを取得するには、TTUTIL_NODATAが返されるまで、アプリケーションでttUtilGetErrorを繰り返しコールする必要があります。

関連項目

「ttUtilAllocEnv」
「ttUtilFreeEnv」
「ttUtilGetErrorCount」

ttUtilGetErrorCount

説明

TimesTen Cユーティリティ・ライブラリ関数(ttUtilAllocEnvおよびttUtilFreeEnvを除く)への最後のコールによって生成されたエラーおよび警告の数を取得します。これらの各関数は、アプリケーションからの1回のコールで、複数のエラーおよび警告を生成する可能性があります。これらのエラーおよび警告のすべてを取得するには、TTUTIL_NODATAが返されるまで、アプリケーションでttUtilGetErrorを繰り返しコールする必要があります。

必要な権限

ありません。

構文

ttUtilGetErrorCount (ttUtilHandle handle,
unsigned int* errCount)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

errCount

unsigned int*

TimesTenユーティリティ・ライブラリへの最後のコール(ttUtilAllocEnvおよびttUtilFreeEnvを除く)によって生成されたエラーおよび警告の数を示します。

リターン・コード

このユーティリティは、ttutillib.hで定義されている次のコードを返します。

コード

説明

TTUTIL_SUCCESS

成功時に返します。

TTUTIL_INVALID_HANDLE

無効なユーティリティ・ライブラリ・ハンドルが指定されている場合に返します。

例

この例では、payrollというDSNに対してttDestroyDataStoreをコールした後に、エラーおよび警告のカウント情報を取得します。

int            rc;
unsigned int   errCount;
ttUtilHandle   utilHandle;

rc = ttDestroyDataStore (utilHandle, "DSN=payroll", 30);
if (rc == TTUTIL_SUCCESS)
printf ("Datastore payroll successfully destroyed.\n")

else if (rc == TTUTIL_INVALID_HANDLE)
printf ("TimesTen utility library handle is invalid.\n");
else
{
rc = ttUtilGetErrorCount(utilHandle, &errCount);
...
...
}

注意

各TimesTenユーティリティ・ライブラリ関数は、アプリケーションからの1回のコールで、複数のエラーおよび警告を生成する可能性があります。これらのエラーおよび警告のすべてを取得するには、TTUTIL_NODATAが返されるまで、アプリケーションでttUtilGetErrorを繰り返しコールする必要があります。

関連項目

「ttUtilAllocEnv」
「ttUtilFreeEnv」
「ttUtilGetError」

ttXactIdRollback

説明

指定したトランザクションIDによって示されたトランザクションをロールバックします。ttXactIdRollbackの対象ユーザーは、ttXactAdminユーティリティです。ただし、他のスレッドの処理をロールバックできるスレッドを持つプログラムでは、処理を開始する前にそれらのスレッドでttXactIdGet組込みプロシージャをコールし、トランザクションをロールバックするスレッドによって認識される場所にその結果を配置する必要があります。(『Oracle TimesTen In-Memory Databaseリファレンス』のttXactIdGetに関する説明を参照してください。)

必要な権限

ADMIN

構文

ttXactIdRollback (ttUtilHandle handle, const char* connStr,
const char* xactId)

パラメータ

パラメータ

型

説明

handle

ttUtilHandle

ttUtilAllocEnvを使用して割り当てられるTimesTenユーティリティ・ライブラリ環境ハンドルを指定します。

connStr

const char**

ロールバックするトランザクションが含まれているデータベースの接続文字列を指定します。

xactId

const char*

ロールバックするトランザクションのトランザクションIDを示します。

例

この例では、payrollというデータベースでIDが3.4567のトランザクションをロールバックします。

char            errBuff [256];
int             rc;
unsigned int    retCode;
ttUtilErrType   retType;
ttUtilHandle    utilHandle;
...
rc = ttXactIdRollback (utilHandle, "DSN=payroll", "3.4567");
if (rc == TTUTIL_SUCCESS)
printf ("Transaction ID successfully rolled back.\n");
else if (rc == TTUTIL_INVALID_HANDLE)
printf ("TimesTen utility library handle is invalid.\n");
else
while ((rc = ttUtilGetError (utilHandle, 0, &retCode,
&retType, errBuff, sizeof (errBuff), NULL)) != TTUTIL_NODATA)
{
...
}

9 XLAリファレンス

この章では、第5章「XLAおよびTimesTenイベント管理」で説明したトランザクション・ログAPI(XLA)のリファレンス情報を示します。内容は次のとおりです。

- XLA関数について

- カテゴリ別のXLA関数の概要

- XLA関数リファレンス

- XLAレプリケーション関数参照

- XLAで使用されるCデータ構造体

XLA関数について

この項では、XLA関数に関する全般情報について説明します。

リターン・コードについて

この章で説明するすべてのXLA API関数は、SQLRETURN型の値を返しますが、この値は、ODBCによって次のいずれかの値になるように定義されています。

- SQL_SUCCESS

- SQL_SUCCESS_WITH_INFO

- SQL_NO_DATA_FOUND

- SQL_ERROR

XLAエラーの処理方法については、「XLAエラーの処理」を参照してください。

パラメータ・タイプ(入力、出力、入力/出力)について

関数の説明では、次のことに注意してください。

- 特に示されていないかぎり、すべてのパラメータは入力専用です。

- 出力パラメータにはOUTという接頭辞が付いています。

- 入力/出力パラメータにはIN OUTという接頭辞が付いています。

関数による出力結果について

このAPIのほとんどのルーチンは、結果をアプリケーション・バッファにコピーします。結果が含まれているバッファへのポインタを生成する一部のルーチンは、同じXLAハンドルを使用した次のコールが実行されるまでのみ有効性が保証されます。

このルールには次の例外があります。

- 診断情報を提供するttXlaError関数へのコール間では、バッファは有効なままです。

- ttXlaNextUpdateによって返された結果は、次にttXlaNextUpdateをコールするまで有効なままです。

- ttXlaAcknowledgeの場合、アプリケーションでバッファへのアクセスを長時間維持する必要がある場合は、XLAによって返されるバッファの情報をアプリケーション専用のバッファにコピーする必要があります。

実際の列値を除き、XLA内の文字列値は空文字で終了します。固定長のCHAR列は、その長さに合せて空白が埋め込まれます。VARCHAR列は、長さが明示的にエンコードされています。

XLAは、32ビットおよび64ビットの両方のプラットフォームに同じデータ構造を使用します。SQLUINTEGERおよびSQLUBIGINT型を使用して、32ビットおよび64ビットの整数が明示的に参照されます。各SQLUINTEGER値が4バイト境界、各SQLUBIGINT値が8バイト境界に存在するように型定義に入力することによって、位置合せおよび埋込みの問題に対処します。他のTimesTenデータ型の記憶域要件については、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』の行の理解に関する項を参照してください。

必要な権限について

XLA機能に対するTimesTenアクセス制御機能の影響については、「アクセス制御がXLAに与える影響」を参照してください。XLA機能の実行には、システム権限XLAが必要になります。

カテゴリ別のXLA関数の概要

TimesTen XLAは、データベースへの更新を検出するために使用したり、独自のレプリケーション・ソリューションを構築するツールキットとして使用できます(第5章「XLAおよびTimesTenイベント管理」を参照)。

この項では、XLA関数をその使用方法を基準に分類し、各関数について簡単に説明します。次のカテゴリがあります。

- XLAコア関数

- XLAデータ型変換関数

- XLAレプリケーション関数

XLAコア関数

次の表に、すべてのXLAアプリケーションで使用可能なXLAコア関数を示しますが、データ型変換関数に関してはこの後の表に別にリストしています。

関数

説明

ttXlaAcknowledge

1つ以上のトランザクション更新レコードをトランザクション・ログから取得したことを確認します。

ttXlaClose

ttXlaPersistOpenによってオープンされたXLAハンドルをクローズします。

ttXlaConvertCharType

列データを接続キャラクタ・セットに変換します。

ttXlaDeleteBookmark

トランザクション・ログ・ブックマークを削除します。

ttXlaError

エラー情報を取得します。

ttXlaErrorRestart

エラー・スタック情報をリセットします。

ttXlaGetColumnInfo

表内のすべての列に関する情報を取得します。

ttXlaGetLSN

データベースの現在のブックマークのログ・レコード識別子を取得します。

ttXlaGetTableInfo

表に関する情報を取得します。

ttXlaGetVersion

XLAの現行のバージョンを取得します。

ttXlaNextUpdate

TimesTenから一連の更新を取得します。

ttXlaNextUpdateWait

TimesTenから一連の更新を取得します。使用可能な更新がトランザクション・ログにない場合は、指定した時間待機します。

ttXlaPersistOpen

トランザクション・ログにアクセスするためにデータベースへのハンドルを初期化します。

「ttXlaSetLSN」

データベースの現在のブックマークのログ・レコード識別子を設定します。

ttXlaSetVersion

使用するXLAのバージョンを設定します。

ttXlaTableByName

所有者および名前が指定された表のシステム表識別子およびユーザー表識別子を検出します。

ttXlaTableStatus

表のXLAステータスを設定および取得します。

ttXlaTableVersionVerify

キャッシュされた表定義が、処理中のXLAレコードと互換性があること確認します。

ttXlaVersionColumnInfo

変更更新レコードの処理を必要とする表の列に関する情報を取得します。

ttXlaVersionCompare

2つのXLAバージョンを比較します。

これらの関数の使用方法については、「XLAイベント・ハンドラ・アプリケーションの作成」を参照してください。

XLAデータ型変換関数

次の表に、データ型変換関数を示します。

関数

説明

ttXlaDateToODBCCType

TTXLA_DATE_TT値を、アプリケーションで使用可能なODBC C値に変換します。

ttXlaDecimalToCString

TTXLA_DECIMAL_TT値を、アプリケーションで使用可能な文字列に変換します。

ttXlaNumberToBigInt

TTXLA_NUMBER値を、アプリケーションで使用可能なSQLBIGINT C値に変換します。

ttXlaNumberToCString

TTXLA_NUMBER値を、アプリケーションで使用可能な文字列に変換します。

ttXlaNumberToDouble

TTXLA_NUMBER値を、アプリケーションで使用可能な長い浮動小数点数値に変換します。

ttXlaNumberToInt

TTXLA_NUMBER値を、アプリケーションで使用可能な整数に変換します。

ttXlaNumberToSmallInt

TTXLA_NUMBER値を、アプリケーションで使用可能なSQLSMALLINT C値に変換します。

ttXlaNumberToTinyInt

TTXLA_NUMBER値を、アプリケーションで使用可能なSQLCHAR C値に変換します。

ttXlaNumberToUInt

TTXLA_NUMBER値を、アプリケーションで使用可能な符号なし整数に変換します。

ttXlaOraDateToODBCTimeStamp

TTXLA_DATE値を、アプリケーションで使用可能なODBCタイムスタンプに変換します。

ttXlaOraTimeStampToODBCTimeStamp

TTXLA_TIMESTAMP値を、アプリケーションで使用可能なODBCタイムスタンプに変換します。

ttXlaRowidToCString

ROWID値を、アプリケーションで使用可能な文字列値に変換します。

ttXlaTimeToODBCCType

TTXLA_TIME値を、アプリケーションで使用可能なODBC C値に変換します。

ttXlaTimeStampToODBCCType

TTXLA_TIMESTAMP_TT値を、アプリケーションで使用可能なODBC C値に変換します。

XLAデータ型の詳細は、「XLAデータ型について」を参照してください。

XLAレプリケーション関数

『Oracle TimesTen In-Memory Database開発者および管理者ガイド』に記載されているとおり、TimesTenのレプリケーションは、ほとんどの顧客要件を満たすには十分ですが、XLA関数を使用して、1つのデータベースから別のデータベースに更新をレプリケートすることもできます。この方法で独自のレプリケーション・スキームをXLAの上に実装することはかなり困難ですが、TimesTenのレプリケーションがなんらかの理由で実行できない場合には検討できます。

次の表に、レプリケーション・メカニズムとしてXLAのみを使用する関数を示します。(これらの関数についてのリファレンス情報は、他のXLA関数に関する別の項の「XLAレプリケーション関数参照」を参照してください。)

関数

説明

ttXlaApply

XLAハンドルに関連付けられているデータベースに更新を適用します。

ttXlaCommit

トランザクションをコミットします。

ttXlaGenerateSQL

更新レコードの結果を示すSQL文を生成します。

ttXlaLookup

特定のキー値を持つ表の更新レコードを検索します。

ttXlaRollback

トランザクションをロールバックします。

ttXlaTableCheck

送信側のデータベースから受信した表記述内の指定した表が、受信側のデータベースと互換性があることを検証します。

これらの関数の使用方法については、「レプリケーション・メカニズムとしてのXLAの使用」を参照してください。

XLA関数リファレンス

この項では、XLAコア関数およびXLAデータ型変換関数のリファレンス情報を示します。関数は、アルファベット順に示されています。

注意:
レプリケーション・メカニズムとしてXLAのみで使用される関数については、別の項(「XLAレプリケーション関数参照」)を参照してください。

ttXlaAcknowledge

説明

この関数は、1つ以上のレコードがttXlaNextUpdate関数またはttXlaNextUpdateWait関数によってトランザクション・ログから読み取られたことを確認するために使用します。

この関数をコールすると、以前に返されたいずれのレコードも再読取りできないようにブックマークが再設定されます。ttXlaAcknowledgeは、メッセージが完全に処理された場合にのみコールします。

注意:

- ブックマークは、指定したハンドルに対してのみ再設定されます。システム内の他のハンドルは、以前のトランザクションにアクセス可能な場合があります。

- ブックマークは、確認する関連更新レコードがない場合でも再設定されます。

ttXlaAcknowledgeは、必要な場合にのみ使用する必要がある高コストの処理です。XLAではトランザクション・ログ・ファイルが一度に1つしかパージされないため、トランザクション・ログ・ファイルを読み取るたびにttXlaAcknowledgeを複数回コールしても、トランザクション・ログのボリュームは減少しません。新しいトランザクション・ログ・ファイルの生成を検出するには、システム表SYS.TRANSACTION_LOG_APIのブックマークのpurgeLSN(PURGELSNHIGHとPURGELSNLOWの値で示される)を調べることで、ブックマークが含まれるログ・ファイルを確認できます。その後、ttXlaAcknowledgeをコールして、古いトランザクション・ログ・ファイルをパージできます。(この表を表示するには、ADMINまたはSELECT ANY TABLE権限が必要です。)

ttXlaAcknowledgeの2番目の目的は、XLAREUSEオプションが指定されたttXlaPersistOpen関数をコールして、以前使用されたブックマークに接続する場合に確認されたレコードがXLAアプリケーションで認識されないようにすることです。ブックマークを再利用する場合、ttXlaCloseをコールする前にttXlaAcknowledgeをコールしてブックマークの位置を現在のレコードに再設定します。

この関数の使用方法については、「トランザクション・ログからの更新レコードの取得」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaAcknowledge(ttXlaHandle_h handle)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

トランザクション・ログ・ハンドル

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaAcknowledge(xlahandle);

関連項目

ttXlaNextUpdate
ttXlaNextUpdateWait

ttXlaClose

説明

ttXlaPersistOpenによってオープンされたXLAハンドルをクローズします。この関数の使用方法については、「XLAアプリケーションの終了」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaClose(ttXlaHandle_h handle)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのODBCハンドル

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

前述の例でオープンしたXLAハンドルをクローズするには、次のコールを実行します。

rc = ttXlaClose(xlahandle);

関連項目

ttXlaPersistOpen

ttXlaConvertCharType

説明

colinfoパラメータおよびtupパラメータで示されている列データを、トランザクション・ログ・ハンドルに関連付けられている接続キャラクタ・セットに変換し、結果をバッファに格納します。

必要な権限

XLA

構文

SQLRETURN ttXlaConvertCharType (ttXlaHandle_h handle,
ttXlaColDesc_t*  colinfo,
void* tup,
void* buf,
size_t buflen)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

colinfo

ttXlaColDesc_t*

列記述を保持するバッファへのポインタ

tup

void*

変換されるデータ

buf

void*

変換されたデータが格納される場所

buflen

size_t

変換されたデータが格納されるバッファのサイズ

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaDateToODBCCType

説明

TTXLA_DATE_TT値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。

この関数は、TTXLA_DATE_TTデータ型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaDateToODBCCType(void* fromData,
out DATE_STRUCT* returnData)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたDATE値へのポインタ

returnData

DATE_STRUCT*

変換された日付を保持するように割り当てられた記憶域へのポインタ

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaDecimalToCString

説明

TTXLA_DECIMAL_TT値を、アプリケーションで使用可能な文字列に変換します。scaleおよびprecisionの値は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。scaleパラメータは、小数点以下の最大桁数を指定します。DECIMAL値が1より大きい場合、precisionパラメータは小数点をはさんだ最大桁数を指定します。DECIMAL値が1より小さい場合、precisionはscaleと同じになります。

この関数は、TTXLA_DECIMAL_TT型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

この関数の使用方法については、「複合データ型の変換」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaDecimalToCString(void* fromData,
out char* returnData,
SQLSMALLINT precision,
SQLSMALLINT scale)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたDECIMAL値へのポインタ

returnData

char*

変換された文字列を保持するように割り当てられた記憶域へのポインタ

precision

SQLSMALLINT

fromDataが1より大きい場合は、小数点をはさんだ最大桁数
fromDataが1より小さい場合は、scaleと同じ

scale

SQLSMALLINT

小数点以下の最大桁数

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、ttXlaColDesc_t構造体からoffset、precisionおよびscaleの値を取得し、トランザクション・ログ・レコードに返された行からDECIMAL値(pColVal)を取得するためにoffsetを使用していると想定しています。

char decimalData[50];
static ttXlaColDesc_t colDesc[255];

rc = ttXlaDecimalToCString(pColVal, (char*)&decimalData,
colDesc->precision,
colDesc->scale);

ttXlaDeleteBookmark

説明

指定したトランザクション・ログ・ハンドルに関連付けられているブックマークを削除します。ブックマークは削除するとアクセスできなくなり、ブックマークの識別子は別のブックマークで再利用できます。ブックマークを削除すると、データベース・ハンドルとの関連が失われ、XLANONEオプションを指定して接続をオープンした場合と同じ結果になります。

ブックマークを使用している場合は、不要になるまで削除できません。

この関数の使用方法については、「ブックマークの削除」を参照してください。

注意:

- この関数をTimesTenの組込みプロシージャttXlaBookmarkDeleteと混同しないでください(『Oracle TimesTen In-Memory Databaseリファレンス』のttXlaBookmarkDeleteに関する項を参照)。

- レプリケーション・エージェントの実行中は、レプリケートされたブックマークを削除できません。

必要な権限

XLA

構文

SQLRETURN ttXlaDeleteBookmark(ttXlaHandle_h handle)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

トランザクション・ログ・ハンドル

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

xlahandleのブックマークを削除します。

rc = ttXlaDeleteBookmark(xlahandle);

関連項目

「ttXlaPersistOpen」
「ttXlaGetLSN」
「ttXlaSetLSN」

ttXlaError

説明

特定のトランザクション・ログ・ハンドルに対して以前コールした際に発生したエラーの詳細をレポートします。ttXlaErrorへの後続のコールで、複数のエラーが返される場合があります。エラー・スタックは、ttXlaError自体およびttXlaErrorRestart以外の関数をコールするたびに消去されます。

この関数の使用方法については、「XLAエラーの処理」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaError(ttXlaHandle_h handle,
out SQLINTEGER* errCode,
out char* errMessage,
SQLINTEGER maxLen,
out SQLINTEGER* retLen)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

errCode

SQLINTEGER*

errMessageバッファにコピーされるエラー・メッセージのコード

errMessage

char*

エラー・テキストが保持されるバッファ

maxLen

SQLINTEGER

errMessageバッファの最大長

retLen

SQLINTEGER*

エラー・メッセージの実際のサイズ

結果

エラー情報が返される場合はSQL_SUCCESSを返し、またはエラー・スタックにそれ以上エラーがない場合はSQL_NO_DATA_FOUNDを返します。errMessageバッファの大きさが十分でない場合、ttXlaErrorはSQL_SUCCESS_WITH_INFOを返します。

例

エラー・スタックに複数のエラーが存在する可能性があります。この例では、それらをすべて読み取る方法を示します。

char message[100];
SQLINTEGER code;

for (;;) {
rc = ttXlaError(xlahandle, &code, message, sizeof (message), &retLen);
if (rc == SQL_NO_DATA_FOUND)
break;
if (rc == SQL_ERROR) {
printf("Error in fetching error message\n");
break;
}
else {
printf("Error code %d: %s\n", code, message);
}
}

注意

複数のスレッドを使用して単一のXLA接続のTimesTenトランザクション・ログにアクセスすると、同時アクセスを制御するためのラッチが作成されます。なんらかの理由でスレッドでラッチを取得できない場合、XLA関数はSQL_INVALID_HANDLEを返します。

関連項目

ttXlaErrorRestart

ttXlaErrorRestart

説明

アプリケーションでエラーを再度読み取ることができるように、エラー・スタックをリセットします。この関数の使用方法については、「XLAエラーの処理」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaErrorRestart(ttXlaHandle_h handle)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaErrorRestart(xlahandle);

関連項目

ttXlaError

ttXlaGetColumnInfo

説明

表内のすべての列に関する情報を取得します。通常、返される列の数の出力パラメータ(nreturned)は、colinfoに返される列の数に設定されます。systemTableIDまたはuserTableIDパラメータは、目的の表について記述します。このコールは、表の定義内の変更に対してシリアライズされます。

この関数の使用方法については、「列記述の取得」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaGetColumnInfo(ttXlaHandle_h handle,
SQLUBIGINT systemTableID,
SQLUBIGINT userTableID,
out ttXlaColDesc_t* colinfo,
SQLINTEGER maxcols,
out SQLINTEGER* nreturned)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

systemTableID

SQLUBIGINT

表のシステムID

userTableID

SQLUBIGINT

表のユーザーID

colinfo

ttXlaColDesc_t*

maxcols列の個別の記述を保持できる十分な大きさのバッファへのポインタ

maxcols

SQLINTEGER

colInfoバッファに格納可能な列の最大数
この表にmaxcolsを超える列を含めると、エラーが返されます。

nreturned

SQLINTEGER*

返される列の数

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の定義を想定しています。

ttXlaColDesc_t colinfo[20];
SQLUBIGINT systemTableID, userTableID;
SQLINTEGER ncols;

システム表識別子を使用して最大20列の記述を取得するには、次のコールを実行します。

rc = ttXlaGetColumnInfo(xlahandle, systemTableID, 0, colinfo, 20, &ncols);

ユーザー表識別子も、同様に使用できます。

rc = ttXlaGetColumnInfo(xlahandle, 0, userTableID, colinfo, 20, &ncols);

返された行内の列データにアクセスする方法の詳細および例については、「ttXlaColDesc_t」を参照してください。

関連項目

「ttXlaGetTableInfo」
「ttXlaDecimalToCString」
「ttXlaDateToODBCCType」
「ttXlaTimeToODBCCType」
「ttXlaTimeStampToODBCCType」

ttXlaGetLSN

説明

トランザクション・ログ・ハンドルで指定された接続の現行読取りログ・レコード識別子を返します。この関数の使用方法については、「ブックマークの動作」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaGetLSN(ttXlaHandle_h handle,
out tt_XlaLsn_t* LSN)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

LSN

tt_XlaLsn_t*

ハンドルの現行読取りログ・レコード識別子

注意:
tt_XlaLsn_tの、特にlogFileフィールドおよびlogOffsetフィールドの使用方法が以前のリリースとは異なり、これらのフィールドが連続的に増加するLSNではなく、ログ・レコード識別子を参照する点に注意してください。「tt_XlaLsn_t」の注意を参照してください。

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、現行読取りログ・レコード識別子CurLSNを返します。

tt_XlaLsn_t CurLSN;

rc = ttXlaGetLSN(xlahandle, &CurLSN);

関連項目

「ttXlaSetLSN」

ttXlaGetTableInfo

説明

表内の行に関する情報を取得します(ttXlaTblDesc_tデータ型に関する説明を参照)。userTableIDパラメータが0(ゼロ)以外の場合は、userTableIDの値を使用して目的の表を検出します。そうでない場合は、systemTableIDの値を使用して表を検出します。両方が0(ゼロ)の場合は、エラーが返されます。記述は、出力パラメータtblinfoに格納されます。このコールは、表の定義内の変更に対してシリアライズされます。

必要な権限

XLA

構文

SQLRETURN ttXlaGetTableInfo(ttXlaHandle_h handle,
SQLUBIGINT systemTableID,
SQLUBIGINT userTableID,
out ttXlaTblDesc_t* tblinfo)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

systemTableID

SQLUBIGINT

システム表ID

userTableID

SQLUBIGINT

ユーザー表ID

tblinfo

ttXlaTblDesc_t*

行の情報

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の定義を想定しています。

ttXlaTblDesc_t tabinfo;
SQLUBIGINT systemTableID, userTableID;

システム識別子を使用して表の情報を取得するには、ttXlaTableByNameまたは他の方法を使用してシステム表識別子を検出して次のコールを実行します。

rc = ttXlaGetTableInfo(xlahandle, systemTableID, 0, &tabinfo);

また、表の情報は、ユーザー表識別子を使用して取得することもできます。

rc = ttXlaGetTableInfo(xlahandle, 0, userTableID, &tabinfo);

関連項目

ttXlaGetColumnInfo

ttXlaGetVersion

説明

この関数は、古いバージョンのXLA用に作成されたXLAアプリケーションを新しいバージョンで動作させるために、ttXlaSetVersionと組み合せて使用します。通常、configured versionが古いバージョンで、actual versionが新しいバージョンです。

この関数は、現在構成されているXLAのバージョンを取得して、configuredVersionパラメータに格納します。基礎となるXLAの実際のバージョンはactualVersionに格納されます。ttXlaSetVersionをコールしたため、コールごとにconfiguredVersionの結果が異なる場合がありますが、actualVersionの結果は同じままです。

この関数の使用方法については、「XLAの基本」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaGetVersion(ttXlaHandle_h handle,
out ttXlaVersion_t* configuredVersion,
out ttXlaVersion_t* actualVersion)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

configuredVersion

ttXlaVersion_t*

構成されているXLAのバージョン

actualVersion

ttXlaVersion_t*

XLAの実際のバージョン

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の指示を想定しています。

ttXlaVersion_t configured, actual;

現行のバージョン構成を確認するには、次のコールを実行します。

rc = ttXlaGetVersion(xlahandle, &configured, &actual);

関連項目

「ttXlaVersionCompare」
「ttXlaSetVersion」

ttXlaNextUpdate

説明

この関数は、トランザクション・ログから更新レコードの指定した最大数をフェッチし、コミットされたトランザクションに関連付けられているレコードを指定したバッファに返します。実際に返されたレコードの数が出力パラメータnreturnedに記録されます。この関数を使用するには、ブックマークがデータベース内に存在し、関数で使用する接続と関連付けられる必要があります。

ttXlaNextUpdateをコールするたびに、最後に読み取られたレコードにブックマークが再設定され、次のレコードのリストを返すためにttXlaNextUpdateへの次のコールが有効にされます。

この関数の使用方法については、「トランザクション・ログからの更新レコードの取得」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaNextUpdate(ttXlaHandle_h handle,
out ttXlaUpdateDesc_t*** records,
SQLINTEGER maxrecords,
out SQLINTEGER* nreturned)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

record

ttXlaUpdateDesc_t***

完了したトランザクション・レコードを保持するバッファ

maxrecords

SQLINTEGER

フェッチされるレコードの最大数

nreturned

SQLINTEGER*

実際に返されたレコードの数ですが、使用可能な更新データがない場合は、0(ゼロ)が返されます。

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、最大100個のレコードを取得し、各レコードが処理されるループについて記述します。

ttXlaUpdateDesc_t** records;
SQLINTEGER nreturned;
SQLINTEGER i;

rc = ttXlaNextUpdate(xlahandle, &records, 100, &nreturned);
/* Check for errors; if none, process the records */
for (i = 0; i < nreturned; i++) {
process(records[i]);
}

注意

追跡ステータスに関係なく、すべてのデータ定義文に対して更新が生成されます。また、更新はブックマークに関係付けられているすべての追跡対象表でのデータ更新処理に対して生成されます。

また、表および列に対するアプリケーション・レベルの識別子の割当て、表の追跡ステータスの変更などの特定の処理でも更新が生成されます。

関連項目

「ttXlaNextUpdateWait」
「ttXlaAcknowledge」

ttXlaNextUpdateWait

説明

これは、ttXlaNextUpdate関数と同様の処理を行いますが、使用可能なレコードがトランザクション・ログにない場合に待機する秒数を指定するパラメータsecondsがあります。実際に待機する秒数は、secondsに指定された値より最大で2秒長くなる場合があります。

「トランザクション・ログからの更新レコードの取得」も参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaNextUpdateWait(ttXlaHandle_h handle,
out ttXlaUpdateDesc_t*** records,
SQLINTEGER maxrecords,
out SQLINTEGER* nreturned,
SQLINTEGER seconds)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

record

ttXlaUpdateDesc_t***

完了したトランザクション・レコードを保持するバッファ

maxrecords

SQLINTEGER

フェッチされるレコードの最大数
注意: 有効な最大値は1000レコードです。

nreturned

SQLINTEGER*

実際に返されたレコードの数ですが、secondsの待機時間内に使用可能な更新データがない場合は、0(ゼロ)が返されます。

seconds

SQLINTEGER

ログが空の場合に待機する時間(秒)

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

最大100個のレコードを取得し、使用可能なレコードがトランザクション・ログにない場合に最大60秒待機します。

ttXlaUpdateDesc_t** records;
SQLINTEGER nreturned;
SQLINTEGER i;

rc = ttXlaNextUpdateWait(xlahandle, &records, 100, &nreturned, 60);
/* Check for errors; if none, process the records */
for (i = 0; i < nreturned; i++) {
process(records[i]);
}

関連項目

「ttXlaNextUpdate」
「ttXlaAcknowledge」

ttXlaNumberToBigInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能なSQLBIGINT値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaNumberToBigInt(void* fromData,
SQLBIGINT* bint)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたNUMBER値へのポインタ

bint

SQLBIGINT*

XLA NUMBER値から変換されたSQLBIGINT値

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaNumberToCString

説明

TTXLA_NUMBER値を、アプリケーションで使用可能な文字列に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaNumberToCString(ttXlaHandle_h handle,
void* fromData,
char* buf,
int buflen
int* reslen)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたNUMBER値へのポインタ

buf

char*

変換されたデータが格納される場所

buflen

int

変換されたデータが格納されるバッファのサイズ

reslen

int

buflenの大きさが十分であると想定される場合は、書き込まれたバイト数(十分でない場合は、書き込まれたはずのバイト数)

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaNumberToDouble

説明

TTXLA_NUMBER値を、アプリケーションで使用可能な長い浮動小数点数値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaNumberToDouble(void* fromData,
double* dbl)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたNUMBER値へのポインタ

dbl

double*

XLA NUMBER値から変換された長い浮動小数点数値

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaNumberToInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能なSQLINTEGER値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaNumberToInt(void* fromData,
SQLINTEGER* ival)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたNUMBER値へのポインタ

ival

SQLINTEGER*

XLA NUMBER値から変換されたSQLINTEGER値

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaNumberToSmallInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能なSQLSMALLINT値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaNumberToSmallInt(void* fromData,
SQLSMALLINT* smint)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたNUMBER値へのポインタ

smint

SQLSMALLINT*

XLA NUMBER値から変換されたSQLSMALLINT値

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaNumberToTinyInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能な小さい整数値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaNumberToTinyInt(void* fromData,
SQLCHAR* tiny)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたNUMBER値へのポインタ

tiny

SQLCHAR*

XLA NUMBER値から変換された小さい整数値

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaNumberToUInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能な符号なし整数値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaNumberToInt(void* fromData,
SQLUINTEGER* ival)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたNUMBER値へのポインタ

ival

SQLUINTEGER*

XLA NUMBER値から変換された整数値

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaOraDateToODBCTimeStamp

説明

TTXLA_DATE値をODBCタイムスタンプに変換します。

この関数は、TTXLA_DATE型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaOraDateToODBCTimeStamp(void* fromData,
TIMESTAMP_STRUCT* returnData)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたNUMBER値へのポインタ

returnData

TIMESTAMP_STRUCT*

XLA Oracle Database DATE値から変換されたODBCタイムスタンプ値

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaOraTimeStampToODBCTimeStamp

説明

TTXLA_TIMESTAMP値をODBCタイムスタンプに変換します。

この関数は、TTXLA_TIMESTAMP型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

構文

SQLRETURN ttXlaOraTimeStampToODBCTimeStamp(void* fromData,
TIMESTAMP_STRUCT* returnData)

必要な権限

XLA

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたNUMBER値へのポインタ

returnData

TIMESTAMP_STRUCT*

XLA Oracle Database TIMESTAMP値から変換されたODBCタイムスタンプ値

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

ttXlaPersistOpen

説明

データベースに対するトランザクション・ログ・ハンドルを初期化して、トランザクション・ログへのアクセスを有効にします。hdbcパラメータは、データベースへのODBC接続ハンドルです。ODBC接続ごとに1つのXLAハンドルのみを作成します。ODBC接続に対してXLAハンドルを作成してから、ttXlaCloseでクローズするまで、ODBC接続に対して他のODBCコールは発行しないでください。

tagは、XLAブックマークを識別する文字列です(「XLAブックマークについて」を参照)。tagでは、optionsパラメータの指定に応じて、新しいブックマーク(レプリケートされていないブックマークまたはレプリケートされたブックマーク)、またはシステムに存在するブックマークを識別できます。handleパラメータは、このコールによって初期化され、XLAに対する後続の各コールで指定する必要があります。

一部の処理は、ブックマークなしで実行できます。これらのタイプの処理を実行する場合は、XLANONEオプションを使用して、ブックマークなしでトランザクション・ログにアクセスできます。次に、ブックマークなしでは実行できない処理を示します。

- ttXlaAcknowledge

- ttXlaGetLSN

- 「ttXlaSetLSN」

- ttXlaNextUpdate

- ttXlaNextUpdateWait

複数のアプリケーションが同時にトランザクション・ログから読取りを実行できます。この関数の使用方法については、「XLAの初期化およびXLAハンドルの取得」を参照してください。

この関数が成功すると、XLAは自動コミット・モードをOFFに設定します。

この関数が失敗しても、まだハンドルを作成する場合は、メモリー・リークを防ぐためにハンドルを閉じる必要があります。

注意:
このコールによって領域が割り当てられます。終了後にttXlaCloseをコールして、領域を解放します。

必要な権限

XLA

構文

SQLRETURN ttXlaPersistOpen(SQLHDBC hdbc,
SQLCHAR* tag,
SQLUINTEGER options,
out ttXlaHandle_h* handle)

パラメータ

パラメータ

型

説明

hdbc

SQLHDBC

データベースのODBCハンドル

tag

SQLCHAR*

XLAブックマークの識別子
optionsがXLANONEに設定されている場合は、NULLを指定できます。許容最大長は31です。

options

SQLUINTEGER

ブックマーク・オプションは、次のとおりです。

- XLANONE: ブックマークなしで接続します。tagフィールドは無視されます。

- XLACREAT: 新しいレプリケートされていないブックマークを作成します。ブックマークがすでに存在する場合は失敗します。

- XLAREPL: 新しいレプリケートされたブックマークを作成します。ブックマークがすでに存在する場合は失敗します。

- XLAREUSE: 既存のブックマーク(レプリケートされていないブックマークまたはレプリケートされたブックマーク)に関連付けます。ブックマークが存在しない場合は失敗します。

handle

ttXlaHandle_h*

このコールによって返されるトランザクション・ログ・ハンドル

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、トランザクション・ログをオープンし、xlahandleというハンドルを返して、mybookmarkという新しいレプリケートされていないブックマークを作成します。

SQLHDBC hdbc;
ttXlaHandle_h xlahandle;

rc = ttXlaPersistOpen(hdbc, ( SQLCHAR*)mybookmark,
XLACREAT, &xlahandle);

または、次のように新しいレプリケートされたブックマークを作成します。

SQLHDBC hdbc;
ttXlaHandle_h xlahandle;

rc = ttXlaPersistOpen(hdbc, ( SQLCHAR*)mybookmark,
XLAREPL, &xlahandle);

注意

マルチスレッド・アプリケーションでは、スレッドごとに別々のXLAハンドルを作成する必要があります。複数のスレッドで同じXLAハンドルを使用する必要がある場合は、1つのスレッドのみが一度に1つのXLA処理を実行できるように、mutexを使用してそのXLAハンドルへのスレッド・アクセスをシリアライズします。

関連項目

「ttXlaClose」
「ttXlaDeleteBookmark」
「ttXlaGetLSN」
「ttXlaSetLSN」

ttXlaRowidToCString

説明

ROWID値を、アプリケーションで使用可能な文字列値に変換します。

必要な権限

XLA

構文

SQLRETURN ttXlaRowidToCString(void* fromData, char* buf, int buflen)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたROWID値へのポインタ

buf

char*

変換された文字列を保持するように割り当てられた記憶域へのポインタ

buflen

int

変換された文字列の長さ

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

char charbuf[18];
void* rowiddata;
/* ... */
rc = ttXlaRowidToCString(rowiddata, charbuf, sizeof(charbuf));

ttXlaSetLSN

説明

トランザクション・ログ・ハンドルで指定されたデータベースの現行読取りログ・レコード識別子を設定します。指定するLSNの値が、ttXlaGetLSNから返されるはずです。ユーザーが作成した値および現在のブックマークの初期読取りログ・レコード識別子より小さい値にはなりません。

この関数の使用方法については、「XLAブックマークについて」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaSetLSN(ttXlaHandle_h handle,
tt_XlaLsn_t* LSN)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

LSN

tt_XlaLsn_t*

ハンドルの新しいログ・レコード識別子

注意:
tt_XlaLsn_tの、特にlogFileフィールドおよびlogOffsetフィールドの使用方法が以前のリリースとは異なり、これらのフィールドが連続的に増加するLSNではなく、ログ・レコード識別子を参照する点に注意してください。「tt_XlaLsn_t」の注意を参照してください。

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、現行読取りログ・レコード識別子をCurLSNに設定します。

tt_XlaLsn_t CurLSN;

rc = ttXlaSetLSN(xlahandle, &CurLSN);

関連項目

ttXlaGetLSN

ttXlaSetVersion

説明

アプリケーションで使用されるXLAのバージョンを設定します。このバージョンは、ttXlaGetVersionまたは以前のバージョンで返されるバージョンと同じである必要があります。

この関数の使用方法については、「XLAの基本」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaSetVersion(ttXlaHandle_h handle,
ttXlaVersion_t* version)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

version

ttXlaVersion_t*

必要なXLAのバージョン

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

構成されているバージョンをrequestedVersionで指定された値に設定するには、次のコールを実行します。

rc = ttXlaSetVersion(xlahandle, &requestedVersion);

関連項目

「ttXlaVersionCompare」
ttXlaGetVersion」

ttXlaTableByName

説明

表またはビューの所有者および名前を指定して、表またはマテリアライズド・ビューのシステム表識別子およびユーザー表識別子を検出します。この関数の使用方法については、「更新を監視する表の指定」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaTableByName(ttXlaHandle_h handle,
char* owner,
char* name,
out SQLUBIGINT* sysTableID,
out SQLUBIGINT* userTableID)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

owner

char*

表またはビューの所有者の文字列

name

char*

表またはビューの名前

sysTableID

SQLUBIGINT*

システム表ID

userTableID

SQLUBIGINT*

ユーザー表ID

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

表PURCHASING.INVOICESに関連付けられているシステム表IDおよびユーザー表IDを取得するには、次のコールを実行します。

SQLUBIGINT sysTableID;
SQLUBIGINT userTableID;

rc = ttXlaTableByName(xlahandle, "PURCHASING", "INVOICES",
&sysTableID, &userTableID);

関連項目

ttXlaTableStatus

ttXlaTableStatus

説明

表の更新ステータスを返します。表は、ユーザーID(userTableID)またはシステムID(systemTableID)のいずれかで識別します。userTableIDが0(ゼロ)以外の場合は、userTableIDの値を使用して表が検出されます。そうでない場合は、systemTableIDが使用されます。両方が0(ゼロ)の場合は、エラーが返されます。

newstatusに値を指定すると、更新ステータスが*newstatusに設定されます。ステータスが0(ゼロ)以外の場合は、systemTableIDで指定された表がXLAで使用可能であることを意味します。0(ゼロ)の場合は、表が追跡されないことを意味します。表の更新ステータスへの変更は、すぐに有効になります。

更新が実行された時点で表の更新追跡が有効になっていた場合にのみ、表への更新が追跡されます。このコールは、基礎となる表への更新に対してシリアライズされます。このため、表を更新するトランザクションは、表のステータスが変更される完全前または完全後に実行されます。

ttXlaTableStatusを使用するには、ユーザーはブックマークに接続する必要があります。この関数では、挿入、更新および削除を、表にサブスクライブしたブックマークにのみレポートします。DDLイベントがすべてのブックマークにレポートされます。DDLイベントには、CREATAB、DROPTAB、CREAIND、DROPIND、CREATVIEW、DROPVIEW、CREATSEQ、DROPSEQ、CREATSYN、DROPSYN、ADDCOLS、DRPCOLS、TRUNCATE、SETTBL1およびSETCOL1トランザクションが含まれています。これらのイベント・タイプの詳細は、「ttXlaUpdateDesc_t」を参照してください。

この関数の使用方法については、「更新を監視する表の指定」を参照してください。

注意:
XLAを介して追跡される表へのDML更新では、ttXlaTableStatusの実行を妨げません。ただし、追跡される表へのDDL更新ではSYS.TABLESがロックされるため、SYS.TABLESに対するシリアライズ可能分離レベルでのttXlaTableStatusの実行が遅延します。

必要な権限

XLA

構文

SQLRETURN ttXlaTableStatus(ttXlaHandle_h handle,
SQLUBIGINT systemTableID,
SQLUBIGINT userTableID,
out SQLINTEGER* oldstatus,
SQLINTEGER* newstatus)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

systemTableID

SQLUBIGINT

表のシステムID

userTableID

SQLUBIGINT

表のユーザーID

oldstatus

SQLINTEGER*

XLAの古いステータス:

- 1: On

- 0: Off

newstatus

SQLINTEGER*

XLAの新しいステータス:

- 1: On

- 0: Off

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

次の例では、ttXlaTableByNameまたは他のなんらかの方法を使用して、システム表識別子またはユーザー表識別子が検出されていることを想定しています。

この例では、次の宣言を想定しています。

SQLUBIGINT systemTableID;
SQLUBIGINT userTableID;
SQLINTEGER currentStatus, requestedStatus;

システム表識別子を指定して表のステータスを検出するには、次のコールを実行します。

/* Get system table identifier into systemTableID, then ... */
rc = ttXlaTableStatus(xlahandle, systemTableID, 0,
&currentStatus, NULL);

currentStatusの値は、表の更新追跡が有効になっている場合は0(ゼロ)以外になり、そうでない場合は0(ゼロ)になります。

システム表識別子を指定して表の更新追跡を有効にするには、次のように、リクエストするステータスを1に設定します。

requestedStatus = 1;

rc = ttXlaTableStatus(xlahandle, systemTableID, 0,
NULL, &requestedStatus);

次の例に示すように、新しい更新追跡ステータスを設定し、1回のコールで現在のステータスを取得できます。

requestedStatus = 1;

rc = ttXlaTableStatus(xlahandle, systemTableID, 0,
&currentStatus, &requestedStatus);

前述のコールでは、システム表識別子による表の更新追跡が有効になり、以前の更新追跡ステータスが変数currentStatusに取得されます。

これらのすべての例は、ユーザー表識別子を使用しても実行できます。ユーザー表識別子によって表の更新追跡ステータスを取得するには、次のコールを実行します。

/* Get system table identifier into userTableID, then ... */

rc = ttXlaTableStatus(xlahandle, 0, userTableID,
&currentStatus, NULL);

関連項目

ttXlaTableByName

ttXlaTableVersionVerify

説明

キャッシュされた表定義が、処理中のXLAレコードと互換性があること確認します。列を追加または削除するためにALTER TABLEを使用する場合のみ表定義が変更されます。

トランザクション・タイプADDCOLSおよびDRPCOLSのXLAレコードのXLAストリームを監視すると、この関数の使用のオーバーヘッドを回避できます。トランザクション・タイプADDCOLSまたはDROPCOLSのXLAレコードが発生した場合は、表および列定義をリフレッシュします。トランザクション・タイプのXLAレコードの監視の詳細は、「レコード・ヘッダーの確認および行アドレスの検出」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaTableVersionVerify(ttXlaHandle_h handle
ttXlaTblVerDesc_t* table,
ttXlaUpdateDesc_t* record
out SQLINTEGER* compat)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

table

ttXlaTblVerDesc_t*

キャッシュされた表記述

record

ttXlaUpdateDesc_t*

処理されるXLAレコード

compat

SQLINTEGER*

互換性情報を返します。

- 1: 表に互換性がある。

- 0: 表に互換性がない。

結果

キャッシュされた表定義が処理中のXLAレコードと互換性がある場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、表の互換性を確認します。

SQLINTEGER compat;
ttXlaTbVerDesc_t table;
ttXlaUpdateDesc_t* record;
/*
* Get the desired table definitions into the variable "table"
*/
rc = ttXlaTableVersionVerify(xlahandle, &table, record, &compat);
if (compat) {
/*
* Compatible
*/
}
else {
/*
* Not compatible or some other error occurred
* If not compatible, issue a call to ttXlaVersionTableInfo and
* ttXlaVersionColumnInfo to get the new definition.
*/
}

関連項目

ttXlaVersionColumnInfo
ttXlaVersionTableInfo

ttXlaTimeToODBCCType

説明

TTXLA_TIME値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。

この関数は、TTXLA_TIME型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaTimeToODBCCType (void* fromData,
out TIME_STRUCT* returnData)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたTIME値へのポインタ

returnData

TIME_STRUCT*

変換された時間を保持するように割り当てられた記憶域へのポインタ

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、トランザクション・ログ・レコードに返された行からTIME値pColValを取得するために、ttXlaColDesc_t構造体に返されたoffset値を使用していると想定しています。

TIME_STRUCT time;

rc = ttXlaTimeToODBCCType(pColVal, &time);

ttXlaTimeStampToODBCCType

説明

TTXLA_TIMSTAMP_TT値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。

この関数は、TTXLA_TIMSTAMP_TT型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

XLA

構文

SQLRETURN ttXlaTimeStampToODBCCType(void* fromData,
out TIMESTAMP_STRUCT* returnData)

パラメータ

パラメータ

型

説明

fromData

void*

トランザクション・ログから返されたTIMESTAMP値へのポインタ

returnData

TIMESTAMP_STRUCT*

変換されたタイムスタンプを保持するように割り当てられた記憶域へのポインタ

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、トランザクション・ログ・レコードに返された行からTIMESTAMP値pColValを取得するために、ttXlaColDesc_t構造体に返されたoffset値を使用していると想定しています。

TIMESTAMP_STRUCT timestamp;

rc = ttXlaTimeStampToODBCCType(pColVal, &timestamp);

ttXlaVersionColumnInfo

説明

変更更新XLAレコードの処理を必要とする表の列に関する情報を取得します。

必要な権限

XLA

構文

SQLRETURN ttXlaVersionColumnInfo(ttXlaHandle_h handle,
ttXlaUpdateDesc_t* record,
out ttXlaColDesc_t* colinfo,
SQLINTEGER maxcols,
out SQLINTEGER* nreturned)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

record

ttXlaUpdateDesc_t*

処理されるXLAレコード

colinfo

ttXlaColDesc_t*

maxcols列の記述を保持できる十分な大きさのバッファへのポインタ

maxcols

SQLINTEGER

表に含めることができる列の最大数
注意: この表にmaxcolsを超える列を含めると、エラーが返されます。

nreturned

SQLINTEGER*

返される列の数

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の定義を想定しています。

ttXlaHandle_h xlahandle
ttXlaUpdateDesc_t* record;
ttXlaColDesc_t colinfo[20];
SQLINTEGER ncols;

次のコールでは、最大20の列の記述が取得されます。

rc = ttXlaVersionColumnInfo(xlahandle, record, colinfo, 20, &ncols);

ttXlaVersionCompare

説明

2つのXLAバージョンを比較し、結果を返します。

必要な権限

XLA

構文

SQLRETURN ttXlaVersionCompare(ttXlaHandle_h handle,
ttXlaVersion_t* version1,
ttXlaVersion_t* version2,
out SQLINTEGER* comparison)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

version1

ttXlaVersion_t*

version2と比較するXLAのバージョン

version2

ttXlaVersion_t*

version1と比較するXLAのバージョン

比較

SQLINTEGER*

比較結果を返します。

- 0: version1とversion2が一致している。

- -1: version1がversion2より古い。

- +1: version1がversion2より新しい。

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

XLAのconfiguredバージョンとactualバージョンを比較するには、次のコールを実行します。

ttXlaVersion_t configured, actual;
SQLINTEGER comparision;

rc = ttXlaGetVersion (xlahandle, &configured, &actual);
rc = ttXlaVersionCompare (xlahandle, &configured, &actual,
&comparison);

注意

XLAベースのレプリケーションで2つのシステムを接続する場合は、次の手順を実行します。

1. プライマリ・サイトで、ttXlaGetVersionを使用してXLAバージョンを取得します。このバージョン情報をスタンバイ・サイトに送信します。

2. スタンバイ・サイトで、ttXlaGetVersionを使用してXLAバージョンを取得します。ttXlaVersionCompareを使用して古いバージョンを判別します。2つのサイト間で適切な処理を行うには、古いバージョン番号を使用する必要があります。ttXlaSetVersionを使用してスタンバイ・サイトで使用するインタフェースのバージョンを指定します。古いバージョン番号をプライマリ・サイトに返信します。

3. 選択したバージョンがプライマリ・サイトで受信された後、ttXlaSetVersionを使用して、使用するXLAのバージョンを指定します。

関連項目

ttXlaGetVersion
ttXlaSetVersion

ttXlaVersionTableInfo

説明

処理を必要とする変更更新レコードの表定義を取得します。表記述は、tableinfo出力パラメータに格納されます。

必要な権限

XLA

構文

SQLRETURN ttXlaVersionTableInfo(ttXlaHandle_h handle,
ttXlaUpdateDesc_t* record,
out ttXlaTblVerDesc_t* tblinfo)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

record

ttXlaUpdateDesc_t*

処理されるXLAレコード

tableinfo

ttXlaTblVerDesc_t*

表定義に関する情報

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の定義を想定しています。

ttXlaHandle_h xlahandle;
ttXlaUpdateDesc_t* record;
ttXlaTblVerDesc_t tabinfo;

次のコールでは、表定義が取得されます。

rc = ttXlaVersionTableInfo(xlahandle, record, &tabinfo);

XLAレプリケーション関数参照

『Oracle TimesTen In-Memory Database開発者および管理者ガイド』に記載されているとおり、TimesTenのレプリケーションは、ほとんどの顧客要件を満たすには十分ですが、XLA関数を使用して、1つのデータベースから別のデータベースに更新をレプリケートすることもできます。この方法で独自のレプリケーション・スキームをXLAの上に実装することはかなり困難ですが、TimesTenのレプリケーションがなんらかの理由で実行できない場合には検討できます。

この項では、レプリケーション・メカニズムとしてXLAのみを使用する関数について説明します。関数は、アルファベット順に示されています。

ttXlaApply

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

トランザクション・ログ・ハンドルに関連付けられているデータベースに更新を適用します。戻り値は、更新が成功したかどうかを示します。また、更新によって永続的な問題が発生したかどうかも示します。(更新で一時的な問題(デッドロック、タイムアウトなど)が発生したかどうかを確認するには、ttXlaErrorをコールし、エラー・コードを確認する必要があります。)

ttXlaUpdateDesc_tレコードがトランザクション・コミットの場合、基盤となるデータベース・トランザクションがコミットされます。ttXlaApplyで他のトランザクション・コミットは実行されません。パラメータtestがtrueの場合は、レコードの更新および削除のために、更新記述内の古い値がデータベースの現在の内容と比較されます。更新記述内の古い値がデータベースの対応する行と一致しない場合、この関数は更新を拒否して、sb_ErrXlaTupleMismatchエラーを返します。

この関数の使用方法については、「レプリケーション・メカニズムとしてのXLAの使用」を参照してください。

注意:
表定義が最初にトランザクション・ログに書き込まれてから変更された場合、ttXlaApplyは使用できません。文のレベルではなく、行のレベルで一意キー制約および外部キー制約がチェックされます。

必要な権限

ADMIN

ttXlaApply処理の対象となるターゲット・データベースでは、他の権限が必要になる場合があります。たとえば、ターゲット・データベースにCREATETAB(表の作成)レコードを適用するには、必要に応じて、CREATE TABLEまたはCREATE ANY TABLE権限を持つ必要があります。

構文

SQLRETURN ttXlaApply(ttXlaHandle_h handle,
ttXlaUpdateDesc_t* record,
SQLINTEGER test)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

record

ttXlaUpdateDesc_t*

SQL文を生成するトランザクション

テスト

SQLINTEGER

古い値のテスト:

- 1: テストは有効

- 0: テストは無効

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

testが1で、ttXlaApplyで更新の競合が検出されると、sb_ErrXlaTupleMismatchエラーが返されます。

例

この例では、既存のレコードの以前の値をテストせずに、更新をデータベースに適用します。

ttXlaUpdateDesc_t record;
rc = ttXlaApply(xlahandle, &record, 0);

注意

ttXlaApplyをコールすると、更新が同時トランザクションでタイムアウトまたはデッドロックする可能性があります。この場合は、アプリケーションによって、トランザクションをロールバックし、更新を再適用してください。

関連項目

ttXlaCommit
ttXlaRollback
ttXlaLookup
ttXlaTableCheck
ttXlaGenerateSQL

ttXlaCommit

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

トランザクション・ログ・ハンドルに対して適用中の現行のトランザクションをコミットします。トランザクションが完了しているかどうかに関係なく、このルーチンはトランザクションをコミットします。このルーチンをコールすると、ttXlaApplyによってレポートされた一時的なエラー(タイムアウトまたはデッドロック)に応答でき、ttXlaApplyは、エラーが発生しなければ現在のトランザクションを適用します。

この関数の使用方法については、「タイムアウトおよびデッドロックのエラーの処理」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaCommit(ttXlaHandle_h handle)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaCommit(xlahandle);

関連項目

「ttXlaApply」
「ttXlaRollback」
「ttXlaLookup」
「ttXlaTableCheck」
「ttXlaGenerateSQL」

ttXlaGenerateSQL

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

注意:
この関数は、現在はLOBロケータでは動作しません。

説明

更新レコードの結果を示すSQL DMLまたはDDL文を生成します。生成された文は、データベースには適用されません。かわりに、文は、最大サイズがmaxLenパラメータによって指定される特定のバッファに返されます。バッファの実際のサイズはactualLenによって返されます。更新および削除のレコードの場合、正しいSQLを生成するために、ttXlaGenerateSQLには、NULL値可能でない列に対する主キー索引または一意索引が必要です。

生成されたSQL文は、XLAハンドルのODBC接続に関係付けられている接続キャラクタ・セットでエンコードされます。

「TimesTen以外のデータベースへの更新のレプリケート」も参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaGenerateSQL(ttXlaHandle_h handle,
ttXlaUpdateDesc_t* record,
out char* buffer,
SQLINTEGER maxLen,
out SQLINTEGER* actualLen)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

record

ttXlaUpdateDesc_t*

SQLに変換されるレコード

buffer

char*

変換されたSQL文の場所

maxLen

SQLINTEGER

バッファの最大長(バイト)

actualLen

SQLINTEGER*

バッファの実際の長さ(バイト)

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、更新レコードによって表現されるUPDATEに相当するSQL文のテキストを生成します。

ttXlaUpdateDesc_t record;
char buffer[200];
/*
* Get the desired update record into the varable record.
*/

SQLINTEGER actualLength;

rc = ttXlaGenerateSQL(xlahandle, &record, buffer, 200,
&actualLength);

注意

ttXlaGenerateSQL関数は、削除された表、またはレコードが生成された後で変更された表に関連付けられている更新レコードに対してはSQL文を生成できません。

関連項目

「ttXlaApply」
「ttXlaCommit」
「ttXlaRollback」
「ttXlaLookup」
「ttXlaTableCheck」

ttXlaLookup

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

この関数は、keysパラメータに指定されているキー値を持つ特定の表のレコードを検索します。keysおよびresultレコードの書式は、通常の行の書式と同じです。この関数では、基礎となる表に主キーが必要です。

必要な権限

XLA

構文

SQLRETURN ttXlaLookup(ttXlaHandle_h handle,
ttXlaTableDesc_t* table,
void* keys,
out void* result,
SQLINTEGER maxsize,
out SQLINTEGER* retsize)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

table

ttXlaTblDesc_t*

検索する表

キー

void*

表に対して定義された構造内のレコード
表の主キーの一部であるキー・レコードの列のみが調べられます。

result

void*

検出されたレコードのコピー先
一致するキー列を持つレコードが存在しない場合は、エラーが返されます。

maxsize

SQLINTEGER

resultバッファに格納可能な最大レコードのサイズ

retsize

SQLINTEGER*

レコードの実際のサイズ

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、一組の整数キー値を指定してレコードを調べます。このコールの前に、目的の表がtableに記述され、キー列が設定されているレコードがkeybufferに含まれている必要があります。

char keybuffer[100];
char recbuffer[2000];
ttXlaTableDesc_t table;
SQLINTEGER recordSize;

rc = ttXlaLookup(xlahandle, &table, keybuffer, recbuffer,
sizeof (recbuffer), &recordSize);

関連項目

「ttXlaApply」
「ttXlaCommit」
「ttXlaRollback」
「ttXlaTableCheck」
「ttXlaGenerateSQL」

ttXlaRollback

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

トランザクション・ログ・ハンドルに対して適用中の現行のトランザクションをロールバックします。このルーチンをコールすると、ttXlaApplyによってレポートされた一時的なエラー(タイムアウトまたはデッドロック)に応答できます。

この関数の使用方法については、「タイムアウトおよびデッドロックのエラーの処理」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaRollback(ttXlaHandle_h handle)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaRollback(xlahandle);

関連項目

「ttXlaApply」
「ttXlaCommit」
「ttXlaLookup」
「ttXlaTableCheck」
「ttXlaGenerateSQL」

ttXlaTableCheck

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

レプリケーション・メカニズムとしてXLAを使用する場合、この関数は、マスター・データベースから受信したttXlaTblDesc_t構造体内の名前付き表が、トランザクション・ログ・ハンドルに関連付けられているサブスクライバ・データベースまたはデータベースと互換性があることを検証します。compatパラメータは、表に互換性があるかどうかを示します。

この関数の使用方法については、「データベース間での表の互換性の確認」を参照してください。

必要な権限

XLA

構文

SQLRETURN ttXlaTableCheck(ttXlaHandle_h handle,
ttXlaTblDesc_t* table,
ttXlaColDesc_t* columns,
out SQLINTEGER* compat)

パラメータ

パラメータ

型

説明

handle

ttXlaHandle_h

データベースのトランザクション・ログ・ハンドル

table

ttXlaTblDesc_t*

表記述

columns

ttXlaColDesc_t*

表の列記述

compat

SQLINTEGER*

互換性情報を返します。

- 1: 表に互換性がある。

- 0: 表に互換性がない。

結果

コールが成功した場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、表の互換性を確認します。

SQLINTEGER compat;
ttXlaTblDesc_t table;
ttXlaColDesc_t columns[20];
/*
* Get the desired table and column definitions into
* the variables "table" and "columns"
*/
rc = ttXlaTableCheck(xlahandle, &table, columns, &compat);
if (compat) {
/* Compatible */
}
else {
/*
* Not compatible or some other error occurred
*/
}

関連項目

「ttXlaApply」
「ttXlaCommit」
「ttXlaRollback」
「ttXlaLookup」
「ttXlaGenerateSQL」

XLAで使用されるCデータ構造体

この項では、この章で説明されているXLA関数で使用されるCデータ構造体について説明します。これらの構造体は、次のファイルで定義されています。

install_dir/include/tt_xla.h

XLAアプリケーションの作成時に、このファイルをインクルードする必要があります。

表9-1 Cデータ構造体の概要

Cデータ構造体

説明

ttXlaNodeHdr_t

レコード・タイプについて記述します。XLAによって返されるレコードの先頭で使用されます。

ttXlaUpdateDesc_t

更新レコードについて記述します。

ttXlaVersion_t

ttXlaGetVersionによって返されるXLAのバージョン情報について記述します。

ttXlaTblDesc_t

ttXlaGetTableInfoによって返される表情報について記述します。

ttXlaTblVerDesc_t

ttXlaVersionTableInfoによって返される表バージョンについて記述します。

ttXlaColDesc_t

ttXlaGetColumnInfoによって返される表の列情報について記述します。

tt_LSN_t

ブックマークで使用されるログ・レコード識別子について記述します。この構造体は、ttXlaUpdateDesc_t構造体によって使用されます。

tt_XlaLsn_t

XLAブックマークで使用されるログ・レコード識別子について記述します。

ttXlaNodeHdr_t

ほとんどCデータ構造体は、データのレコード・タイプおよび長さについて記述する標準ヘッダーで始まります。標準ヘッダーの型はttXlaNodeHdr_tです。

このヘッダーには、次のフィールドがあります。

フィールド

型

説明

nodeType

char

レコードのタイプ。

- TTXLANHVERSION: バージョン

- TTXLANHUPDATE: 更新

- TTXLANHTABLEDESC: 表の説明

- TTXLANHCOLDESC: 列の説明

- TTXLANHSTATUS: ステータス

- TTXLANHINVALID: 無効

byteOrder

char

レコードのバイト順序。

- 1: ビッグ・エンディアン

- 2: リトル・エンディアン

length

SQLUINTEGER

すべての添付ファイルを含むレコードの全長

ttXlaUpdateDesc_t

この構造体は、データベース内の単一行(またはタプル)への更新処理について記述します。ttXlaNextUpdateまたはttXlaNextUpdateWait関数によって返される各更新レコードは、固定長ヘッダーttXlaUpdateDesc_tで始まり、その後に0(ゼロ)から2行のデータベースからの行が続きます。行データはttXlaUpdateDesc_tヘッダーにレポートされたレコード・タイプによって異なります。

- COMMITONLYレコードに行はありません。

- INSERTTUPまたはDELETETUPには1つの行があります。

- UPDATETUPレコードには2つの行があり、更新前および更新後の行データがレポートされます。

- CREATAB、DROPTAB、CREAIND、DROPIND、CREATVIEW、DROPVIEW、CREATSEQ、DROPSEQ、CREATSYN、DROPSYN、ADDCOLSおよびDRPCOLSレコードには特別な書式行があります(「特別な更新データの書式」を参照)。

flagsフィールドは、レコード更新の特別なオプションのビットマップです。

connIDフィールドは、更新を開始したODBC接続ハンドルを識別します。この値を使用すると、更新が同一の接続から行われたかどうかを確認できます。

個別のコミットXLAレコードは、ttApplicationContextプロシージャをコールした後にXLAレコードを生成する処理が行われない場合に生成されます。ttApplicationContextプロシージャについては、「アプリケーション・コンテキストの受渡し」を参照してください。

注意

XLAは、次の通知を受信できません。

- 非マテリアライズド・ビューのCREATE VIEWまたはDROP VIEW

- 一時表のCREATE GLOBAL TEMPORARY TABLEまたはDROP TABLE

ALTER TABLE処理で生成可能なXLAレコードは、次のタイプのみです。

- ADDCOLSまたはDRPCOLS(列を追加または削除する場合)

- CREAINDまたはDROPIND(列の一意の属性を変更する場合)

順序の作成(CREATESEQ)と削除(DROPSEQ)はXLAで参照できますが、順序の増分は参照できません。

カスケード削除およびエージングによるすべての削除はXLAで参照できます。削除がカスケードによるものか、またはエージングによるものかは、flagsの値(次の表を参照)で示されます。

ttXlaUpdateDesc_tによって定義される更新ヘッダーのフィールドは、次のとおりです。

フィールド

型

説明

header

ttXlaNodeHdr_t

標準データ・ヘッダー

type

SQLUSMALLINT

レコード・タイプ。

- CREATAB: 表の作成。

- DROPTAB: 表の削除。

- CREAIND: 索引の作成。

- DROPIND: 索引の削除。

- CREATVIEW: ビューの作成。

- DROPVIEW: ビューの削除。

- CREATSEQ: 順序の作成。

- DROPSEQ: 順序の削除。

- CREATSYN: シノニムの作成。

- DROPSYN: シノニムの削除。

- ADDCOLS: 列の追加。

- DRPCOLS: 列の削除。

- TRUNCATE: 表の切捨て。

- INSERTTUP: 挿入。

- UPDATETUP: 更新。

- DELETETUP: 削除。

- COMMITONLY: コミット。

フラグ

SQLUSMALLINT

レコード更新での特別なオプション。

- TT_UPDCOMMIT: 更新レコードがトランザクションの最後のレコードであることを示します。(暗黙的コミット。)

- TT_UPDFIRST: 更新レコードがトランザクションの最初のレコードであることを示します。

- TT_UPDREPL: この更新が別のデータベースからのXLA以外のTimesTenでレプリケートされた更新の結果であったことを示します。

- TT_UPDCOLS: 最後に返された行に続く、行内の更新された列を示すリストの存在を示します。このリストは、SQLUSMALLINT値の配列で構成され、リストの最初は更新された列の数で、更新された列の列番号がそれに続きます。たとえば、1番目および3番目の列が更新された場合、この配列は、使用されたUPDATE文に応じて(2, 1, 3)、(2, 3, 1)などになります。この配列は、すべてのUPDATETUPレコードにあります。

- TT_UPDDEFAULT: 更新レコード(CREATABまたはADDCOLSのいずれか)にデフォルトの列値が含まれていることを示します。デフォルトの列は、設定されている場合、SQLUSMALLINT値の配列として示され、すべてのデフォルト値が連結された文字列がその後に続きます。配列内のSQLUSMALLINT値の数は、CREATABまたはADDCOLSレコード内の列の数と同じです。

- TT_CASCDEL: XLA更新が、カスケード削除処理の一部として生成されたことを示します。

- TT_AGING: XLA更新が、エージング処理の一部として生成されたことを示します。

特定の列の値が0(ゼロ)の場合は、その列にデフォルト値がないことを示します。0(ゼロ)以外のすべての値のデフォルト値は文字列内で連結され、デフォルト値の長さを示す配列値の順序で示されます。たとえば、デフォルト値がINTEGER型の1が含まれる列、デフォルトがない列、およびVARCHAR2(10)型のappleが含まれる列の3つの列は、(1,0,5)1appleとなります。

これらの各flagsビットの10進値は、次のとおりです。(一部のフラグ値は内部使用専用です。)

TT_UPDCOMMIT     1
TT_UPDFIRST      2
TT_UPDREPL       4
TT_UPDCOLS       8
TT_UPDDEFAULT   64
TT_CASCDEL     256
TT_AGING       512

contextOffset

SQLUINTEGER

アプリケーションによって指定されるコンテキスト値のオフセット
コンテキストがない場合、この値は0(ゼロ)です。0(ゼロ)以外の値は、XLAレコードの先頭に対するコンテキストの相対位置を示します。

connID

SQLUBIGINT

トランザクションを所有している接続ID

sysTableID

SQLUBIGINT

システムによって指定される、影響を受ける表の識別子

userTableID

SQLUBIGINT

アプリケーションによって定義される、影響を受ける表の表ID

tranID

SQLUBIGINT

システムによって指定される、読取り専用のトランザクション識別子

LSN

tt_LSN_t

診断に使用される、この処理のトランザクション・ログ・レコード識別子

tuple1

SQLUINTEGER

第1行(tuple)の長さまたは0(ゼロ)

tuple2

SQLUINTEGER

第2行(tuple)の長さまたは0(ゼロ)

注意:
tt_LSN_tの、特にlogFileフィールドおよびlogOffsetフィールドの使用方法が以前のリリースとは異なり、これらのフィールドが連続的に増加するLSNではなく、ログ・レコード識別子を参照する点に注意してください。「tt_LSN_t」の注意を参照してください。

特別な更新データの書式

ttXlaTblDesc_tヘッダーの後には、更新レコードに含まれているデータが続きます。この項では、特定のSQL処理に関連した特別な更新レコードのデータ書式について説明します。

CREATE TABLE

CREATE TABLE処理の場合、特別な行の値は、新しい表について記述するttXlaTblDesc_tレコードおよびその後に続く、各列について記述するttXlaColDesc_tレコードで構成されています。

ALTER TABLE

ALTER TABLE処理の場合、特別な行の値は、ttXlaDropTableTup_tまたはttXlaAddColumnTup_t値およびその後に続く、列について記述するttXlaColDesc_tレコードで構成されます。

ttXlaDropTableTup_t

DROP TABLE処理の場合、行の値は次のようになります。

フィールド

型

説明

tblName

char(31)

削除される表の名前

tblOwner

char(31)

削除される表の所有者

ttXlaTruncateTableTup_t

TRUNCATE TABLE処理の場合、行の値は次のようになります。

フィールド

型

説明

tblName

char(31)

切り捨てられる表の名前。

tblOwner

char(31)

切り捨てられる表の所有者

ttXlaCreateIndexTup_t

CREATE INDEX処理の場合、行の値は次のようになります。

フィールド

型

説明

tblName

char(31)

索引が定義されている表の名前。

tblOwner

char(31)

索引が定義される表の所有者

ixName

char(31)

新しい索引の名前

フラグ

char(31)

索引フラグ。

- P: 主キー

- F: 外部キー

- R: 標準

nixcols

SQLUINTEGER

索引付けされる列の数

ixColsSys

SQLUINTEGER(16)

システム番号を使用して索引付けされる列番号

ixColsUser

SQLUINTEGER(16)

ユーザー定義の列IDを使用して索引付けされる列番号

ixType

char

索引のタイプ。

- T: 範囲

- H: ハッシュ

- B: ビットマップ

ixUnique

char

索引の一意性。

- U: 一意

- N: 一意でない

ページ

SQLUINTEGER

ハッシュ索引のページ数

ttXlaDropIndexTup_t

DROP INDEX処理の場合、行の値は次のようになります。

フィールド

型

説明

tblName

char(31)

索引が削除された表の名前

tblOwner

char(31)

索引が削除された表の所有者

ixName

char(31)

削除された索引の名前

ttXlaAddColumnTup_t

ADD COLUMN処理の場合、行の値は次のようになります。

フィールド

型

説明

ncols

SQLUINTEGER

追加列の数

この特別な行の後に、新しい列について記述するttXlaColDesc_tレコードが続きます。

ttXlaDropColumnTup_t

DROP COLUMN処理の場合、行の値は次のようになります。

フィールド

型

説明

ncols

SQLUINTEGER

削除された列の数

この特別な行の後に、削除された列について記述するttXlaColDesc_tレコードの配列が続きます。

ttXlaCreateSeqTup_t

CREATE SEQUENCE処理の場合、行の値は次のようになります。

フィールド

型

説明

sqName

char(31)

順序の名前

sqOwner

char(31)

順序の所有者

cycle

char

サイクル・フラグ
順序番号ジェネレータが、最大値または最小値に達した後も番号の生成を続行するかどうかを指定します。

- 1: 生成する

- 0: 生成しない

minval

SQLBIGINT

順序の最小値

maxval

SQLBIGINT

順序の最大値

incr

SQLBIGINT

順序番号間の増分
正の値は昇順、負の値は降順を示します。降順の場合、値の範囲はmaxvalからminvalまでです。昇順の場合、値の範囲はminvalからmaxvalまでです。

ttXlaDropSeqTup_t

DROP SEQUENCE処理の場合、行の値は次のようになります。

フィールド

型

説明

sqName

char(31)

順序の名前

sqOwner

char(31)

順序の所有者

ttXlaViewDesc_t

CREATE VIEW処理の場合、行の値は次のようになります。

注意:
これは、マテリアライズド・ビューおよび非マテリアライズド・ビューのどちらにも適用されます。

フィールド

型

説明

vwName

char(31)

ビューの名前

vwOwner

char(31)

ビューの所有者

sysTableID

SQLUBIGINT

SYS.TABLESに格納されたシステム表ID

ttXlaDropViewTup_t

DROP VIEW処理の場合、行の値は次のようになります。

注意:
これは、マテリアライズド・ビューおよび非マテリアライズド・ビューのどちらにも適用されます。

フィールド

型

説明

vwName

char(31)

ビューの名前

vwOwner

char(31)

ビューの所有者

ttXlaCreateSynTup_t

CREATE SYNONYM処理の場合、行の値は次のようになります。

フィールド

型

説明

synName

char(31)

シノニムの名前

synOwner

char(31)

シノニムの所有者

objName

char(31)

シノニムが指すオブジェクトの名前

objOwner

char(31)

シノニムが指すオブジェクトの所有者

isPublic

char

シノニムがパブリックかどうかを示します。

- 1: True

- 0: False

isReplace

char

シノニムがCREATE OR REPLACEを使用して作成されたかどうかを示します。

- 1: True

- 0: False

ttXlaDropSynTup_t

DROP SYNONYM処理の場合、行の値は次のようになります。

フィールド

型

説明

synName

char(31)

シノニムの名前

synOwner

char(31)

シノニムの所有者

isPublic

char

シノニムがパブリックかどうかを示します。

- 1: True

- 0: False

ttXlaSetTableTup_t

SET TABLE ID処理の場合、更新レコードの主要部分で以前に割り当てられたアプリケーション表識別子を使用し、アプリケーション表識別子の新しい値を次の特別な行に指定するように記述されます。

フィールド

型

説明

newID

SQLUBIGINT

新しいユーザー定義の表ID

ttXlaSetColumnTup_t

SET COLUMN ID処理の場合、次の特別な行が記述されます。

フィールド

型

説明

oldUserColID

SQLUINTEGER

以前のユーザー定義の列ID値

newUserColID

SQLUINTEGER

新しいユーザー定義の列ID値

sysColID

SQLUINTEGER

システム列ID

ttXlaSetStatusTup_t

表のレプリケーション・ステータスの変更の場合、次の特別な行が記述されます。

フィールド

型

説明

oldStatus

SQLUINTEGER

以前のレプリケーション・ステータス

newStatus

SQLUINTEGER

新しいレプリケーション・ステータス

ttXlaUpdateDesc_tヘッダーの後に続く行データのアドレスの検出

更新レコードを取得する手順およびttXlaUpdateDesc_tヘッダーの内容を確認する手順の詳細は、「トランザクション・ログからの更新レコードの取得」および「レコード・ヘッダーの確認および行アドレスの検出」を参照してください。次に、これらの手順の概要を示します。

更新ヘッダーの直後に行データが続きます。行データは、ttXlaGetColumnInfoによって返されるttXlaColDesc_t構造体に指定されているオフセットとともに内部形式で格納されます。

更新ヘッダーのサイズにそのアドレスを追加して、行データのアドレスを検出することができます。

次に例を示します。

char* Row = (char*)&ttXlaUpdateDesc_t +
sizeof(ttXlaUpdateDesc_t);

UPDATETUPレコードの場合、ttXlaUpdateDesc_tヘッダーの後に2行のデータが続きます。1つ目の行には更新前のデータ、2つ目の行には更新後のデータが含まれています。

新しい行は古い行の直後に続くため、古い行の長さ(tuple1)にそのアドレスを追加して、新しい行のアドレスを計算することができます。

次に例を示します。

char* oldRow = (char*)&ttXlaUpdateDesc_t +
sizeof(ttXlaUpdateDesc_t);
char* newRow = oldRow + ttXlaUpdateDesc_t.tuple1;

返された行内の列データにアクセスする方法の詳細については、「ttXlaColDesc_t」を参照してください。

ttXlaVersion_t

XLAを将来拡張できるように、バージョン構造体ttXlaVersion_tに、現在のXLAのバージョンおよび構造体のバイト順序が記述されています。この構造体はttXlaGetVersion関数によって返されます。

この構造体には、次のフィールドがあります。

フィールド

型

説明

header

ttXlaNodeHdr_t

標準データ・ヘッダー

hardware

char(16)

ハードウェア・プラットフォームの名前

wordSize

SQLUINTEGER

システム固有のワード・サイズ(32または64ビット)

TTMajor

SQLUINTEGER

TimesTenバージョン番号

TTMinor

SQLUINTEGER

TimesTenリリース番号

TTPatch

SQLUINTEGER

TimesTenポイント・リリース番号

OS

char(16)

オペレーティング・システムの名前

OSMajor

SQLUINTEGER

オペレーティング・システムのバージョン番号

OSMinor

SQLUINTEGER

オペレーティング・システムのリリース番号

ttXlaTblDesc_t

表情報は、ttXlaTblDesc_t構造体を使用して表現されます。この構造体は、ttXlaGetTableInfo関数によって返されます。

この構造体には、次のフィールドがあります。

フィールド

型

説明

header

ttXlaNodeHdr_t

標準データ・ヘッダー

tblName

char(31)

表の名前(空文字で終了)

tblOwner

char(31)

表の所有者(空文字で終了)

sysTableID

SQLUBIGINT

一意のシステム定義表識別子

userTableId

SQLUBIGINT

ユーザー定義表識別子

columns

SQLUINTEGER

列の数

width

SQLUINTEGER

インライン行のサイズ

nPrimCols

SQLUINTEGER

プライマリ列の数

primColsSys

SQLUINTEGER(16)

システム主キー列番号

primColsUser

SQLUINTEGER(16)

ユーザー定義主キー列番号

インライン行のサイズには、すべての固定長列、NULL列フラグ、および可変長列のポインタ情報のためのスペースが含まれています。可変長列ごとに、4バイトのインライン行領域が使用されます。

表に宣言済の主キーがある場合は、次の点に注意してください。

- nPrimColsは0(ゼロ)より大きくなります。

- primColsSys配列には、最初にCREATE TABLE文で宣言した順序と同じ順序で主キーの列番号が含まれます。

- primColsUser配列には、対応するアプリケーション指定の列識別子が含まれます。

ttXlaTblVerDesc_t

このデータ構造体には、表のバージョン番号とttXlaTblDesc_tが含まれています。この構造体はttXlaVersionTableInfoによって返されます。この構造体には、次のフィールドがあります。

フィールド

型

説明

tblDesc

ttXlaTblDesc_t

表記述

tblVer

SQLBIGINT

システム生成表のバージョン番号

ttXlaColDesc_t

列情報は、ttXlaGetColumnInfo関数によって返される、この構造体を使用して提供されます。

この構造体には、次のフィールドがあります。

フィールド

型

説明

header

ttXlaNodeHdr_t

標準データ・ヘッダー

colName [tt_NameLenMax]

char

列の名前

pad0

SQLUINTEGER

4バイト境界まで埋込み

sysColNum

SQLUINTEGER

表の作成時またはその後の変更時に決定された列の序数
SYS.COLUMNSの対応するCOLNUM値と同じです。(『Oracle TimesTen In-Memory Databaseシステム表およびビュー・リファレンス』のSYS.COLUMNSに関する説明を参照してください。)

userColNum

SQLUINTEGER

列の序数(オプションでユーザーが指定した場合)
これは、0(ゼロ)またはttSetUserColumnID TimesTen組込みプロシージャで指定した列番号です。(『Oracle TimesTen In-Memory Databaseリファレンス』のttSetUserColumnIDに関する説明を参照してください。)

dataType

SQLUINTEGER

ODBC TTXLA_*コードの構造体
「XLAデータ型について」を参照してください。

size

SQLUINTEGER

列の最大または基本サイズ

offset

SQLUINTEGER

列の固定長部分に対するオフセット

nullOffset

SQLUINTEGER

NULLバイトに対するオフセット、またはNULL値可能でない場合は0(ゼロ)

precision

SQLSMALLINT

DECIMAL型の数値の精度

scale

SQLSMALLINT

DECIMAL型の数値のスケール

フラグ

SQLUINTEGER

列フラグ。

- TT_COLPRIMKEY: 列は主キーです。

- TT_COLVARYING: 列はアウトラインで格納されています。

- TT_COLNULLABLE: 列はNULL値可能です。

- TT_COLUNIQUE: 列に一意の属性が定義されています。

ttXlaColDesc_t構造体を取得する手順およびその内容を確認する手順は、「列データの確認」を参照してください。次に、これらの手順の概要を示します。

ttXlaColDesc_t構造体は、ttXlaGetColumnInfo関数によって返されます。この構造体には、特定の表の列情報にアクセスするために必要なメタデータが格納されています。たとえば、offsetフィールドを使用すると、ttXlaColDesc_t構造体の後の更新レコードに返された行(一行または複数行)の特定の列データを検出できます。列値のアドレスは、返された行のアドレスにoffsetを追加して検出することができます。その後、dataTypeフィールドに基づいてこの値を対応するC型にキャストしたり、「複合データ型の変換」で説明されている変換ルーチンの1つに渡すことができます。

TimesTenの行データは、固定長データおよびその後に続く可変長データで構成されます。

- 固定長列データの場合、ttXlaColDesc_tは列データのoffsetおよびsizeを返します。offsetはレコードの固定部分の先頭に関連しています。次の例9-1を参照してください。

- 可変長列データ(VARCHAR2、NVARCHAR2およびVARBINARY)の場合、offsetは4バイトのオフセット値を指すアドレスです。オフセット・アドレスをオフセット値に追加すると、行の可変長部分の列データのアドレスを取得できます。この場所の最初のnバイトはデータの長さで、その後に実際のデータが続きます(nは、32ビットのプラットフォームでは4、64ビットのプラットフォームでは8です)。可変長データの場合、返されるsize値は列の許容最大サイズです。次の例9-1を参照してください。

NULL値が含まれる可能性がある列の場合、nullOffsetはレコードのNULLバイトを指します。この値は、列がNULLの場合は1、NULLでない場合は0(ゼロ)になります。詳細は、「NULL値の検出」を参照してください。

flagsビットは、列がNULL値可能であるかどうか、主キーの一部となるかどうか、またはアウトラインで格納されるかどうかを定義します。

sysColNum値は、列に割り当てるシステム列番号です。この値は、最初の列に対しては1から始まります。

注意:
XLAでのLOBのサポートは、次のように制限されています。

- LOB列を含む表にサブスクライブできますが、LOB値自体についての情報は使用できません。

- ttXlaGetColumnInfoでは、LOB列に関する情報が返されます。

- LOBを含む列は、空(長さがゼロ)またはNULL(実際に値がNULLの場合)としてレポートされます。このようにして、NULL列と非NULL列を区別できます。

例9-1 VARCHAR2文字列のコピーと出力

固定長列データの場合、列のアドレスは、次のようにttXlaColDesc_t構造体のoffset値に行のアドレスを追加したものです。

ttXlaColDesc_t colDesc;

void* pColVal = colDesc->offset + row;

列の値は、データ型に対応する型ポインタを使用してこのポインタを参照解除すると取得できます。たとえば、SQL_INTEGERの場合、ODBC型はSQLINTEGERであるため、列の値は次のように入力すると取得できます。

*((SQLINTEGER*) pColVal))

可変長列データの場合、前述の手順で計算されたpColValは4バイトのオフセット値のアドレスになります。このオフセット値をpColValのアドレスに追加すると、可変長列データの先頭を指すポインタが示されます。64ビットのプラットフォームで処理が行われると想定すると、この場所の最初の8バイトはこのデータの長さ(var_len)で、その後に実際のデータ(var_data)が続きます。

この例では、VARCHAR文字列をコピーおよび出力します。

tt_ptrint* var_len = (tt_ptrint*)((char*)pColVal +
*((int*)pColVal));
char* var_data = (char*)(var_len+1);
char* buffer = malloc(*var_len+1);
memcpy(buffer,var_data,*var_len);
buffer[*var_len] = (char)NULL; /* NULL terminate the string */
printf("%s\n",buffer);
free(buffer);

tt_LSN_t

ブックマークで使用されるログ・レコード識別子の記述です。この構造体は、ttXlaUpdateDesc_t構造体によって使用されます。

フィールド

型

説明

logFile

SQLUBIGINT

ログ・レコード識別子の上位部分

logOffset

SQLUBIGINT

ログ・レコード識別子の下位部分

注意:
logFileフィールド名およびlogOffsetフィールド名は、下位互換性を保つために保持されていますが、使用方法は変更されています。以前のリリースでは、値は連続的に増加するLSNを参照しており、この値は具体的な意味を持ち、ログ・ファイル番号とバイト・オフセットを表していました。現在ではログ・レコード識別子を参照していて、この識別子は、より抽象的で、ログ・ファイル番号やバイト・オフセットとは直接関係しません。ログ・レコード識別子の順序に関して想定できることは、ログ・レコード識別子Aよりも後に読み取られたログ・レコード識別子Bは、より大きい値を持つということのみです。

tt_XlaLsn_t

ブックマークで使用されるログ・レコード識別子の記述です。この構造体はttXlaGetLSN関数によって返され、ttXlaSetLSN関数によって使用されます。

checksumはXLAハンドル固有であり、すべてのログ・レコード識別子が特定のXLA接続と関連付けられていることを保証します。

フィールド

型

説明

checksum

SQLUINTEGER

有効なログ・レコード識別子ハンドルであることを保証するためのチェックサム

xid

SQLUSMALLINT

トランザクションID

logFile

SQLUBIGINT

ログ・レコード識別子の上位部分

logOffset

SQLUBIGINT

ログ・レコード識別子の下位部分

注意:
logFileフィールド名およびlogOffsetフィールド名は、下位互換性を保つために保持されていますが、使用方法は変更されています。以前のリリースでは、値は連続的に増加するLSNを参照しており、この値は具体的な意味を持ち、ログ・ファイル番号とバイト・オフセットを表していました。現在ではログ・レコード識別子を参照していて、この識別子は、より抽象的で、ログ・ファイル番号やバイト・オフセットとは直接関係しません。ログ・レコード識別子の順序に関して想定できることは、ログ・レコード識別子Aよりも後に読み取られたログ・レコード識別子Bは、より大きい値を持つということのみです。

10 TimesTen ODBC関数およびオプション

この章では、次に示す内容について説明し、TimesTenでサポートされているODBC関数と、文と接続の関数を設定および取得するためにTimesTenでサポートされているオプションを示します。関数の定義の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。

TimesTenでは、ODBC 2.5、拡張レベル1がサポートされており、この章で示すように、拡張レベル2の機能もあります。

- サポートされているODBC関数

- ODBCの接続関数および文関数のオプションのサポート

- SQLGetInfo用の情報型のサポート

- SQLColAttributes用の列記述子のサポート

サポートされているODBC関数

この項では、TimesTenでサポートされているODBC関数を示し、必要な場合には特に注意事項が記載されています。

表10-1 サポートされているODBC関数

関数

TimesTenでの注意点

SQLAllocConnect

SQLAllocEnv

SQLAllocStmt

SQLBindCol

SQLBindParameter

「SQLBindParameter関数」を参照してください。

SQLCancel

SQLCancelでは、次の操作を取り消すことができます。

- 別のスレッド上のhstmtで実行中の操作

- データを必要とするhstmtで実行中の操作

SQLCancelは、次の操作を取り消すことができません。

- グローバル問合せ
SQLCancelは、ローカル・ノードでのみ取り消すことができます。

- TimesTen Cacheまたはキャッシュ・グリッドでの管理操作

シグナル・ハンドラからSQLCancelを直接コールしないでください。コードを移植できない可能性があります。

SQLColAttributesとSQLColAttributesW

「SQLColAttributes用の列記述子のサポート」を参照してください。

SQLColumnsとSQLColumnsW

SQLConnect

SQLDataSourcesとSQLDataSourcesW

ドライバ・マネージャを使用しているプログラムでのみ使用できます。

SQLDescribeColとSQLDescribeColW

SQLDescribeParam

SQLDisconnect

SQLDriverConnectとSQLDriverConnectW

SQLDriversとSQLDriversW

ドライバ・マネージャを使用しているプログラムでのみ使用できます。

SQLErrorとSQLErrorW

ネイティブ・エラー・コードはTimesTenのエラーです。次のようなエラーが発生する場合があります。「Execution at Oracle failed.Oracle error code nnn.」

SQLExecDirect

SQLExecuteの注意を参照してください。

SQLExecute

TimesTenでは、非同期式の文の実行はサポートしていません。(この章で後述するように、TimesTenではSQL_ASYNC_ENABLE文オプションをサポートしていません。)

SQLFetch

SQLForeignKeysとSQLForeignKeysW

SQLFreeConnect

SQLFreeEnv

SQLFreeStmt

SQLGetConnectOptionとSQLGetConnectOptionW

「SQLSetConnectOptionおよびSQLGetConnectOptionのオプションのサポート」を参照してください。

SQLGetCursorNameとSQLGetCursorNameW

カーソル名の設定または取得はできますが、参照はできません(位置を指定した更新または削除を行うWHERE CURRENT OF句内など)。TimesTenでは、位置を指定した更新または削除文はサポートしていません。

SQLGetData

「Avoid SQLGetData」を参照してください。

SQLGetFunctions

SQLGetInfoとSQLGetInfoW

「SQLGetInfo用の情報型のサポート」を参照してください。

SQLGetStmtOption

「SQLSetStmtOptionおよびSQLGetStmtOptionのオプションのサポート」を参照してください。

SQLGetTypeInfoとSQLGetTypeInfoW

SQLNativeSqlとSQLNativeSqlW

SQLNumParams

SQLNumResultCols

SQLParamData

SQLParamOptions

SQLPrepare

SQLPrimaryKeysとSQLPrimaryKeysW

SQLProcedureColumnsとSQLProcedureColumnsW

SQLProceduresとSQLProceduresW

SQLPutData

SQLRowCount

標準の機能以外に、この関数には、キャッシュ・グループでの特別な使用方法があります。「キャッシュ・グループの管理」を参照してください。

SQLSetConnectOptionとSQLSetConnectOptionW

次の項にある「SQLSetConnectOptionおよびSQLGetConnectOption用のオプションのサポート」を参照してください。

SQLSetCursorNameとSQLSetCursorNameW

カーソル名の設定または取得はできますが、参照はできません(位置を指定した更新または削除を行うWHERE CURRENT OF句内など)。

SQLSetStmtOption

「SQLSetStmtOptionおよびSQLGetStmtOptionのオプションのサポート」を参照してください。

SQLSetParam

これは、ODBC 2.0ではSQLBindParameterに置き換えられたODBC 1.0関数です。下位互換性の目的で保持されています。

SQLSpecialColumnsとSQLSpecialColumnsW

SQLStatisticsとSQLStatisticsW

SQLTablesとSQLTablesW

SQLTransact

注意:
TimesTenでは、各国語キャラクタ・セットとして、UTF-16のみがサポートされています。

ODBCの接続関数および文関数のオプションのサポート

この項では、ODBC関数SQLSetConnectOption、SQLGetConnectOption、SQLSetStmtOptionおよびSQLGetStmtOptionのTimesTenオプションのサポートについて説明します。

これらの関数の一般的な情報は、ODBC APIのリファレンス・マニュアルを参照してください。

SQLSetConnectOptionおよびSQLGetConnectOptionのオプションのサポート

表10-2および表10-3に、ODBCのSQLSetConnectOption関数およびSQLGetConnectOption関数の標準オプションおよびTimesTen固有のオプションに対するTimesTenでのサポート状況を示します。これらの関数を使用すると、初期接続後の接続オプションを設定したり、それらの設定を取得できます。オプションの中には、表に示すように、接続プロセス中に設定できる接続属性と対応するものもあります。

「SQLSetStmtOptionおよびSQLGetStmtOptionのオプションのサポート」も参照してください。これらのオプションは、SQLSetConnectOptionを使用して設定することもできますが、その場合、設定した値は接続時のすべての文に対するデフォルトになります。

注意:

- SQLSetConnectOptionまたはSQLSetStmtOptionを使用したオプション設定は、対応する接続属性の設定よりも優先されます(該当する場合)。

- ここに記載されている説明は、SQLSetConnectOptionWおよびSQLGetConnectOptionWにも適用されます。

表10-2 標準オプション: SQLSetConnectOption、SQLGetConnectOption

オプション

サポート

SQL_ACCESS_MODE

なし

SQL_AUTOCOMMIT

あり

SQL_CURRENT_QUALIFIER

なし

SQL_LOGIN_TIMEOUT

なし

SQL_MAX_ROWS

あり

SQL_NOSCAN

あり

SQL_ODBC_CURSORS

ドライバ・マネージャを使用しているプログラムでは、あり

SQL_OPT_TRACE

ドライバ・マネージャを使用しているプログラムでは、あり

SQL_OPT_TRACEFILE

ドライバ・マネージャを使用しているプログラムでは、あり

SQL_PACKET_SIZE

なし

SQL_QUIET_MODE

なし

SQL_TRANSLATE_DLL

なし

SQL_TRANSLATE_OPTION

なし

SQL_TXN_ISOLATION

vParamがSQL_TXN_READ_COMMITTEDまたはSQL_TXN_SERIALIZABLEの場合は、あり

「複数のデータ行のプリフェッチ」を参照してください。『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』の分離およびロックによる並行性制御に関する説明も参照してください。『Oracle TimesTen In-Memory Databaseリファレンス』の分離に関する説明に記載されている、Isolation一般接続属性と同じ機能です。

表10-3 TimesTenオプション: SQLSetConnectOption、SQLGetConnectOption

オプション

コメント

TT_CLIENT_TIMEOUT

これはクライアント/サーバーの場合のみで、『Oracle TimesTen In-Memory Databaseリファレンス』のTTC_Timeoutに関する説明に記載されている、TTC_Timeout TimesTenクライアント接続属性と同じ機能です。

TT_DYNAMIC_LOAD_ENABLE

『Oracle TimesTen Application-Tier Database Cacheユーザーズ・ガイド』の動的ロードの構成に関する説明を参照してください。これには、『Oracle TimesTen In-Memory Databaseリファレンス』のDynamicLoadEnableに関する説明に記載されている、DynamicLoadEnable TimesTen Cache一般接続属性と同じ機能があります。

TT_DYNAMIC_LOAD_ERROR_MODE

『Oracle TimesTen Application-Tier Database Cacheユーザーズ・ガイド』の動的ロード・エラーの表示に関する説明を参照してください。これには、『Oracle TimesTen In-Memory Databaseリファレンス』のDynamicLoadErrorModeに関する説明に記載されている、DynamicLoadErrorMode TimesTen Cache接続属性と同じ機能があります。

TT_NLS_LENGTH_SEMANTICS

「グローバリゼーション・オプションの設定」を参照してください。これには、『Oracle TimesTen In-Memory Databaseリファレンス』のNLS_LENGTH_SEMANTICSに関する説明に記載されている、NLS_LENGTH_SEMANTICS一般接続属性と同じ機能があります。「その他のグローバリゼーション機能」にも、この機能に関する関連情報があります。

TT_NLS_NCHAR_CONV_EXCP

「グローバリゼーション・オプションの設定」を参照してください。これには、『Oracle TimesTen In-Memory Databaseリファレンス』のNLS_NCHAR_CONV_EXCPに関する説明に記載されている、NLS_NCHAR_CONV_EXCP一般接続属性と同じ機能があります。「その他のグローバリゼーション機能」にも、この機能に関する関連情報があります。

TT_NLS_SORT

「グローバリゼーション・オプションの設定」を参照してください。これには、『Oracle TimesTen In-Memory Databaseリファレンス』のNLS_SORTに関する説明に記載されている、NLS_SORT一般接続属性と同じ機能があります。「その他のグローバリゼーション機能」にも、この機能に関する関連情報があります。

TT_PREFETCH_CLOSE

『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のシリアライズ可能なトランザクションに対するTT_PREFETCH_CLOSEの有効化に関する説明を参照してください。

TT_REGISTER_FAILOVER_CALLBACK

「アプリケーションでの自動クライアント・フェイルオーバーの使用」を参照してください。

TT_REPLICATION_TRACK

「レプリケーションで使用する機能」を参照してください。パラレル・レプリケーションを使用し、レプリケーション・トラックを指定するODBCアプリケーションの場合、これは接続のトラック番号を指定するReplicationTrack一般接続属性と同じ機能があります。

SQLSetStmtOptionおよびSQLGetStmtOptionのオプションのサポート

表10-4と表10-5は、ODBCのSQLSetStmtOptionおよびSQLGetStmtOption関数の標準オプションおよびTimesTen固有のオプションに対するTimesTenでのサポート状況を示しています。これらの関数を使用すると、文オプションの設定またはそれらの設定の取得ができます。

接続に関連付けられているすべての文のオプションのデフォルト値を設定するには、SQLSetConnectOptionを使用します。

注意:
SQLSetConnectOptionまたはSQLSetStmtOptionを使用したオプション設定は、対応する接続属性の設定よりも優先されます(該当する場合)。

表10-4 標準オプション: SQLSetStmtOption、SQLGetStmtOption

オプション

サポート

SQL_ASYNC_ENABLE

なし

SQL_BIND_TYPE

なし

SQL_CONCURRENCY

なし

SQL_CURSOR_TYPE

なし

SQL_KEYSET_SIZE

なし

SQL_MAX_LENGTH

なし

SQL_MAX_LENGTHは設定できますが、指定した値はすべて0で上書きされます(すべての使用可能なデータが返されます)。

SQL_MAX_ROWS

あり

SQL_NOSCAN

あり

SQL_QUERY_TIMEOUT

あり

「SQL文の実行に対するタイムアウトまたはしきい値の設定」を参照してください。

SQL_RETRIEVE_DATA

なし

SQL_ROWSET_SIZE

なし

SQL_SIMULATE_CURSOR

なし

SQL_USE_BOOKMARKS

なし

表10-5 TimesTenオプション: SQLSetStmtOption、SQLGetStmtOption

オプション

コメント

TT_PREFETCH_COUNT

「複数のデータ行のプリフェッチ」を参照してください。

TT_QUERY_THRESHOLD

「SQL文のしきい値期間の設定」を参照してください。これは、SQL文の時間のしきい値(秒単位)を指定するためのオプションで、経過後にTimesTenによってサポート・ログに警告が書き込まれ、SNMPトラップがスローされます。

TT_PRIVATE_COMMANDS

コマンドはその他の接続と共有されません。『Oracle TimesTen In-Memory Databaseリファレンス』のPrivateCommandsに関する項を参照してください。

TT_STMT_PASSTHROUGH_TYPE

特定の準備済の文がTimesTen Cacheのパススルー機能によってOracle Databaseにパススルーされるかどうかを決定します。SQLGetStmtOptionによって返される値は、TT_STMT_PASSTHROUGH_NONEまたはTT_STMT_PASSTHROUGH_ORACLEのいずれかです。

注意: TimesTenでは、このオプションはSQLGetStmtOptionでのみサポートされています。

「パススルー・ステータスの確認」を参照してください。『Oracle TimesTen Application-Tier Database Cacheユーザーズ・ガイド』のパススルー・レベルの設定に関する説明も参照してください。

SQLGetInfo用の情報型のサポート

この項では、ODBC関数SQLGetInfo用にTimesTenでサポートされている標準およびTimesTen固有の情報型について説明します。

この関数および標準的な情報型の全般情報は、ODBC APIリファレンス・ドキュメントを参照してください。

TimesTenでは、次の標準的なODBC 2.x情報型(アルファベット順)をサポートしています。

SQL_ACCESSIBLE_PROCEDURES, SQL_ACCESSIBLE_TABLES, SQL_ACTIVE_CONNECTIONS,
SQL_ACTIVE_STATEMENTS, SQL_ALTER_TABLE, SQL_BOOKMARK_PERSISTENCE,
SQL_COLUMN_ALIAS, SQL_CONCAT_NULL_BEHAVIOR, SQL_CONVERT_BIGINT,
SQL_CONVERT_BINARY, SQL_CONVERT_BIT, SQL_CONVERT_CHAR, SQL_CONVERT_DATE,
SQL_CONVERT_DECIMAL, SQL_CONVERT_DOUBLE, SQL_CONVERT_FLOAT,
SQL_CONVERT_FUNCTIONS, SQL_CONVERT_INTEGER, SQL_CONVERT_LONGVARBINARY,
SQL_CONVERT_LONGVARCHAR, SQL_CONVERT_NUMERIC, SQL_CONVERT_REAL,
SQL_CONVERT_SMALLINT, SQL_CONVERT_TIME, SQL_CONVERT_TIMESTAMP,
SQL_CONVERT_TINYINT, SQL_CONVERT_VARBINARY, SQL_CONVERT_VARCHAR,
SQL_CONVERT_WVARCHAR, SQL_CORRELATION_NAME, SQL_CURSOR_COMMIT_BEHAVIOR,
SQL_CURSOR_ROLLBACK_BEHAVIOR, SQL_DATA_SOURCE_NAME, SQL_DATA_SOURCE_READ_ONLY,
SQL_DATABASE_NAME, SQL_DBMS_NAME, SQL_DBMS_VER, SQL_DEFAULT_TXN_ISOLATION,
SQL_DRIVER_HDBC, SQL_DRIVER_HENV, SQL_DRIVER_HLIB, SQL_DRIVER_HSTMT,
SQL_DRIVER_NAME, SQL_DRIVER_ODBC_VER, SQL_DRIVER_VER, SQL_EXPRESSIONS_IN_ORDERBY,
SQL_FETCH_DIRECTION, SQL_FILE_USAGE, SQL_GETDATA_EXTENSIONS, SQL_GROUP_BY,
SQL_IDENTIFIER_CASE, SQL_IDENTIFIER_QUOTE_CHAR, SQL_KEYWORDS,
SQL_LIKE_ESCAPE_CLAUSE, SQL_LOCK_TYPES, SQL_MAX_BINARY_LITERAL_LEN,
SQL_MAX_CHAR_LITERAL_LEN, SQL_MAX_COLUMN_NAME_LEN, SQL_MAX_COLUMNS_IN_GROUP_BY,
SQL_MAX_COLUMNS_IN_INDEX, SQL_MAX_COLUMNS_IN_ORDER_BY, SQL_MAX_COLUMNS_IN_SELECT,
SQL_MAX_COLUMNS_IN_TABLE, SQL_MAX_CURSOR_NAME_LEN, SQL_MAX_INDEX_SIZE,
SQL_MAX_OWNER_NAME_LEN, SQL_MAX_PROCEDURE_NAME_LEN, SQL_MAX_QUALIFIER_NAME_LEN,
SQL_MAX_ROW_SIZE, SQL_MAX_ROW_SIZE_INCLUDES_LONG, SQL_MAX_STATEMENT_LEN,
SQL_MAX_TABLE_NAME_LEN, SQL_MAX_TABLES_IN_SELECT, SQL_MAX_USER_NAME_LEN,
SQL_MULT_RESULT_SETS, SQL_MULTIPLE_ACTIVE_TXN, SQL_NEED_LONG_DATA_LEN,
SQL_NON_NULLABLE_COLUMNS, SQL_NULL_COLLATION, SQL_NUMERIC_FUNCTIONS,
SQL_ODBC_API_CONFORMANCE, SQL_ODBC_SAG_CLI_CONFORMANCE, SQL_ODBC_SQL_CONFORMANCE,
SQL_ODBC_SQL_OPT_IEF, SQL_ODBC_VER, SQL_OJ_CAPABILITIES,
SQL_ORDER_BY_COLUMNS_IN_SELECT, SQL_OUTER_JOINS, SQL_OWNER_TERM, SQL_OWNER_USAGE,
SQL_POS_OPERATIONS, SQL_POSITIONED_STATEMENTS, SQL_PROCEDURE_TERM,
SQL_PROCEDURES, SQL_QUALIFIER_LOCATION, SQL_QUALIFIER_NAME_SEPARATOR,
SQL_QUALIFIER_TERM, SQL_QUALIFIER_USAGE, SQL_QUOTED_IDENTIFIER_CASE,
SQL_ROW_UPDATES, SQL_SCROLL_CONCURRENCY, SQL_SCROLL_OPTIONS,
SQL_SEARCH_PATTERN_ESCAPE, SQL_SERVER_NAME, SQL_SPECIAL_CHARACTERS,
SQL_STATIC_SENSITIVITY, SQL_STRING_FUNCTIONS, SQL_SUBQUERIES,
SQL_SYSTEM_FUNCTIONS, SQL_TABLE_TERM, SQL_TIMEDATE_ADD_INTERVALS,
SQL_TIMEDATE_DIFF_INTERVALS, SQL_TIMEDATE_FUNCTIONS, SQL_TXN_CAPABLE,
SQL_TXN_ISOLATION_OPTION, SQL_UNION, SQL_USER_NAME

注意:
SQL_DRIVER_HLIBは、ドライバ・マネージャでのみサポートされています。

TimesTenでは、次の標準的なODBC 3.x情報型をサポートしています。

SQL_AGGREGATE_FUNCTIONS, SQL_CONVERT_WCHAR, SQL_CONVERT_WLONGVARCHAR,
SQL_CREATE_VIEW, SQL_DATETIME_LITERALS, SQL_DROP_VIEW,
SQL_SQL92_RELATIONAL_JOIN_OPERATORS, SQL_SQL92_VALUE_EXPRESSIONS

表10-6に、TimesTen固有の情報型を示します。

表10-6 TimesTen情報項目: SQLGetInfo

情報型

データ型

説明

TT_DATA_STORE_INVALID

SQLINTEGER

システム障害やアプリケーション障害などが原因でデータベースが無効な状態にある場合は1を返します。そうでない場合は、0を返します。

注意: エラー846やエラー994などの致命的なエラーは、TimesTenデータベースを無効にし、この項目を1に設定します。

TT_DATABASE_CHARACTER_SET

SQLCHAR

データベースのキャラクタ・セットの名前を返します。

TT_DATABASE_CHARACTER_SET_SIZE

SQLINTEGER

データベースのキャラクタ・セットのキャラクタの最大サイズをバイト単位で返します。

TT_DATABASE_TYPE_MODE

SQLINTEGER

Oracle型モード(標準かつデフォルトの設定)の場合は0を、TimesTen型モード(従来の設定)の場合は1を返します。

注意: 型モードは、TypeMode接続属性を使用して指定できます。

TT_PLATFORM_INFO

ビット・マスク

プラットフォーム情報を示すビット・マスクを返します。ビット0は、64ビット・プラットフォームの場合は値1を、32ビット・プラットフォームの場合は値0を持ちます。ビット1は、ビッグエンディアンの場合は値1を、リトルエンディアンの場合は値0を持ちます。

TT_REPLICATION_INVALID

SQLINTEGER

レプリケーションが失敗した状態の場合は1を、そうでない場合は0を返します。

注意: サブスクライバまたはスタンバイ・データベースでTT_REPLICATION_INVALID=1が設定されている場合、サブスクライバまたはスタンバイが更新を受信していないとレプリケーション・エージェントは停止します。双方向の構成では、レプリケーション・エージェントが稼働していないため、FAILTHRESHOLDは受け付けられません。この状況を解決するには、サブスクライバまたはスタンバイ・データベースを破棄し、ttRepAdmin -duplicateオプションを使用して新しく作成します。詳細は、『Oracle TimesTen In-Memory Database開発者および管理者ガイド』のサブスクライバ機能に関する説明を参照してください。

SQLColAttributes用の列記述子のサポート

この項では、ODBC関数SQLColAttributes用にサポートされているTimesTen固有の列記述子情報について説明します。

この関数および標準的な情報型の全般情報は、ODBC APIリファレンス・ドキュメントを参照してください。

表10-7に、TimesTen固有の列記述子を示します。

表10-7 TimesTen列記述子: SQLColAttributes

記述子

コメント/説明

TT_COLUMN_INLINE

インライン・データを備えた列の場合はTRUEを、そうでない場合はFALSEを返します。これは、SQLColAttributes pfDescパラメータで返されます。

TT_COLUMN_LENGTH_SEMANTICS

キャラクタ型列において、バイト長セマンティクスを備えた列の場合は"BYTE"を、キャラクタ長セマンティクスを備えた列の場合は"CHAR"を返します。キャラクタ以外の列の場合は、""を返します。この情報は、SQLColAttributes rgbDescパラメータで返されます。

この情報は、データ長がバイト単位またはキャラクタ単位のいずれで測定されるかを示しています。TimesTenにおける長さセマンティクスは、Oracle Databaseの場合と同じです。詳細は、『Oracle Databaseグローバリゼーション・サポート・ガイド』の長さセマンティクスに関する説明を参照してください。

索引
A  B  C  D  E  F  G  I  K  L  M  N  O  P  Q  R  S  T  U  V  W  X

A

アクセス制御

接続属性, 2.1.3

接続, 2.1.5

XLAへの影響, 5.1.6

影響の概要, 2.4

レコードが読み取られたことの確認, XLA, 9.2.3 AIX, 接続の考慮事項, 1.3.2 メモリーの割当て, ユーティリティ・ライブラリ環境ハンドル, 8 アプリケーション・コンテキスト, 受渡し, XLA, 5.4.2 データベース更新を適用, XLA, 9.2.3 配列バインド, 「連想配列バインド」を参照 連想配列バインド

OCI, 3.4.2.2

Pro*C, 4.4.1

XAでのAUTOCOMMIT, 6.2.5.1 自動クライアント・フェイルオーバー, 2.6

B

データベースのバックアップ, 8

SQLのバッチ処理, 7.2

バインド変数, 「パラメータのバインド」を参照

パラメータのバインド

OCIでの連想配列バインド, 3.4.2.2

Pro*Cでの連想配列バインド, 4.4.1

OCIでの重複したパラメータ, 3.4.2.1

PL/SQLでの重複したパラメータ, 2.2.6.7

SQLでの重複したパラメータ, 2.2.6.6

浮動小数点データ, 2.2.6.8

入力パラメータ, 2.2.6.3

入力/出力パラメータ, 2.2.6.5

出力パラメータ, 2.2.6.4

パラメータのデータ型の割当ておよび変換, 2.2.6.2

パフォーマンスへの影響, 7.3

精度, 2.2.6.1

スケール, 2.2.6.1

ドライバ・マネージャを使用したSQL_WCHARおよびSQL_WVARCHAR, 2.2.6.9

SQLBindParameter, 2.2.6.1

ブックマーク, 「XLAブックマーク」を参照 buildtmsコマンド, XA, 6.4.2 組込みプロシージャ

TimesTen組込みプロシージャのコール, 2.3.1

ttApplicationContext, 5.4.2, 9.2.3

ttXactIdGet, 8

バルク・フェッチ, 2.2.5, 7.6 バルク挿入, 更新, 削除(バッチ), 7.2

C

C言語関数, 「ユーティリティ・ライブラリ」を参照。

キャッシュ

自動リフレッシュ・キャッシュ・グループおよびXLA, 5.1.7

キャッシュグループ, 影響を受けるキャッシュ・インスタンス, OCI, 3.4.3.2

キャッシュグループ, 影響を受けるキャッシュ・インスタンス, ODBC, 2.3.3.3

パススルー・ステータスの取得, 2.3.3.2

Oracleパスワード, 指定, OCI, 3.4.3.1

Oracleパスワード, 指定, Pro*C/C++, 4.3.3.3

パススルー・レベルの設定, 2.3.3.1

CALL

PL/SQLプロシージャおよびファンクション, 2.3.1

TimesTen組込みプロシージャ, 2.3.1

キャラクタ・セット(character set)

SQLGetInfo情報型, 10.3

サイズに関するSQLGetInfo情報型, 10.3

キャラクタ・セットの変換, 2.3.4 クライアント・フェイルオーバー

自動クライアント・フェイルオーバー, 2.6

構成, 2.6.2

フェイルオーバーのコールバック関数, 2.6.3

トランザクション・ログAPI処理のクローズ, XLA, 9.2.3 列データ, 確認, XLA, 5.2.6 トランザクションのコミット

ODBC, 2.2.11

XLA, 9.2.3

アプリケーションのコンパイル

OCIアプリケーション, 3.3.2

Pro*C/C++アプリケーション, 4.3.2

UNIX, 1.3.2

Windows, 1.3.1

同時実行性の制御, 10.2.1 接続属性

初期接続属性, 2.1.3

一般接続属性, 2.1.3

接続

アクセス制御, 2.1.5

属性, プログラムでの設定, 2.1.3

データベースへの接続, 2.1.2

デフォルトDSN, 2.1.4

データベースからの切断, 2.1.2

外部ユーザー(OCI), 3.3.3.4

外部ユーザー(Pro*C/C++), 4.3.3.4

管理, 2.1

OCI, データベースへの接続, 3.3.3

Pro*C/C++, データベースへの接続, 4.3.3

SQLConnect, SQLDriverConnect, SQLAllocConnect, SQLDisconnect, 2.1.1

SQLSetConnectOptionおよびSQLGetConnectOptionでサポートされているオプション, 10.2.1

カーソル

REF CURSOR, 2.2.7

使用方法, 2.2.3

D

データ構造体, XLA

概要, 9.2.3

tt_LSN_t, 9.2.3

tt_XlaLsn_t, 9.2.3

ttXlaColDesc_t, 9.2.3

ttXlaNodeHdr_t, 9.2.3

ttXlaTblDesc_t, 9.2.3

ttXlaTblVerDesc_t, 9.2.3

ttXlaUpdateDesc_t, 9.2.3

ttXlaVersion_t, 9.2.3

データ型

変換およびパフォーマンス, 7.5

ODBC 2.0データ型とODBC 3.0データ型の比較, 2.3.6

パラメータのバインド用のデータ型のマッピング/変換, 2.2.6.2

XLA, 5.1.5

データベース

更新の適用, XLA, 9.2.3

バックアップ, 8

接続ハンドル, 取得, XLA, 5.2.1

破棄, 8, 8

RAMの使用方法, 8, 8, 8, 8

レプリケート, 8

リストア, 8

デッドロック・エラー, 5.3.3 遅延準備

OCI, 3.4.1

ODBC, 2.2.4

デモ・アプリケーション, クイック・スタート, 1.4 データベースの破棄, 8, 8 診断フレームワークの考慮事項(OCI), 3.3.5 障害時リカバリ, 8 分散トランザクション処理(XA)

「XA」も参照

概要, 6.1

リソース・マネージャ, 6.1.1

トランザクション・マネージャ, 6.1.1

トランザクション・リカバリ, 6.2.2

DML RETURNING, 2.2.8 ドライバ・マネージャ

リンク, 1.2.2

パフォーマンスへの影響, 7.1

SQL_WCHARおよびSQL_WVARCHARの使用, 2.2.6.9

XA, サポート(Windows), 6.3

XLAブックマークを使用する表の削除, 5.2.8 DSN, デフォルト, 2.1.4 重複したパラメータのバインド

OCI, 3.4.2.1

OracleモードとTimesTenモードの比較, 2.2.6.6

DuplicateBindMode一般的な接続属性, 2.2.6.6 DurableCommit, XA, 6.2.1

E

簡易接続

OCI, 3.3.3.2

Pro*C/C++, 4.3.3.2

環境変数

OCI, 3.3.1

TimesTen, 1.1

エラー

エラーおよび警告のレベル, 2.5.2

エラー処理, 2.5

OCIエラー・レポート, 3.3.4

Pro*C/C++エラー・レポート, 4.3.4

リカバリ, 2.5.3

トランザクション・ログAPIのエラー処理, 5.2.7

ユーティリティ・ライブラリ・エラー, カウント, 8

ユーティリティ・ライブラリ・エラー, 取得, 8

イベント管理(XLA), 5 SQLの実行

文の実行, 2.2.2.2

SQLExecDirectおよびSQLExecute, 2.2.2.1

外部ユーザー, 接続

OCI, 3.3.3.4

Pro*C/C++, 4.3.3.4

F

フェイルオーバー, 2.6

結果のフェッチ

バルク・フェッチ, プリフェッチ, 2.2.5, 7.6

例, 2.2.3

初期接続属性, 2.1.3 浮動小数点データ, バインド, 2.2.6.8 メモリーの開放, ユーティリティ・ライブラリ環境ハンドル, 8

G

一般接続属性, 2.1.3

グローバリゼーション・オプション

OCI, 3.2.2

ODBC, 2.3.4

I

-Iフラグ(コンパイル), 1.3.1, 1.3.2

インクルード・ファイル, TimesTen(#include), 2.2.1

サポートされている情報型, SQLGetInfo, 10.3

データベース・ハンドルの初期化, XLA, 9.2.3

入力パラメータ, 2.2.6.3

入力/出力パラメータ, 2.2.6.5

分離レベル, 10.2.1

K

キーが見つからないエラー, 5.3.3

L

-Lフラグ(コンパイル), 1.3.2

アプリケーションのリンク

AIXの考慮事項, 1.3.2

OCIアプリケーション, 3.3.2

Pro*C/C++アプリケーション, 4.3.2

Solarisの考慮事項, 1.3.2

UNIX, 1.3.2

Windows, 1.3.1

ドライバ・マネージャ, 1.2.2

TimesTenドライバ, 1.2.1

LOB

OCI, 3.4.4

ODBC, 2.2.10

概要, 2.2.10

Pro*C, 4.4.2

XLAの制限事項, 5.1.7

XLA のサポート, 5.2.3, 9.2.3

ログ・レコード識別子, 5.1.4

M

XLAを使用したマテリアライズド・ビュー, 5.1.3

N

NVARCHAR型, 5.2.6.3

O

OCI

TimesTenのアーキテクチャ, 3.2.1

コール・サポート, 3.5.1

アプリケーションのコンパイルおよびリンク, 3.3.2

外部ユーザーとして接続, 3.3.3.4

TimesTenデータベースへの接続, 3.3.3

遅延準備, 3.4.1

デモ・アプリケーション, 3.3.6

記述子のサポート, 3.5.3

診断フレームワークの考慮事項, 3.3.5

簡易接続, 使用, 3.3.3.2

環境変数, 3.3.1

エラー・レポート, 3.3.4

外部ユーザーの接続, 3.3.3.4

ハンドルのサポート, 3.5.2

Oracleパスワード, キャッシュ用の指定, 3.4.3.1

概要, 3.1

パラメータ属性のサポート, 3.5.5

TimesTenの制限, 3.2.3

シグナル処理の考慮事項, 3.3.5

SQLデータ型のサポート, 3.5.4

文のキャッシュ, 3.1, 3.5.1

TimesTenのサポート, 3.2

tnsnames, 使用, 3.3.3.1

OCIBindByPos, 3.4.2.1 ODBC関数, TimesTenでのサポート, 10.1 Oracle Call Interfaceのサポート, 3 出力パラメータ, 2.2.6.4

P

パラレル・レプリケーション, ユーザー定義, 設定およびODBCのサポート, 2.3.5

パラメータのバインド

OCIでの連想配列バインド, 3.4.2.2

Pro*Cでの連想配列バインド, 4.4.1

OCIでの重複したパラメータ, 3.4.2.1

PL/SQLでの重複したパラメータ, 2.2.6.7

SQLでの重複したパラメータ, 2.2.6.6

浮動小数点データ, 2.2.6.8

入力パラメータ, 2.2.6.3

入力/出力パラメータ, 2.2.6.5

出力パラメータ, 2.2.6.4

パラメータのデータ型の割当ておよび変換, 2.2.6.2

ドライバ・マネージャを使用したSQL_WCHARおよびSQL_WVARCHAR, 2.2.6.9

SQLBindParameter, 2.2.6.1

パススルー

TT_STMT_PASSTHROUGH_TYPE ODBCオプションを使用したステータスの取得, 2.3.3.2, 10.2.2

ttOptSetFlagを使用したレベルの設定, 2.3.3.1

パフォーマンス

SQLのバッチ処理, 7.2

パラメータのバインド, 7.3

バルク・フェッチ, プリフェッチ, 7.6

データ型の変換, 7.5

SQLGetData, 7.4

PL/SQLのプロシージャとファンクション, コール, 2.3.1 精度, 2.2.6.1 複数行のプリフェッチ, 2.2.5, 7.6 SQLの準備

遅延準備, 2.2.4

文の準備, 2.2.3

権限, 「アクセス制御」を参照 Pro*C/C++プリコンパイラ

TimesTenのアーキテクチャ, 3.2.1

アプリケーションの構築, 4.3.2, 4.3.2

コマンドおよび句, サポートされていないか制限されている(概要), 4.2.7

外部ユーザーとして接続, 4.3.3.4

TimesTenデータベースへの接続, 4.3.3

接続の制限, 4.2.6, 4.2.6

デモ・アプリケーション, 4.3.5

簡易接続, 使用, 4.3.3.2

埋込みPL/SQLの制限, 4.2.4

埋込みSQLの制限, 4.2.2

エラー・レポート, 4.3.4

外部ユーザーの接続, 4.3.3.4

開始, 4.3

オプション設定, 4.5.2

オプションのサポート, 4.5.1, 4.5.1

Oracleパスワード, キャッシュ用の指定, 4.3.3.3

概要, 4.1

セマンティック・チェックの制限, 4.2.3

SQLLIBのサポート, 4.2.2

TimesTenのサポート, 4.2

tnsnames, 使用, 4.3.3.2

トランザクションの制限, 4.2.5

Q

問合せの結果, カーソルの使用, 2.2.3

問合せ(またはすべての文)のしきい値, 2.3.2.2

問合せ(またはすべての文)のタイムアウト, 2.3.2.1

クイック・スタート, デモ・アプリケーション, 1.4

R

RAMの使用方法

ttRamGrace, 8

ttRamLoad, 8

ttRamPolicy, 8

ttRamUnload, 8

レコード・ヘッダー, 確認, XLA, 5.2.5 REF CURSOR, 2.2.7 データベースのレプリケート

ユーティリティ関数, 8

XLA, レプリケーション用に使用, 5.3

レプリケーションが無効, SQLGetInfo情報型, 10.3 リソース・マネージャ, XA, 6.1.1 データベースのリストア, 8 RETURNING INTO句, 2.2.8 トランザクションのロールバック

ユーティリティ関数, 8

XLA, 9.2.3

ROWID

ROWIDの文字列への変換, XLA9.2.3

ROWIDの使用, ROWIDのデータ型, 2.2.9

S

sb_ErrXlaTupleMismatchエラー, 5.3.4, 9.2.3, 9.2.3

スケール, 2.2.6.1

セキュリティ, 「アクセス制御」を参照

シグナル処理の考慮事項(OCI), 3.3.5

Solaris, 接続の考慮事項, 1.3.2

SQL_QUERY_TIMEOUTオプション, 2.3.2.1

ドライバ・マネージャを使用したSQL_WCHARおよびSQL_WVARCHAR, 2.2.6.9

SQLAllocConnect, 2.1.1

SQLBindCol, パフォーマンス, 7.3

SQLBindParameter

引数, 使用方法, 2.2.6.1

パフォーマンス, 7.3

SQLColAttributes TimesTen記述子

TT_COLUMN_INLINE, 10.4

TT_COLUMN_LENGTH_SEMANTICS, 10.4

SQLConnect, 2.1.1 SQLDisconnect, 2.1.1 SQLDriverConnect, 2.1.1, 2.1.3 SQLExecDirect, 2.2.2.1 SQLExecute, 2.2.2.1 SQLGetConnectOption, サポートされているオプション, 10.2.1 SQLGetDataおよびパフォーマンス, 7.4 SQLGetInfo TimesTen情報型

TT_DATA_STORE_INVALID, 10.3

TT_DATABASE_CHARACTER_SET, 10.3

TT_DATABASE_CHARACTER_SET_SIZE, 10.3

TT_DATABASE_TYPE_MODE, 10.3

TT_PLATFORM_INFO, 10.3

TT_REPLICATION_INVALID, 10.3

SQLGetInfo, サポートされている情報型, 10.3 SQLGetStmtOption() ODBC関数

TT_STMT_PASSTHROUGH_TYPE option, 2.3.3.2

SQLGetStmtOption, サポートされているオプション, 10.2.2 SQLLIBのサポート(Pro*C/C++), 4.2.2 SQLParamOptions関数, 7.2 SQLRowCount, 2.2.11, 2.3.3.3 SQLSetConnectOption, サポートされているオプション, 10.2.1 SQLSetStmtOption, サポートされているオプション, 10.2.2 文のキャッシュ, OCI, 3.1, 3.5.1 文の実行(SQL)

文の実行, 2.2.2.2

SQLExecDirectおよびSQLExecute, 2.2.2.1

文のオプション, SQLSetStmtOptionおよびSQLGetStmtOption, サポートされているオプション, 10.2.2 文の準備(SQL)

遅延準備, 2.2.4

文の準備, 2.2.3

T

監視する表, XLA, 5.2.3

SQL文のしきい値, 2.3.2.2

タイムアウト

SQL文, 2.3.2.1

タイムアウト・エラーの処理, 5.3.3

TimesTen Cache, 「キャッシュ」を参照 timesten.h

簡単な説明, 2.2.1

グローバリゼーション・オプション, 2.3.4

ttFailoverCallback_t構造体, 2.6.3

tnsnames

OCI, 3.3.3.1

Pro*C/C++, 4.3.3.2

トランザクション・ログAPI

「XLA」も参照

ブックマーク, 5.1.4

ハンドルのクローズ, 9.2.3

データ構造体, 9.2.3

デモ, 5.1.8

エラー処理, 5.2.7

関数, 概要, 9.1

関数, 概要, 9.2

概要, 5

レプリケーション, 5.3

tt_LSN_tデータ構造体, 9.2.3

tt_XlaLsn_tデータ構造体, 9.2.3

ttXlaAcknowledge, 9.2.3

ttXlaApply, 9.2.3

ttXlaClose, 9.2.3

ttXlaColDesc_tデータ構造体, 9.2.3

ttXlaCommit, 9.2.3

ttXlaConvertType, 9.2.3

ttXlaDateToODBCCType, 9.2.3

ttXlaDecimalToCString, 9.2.3

ttXlaDeleteBookmark, 9.2.3

ttXlaError, 9.2.3

ttXlaErrorRestart, 9.2.3

ttXlaGenerateSQL, 9.2.3

ttXlaGetColumnInfo, 9.2.3

ttXlaGetLSN, 9.2.3

ttXlaGetTableInfo, 9.2.3

ttXlaGetVersion, 9.2.3

ttXlaLookup, 9.2.3

ttXlaNextUpdate, 9.2.3

ttXlaNextUpdateWait, 9.2.3

ttXlaNodeHdr_tデータ構造体, 9.2.3

ttXlaNumberToBigInt, 9.2.3

ttXlaNumberToCString, 9.2.3

ttXlaNumberToDouble, 9.2.3

ttXlaNumberToInt, 9.2.3

ttXlaNumberToSmallInt, 9.2.3

ttXlaNumberToTinyInt, 9.2.3

ttXlaNumberToUInt, 9.2.3

ttXlaOraDateToODBCTimeStamp, 9.2.3

ttXlaOraTimeStampToODBCTimeStamp, 9.2.3

ttXlaPersistOpen, 9.2.3

ttXlaRollback, 9.2.3

ttXlaRowdToCString, 9.2.3

ttXlaSetLSN, 9.2.3

ttXlaSetVersion, 9.2.3

ttXlaTableByName, 9.2.3

ttXlaTableCheck, 9.2.3

ttXlaTableStatus, 9.2.3

ttXlaTableVersionVerify, 9.2.3

ttXlaTblDesc_tデータ構造体, 9.2.3

ttXlaTblVerDesc_tデータ構造体, 9.2.3

ttXlaTimeStampToODBCCType, 9.2.3

ttXlaTimeToODBCCType, 9.2.3

ttXlaUpdateDesc_tデータ構造体, 9.2.3

ttXlaVersion_tデータ構造体, 9.2.3

ttXlaVersionColumnInfo, 9.2.3

ttXlaVersionCompare, 9.2.3

ttXlaVersionTableInfo, 9.2.3

トランザクション・マネージャ, XA, 6.1.1 TT_COLUMN_INLINE SQLColAttributes記述子, 10.4 TT_COLUMN_LENGTH_SEMANTICS SQLColAttributes記述子, 10.4 TT_DATA_STORE_INVALID SQLGetInfo情報型, 10.3 TT_DATABASE_CHARACTER_SET SQLGetInfo情報型, 10.3 TT_DATABASE_CHARACTER_SET_SIZE SQLGetInfo情報型, 10.3 TT_DATABASE_TYPE_MODE SQLGetInfo情報型, 10.3 tt_ErrBadXlaRecord, 5.2.7 tt_ErrCondLockConflict, 5.2.7 tt_ErrDbAllocFailed, 5.2.7 tt_ErrDeadlockVictim, 5.2.7 tt_ErrDeadlockVictimエラー, 5.3.3 tt_ErrPermSpaceExhausted, 5.2.7 tt_ErrTempSpaceExhausted, 5.2.7 tt_ErrTimeoutVictim, 5.2.7 tt_ErrTimeoutVictimエラー, 5.3.3 tt_ErrXlaBookmarkUsed, 5.2.7 tt_ErrXlaDedicatedConnection, 5.2.7 tt_ErrXlaLsnBad, 5.2.7 tt_ErrXlaNoLogging, 5.2.7 tt_ErrXlaNoSQL, 5.2.7 tt_ErrXlaParameter, 5.2.7 tt_ErrXlaTableDiff, 5.2.7 tt_ErrXlaTableSystem, 5.2.7 tt_ErrXlaTupleMismatch, 5.2.7 tt_LSN_tデータ構造体, XLA, 9.2.3 TT_NLS_LENGTH_SEMANTICS ODBCオプション, 2.3.4.2 TT_NLS_NCHAR_CONV_EXCP ODBCオプション, 2.3.4.3 TT_NLS_SORT ODBCオプション, 2.3.4.1 TT_PLATFORM_INFO SQLGetInfo情報型, 10.3 TT_PREFETCH_CLOSE接続オプション, 1.2.2 TT_PREFETCH_COUNT, 2.2.5, 7.6 TT_QUERY_THRESHOLD, 2.3.2.2 TT_REPLICATION_INVALID SQLGetInfo情報型, 10.3 TT_STMT_PASSTHROUGH_TYPE ODBCオプション, 10.2.2 tt_xa_context()関数, XA, 6.2.4 tt_xa_switch, XA, 6.2.6.2 tt_xla.h includeファイル, 5.2 tt_XlaLsn_tデータ構造体, XLA, 9.2.3 ttApplicationContext, 5.4.2, 5.4.2, 9.2.3 ttBackup, 8 ttCkpt組込みプロシージャ, 5.2.9 ttCkptBlocking組込みプロシージャ, 5.2.9 ttDestroyDataStore, 8 ttDestroyDataStoreForce, 8 ttDurableCommit, XA, 6.2.1 ttRamGrace, 8 ttRamLoad, 8 ttRamPolicy, 8 ttRamUnload, 8 ttRepDuplicateEx, 8 ttRestore, 8 ttSrcScanユーティリティ, 3.2.4, 4.2.8 ttUtilAllocEnv, 8 ttUtilFreeEnv, 8 ttUtilGetError, 8 ttUtilGetErrorCount, 8 ttXactIdGet組込みプロシージャ, 8 ttXactIdRollback, 8 ttxadm43.dllライブラリ, XA, 6.3.2 ttXlaAcknowledge, 5.2.4, 9.2.3 ttXlaApply, 5.3.2, 9.2.3 ttXlaBookmarkDelete組込みプロシージャ, 5.2.9 ttXlaClose, 9.2.3 ttXlaColDesc_t, 5.2.6.1 ttXlaColDesc_tデータ構造体, XLA, 9.2.3 ttXlaCommit, 5.3.3, 5.3.3, 9.2.3 ttXlaConvertCharType, 9.2.3 ttXlaDateToODBCCType, 5.2.6.5, 5.2.6.5, 9.2.3 ttXlaDecimalToCString, 5.2.6.5, 5.2.6.5, 9.2.3 ttXlaDeleteBookmark, 5.2.9, 9.2.3 ttXlaError, 5.2.7, 9.2.3 ttXlaErrorRestart, 5.2.7, 9.2.3 ttXlaGenerateSQL, 5.3.5, 9.2.3 ttXlaGetColumnInfo, 5.2.6.1, 9.2.3 ttXlaGetLSN, 5.3.3, 9.2.3 ttXlaGetTableInfo, 5.2.6.1, 9.2.3 ttXlaGetVersion, 9.2.3 ttXlaHandle_h XLA handle, 5.2.2 ttXlaLookup, 9.2.3 ttXlaNextUpdate, 5.2.4, 9.2.3 ttXlaNextUpdateWait, 5.2.4, 9.2.3 ttXlaNodeHdr_t, 9.2.3 ttXlaNodeHdr_tデータ構造体, XLA, 9.2.3 ttXlaNumberToBigInt, 5.2.6.5, 9.2.3 ttXlaNumberToCString, 5.2.6.5, 9.2.3 ttXlaNumberToDouble, 5.2.6.5, 9.2.3 ttXlaNumberToInt, 5.2.6.5, 9.2.3 ttXlaNumberToSmallInt, 5.2.6.5, 9.2.3 ttXlaNumberToTinyInt, 5.2.6.5, 9.2.3 ttXlaNumberToUInt, 5.2.6.5, 9.2.3 ttXlaOraDateToODBCTimeStamp, 5.2.6.5, 9.2.3 ttXlaOraTimeStampToODBCTimeStamp, 5.2.6.5, 9.2.3 ttXlaPersistOpen, 5.2.2, 9.2.3 ttXlaRollback, 5.3.3, 9.2.3 ttXlaRowdToCString, 9.2.3 ttXlaSetLSN, 5.3.3, 9.2.3 ttXlaSetVersion, 9.2.3 ttXlaTableByName, 5.2.3, 9.2.3 ttXlaTableCheck, 9.2.3 ttXlaTableStatus, 5.2.3, 9.2.3 ttXlaTableVersionVerify, 9.2.3 ttXlaTblDesc_tデータ構造体, XLA, 9.2.3 ttXlaTblVerDesc_tデータ構造体, XLA, 9.2.3 ttXlaTimeStampToODBCCType, 5.2.6.5, 5.2.6.5, 9.2.3 ttXlaTimeToODBCCType, 5.2.6.5, 5.2.6.5, 9.2.3 ttXlaUnsubscribe組込みプロシージャ, 5.2.8 ttXlaUpdateDesc_t

説明, 使用方法, 9.2.3

更新レコードの後続のデータ行, 5.2.6

TT_AGINGフラグ, 9.2.3

TT_CASCDELフラグ, 9.2.3

TT_UPDCOLSフラグ, 9.2.3

TT_UPDCOMMITフラグ, 9.2.3

TT_UPDDEFAULTフラグ, 9.2.3

TT_UPDFIRSTフラグ, 9.2.3

TT_UPDREPLフラグ, 9.2.3

ttXlaAddColumnTup_t, 9.2.3

ttXlaCreateIndexTup_t, 9.2.3

ttXlaCreateSeqTup_t, 9.2.3

ttXlaCreateSynTup_t, 9.2.3

ttXlaDropColumnTup_t, 9.2.3

ttXlaDropindexTup_t, 9.2.3

ttXlaDropSeqTup_t, 9.2.3

ttXlaDropSynTup_t, 9.2.3

ttXlaDropTableTup_t, 9.2.3

ttXlaDropViewTup_t, 9.2.3

ttXlaSetColumnTup_t, 9.2.3

ttXlaSetStatusTup_t, 9.2.3

ttXlaSetTableTup_t, 9.2.3

ttXlaTruncateTableTup_t, 9.2.3

ttXlaViewDesc_t, 9.2.3

更新ヘッダー, 記述, 5.2.4

記述内容, 5.2.5

ttXlaVersion_tデータ構造体, XLA, 9.2.3 ttXlaVersionColumnInfo, 9.2.3 ttXlaVersionCompare, 9.2.3 ttXlaVersionTableInfo, 9.2.3 Tuxedo, XAの構成6.4 2フェーズ・コミットのプロトコル, XA, 6.1.2 パラメータのバインド用のデータ型のマッピング/変換, 2.2.6.2

U

UBBCONFIGファイル, XA, 6.4.3

UNIX, アプリケーションのコンパイルおよびリンク, 1.3.2

更新競合, XLA, 5.3.4

更新レコード, 取得, XLA, 5.2.4

ユーティリティ・ライブラリ

説明, 概要, 8

ttBackup, データベースのバックアップ, 8

ttDestroyDataStore, データベースの破棄, 8

ttDestroyDataStoreForce, データベースの破棄, 8

ttRamGrace, RAMの使用方法, 8

ttRamLoad, RAMの使用方法, 8

ttRamPolicy, RAMの使用方法, 8

ttRamUnload, RAMの使用方法, 8

ttRepDuplicateEx, データベースのレプリケート, 8

ttRestore, データベースのリストア, 8

ttUtilAllocEnv, ライブラリ環境ハンドルの割当て, 8

ttUtilFreeEnv, ライブラリ環境ハンドルの解放, 8

ttUtilGetError, ユーティリティ・ライブラリ・エラー, 8

ttUtilGetErrorCount, ユーティリティ・ライブラリ・エラー・カウント, 8

ttXactIdRollback, ロールバック・トランザクション, 8

V

VARBINARY型, 5.2.6.3

VARCHAR型, 5.2.6.3

W

Windows, アプリケーションのコンパイルおよびリンク, 1.3.1

X

XA

XAでのAUTOCOMMIT, 6.2.5.1

ドライバ・マネージャを介したサポート(Windows), 6.3

DurableCommit, 6.2.1

リソース・マネージャ, 6.1.1

トランザクション・マネージャ, 6.1.1

トランザクション・リカバリ, 6.2.2

tt_xa_context()関数, 6.2.4

tt_xa_switch, 6.2.6.2

ttDurableCommit, 6.2.1

Tuxedoの構成6.4

2フェーズ・コミット, 6.1.2

XIDパラメータ, 6.2.3.3

xa_close()関数, 6.2.3.2 xa_open()関数, 6.2.3.1 xa_switch_t, 6.2.6.1 XIDパラメータ, XA, 6.2.3.3 XLA

アクセス制御, 5.1.6

レコードが読み取られたことの確認, 9.2.3

「トランザクション・ログAPI」も参照

「XLAブックマーク」も参照

アプリケーション・コンテキスト, 受渡し, 5.4.2

データベース更新を適用, 9.2.3

トランザクション・ログAPI処理のクローズ, XLA, 9.2.3

列データ, 確認, 5.2.6

列情報, 取得, 9.2.3

トランザクションのコミット, 9.2.3

概念, 5.1

データ構造体, 9.2.3

データ型, 5.1.5

データベース接続ハンドル, 取得, 5.2.1

ブックマークを使用する表の削除, 5.2.8

エラー, トランザクション・ログ・エラーの読取り, 9.2.3

エラー, トランザクション・ログ・エラー・スタックのリセット, 9.2.3

イベント・ハンドラ・アプリケーション, 5.2

関数, 概要, 9.1

関数, 概要, 9.2

データベース・ハンドルの初期化, 9.2.3

制限, 5.1.7

LOBのサポート, 5.2.3, 9.2.3

マテリアライズド・ビュー, 使用, 5.1.3

レコード・ヘッダー, 確認, 5.2.5

レコード, 検索, 9.2.3

XLAを使用したレプリケーション, 5.3

トランザクションのロールバック, 9.2.3

表の互換性, 検証, 9.2.3

表情報, 取得, 9.2.3, 9.2.3

表のステータス, 9.2.3

監視する表, 指定, 5.2.3

XLAアプリケーションの終了, 5.2.10

更新競合, 5.3.4

更新データ, 取得, 9.2.3

更新レコード, 取得, 5.2.4

バージョン, トランザクション・ログAPIのバージョンの取得, 9.2.3

バージョン, トランザクション・ログAPIのバージョンの設定, 9.2.3

XLAハンドル, 初期化, , 5.2.2

XLAブックマーク

作成または再利用, 5.1.4.1

削除, 5.2.9, 9.2.3

サブスクライブされた表の決定, 5.2.3

ブックマークの動作, 5.1.4.2

位置, 変更, 5.4.1

概要, 5.1.4

レプリケートされたブックマーク, 5.1.4.3

DDLイベントのレポート, 5.2.3

X/Open DTPモデル, 6.1.1

オラクル社の法律上の注意点について

コピーライトについて

Copyright © 1994-2015, Oracle and/or its affiliates.All rights reserved.

商標と登録商標について

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

ライセンス制約の保証と結果的に生じる損害の免責

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

保証免責

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

制限付権利

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations.As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

危険な用途への使用について

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション（人的傷害を発生させる可能性があるアプリケーションを含む）への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性（redundancy）、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

第三者のコンテンツ、製品、サービスに対する免責事項

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

ドラフトのアルファ版およびベータ版ドキュメントについて

このドキュメントが試作版の場合:

このドキュメントは試作版であり、デモおよび暫定使用のみを目的としたものです。このソフトウェアを使用するハードウェアに限定するものではありません。オラクル社およびその関連会社は、このドキュメントに関して一切の責任を負わず、いかなる保証もいたしません。また、このドキュメントを使用したことによって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。