Oracle® Call Interface

プログラマーズ・ガイド

11g リリース2 (11.2)

E50264-03(原本部品番号:E10646-15)

2014年7月

Oracle Call Interfaceプログラマーズ・ガイド, 11g リリース2(11.2)

E50264-03

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

原本著者: Rod Ward、Jack Melnick

原本協力者: Geeta Arora、Varun Arora、A.Bande、D.Banerjee、S.Banerjee、M.Bastawala、E.Belden、N.Bhatt、T.Bhosle、Janet Blowney、R.Chakravarthula、S.Chandrasekar、D.Chiba、L.Chidambaran、Thuvan Hoang、N.Ikeda、K.Itikarlapalli、Chandrasekhar Iyer、Shankar Iyer、B.Khaladkar、S.Krishnaswamy、S.Lahorani、S.Lari、Tianshu Li、Chao Liang、Edwina Lu、S.Lynn、Valarie Moore、A.Mullick、K.Neel、E.Paapanen、R.Phillips、R.Pingte、R.Rajamani、M.Ramacher、A.Ramappa、A.Saxena、S.Seshadri、Rupa Singh、B.Sinha、H.Slattery、Lu Sun、Mallikharjun Vemana、S.Vemuri、G.Viswanathan、Lik Wong、S.Youssef

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

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

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

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の登録商標です。

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

目次

例一覧

図一覧

表一覧

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

はじめに

- 対象読者

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

- 関連ドキュメント

- 表記規則

Oracle Call Interfaceの新機能

- Oracle Call Interfaceリリース11.2の新機能

- Oracle Call Interfaceリリース11.1の新機能

1 OCI: 概要およびアップグレード

- OCIの概要

- OCIの利点

- OCIアプリケーションの構築

- OCIの分類

- 手続き型および非手続き型要素

- オブジェクトのサポート

- SQL文

- データ定義言語

- 制御文

- データ操作言語

- 問合せ

- PL/SQL

- 埋込みSQL

- SQL用のOCIの特殊用語

- カプセル化されたインタフェース

- ユーザー認証およびパスワード管理の簡易化

- アプリケーションのパフォーマンスおよび拡張性を改善する拡張機能

- OCIによるオブジェクトのサポート

- クライアント側のオブジェクト・キャッシュ

- アソシエイティブ・インタフェースおよびナビゲーショナル・インタフェース

- オブジェクト用のOCIランタイム環境

- 型管理: マッピングおよび操作関数

- Object Type Translator

- OCIでのOracle Streams Advanced Queuingのサポート

- XAライブラリ・サポート

- 互換性およびアップグレード

- 静的にリンクされたアプリケーションと動的にリンクされたアプリケーションのバージョンの互換性

- 既存OCIリリース7アプリケーションのアップグレードの簡易化

- 使用されなくなったOCIルーチン

- サポートされないOCIルーチン

- 異なるリリースのOCIおよびサーバー間の互換性

- OCIのアップグレード

- リリース7.x以上のOCIコールのリリース7.xアプリケーションへの追加

- OCI Instant Client

- Instant Clientの利点

- OCI Instant Clientのインストール・プロセス

- Instant Clientを使用する場合

- LinuxまたはUNIXでのInstant Client共有ライブラリへのパッチの適用

- データ共有ライブラリ、zipおよびRPMファイルの再生成

- データ共有ライブラリlibociei.soの再生成

- データ共有ライブラリlibociicus.soの再生成

- データ共有ライブラリlibociei.soおよびlibociicus.soの同時再生成

- 基本パッケージ用のzipおよびRPMファイルの再生成

- 基本軽量パッケージ用のzipおよびRPMファイルの再生成

- JDBCパッケージ用のzipおよびRPMファイルの再生成

- ODBCパッケージ用のzipおよびRPMファイルの再生成

- SQL*Plusパッケージ用のzipおよびRPMファイルの再生成

- ツール・パッケージ用のzipおよびRPMファイルの再生成

- 全パッケージ用のzipおよびRPMファイルの再生成

- OCI Instant Clientのデータベース接続文字列

- Instant Client接続識別子の例

- OCI Instant Clientの環境変数

- Instant Client Light(English)

- グローバリゼーション設定

- Instant Client Lightの動作

- Instant Client Lightのインストール

- Instant Client SDK

2 OCIプログラミングの基本

- ヘッダー・ファイルおよびMakefileの場所

- OCIプログラムのプログラミングの概要

- OCIデータ構造

- ハンドル

- ハンドルの割当てと解放

- 環境ハンドル

- エラー・ハンドル

- サービス・コンテキスト・ハンドルとそれに対応付けられたハンドル

- 文ハンドル、バインド・ハンドルおよび定義ハンドル

- 記述ハンドル

- 複合オブジェクト検索ハンドル

- スレッド・ハンドル

- サブスクリプション・ハンドル

- ダイレクト・パス・ハンドル

- 接続プール・ハンドル

- ハンドル属性

- OCI記述子

- OCIプログラミング・ステップ

- OCI環境の初期化

- OCI環境の作成

- ハンドルおよび記述子の割当て

- アプリケーションの初期化、接続およびセッション作成

- OCIでのSQL文の処理

- 操作のコミットまたはロールバック

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

- OCIでのエラー処理

- データのリターン・コードおよびエラー・コード

- その他の値を戻す関数

- その他のコーディング・ガイドライン

- オペレーティング・システムの考慮事項

- パラメータの型

- アドレス・パラメータ

- 整数パラメータ

- 文字列パラメータ

- 列へのNULLの挿入

- 標識変数

- 入力

- 出力

- 名前付きデータ型用およびREF用の標識変数

- コールの取消し

- 位置指定の更新および削除

- 予約語

- Oracle予約済ネームスペース

- OCIでのポーリング・モード操作

- OCIでの非ブロック化モード

- ブロック化モードの設定

- 非ブロック化コールの取消し

- OCIプログラムでのPL/SQL使用方法

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

- OCIからのクライアント・キャラクタ・セットの制御

- 文字制御とOCIインタフェース

- OCIでの文字長セマンティクス

- OCIでのキャラクタ・セットのサポート

- その他のOCIグローバリゼーション・サポート関数

- OCIでのロケール情報の取得

- OCIでの文字列の操作

- OCIでのキャラクタ・セットの変換

- OCIメッセージ関数

- lmsgenユーティリティ

- テキスト・メッセージ・ファイルのガイドライン

- テキスト・メッセージ・ファイルからのバイナリ・メッセージ・ファイル作成の例

3 データ型

- Oracleデータ型

- 外部データ型コードの使用

- 内部データ型

- LONG、RAW、LONG RAW、VARCHAR2

- 文字列およびバイト配列

- UROWID

- BINARY_FLOATおよびBINARY_DOUBLE

- 外部データ型

- VARCHAR2

- 入力

- 出力

- NUMBER

- 64ビット整数ホスト・データ型

- 64ビット整数のOCIバインドおよび定義

- 文を戻すOUTバインドDMLのサポート

- INTEGER

- FLOAT

- STRING

- 入力

- 出力

- VARNUM

- LONG

- VARCHAR

- DATE

- RAW

- VARRAW

- LONG RAW

- UNSIGNED

- LONG VARCHAR

- LONG VARRAW

- CHAR

- 入力

- 出力

- CHARZ

- 名前付きデータ型: オブジェクト、VARRAY、ネストした表

- REF

- ROWID記述子

- LOB記述子

- BFILE

- BLOB

- CLOB

- NCLOB

- 日時および時間隔のデータ型記述子

- ANSI DATE

- TIMESTAMP

- TIMESTAMP WITH TIME ZONE

- TIMESTAMPWITHLOCALTIMEZONE

- INTERVALYEARTOMONTH

- INTERVALDAYTOSECOND

- 日時を使用する際の予期しない結果の回避

- システム固有のfloatおよびdouble

- Cオブジェクト・リレーショナル・データ型マッピング

- データ変換

- LOBデータ型記述子のデータ変換

- 日時および時間隔データ型のデータ変換

- 代入に関する注意

- 日時および時間隔型のデータ変換に関する注意

- 日時および日付のアップグレード規則

- リリース1(9.0.1)より前のクライアントとリリース1(9.0.1)以上のサーバー

- リリース1(9.0.1)より前のサーバーとリリース1(9.0.1)以上のクライアント

- OCIでのBINARY_FLOATおよびBINARY_DOUBLEのデータ変換

- 型コード

- SQLT値およびOCI_TYPECODE値の関係

- oratypes.hの定義

4 OCIでのSQL文の使用

- SQL文の処理の概要

- 文の準備

- プリペアド文を複数のサーバーで使用する方法

- OCIのプレースホルダのバインド

- プレースホルダのルール

- 文の実行

- 実行スナップショット

- OCIStmtExecute()の実行モード

- バッチ・エラー・モード

- バッチ・エラー・モードの例

- 選択リスト項目の記述

- 暗黙的記述

- 問合せの明示的記述

- OCIでの出力変数の定義

- 結果のフェッチ

- LOBデータのフェッチ

- プリフェッチ・カウントの設定

- OCIでのスクロール・カーソルの使用

- スクロール・カーソルのパフォーマンスの向上

- スクロール・カーソルでのアクセスの例

5 OCIでのバインドおよび定義

- OCIでのバインドの概要

- 名前付きバインドおよび定位置バインド

- OCI配列インタフェース

- PL/SQLのプレースホルダのバインド

- OCIバインドで使用するステップ

- OCIプログラムでのPL/SQLブロック

- OCIでの拡張バインド操作

- LOBのバインド

- LOBロケータのバインド

- LOBデータのバインド

- OCI_DATA_AT_EXECモードでのバインド

- REF CURSOR変数のバインド

- OCIでの定義の概要

- OCIの定義に使用するステップ

- OCIでの拡張定義操作

- LOB出力変数の定義

- LOBロケータの定義

- LOBデータの定義

- PL/SQL出力変数の定義

- ピース単位フェッチの定義

- OCIでの構造体配列のバインドと定義

- スキップ・パラメータ

- 標準配列のスキップ・パラメータ

- 構造体配列で使用されるOCIコール

- 構造体配列と標識変数

- 複数バッファのバインドと定義

- OCIでのRETURNING句を使用したDML

- 2つのSQL文を結合するためのDMLでのRETURNINGの使用

- RETURNING...INTO変数のバインド

- OCIエラー処理

- OCIでのRETURNING REF...INTO句を使用したDML

- 出力変数のバインド

- OCIコールバックに関するその他の注意

- OCIでのDML RETURNING文に対する配列インタフェース

- OCIバインドおよび定義における文字変換

- キャラクタ・セットの選択

- キャラクタ・セット・フォームとキャラクタ・セットID

- CHARとNCHARの間の暗黙的な変換

- OCIでのクライアント・キャラクタ・セットの設定

- OCIでの変数のバインド

- OCI_ATTR_MAXDATA_SIZE属性の使用

- OCI_ATTR_MAXCHAR_SIZE属性の使用

- OCIバインド時のバッファの拡張

- 定義時の制約チェック

- OCIでの文字長セマンティクスの互換性に関する一般的な問題

- OCIでのPL/SQL REF CURSORおよびNESTED TABLE

- OCIでのランタイム・データ割当てとピース単位操作

- ピース単位操作に有効なデータ型

- ピース単位操作の種類

- 実行時のINSERTまたはUPDATEデータの提供

- ピース単位の挿入または更新の実行

- PL/SQLでのピース単位操作

- PL/SQL索引付き表のバインドのサポート

- 制限

- 実行時のフェッチ情報の提供

- ピース単位フェッチの実行

- LOBのピース単位のバインドおよび定義

6 スキーマ・メタデータの記述

- OCIDescribeAny()の使用

- OCIDescribeAny()に関する制限

- 型および属性の注意

- データ型コード

- 型の記述

- 暗黙的および明示的記述操作

- OCI_ATTR_LIST_ARGUMENTS属性

- パラメータ属性

- 表またはビューのパラメータ

- プロシージャ、ファンクション、サブプログラム属性

- パッケージ属性

- 型属性

- 型属性の属性

- 型メソッド属性

- コレクション属性

- シノニム属性

- 順序属性

- 列属性

- 引数および結果の属性

- リスト属性

- スキーマ属性

- データベース属性

- ルール属性

- ルール・セット属性

- 評価コンテキスト属性

- 表別名の属性

- 変数型の属性

- 名前/値の属性

- 記述操作での文字長セマンティクスのサポート

- 暗黙的記述

- 明示的記述

- 記述に関するクライアントとサーバー間の互換性の問題

- OCIDescribeAny()の使用例

- 表用の列データ型の取出し

- ストアド・プロシージャの記述

- オブジェクト型の属性の取出し

- 名前付きコレクション型のコレクション要素のデータ型の取出し

- 文字長セマンティクスを使用した記述

7 LOBおよびBFILEの操作

- LOBでのOCI関数の使用

- 永続LOBの作成と変更

- 表内のBFILEとオペレーティング・システム・ファイルの関連付け

- オブジェクトのLOB属性

- オブジェクトのLOB属性への書込み

- LOB属性を持つ一時オブジェクト

- LOBの配列インタフェース

- 4GBより大きいサイズのLOBの使用

- 増加したLOBサイズに対して使用する関数

- 互換性および移行

- OCIのLOB関数およびBFILE関数

- LOBの読取り/書込みパフォーマンスの向上

- LOBに対するデータ・インタフェースの使用

- OCILobGetChunkSize()の使用方法

- OCILobWriteAppend2()の使用方法

- OCILobArrayRead()およびOCILobArrayWrite()の使用方法

- LOBバッファリング関数

- LOBのオープンおよびクローズのための関数

- LOBのオープンおよびクローズに関する制限事項

- LOB読取りおよび書込みコールバック

- ストリーム転送のコールバック・インタフェース

- コールバックを使用したLOBの読取り

- コールバックを使用したLOBの書込み

- 一時LOBのサポート

- 一時LOBの作成および解放

- 一時LOBの継続時間

- 一時LOBの解放

- ポインタを割り当てる際の注意事項

- 一時LOBの例

- LOBデータ、長さおよびチャンク・サイズのプリフェッチ

- SecureFiles LOBのオプション

8 スケーラブルなプラットフォームの管理

- OCIでのトランザクションのサポート

- トランザクションの複雑度のレベル

- 単純なローカル・トランザクション

- シリアライズ可能または読取り専用のローカル・トランザクション

- グローバル・トランザクション

- トランザクション識別子

- OCI_ATTR_TRANS_NAME属性

- トランザクション・ブランチ

- ブランチの状態

- ブランチの連結解除と再開

- クライアント・データベース名の設定

- 1フェーズ・コミットと2フェーズ・コミット

- 単一のメッセージによる複数のブランチの準備

- トランザクションの例

- 初期化パラメータ

- 更新成功、1フェーズ・コミット

- トランザクションの開始、連結解除、再開、準備、2フェーズ・コミット

- 読取り専用トランザクションの更新失敗

- 読取り専用トランザクションの開始、選択およびコミット

- パスワードおよびセッションの管理

- OCIの認証管理

- OCIでのパスワード管理

- セキュアな外部パスワード・ストア

- OCIでのセッション管理

- OCIでの中間層アプリケーション

- 中間層アプリケーションのOCI属性

- OCI_CRED_PROXY

- OCI_ATTR_PROXY_CREDENTIALS

- OCI_ATTR_DISTINGUISHED_NAME

- OCI_ATTR_CERTIFICATE

- OCI_ATTR_INITIAL_CLIENT_ROLES

- OCI_ATTR_CLIENT_IDENTIFIER

- OCI_ATTR_PASSWORD

- 外部でOCIから初期化されたコンテキスト

- 外部でOCIから初期化されたコンテキスト属性

- OCI_ATTR_APPCTX_SIZE

- OCI_ATTR_APPCTX_LIST

- 外部で初期化されたコンテキストの設定に使用するセッション・ハンドル属性

- エンドツーエンド・アプリケーションのトレース

- OCI_ATTR_COLLECT_CALL_TIME

- OCI_ATTR_CALL_TIME

- エンドツーエンド・アプリケーションのトレースの属性

- 外部で初期化されたコンテキストによるOCISessionBegin()の使用

- クライアント・アプリケーション・コンテキスト

- 複数のSET操作

- SET操作間のCLEAR-ALL操作

- クライアント・ネームスペースでのネットワーク・トランスポートおよびPL/SQL

- Editionベースの再定義

- OCIセキュリティ拡張機能

- 表示されるデータベース・バージョン・バナーの制御

- 不正なアクセスおよびユーザー・アクション監査用のバナー

- 非遅延リンケージ

- OCIマルチスレッド開発の概要

- OCIスレッド・セーフティの利点

- OCIスレッド・セーフティと3層アーキテクチャ

- スレッド・セーフティの実装

- ポーリング・モード操作とスレッド・セーフティ

- リリース7.xとそれより後のリリースのOCIコールの混在

- OCIThreadパッケージ

- 初期化および終了

- OCIThreadコンテキスト

- 非アクティブなスレッドの基本形

- OCIThreadMutex

- OCIThreadKey

- OCIThreadKeyDestFunc

- OCIThreadId

- アクティブなスレッドの基本形

- OCIThreadHandle

9 OCIプログラミングの高度なトピック

- OCIでの接続プーリング

- OCI接続プーリングの概念

- 共有サーバーとの類似点と相違点

- ステートレス・セッションとステートフル・セッション

- 複数の接続プール

- 透過的アプリケーション・フェイルオーバー

- 接続プーリングのOCIコール

- プール・ハンドルの割当て

- 接続プールの作成

- データベースへのログイン

- 接続プーリングでのSGA制限の処理

- データベースからのログオフ

- 接続プールの破棄

- プール・ハンドルの解放

- OCI接続プーリングの例

- OCIでのセッション・プーリング

- OCIセッション・プーリングの機能

- 同種セッション・プールおよび異種セッション・プール

- セッション・プーリングでのタグの使用

- セッション・プーリング用のOCIハンドル

- OCISPool

- OCIAuthInfo

- OCIセッション・プーリングの使用

- セッション・プーリングのOCIコール

- プール・ハンドルの割当て

- プール・セッションの作成

- データベースへのログイン

- データベースからのログオフ

- セッション・プールの破棄

- プール・ハンドルの解放

- OCIセッション・プーリングの例

- 実行時接続ロード・バランシング

- ロード・バランシング・アドバイザFANイベントの受信

- データベース常駐接続プーリング

- データベース常駐接続プーリングの構成

- DRCPでのOCIセッション・プールAPIの使用

- セッション純正値および接続クラス

- セッション純正値

- 接続クラス

- セッション純正値および接続クラスのデフォルト

- データベース常駐接続プールの開始

- データベース常駐接続プーリングの有効化

- OCIアプリケーションにおけるDRCPの拡張性による利点

- DRCPの使用に関するベスト・プラクティス

- 互換性および移行

- データベース常駐接続プーリングの使用に対する制限

- カスタム・プールでのDRCPの使用

- ステートフルまたはステートレスとしてのセッションの明示的作成

- DRCPとReal Application Clusters

- DRCPとData Guard

- 接続プーリングまたはセッション・プーリングの使用/不使用の判断

- セッション作成用の関数

- 様々なタイプのOCIセッションの選択

- OCIでの文キャッシュ

- OCIでの、セッション・プーリングを使用しない文キャッシュ

- OCIでの、セッション・プーリングを使用した文キャッシュ

- OCIでの文キャッシュの規則

- 文キャッシュでのバインドおよび定義の最適化

- OCIでの文キャッシュのコード例

- OCIでのユーザー定義コールバック関数

- OCIでのユーザー・コールバックの登録

- OCIUserCallbackRegister

- ユーザー・コールバック関数

- ユーザー・コールバックの制御フロー

- OCIErrorGet()のユーザー・コールバック

- 最初のコールバックのエラー

- 動的なコールバック登録

- 複数のパッケージのロード

- パッケージ・フォーマット

- ユーザー・コールバックの連鎖

- OCIを介した他のデータ・ソースへのアクセス

- コールバック関数の制限

- OCIコールバックの例

- 外部プロシージャからのOCIコールバック

- OCIでの透過的アプリケーション・フェイルオーバー

- 透過的アプリケーション・フェイルオーバーの構成

- OCIでの透過的アプリケーション・フェイルオーバー・コールバック

- フェイルオーバー・コールバック構造およびパラメータ

- フェイルオーバー・コールバックの登録

- フェイルオーバー・コールバックの例

- OCI_FO_ERRORの処理

- HAイベント通知

- OCIEventハンドル

- 接続プールおよびセッション・プールのOCIフェイルオーバー

- 独立した接続のOCIフェイルオーバー

- イベント・コールバック

- カスタム・プーリング: タグ付けされたサーバー・ハンドル

- 透過的アプリケーション・フェイルオーバー(TAF)機能の決定

- OCIおよびStreamsアドバンスト・キューイング

- OCI Streamsアドバンスト・キューイング関数

- OCI Streamsアドバンスト・キューイングの説明

- OCI Streamsアドバンスト・キューイングとPL/SQL

- バッファ・メッセージ

- OCIでのパブリッシュ・サブスクライブの通知

- OCIでのパブリッシュ・サブスクライブの登録関数

- データベースへのパブリッシュ・サブスクライブの直接登録

- パブリッシュ・サブスクライブのオープン登録

- OCIを使用したLDAPのオープン登録

- QOS、タイムアウト間隔、ネームスペース、クライアント・アドレスおよびポート番号の設定

- パブリッシュ・サブスクライブ通知の管理に使用するOCI関数

- OCIでの通知コールバック

- 通知プロシージャ

- パブリッシュ・サブスクライブの直接登録の例

- パブリッシュ・サブスクライブのLDAP登録の例

10 OCIに関する高度なトピック

- 連続問合せ通知

- 問合せ結果セット通知の使用

- 連続問合せ通知の登録

- 連続問合せ通知のサブスクリプション・ハンドル属性

- OCI_ATTR_CQ_QUERYID属性の使用

- 連続問合せ通知の記述子

- OCI_DTYPE_CHDES

- 連続問合せ通知の例

- データベースの起動と停止

- OCIでの起動と停止の例

- ROWIDの暗黙的フェッチ

- ROWIDの暗黙的フェッチの例

- クライアント結果キャッシュ

- クライアント結果キャッシュの利点

- クライアント結果キャッシュ使用のガイドライン

- SQLヒント

- 表注釈

- 表注釈モードのチェック

- セッション・パラメータ

- 有効な結果キャッシュ表モード

- キャッシュ例の使用例

- キャッシュされない問合せ

- クライアント・キャッシュの一貫性

- クライアント結果キャッシュに関するデプロイメント時設定

- クライアント構成ファイル

- クライアント・キャッシュの統計

- クライアント結果キャッシュの検証

- タイミングの測定

- v$mystatの使用

- v$sqlareaの使用

- OCIクライアント側結果キャッシュおよびサーバー結果キャッシュ

- クライアント結果キャッシュ・デモ・ファイル

- 以前のリリースとの互換性

- OCIでの障害診断

- ADRベースの場所

- ADRCIの使用

- sqlnet.oraを使用したADRの作成の管理および障害診断の無効化

- 異なるバージョンのタイムゾーン・ファイルで操作するクライアントとサーバー

11 OCIオブジェクト・リレーショナル・プログラミング

- OCIオブジェクトの概要

- OCIでのオブジェクトの操作

- 基本的なオブジェクト・プログラム構造体

- 永続オブジェクト、一時オブジェクトおよび値

- 永続オブジェクト

- 一時オブジェクト

- 値

- OCIオブジェクト・アプリケーションの開発

- Cアプリケーションでのオブジェクトの表現

- 環境およびオブジェクト・キャッシュの初期化

- データベース接続の実行

- サーバーからのオブジェクト参照の取出し

- オブジェクトの確保

- 配列確保

- オブジェクト属性の操作

- オブジェクトのマークおよび変更のフラッシュ

- 埋込みオブジェクトのフェッチ

- オブジェクトのメタ属性

- 永続オブジェクトのメタ属性

- その他の属性関数

- 一時オブジェクトのメタ属性

- 複合オブジェクト検索

- オブジェクトのプリフェッチ

- OCIでの複合オブジェクト検索の実装

- CORプリフェッチ

- CORインタフェース

- CORの例

- OCIとSQLのオブジェクトへのアクセス

- 確保カウントおよび確保解除

- NULLインジケータ構造体

- オブジェクトの作成

- 新規オブジェクトの属性値

- オブジェクトの解放およびコピー

- オブジェクト参照と型参照

- オブジェクト・ビューおよび主キー・ベースのOIDを備えたオブジェクト表に基づくオブジェクトの作成

- オブジェクト・アプリケーションでのエラー処理

- 型の継承

- 代入性

- NOT INSTANTIABLEの型とメソッド

- OCIでの型の継承のサポート

- OCIDescribeAny()

- バインド関数および定義関数

- OCIObjectGetTypeRef()

- OCIObjectCopy()

- OCICollAssignElem()

- OCICollAppend()

- OCICollGetElem()

- OTTでの型の継承のサポート

- 型の変更

12 OCIのオブジェクト・リレーショナル・データ型

- オブジェクトに対するOCI関数の概要

- Oracleデータ型のCへのマッピング

- OCI型マッピングの方法論

- OCIでのCデータ型の操作

- Oracle数値操作の精度

- 日付(OCIDate)

- 日付の例

- 日時および時間隔(OCIDateTime、OCIInterval)

- 日時関数

- 日時の例

- 時間隔関数

- 数値(OCINumber)

- OCINumberの例

- 固定長または可変長文字列(OCIString)

- 文字列関数

- 文字列の例

- ロー(OCIRaw)

- ロー関数

- ローの例

- コレクション(OCITable、OCIArray、OCIColl、OCIIter)

- 汎用コレクション関数

- コレクション・データ操作関数

- コレクション・スキャン関数

- VARRAY/コレクション・イテレータの例

- ネストした表の操作関数

- ネストした表の要素への順序付け

- ネストした表のロケータ

- マルチレベル・コレクション型

- マルチレベル・コレクション型の例

- REF(OCIRef)

- REF操作関数

- REFの例

- オブジェクト型情報の格納およびアクセス

- 記述子オブジェクト

- AnyTypeインタフェース、AnyDataインタフェースおよびAnyDataSetインタフェース

- 型インタフェース

- OCITypeコールのパラメータ記述子の作成

- 永続型のOCITypeの取得

- 型のアクセス・コール

- OCIDescribeAny()への拡張

- OCIAnyDataインタフェース

- OCIAnyData関数のNCHAR型コード

- OCIAnyDataSetインタフェース

- 名前付きデータ型のバインド

- 名前付きデータ型のバインド

- REFのバインド

- 名前付きデータ型およびREFバインドの情報

- 配列バインドに関する情報

- 名前付きデータ型の定義

- 名前付きデータ型出力変数の定義

- REF出力変数の定義

- 名前付きデータ型、REF定義およびPL/SQL OUTバインドの情報

- 配列定義に関する情報

- Oracle Cデータ型のバインドおよび定義

- バインドおよび定義の例

- 給与更新の例

- 方法1 - フェッチ、変換、割当て

- 方法2 - フェッチ、割当て

- 方法3 - 直接フェッチ

- まとめと注意

- SQLT_NTYのバインドおよび定義の例

- SQLT_NTYのバインドの例

- SQLT_NTYの定義の例

13 ダイレクト・パス・ロード

- ダイレクト・パス・ロードの概要

- ダイレクト・パス・ロードでサポートされるデータ型

- ダイレクト・パス・ハンドル

- ダイレクト・パス・コンテキスト

- OCIダイレクト・パス関数コンテキスト

- ダイレクト・パス列配列およびダイレクト・パス関数列配列

- ダイレクト・パス・ストリーム

- ダイレクト・パス・インタフェースの関数

- ダイレクト・パス・ロード・インタフェースに関する制限と制約

- スカラー列に対するダイレクト・パス・ロードの例

- ダイレクト・パス・ロードの例で使用されているデータ構造

- スカラー列に対するダイレクト・パス・ロードの例の概略

- OCIのダイレクト・パス・ロードでの日付キャッシュの使用

- OCI_ATTR_DIRPATH_DCACHE_SIZE

- OCI_ATTR_DIRPATH_DCACHE_NUM

- OCI_ATTR_DIRPATH_DCACHE_MISSES

- OCI_ATTR_DIRPATH_DCACHE_HITS

- OCI_ATTR_DIRPATH_DCACHE_DISABLE

- オブジェクト型のダイレクト・パス・ロード

- ネストした表のダイレクト・パス・ロード

- ネストした表の列とそのネストした表の記述

- 列オブジェクトのダイレクト・パス・ロード

- 列オブジェクトの記述

- 列配列の列オブジェクトへの割当て

- 列オブジェクト・データの列配列へのロード

- OCI_DIRPATH_COL_ERROR

- SQL文字列の列のダイレクト・パス・ロード

- SQL文字列の列の記述

- 列配列のSQL文字列の列への割当て

- SQL文字列データの列配列へのロード

- REF列のダイレクト・パス・ロード

- REF列の記述

- 列配列のREF列への割当て

- REFデータの列配列へのロード

- NOT FINALオブジェクトおよびREF列のダイレクト・パス・ロード

- 継承階層

- ロード対象の固定的な派生型の記述

- 列配列の割当て

- データの列配列へのロード

- オブジェクト表のダイレクト・パス・ロード

- NOT FINALオブジェクト表のダイレクト・パス・ロード

- ピース単位のダイレクト・パス・ロード

- オブジェクト型のピース単位のロード

- ダイレクト・パス・コンテキスト・ハンドルとオブジェクト型の属性

- ダイレクト・パス・コンテキストの属性

- OCI_ATTR_DIRPATH_OBJ_CONSTR

- ダイレクト・パス関数コンテキストと属性

- OCI_ATTR_DIRPATH_OBJ_CONSTR

- OCI_ATTR_NAME

- OCI_ATTR_DIRPATH_EXPR_TYPE

- OCI_ATTR_DIRPATH_NO_INDEX_ERRORS

- OCI_ATTR_NUM_COLS

- OCI_ATTR_NUM_ROWS

- ダイレクト・パス列パラメータ属性

- OCI_ATTR_NAME

- OCI_ATTR_DIRPATH_SID

- OCI_ATTR_DIRPATH_OID

- 非スカラー列のダイレクト・パス関数列配列ハンドル

- OCI_ATTR_NUM_ROWS属性

14 OCIのオブジェクトに関する高度なトピック

- オブジェクト・キャッシュおよびメモリー管理

- キャッシュの一貫性

- オブジェクト・キャッシュ・パラメータ

- オブジェクト・キャッシュ操作

- 確保と確保解除

- 解放

- マークとマーク解除

- フラッシュ

- リフレッシュ

- オブジェクト・コピーのロードと削除

- オブジェクト・コピーの確保

- オブジェクト・コピーの確保解除

- オブジェクト・コピーの解放

- オブジェクト・コピーの変更

- オブジェクト・コピーのマーク

- オブジェクト・コピーのマーク解除

- オブジェクト・コピーとサーバーとの同期化

- 変更をサーバーにフラッシュ

- オブジェクト・コピーのリフレッシュ

- オブジェクトのロック

- ロック・オプション

- 更新するためのオブジェクトのロック

- NOWAITオプションを使用したロック

- コミット時ロックの実装

- オブジェクト・アプリケーションでのコミットおよびロールバック

- オブジェクト継続時間

- 継続時間例

- インスタンスのメモリー・レイアウト

- オブジェクト・ナビゲーション

- 単純なオブジェクト・ナビゲーション

- OCIナビゲーショナル関数

- 確保/確保解除/解放関数

- フラッシュおよびリフレッシュ関数

- マークおよびマーク解除関数

- オブジェクトのメタ属性アクセッサ関数

- その他の関数

- 型の変更とオブジェクト・キャッシュ

- OCIでのXMLのサポート

- XMLコンテキスト

- サーバー上のXMLデータ

- OCI XML DB関数の使用

- OCIクライアントからバイナリXMLへのアクセス

- OCIアプリケーションからXMLデータへのアクセス

- リポジトリ・コンテキスト

- 専用OCI接続からのリポジトリ・コンテキストの作成

- 接続プールからのリポジトリ・コンテキストの作成

- リポジトリ・コンテキストとデータ接続の関連付け

- XMLTypeエンコーディング形式のプリファレンス設定

- 接続プールの使用例

15 OCIでのObject Type Translatorの使用

- OTTの概要

- Object Type Translatorの使用方法

- データベースでの型の作成

- OTTの起動

- コマンドライン

- 構成ファイル

- INTYPEファイル

- OTTのコマンドライン

- OTTコマンドライン起動の例

- OTT

- USERID

- INTYPE

- OUTTYPE

- CODE

- HFILE

- INITFILE

- intypeファイル

- OTTデータ型マッピング

- オブジェクト・データ型のCへのマッピング

- OTT型マッピングの例

- NULLインジケータ構造体

- OTTでの型の継承のサポート

- 置換可能なオブジェクト属性

- outtypeファイル

- OCIアプリケーションでのOTTの使用方法

- OCIでのオブジェクトへのアクセスおよび操作

- 初期化関数のコール

- 初期化関数の作業

- OTTリファレンス

- OTTコマンドラインの構文

- OTTパラメータ

- USERID

- INTYPE

- OUTTYPE

- CODE

- INITFILE

- INITFUNC

- HFILE

- CONFIG

- ERRTYPE

- CASE

- SCHEMA_NAMES

- TRANSITIVE

- URL

- OTTパラメータの指定可能な場所

- intypeファイルの構造体

- intypeファイルの型指定

- ネストされたインクルード・ファイルの生成

- SCHEMA_NAMESの使用方法

- 例: Schema_Namesの使用方法

- デフォルトの名前のマッピング

- OTTでのファイル名比較の制限事項

16 OCIリレーショナル関数

- リレーショナル関数の概要

- OCI関数の規則

- 用途

- 構文

- パラメータ

- コメント

- 戻り値

- 例

- 関連関数

- OCI関数のコール

- LOB関数用のサーバー・ラウンドトリップ

- 接続関数、認証関数および初期化関数

- OCIAppCtxClearAll()

- OCIAppCtxSet()

- OCIConnectionPoolCreate()

- OCIConnectionPoolDestroy()

- OCIDBShutdown()

- OCIDBStartup()

- OCIEnvCreate()

- OCIEnvNlsCreate()

- OCILogoff()

- OCILogon()

- OCILogon2()

- OCIServerAttach()

- OCIServerDetach()

- OCISessionBegin()

- OCISessionEnd()

- OCISessionGet()

- OCISessionPoolCreate()

- OCISessionPoolDestroy()

- OCISessionRelease()

- OCITerminate()

- ハンドル関数および記述子関数

- OCIArrayDescriptorAlloc()

- OCIArrayDescriptorFree()

- OCIAttrGet()

- OCIAttrSet()

- OCIDescriptorAlloc()

- OCIDescriptorFree()

- OCIHandleAlloc()

- OCIHandleFree()

- OCIParamGet()

- OCIParamSet()

- バインド関数、定義関数および記述関数

- OCIBindArrayOfStruct()

- OCIBindByName()

- OCIBindByPos()

- OCIBindDynamic()

- OCIBindObject()

- OCIDefineArrayOfStruct()

- OCIDefineByPos()

- OCIDefineDynamic()

- OCIDefineObject()

- OCIDescribeAny()

- OCIStmtGetBindInfo()

17 その他のOCIリレーショナル関数

- リレーショナル関数の概要

- OCI関数の規則

- 文関数

- OCIStmtExecute()

- OCIStmtFetch2()

- OCIStmtGetPieceInfo()

- OCIStmtPrepare()

- OCIStmtPrepare2()

- OCIStmtRelease()

- OCIStmtSetPieceInfo()

- LOB関数

- OCIDurationBegin()

- OCIDurationEnd()

- OCILobAppend()

- OCILobArrayRead()

- OCILobArrayWrite()

- OCILobAssign()

- OCILobCharSetForm()

- OCILobCharSetId()

- OCILobClose()

- OCILobCopy2()

- OCILobCreateTemporary()

- OCILobDisableBuffering()

- OCILobEnableBuffering()

- OCILobErase2()

- OCILobFileClose()

- OCILobFileCloseAll()

- OCILobFileExists()

- OCILobFileGetName()

- OCILobFileIsOpen()

- OCILobFileOpen()

- OCILobFileSetName()

- OCILobFlushBuffer()

- OCILobFreeTemporary()

- OCILobGetChunkSize()

- OCILobGetContentType()

- OCILobGetLength2()

- OCILobGetOptions()

- OCILobGetStorageLimit()

- OCILobIsEqual()

- OCILobIsOpen()

- OCILobIsTemporary()

- OCILobLoadFromFile2()

- OCILobLocatorAssign()

- OCILobLocatorIsInit()

- OCILobOpen()

- OCILobRead2()

- OCILobSetContentType()

- OCILobSetOptions()

- OCILobTrim2()

- OCILobWrite2()

- OCILobWriteAppend2()

- Streamsアドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数

- OCIAQDeq()

- OCIAQDeqArray()

- OCIAQEnq()

- OCIAQEnqArray()

- OCIAQListen2()

- OCISubscriptionDisable()

- OCISubscriptionEnable()

- OCISubscriptionPost()

- OCISubscriptionRegister()

- OCISubscriptionUnRegister()

- ダイレクト・パス・ロード関数

- OCIDirPathAbort()

- OCIDirPathColArrayEntryGet()

- OCIDirPathColArrayEntrySet()

- OCIDirPathColArrayReset()

- OCIDirPathColArrayRowGet()

- OCIDirPathColArrayToStream()

- OCIDirPathDataSave()

- OCIDirPathFinish()

- OCIDirPathFlushRow()

- OCIDirPathLoadStream()

- OCIDirPathPrepare()

- OCIDirPathStreamReset()

- スレッド管理関数

- OCIThreadClose()

- OCIThreadCreate()

- OCIThreadHandleGet()

- OCIThreadHndDestroy()

- OCIThreadHndInit()

- OCIThreadIdDestroy()

- OCIThreadIdGet()

- OCIThreadIdInit()

- OCIThreadIdNull()

- OCIThreadIdSame()

- OCIThreadIdSet()

- OCIThreadIdSetNull()

- OCIThreadInit()

- OCIThreadIsMulti()

- OCIThreadJoin()

- OCIThreadKeyDestroy()

- OCIThreadKeyGet()

- OCIThreadKeyInit()

- OCIThreadKeySet()

- OCIThreadMutexAcquire()

- OCIThreadMutexDestroy()

- OCIThreadMutexInit()

- OCIThreadMutexRelease()

- OCIThreadProcessInit()

- OCIThreadTerm()

- トランザクション関数

- OCITransCommit()

- OCITransDetach()

- OCITransForget()

- OCITransMultiPrepare()

- OCITransPrepare()

- OCITransRollback()

- OCITransStart()

- その他の関数

- OCIBreak()

- OCIClientVersion()

- OCIErrorGet()

- OCILdaToSvcCtx()

- OCIPasswordChange()

- OCIPing()

- OCIReset()

- OCIRowidToChar()

- OCIServerRelease()

- OCIServerVersion()

- OCISvcCtxToLda()

- OCIUserCallbackGet()

- OCIUserCallbackRegister()

18 OCIのナビゲーショナル関数と型関数

- ナビゲーショナル関数および型関数の概要

- オブジェクト型と存続期間

- 用語

- OCI関数の規則

- 戻り値

- ナビゲーショナル関数の戻り値

- キャッシュ関数およびオブジェクト関数用のサーバー・ラウンドトリップ

- ナビゲーショナル関数エラー・コード

- OCIフラッシュまたはリフレッシュ関数

- OCICacheFlush()

- OCICacheRefresh()

- OCIObjectFlush()

- OCIObjectRefresh()

- OCIオブジェクトおよびキャッシュへのマークまたはマーク解除関数

- OCICacheUnmark()

- OCIObjectMarkDelete()

- OCIObjectMarkDeleteByRef()

- OCIObjectMarkUpdate()

- OCIObjectUnmark()

- OCIObjectUnmarkByRef()

- OCIのオブジェクト・ステータス取得関数

- OCIObjectExists()

- OCIObjectGetProperty()

- OCIObjectIsDirty()

- OCIObjectIsLocked()

- その他のOCIオブジェクト関数

- OCIObjectCopy()

- OCIObjectGetAttr()

- OCIObjectGetInd()

- OCIObjectGetObjectRef()

- OCIObjectGetTypeRef()

- OCIObjectLock()

- OCIObjectLockNoWait()

- OCIObjectNew()

- OCIObjectSetAttr()

- OCIの確保関数、確保解除関数および解放関数

- OCICacheFree()

- OCICacheUnpin()

- OCIObjectArrayPin()

- OCIObjectFree()

- OCIObjectPin()

- OCIObjectPinCountReset()

- OCIObjectPinTable()

- OCIObjectUnpin()

- OCIの型情報アクセッサ関数

- OCITypeArrayByName()

- OCITypeArrayByRef()

- OCITypeByName()

- OCITypeByRef()

19 OCIのデータ型マッピング関数および操作関数

- データ型マッピング関数および操作関数の概要

- OCI関数の規則

- 戻り値

- データ型マッピング関数および操作関数の戻り値

- その他の値を戻す関数

- データ型マッピング関数および操作関数のサーバー・ラウンドトリップ回数

- 例

- OCIコレクションおよびイテレータ関数

- OCICollAppend()

- OCICollAssign()

- OCICollAssignElem()

- OCICollGetElem()

- OCICollGetElemArray()

- OCICollIsLocator()

- OCICollMax()

- OCICollSize()

- OCICollTrim()

- OCIIterCreate()

- OCIIterDelete()

- OCIIterGetCurrent()

- OCIIterInit()

- OCIIterNext()

- OCIIterPrev()

- OCIの日付関数、日時関数および時間隔関数

- OCIDateAddDays()

- OCIDateAddMonths()

- OCIDateAssign()

- OCIDateCheck()

- OCIDateCompare()

- OCIDateDaysBetween()

- OCIDateFromText()

- OCIDateGetDate()

- OCIDateGetTime()

- OCIDateLastDay()

- OCIDateNextDay()

- OCIDateSetDate()

- OCIDateSetTime()

- OCIDateSysDate()

- OCIDateTimeAssign()

- OCIDateTimeCheck()

- OCIDateTimeCompare()

- OCIDateTimeConstruct()

- OCIDateTimeConvert()

- OCIDateTimeFromArray()

- OCIDateTimeFromText()

- OCIDateTimeGetDate()

- OCIDateTimeGetTime()

- OCIDateTimeGetTimeZoneName()

- OCIDateTimeGetTimeZoneOffset()

- OCIDateTimeIntervalAdd()

- OCIDateTimeIntervalSub()

- OCIDateTimeSubtract()

- OCIDateTimeSysTimeStamp()

- OCIDateTimeToArray()

- OCIDateTimeToText()

- OCIDateToText()

- OCIDateZoneToZone()

- OCIIntervalAdd()

- OCIIntervalAssign()

- OCIIntervalCheck()

- OCIIntervalCompare()

- OCIIntervalDivide()

- OCIIntervalFromNumber()

- OCIIntervalFromText()

- OCIIntervalFromTZ()

- OCIIntervalGetDaySecond()

- OCIIntervalGetYearMonth()

- OCIIntervalMultiply()

- OCIIntervalSetDaySecond()

- OCIIntervalSetYearMonth()

- OCIIntervalSubtract()

- OCIIntervalToNumber()

- OCIIntervalToText()

- OCI NUMBER関数

- OCINumberAbs()

- OCINumberAdd()

- OCINumberArcCos()

- OCINumberArcSin()

- OCINumberArcTan()

- OCINumberArcTan2()

- OCINumberAssign()

- OCINumberCeil()

- OCINumberCmp()

- OCINumberCos()

- OCINumberDec()

- OCINumberDiv()

- OCINumberExp()

- OCINumberFloor()

- OCINumberFromInt()

- OCINumberFromReal()

- OCINumberFromText()

- OCINumberHypCos()

- OCINumberHypSin()

- OCINumberHypTan()

- OCINumberInc()

- OCINumberIntPower()

- OCINumberIsInt()

- OCINumberIsZero()

- OCINumberLn()

- OCINumberLog()

- OCINumberMod()

- OCINumberMul()

- OCINumberNeg()

- OCINumberPower()

- OCINumberPrec()

- OCINumberRound()

- OCINumberSetPi()

- OCINumberSetZero()

- OCINumberShift()

- OCINumberSign()

- OCINumberSin()

- OCINumberSqrt()

- OCINumberSub()

- OCINumberTan()

- OCINumberToInt()

- OCINumberToReal()

- OCINumberToRealArray()

- OCINumberToText()

- OCINumberTrunc()

- OCIロー関数

- OCIRawAllocSize()

- OCIRawAssignBytes()

- OCIRawAssignRaw()

- OCIRawPtr()

- OCIRawResize()

- OCIRawSize()

- OCI REF関数

- OCIRefAssign()

- OCIRefClear()

- OCIRefFromHex()

- OCIRefHexSize()

- OCIRefIsEqual()

- OCIRefIsNull()

- OCIRefToHex()

- OCI文字列関数

- OCIStringAllocSize()

- OCIStringAssign()

- OCIStringAssignText()

- OCIStringPtr()

- OCIStringResize()

- OCIStringSize()

- OCI表関数

- OCITableDelete()

- OCITableExists()

- OCITableFirst()

- OCITableLast()

- OCITableNext()

- OCITablePrev()

- OCITableSize()

20 OCIカートリッジ関数

- 外部プロシージャ関数およびカートリッジ・サービス関数の概要

- OCI関数の規則

- リターン・コード

- With_Context型

- カートリッジ・サービス: OCI外部プロシージャ

- OCIExtProcAllocCallMemory()

- OCIExtProcGetEnv()

- OCIExtProcRaiseExcp()

- OCIExtProcRaiseExcpWithMsg()

- カートリッジ・サービス: メモリー・サービス

- OCIDurationBegin()

- OCIDurationEnd()

- OCIMemoryAlloc()

- OCIMemoryFree()

- OCIMemoryResize()

- カートリッジ・サービス: コンテキストのメンテナンス

- OCIContextClearValue()

- OCIContextGenerateKey()

- OCIContextGetValue()

- OCIContextSetValue()

- カートリッジ・サービス: パラメータ・マネージャ・インタフェース

- OCIExtractFromFile()

- OCIExtractFromList()

- OCIExtractFromStr()

- OCIExtractInit()

- OCIExtractReset()

- OCIExtractSetKey()

- OCIExtractSetNumKeys()

- OCIExtractTerm()

- OCIExtractToBool()

- OCIExtractToInt()

- OCIExtractToList()

- OCIExtractToOCINum()

- OCIExtractToStr()

- カートリッジ・サービス: ファイルI/Oインタフェース

- OCIFileClose()

- OCIFileExists()

- OCIFileFlush()

- OCIFileGetLength()

- OCIFileInit()

- OCIFileOpen()

- OCIFileRead()

- OCIFileSeek()

- OCIFileTerm()

- OCIFileWrite()

- カートリッジ・サービス: 文字列のフォーマット・インタフェース

- OCIFormatInit()

- OCIFormatString()

- OCIFormatTerm()

21 OCIの任意型関数および任意データ関数

- 任意型インタフェースおよび任意データ・インタフェースの概要

- OCI関数の規則

- 関数戻り値

- OCIの型インタフェース関数

- OCITypeAddAttr()

- OCITypeBeginCreate()

- OCITypeEndCreate()

- OCITypeSetBuiltin()

- OCITypeSetCollection()

- OCI任意データ・インタフェース関数

- OCIAnyDataAccess()

- OCIAnyDataAttrGet()

- OCIAnyDataAttrSet()

- OCIAnyDataBeginCreate()

- OCIAnyDataCollAddElem()

- OCIAnyDataCollGetElem()

- OCIAnyDataConvert()

- OCIAnyDataDestroy()

- OCIAnyDataEndCreate()

- OCIAnyDataGetCurrAttrNum()

- OCIAnyDataGetType()

- OCIAnyDataIsNull()

- OCIAnyDataTypeCodeToSqlt()

- OCI任意データ・セット・インタフェース関数

- OCIAnyDataSetAddInstance()

- OCIAnyDataSetBeginCreate()

- OCIAnyDataSetDestroy()

- OCIAnyDataSetEndCreate()

- OCIAnyDataSetGetCount()

- OCIAnyDataSetGetInstance()

- OCIAnyDataSetGetType()

22 OCIグローバリゼーション・サポート関数

- OCIにおけるグローバリゼーション・サポートの概要

- OCI関数の規則

- 戻り値

- OCIロケール関数

- OCINlsCharSetIdToName()

- OCINlsCharSetNameToId()

- OCINlsEnvironmentVariableGet()

- OCINlsGetInfo()

- OCINlsNumericInfoGet()

- OCIロケールマッピング関数

- OCINlsNameMap()

- OCI文字列操作関数

- OCIMultiByteInSizeToWideChar()

- OCIMultiByteStrCaseConversion()

- OCIMultiByteStrcat()

- OCIMultiByteStrcmp()

- OCIMultiByteStrcpy()

- OCIMultiByteStrlen()

- OCIMultiByteStrncat()

- OCIMultiByteStrncmp()

- OCIMultiByteStrncpy()

- OCIMultiByteStrnDisplayLength()

- OCIMultiByteToWideChar()

- OCIWideCharInSizeToMultiByte()

- OCIWideCharMultibyteLength()

- OCIWideCharStrCaseConversion()

- OCIWideCharStrcat()

- OCIWideCharStrchr()

- OCIWideCharStrcmp()

- OCIWideCharStrcpy()

- OCIWideCharStrlen()

- OCIWideCharStrncat()

- OCIWideCharStrncmp()

- OCIWideCharStrncpy()

- OCIWideCharStrrchr()

- OCIWideCharToLower()

- OCIWideCharToMultiByte()

- OCIWideCharToUpper()

- OCI文字分類関数

- OCIWideCharIsAlnum()

- OCIWideCharIsAlpha()

- OCIWideCharIsCntrl()

- OCIWideCharIsDigit()

- OCIWideCharIsGraph()

- OCIWideCharIsLower()

- OCIWideCharIsPrint()

- OCIWideCharIsPunct()

- OCIWideCharIsSingleByte()

- OCIWideCharIsSpace()

- OCIWideCharIsUpper()

- OCIWideCharIsXdigit()

- OCIキャラクタ・セット変換関数

- OCICharSetConversionIsReplacementUsed()

- OCICharSetToUnicode()

- OCINlsCharSetConvert()

- OCIUnicodeToCharSet()

- OCIメッセージ関数

- OCIMessageClose()

- OCIMessageGet()

- OCIMessageOpen()

23 OCI XML DB関数

- OCIにおけるXML DBサポートの概要

- OCI関数の規則

- 戻り値

- OCI XML DB関数

- OCIBinXmlCreateReposCtxFromConn()

- OCIBinXmlCreateReposCtxFromCPool()

- OCIBinXmlSetFormatPref()

- OCIBinXmlSetReposCtxForConn()

- OCIXmlDbFreeXmlCtx()

- OCIXmlDbInitXmlCtx()

A ハンドルおよび記述子の属性

- 表記規則

- 環境ハンドル属性

- エラー・ハンドル属性

- サービス・コンテキスト・ハンドル属性

- サーバー・ハンドル属性

- 認証情報ハンドル

- ユーザー・セッション・ハンドル属性

- 管理ハンドル属性

- 接続プール・ハンドル属性

- セッション・プール・ハンドル属性

- トランザクション・ハンドル属性

- 文ハンドル属性

- バインド・ハンドル属性

- 定義ハンドル属性

- 記述ハンドル属性

- パラメータ記述子属性

- LOBロケータ属性

- 複合オブジェクト属性

- 複合オブジェクト検索ハンドル属性

- 複合オブジェクト検索記述子の属性

- Streamsアドバンスト・キューイング記述子の属性

- OCIAQEnqOptions記述子の属性

- OCIAQDeqOptions記述子の属性

- OCIAQMsgProperties記述子の属性

- OCIAQAgent記述子の属性

- OCIServerDNs記述子の属性

- サブスクリプション・ハンドル属性

- 連続問合せ通知属性

- 連続問合せ通知の記述子の属性

- 通知の記述子の属性

- 無効化された問合せの属性

- ダイレクト・パス・ロード・ハンドル属性

- ダイレクト・パス・コンテキスト・ハンドル(OCIDirPathCtx)の属性

- ダイレクト・パス関数のコンテキスト・ハンドル(OCIDirPathFuncCtx)属性

- ダイレクト・パス関数の列配列ハンドル(OCIDirPathColArray)属性

- ダイレクト・パス・ストリーム・ハンドル(OCIDirPathStream)属性

- ダイレクト・パス列パラメータ属性

- 列パラメータ属性へのアクセス

- プロセス・ハンドル属性

- イベント・ハンドル属性

B OCIデモ・プログラム

C OCI関数のサーバー・ラウンドトリップ

- サーバー・ラウンドトリップの概要

- リレーショナル関数のラウンドトリップ

- LOB関数のラウンドトリップ

- オブジェクト関数およびキャッシュ関数のラウンドトリップ

- 記述操作のラウンドトリップ

- データ型マッピング関数および操作関数のラウンドトリップ

- 任意型関数および任意データ関数のラウンドトリップ

- その他のローカル関数

D OCI for Windowsスタート・ガイド

- OCI for Windowsパッケージの内容

- WindowsでのOracleディレクトリ構造

- Windows用サンプルOCIプログラム

- Windows用OCIアプリケーションのコンパイル

- Windows用OCIアプリケーションのリンク

- oci.lib

- LoadLibrary()使用時のクライアントDLLのロード

- Windows用OCIアプリケーションの実行

- Oracle XAライブラリ

- Oracle XAライブラリを使用したOCIプログラムのコンパイルおよびリンク

- XAの動的な登録の使用

- 現行セッション用の環境変数の追加

- 全セッション用のレジストリ変数の追加

- レジストリ変数の追加手順

- XAおよびTPモニターに関する情報

- Object Type Translator for Windowsの使用

E 非推奨のOCI関数

- 非推奨の初期化関数

- OCIEnvInit()

- OCIInitialize()

- 非推奨の文関数

- OCIStmtFetch()

- 非推奨のLOB関数

- OCILobCopy()

- OCILobErase()

- OCILobGetLength()

- OCILobLoadFromFile()

- OCILobRead()

- OCILobTrim()

- OCILobWrite()

- OCILobWriteAppend()

- 非推奨のStreamsアドバンスト・キューイング関数

- OCIAQListen()

索引

例一覧

- 2-1 セッション・ハンドルでユーザー名を設定するためのOCI_ATTR_USERNAME属性の使用

- 2-2 選択リスト項目に関する記述情報の文ハンドルへの戻り

- 2-3 シングル・ユーザー・セッションのためのOCILogon2コールの使用

- 2-4 ローカル・ユーザーに別のユーザーの代理の役割を付与

- 2-5 代理ユーザー用に使用する接続文字列

- 2-6 ローカル・ユーザーに別のユーザーの代理の役割を付与する際の大文字と小文字の区別の維持

- 2-7 接続文字列での大文字と小文字の区別の維持

- 2-8 接続文字列での"dilbert[mybert]"の使用

- 2-9 接続文字列での"dilbert[mybert]"["joe[myjoe]"]の使用

- 2-10 ターゲット・ユーザー名の設定

- 2-11 OCIを使用したOCI_ATTR_PROXY_CLIENT属性および代理dilbertの設定

- 2-12 OCI環境の作成および初期化

- 2-13 OCIでのロケール情報取得

- 2-14 OCIでの基本的な文字列操作

- 2-15 OCIでの文字列分類

- 2-16 OCIでのキャラクタ・セットの変換

- 2-17 テキスト・メッセージ・ファイルからのメッセージ取得

- 3-1 64ビット整数のOCIバインドおよび定義のサポート

- 3-2 文を戻すDMLのOUTバインドの8バイト整数データ型のバインド

- 4-1 問合せ以外の操作での入力変数と出力変数両方のバインド

- 4-2 配列DML操作中に発生したエラー数を取り出すためのOCIAttrGet()のコール

- 4-3 配列のDML操作後の各エラーに関する情報の取出し

- 4-4 バッチ・エラー実行モードの使用

- 4-5 暗黒的記述 - 選択リストは文ハンドルの属性として取得可能

- 4-6 明示的記述 - 列ごとに選択リストの記述を戻す

- 4-7 スクロール・カーソルでのアクセス

- 5-1 SQL文の各プレースホルダのハンドル割当てとバインド

- 5-2 OCIで使用されるPL/SQL文の定義

- 5-3 単一のロケータを挿入するためのプレースホルダのバインドと文の実行

- 5-4 ロケータ配列を挿入するためのプレースホルダのバインドと文の実行

- 5-5 実行できない一部の暗黙的変換の説明

- 5-6 可能: C1、C2およびL列に、それぞれサイズが最大8000、8000および2000バイトのバインド可変データ値を挿入

- 5-7 可能: C1およびL列に、それぞれサイズが最大2000および8000バイトのバインド可変データ値を挿入

- 5-8 可能: C1、C2およびL列を、それぞれサイズが最大8000、8000および2000バイトのバインド可変データ値に更新

- 5-9 可能: C1、C2およびL列を、それぞれサイズが最大2000、2000および8000バイトのバインド可変データ値に更新

- 5-10 可能: ピース単位、コールバックおよび配列挿入または更新の操作

- 5-11 不可能: LOB列とLONG列の両方に4000バイトを超えるデータを同じINSERT文を使用して挿入

- 5-12 可能: CT3 LOB列にサイズが最大2000バイトのバインド変数データ値を挿入

- 5-13 不可能: 選択操作としての挿入で任意の長さのデータをLOB列にバインド

- 5-14 実行および記述操作後のスカラー出力変数の定義

- 5-15 実行前のLOBの定義

- 5-16 実行後のLOBの定義

- 5-17 複数のバインドおよび定義バッファの使用

- 5-18 OCIアプリケーションでのREF出力変数のバインド

- 5-19 OCIでのクライアント・キャラクタ・セットのOCI_UTF16IDへの設定

- 5-20 OCI_ATTR_MAXCHAR_SIZE属性を使用した挿入および選択操作

- 5-21 UTF-16データのバインドと定義

- 5-22 プレースホルダ:cursor1を文ハンドルstm2pにREF CURSORとしてバインド

- 5-23 ネストした表(2番目の位置)を文ハンドルとして定義

- 6-1 オブジェクト・モードでのOCIプロセスの初期化

- 6-2 表の列データ型を取り出す明示的な記述の使用方法

- 6-3 ストアド・プロシージャの記述

- 6-4 名前付きオブジェクト型についての明示的な記述の使用方法

- 6-5 名前付きコレクション型についての明示的な記述の使用

- 6-6 データ型、列名および文字長セマンティクスを取り出すためのパラメータ記述子の使用

- 7-1 LOBロケータの使用と記述子の割当て

- 7-2 OCILobRead2()を使用した読取りコールバック関数の実装

- 7-3 OCILobWrite2()を使用した書込みコールバック関数の実装

- 7-4 一時LOBの使用方法

- 7-5 LOBデータ、長さおよびチャンク・サイズのプリフェッチ

- 8-1 サーバー・グループ名を渡すためのOCI_ATTR_SERVER_GROUP属性の定義

- 8-2 クライアント認証用のアプリケーション・サーバーの資格証明を指定するためのOCI_ATTR_PROXY_CREDENTIALS属性の定義

- 8-3 クライアントの識別名を渡すためのOCI_ATTR_DISTINGUISHED_NAME属性の定義

- 8-4 X.509証明書全体を渡すためのOCI_ATTR_CERTIFICATE属性の定義

- 8-5 クライアント・ロールを渡すためのOCI_ATTR_INITIAL_CLIENT_ROLES属性の定義

- 8-6 エンドユーザー識別情報を渡すためのOCI_ATTR_CLIENT_IDENTIFIER属性の定義

- 8-7 検証のパスワードを渡すためのOCI_ATTR_PASSWORD属性の定義

- 8-8 クライアントの外部名と初期権限を指定できるOCI属性

- 8-9 コンテキストの配列サイズを任意の数のコンテキスト属性で初期化するためのOCI_ATTR_APPCTX_SIZE属性の定義

- 8-10 セッションに対するアプリケーション・コンテキスト・リスト記述子のハンドルを取得するためのOCI_ATTR_APPCTX_LIST属性の使用

- 8-11 アプリケーション・コンテキスト・リスト記述子を使用して、i番目のアプリケーション・コンテキストの個々の記述子を取得するためのOCIParamGet()のコール

- 8-12 外部で初期化されたコンテキストを設定するためのセッション・ハンドル属性の定義

- 8-13 最後のサーバー・コールの経過時間を取得するためのOCI_ATTR_CALL_TIME属性の使用

- 8-14 外部で初期化されたコンテキストによるOCISessionBegin()の使用

- 8-15 CLIENTCONTEXTネームスペース内の"responsibility"属性値の変更

- 8-16 クライアント・ネームスペース内の特定の属性情報を消去するための2つの方法

- 8-17 特定のクライアント・ネームスペースでのすてべのコンテキスト情報の消去

- 8-18 OCI_ATTR_EDITION属性を設定するためのOCIAttrSet()のコール

- 9-1 セッション純正値の設定

- 9-2 接続クラスをHRMSとして設定

- 9-3 接続クラスをRECMSとして設定

- 9-4 DRCP有効化のために簡易接続文字列で:POOLEDを指定

- 9-5 DRCP有効化のためにTNS接続文字列でSERVER=POOLEDを指定

- 9-6 データベース常駐接続プーリング・アプリケーション

- 9-7 DRCPが無効である専用サーバー・モードのデプロイメントで使用する接続文字列

- 9-8 DRCPが有効であるデプロイメントに使用する接続文字列

- 9-9 キャッシュ内の文に対するバインドおよび定義操作の最適化

- 9-10 典型的なOCIコールの全体的な処理を説明する擬似コード

- 9-11 ORA_OCI_UCBPKG変数に対する環境変数の設定

- 9-12 pkgNInit()関数とPkgNEnvCallback()関数の指定

- 9-13 pkgNEnvCallback()を使用した最初、置換および最後のコールバックの登録

- 9-14 ユーザー・コールバックのNULL ucbDescへの登録

- 9-15 コールバックを順にコールするためのOCIStmtPrepare()の使用

- 9-16 ユーザー定義フェイルオーバー・コールバック関数の定義

- 9-17 フェイルオーバー・コールバックの登録

- 9-18 フェイルオーバー・コールバックの登録解除

- 9-19 フェイルオーバー手法を実装するコールバック関数

- 9-20 イベント通知

- 9-21 エンキュー・バッファ・メッセージ

- 9-22 デキュー・バッファ・メッセージ

- 9-23 QOSレベル、通知グループ化のクラス、値およびタイプ、ネームスペース固有のコンテキストの設定

- 9-24 OCI通知コールバックでのAQグループ化通信属性の使用

- 9-25 パブリッシュ・サブスクライブ通知の実装

- 9-26 コールバック関数を使用する通知の登録

- 9-27 LDAP登録

- 10-1 連続問合せ通知を説明するプログラムのリスト

- 10-2 データベースの起動操作を実行するOCIDBStartup()のコール

- 10-3 OCI_DBSHUTDOWN_FINALモードでのOCIDBShutdown()のコール

- 10-4 OCI_DBSHUTDOWN_ABORTモードでのOCIDBShutdown()のコール

- 10-5 ROWIDの暗黙的フェッチ

- 11-1 スタンドアロン・オブジェクトのSQL定義

- 11-2 埋込みオブジェクトのSQL定義

- 11-3 オブジェクトの確保

- 11-4 OCIでのオブジェクト属性の操作

- 11-5 OCIでの複合オブジェクト検索の使用

- 11-6 型のC表現とそれらに対応するNULLインジケータ構造体

- 11-7 オブジェクト・ビューに対する新規オブジェクトの作成

- 12-1 OCIDate型の属性の操作

- 12-2 OCIDateTime型の属性の操作

- 12-3 OCINumber型の属性の操作

- 12-4 OCIDescribeAny()コールから戻されたOCINumber形式の値の符号なし整数への変換

- 12-5 OCIString型の属性の操作

- 12-6 OCIRaw型の属性の操作

- 12-7 コレクション・データ操作関数の使用

- 12-8 マルチレベル・コレクション・データ操作関数の使用

- 12-9 REF操作関数の使用

- 12-10 型インタフェースを使用したオブジェクト型の作成

- 12-11 型インタフェースを使用したコレクション型の作成

- 12-12 パフォーマンス改善のための特別な構成とアクセス・コールの使用

- 12-13 給与更新の方法1: フェッチ、変換、割当て

- 12-14 給与更新の方法2: フェッチ、割当て、変換なし

- 12-15 給与更新の方法3: 直接フェッチ

- 12-16 OCIBindObject()などのSQLT_NTYバインド・コールの使用

- 12-17 OCIDefineObject()などのSQLT_NTY定義コールの使用

- 13-1 ヘッダー・ファイルを組み込む必要があるダイレクト・パス・プログラム

- 13-2 関数コンテキストを割り当てるためにハンドル型を渡す例

- 13-3 ダイレクト・パス列配列ハンドルの明示的な割当て

- 13-4 ダイレクト・パス関数列配列ハンドルの明示的な割当て

- 13-5 ダイレクト・パス・ストリーム・ハンドルの割当て

- 13-6 ダイレクト・パス・ロードの例で使用されているデータ構造

- 13-7 ヘッダー・ファイルcdemodp.hの内容

- 13-8 OCIダイレクト・パス・インタフェースの使用方法

- 13-9 列配列とストリーム・ハンドルの割当て

- 13-10 行数と列数の取得

- 13-11 入力データ・フィールドの設定

- 13-12 列配列の状態のリセット

- 13-13 ストリームの状態のリセット

- 13-14 データのストリーム形式への変換

- 13-15 ストリームのロード

- 13-16 ダイレクト・パス・ロード操作の終了

- 13-17 ダイレクト・パス・ハンドルの解放

- 13-18 列オブジェクトへの子の列配列の割当て

- 13-19 SQL文字列の列への子の列配列の割当て

- 13-20 REF列への子の列配列の割当て

- 13-21 列配列のオブジェクト表への割当て

- 13-22 OCI_ATTR_DIRPATH_EXPR_TYPE属性への値の指定

- 13-23 列属性としての関数コンテキストの設定

- 13-24 関数コンテキストへの子の列配列の割当て

- 14-1 Department行のオブジェクト型の表現

- 14-2 Department行のC表現

- 14-3 C APIによるXMLコンテキストの初期化および終了

- 15-1 intypeファイルにリストされたemployeeオブジェクト型の定義

- 15-2 生成されたヘッダー・ファイルdemo.hの内容

- 15-3 demov.cファイルの内容

- 15-4 コマンドラインからのOTTの起動

- 15-5 ユーザー作成intypeファイルの内容

- 15-6 従業員用のオブジェクト型定義

- 15-7 OTTで生成した構造体宣言

- 15-8 OTT型マッピング用のオブジェクト型定義の例

- 15-9 オブジェクト型定義からOTTで作成される各種の型のマッピング

- 15-10 オブジェクト型とサブタイプの定義

- 15-11 intypeファイルの内容

- 15-12 OTTによる型に対するC構造体とNULLインジケータ構造体の生成

- 15-13 intypeファイルの内容

- 15-14 OTT実行後のouttypeファイルの内容

- 15-15 ex2c.typという名前のintypeファイルの内容

- 15-16 OTTの起動と初期化関数の指定

- 15-17 ex2cv.cという名前のOTTで生成したファイルの内容

- 15-18 OTTによるインクルード・ファイルの生成方法を示すオブジェクト型定義

- 15-19 intypeファイルの内容

- 15-20 コマンドラインからのOTTの起動

- 15-21 ヘッダー・ファイルtott95b.hの内容

- 15-22 ヘッダー・ファイルtott95a.hの内容

- 15-23 ヘッダー・ファイルtott95b.hを条件付きで組み込むために使用する構造体

- 16-1 N置換をオンにしたスレッド・セーフのOCI環境の作成

- 16-2 OCIServerAttach()コールの使用

- 16-3 OCISessionBegin()コールの使用

- 16-4 OCIセッション・プーリングを指定したOCI_ATTR_MODULE属性の使用

- 16-5 OCIセッション・プーリングを指定したOCI_ATTR_EDITION属性の使用

- 16-6 実行時ロード・バランシングの無効化

- 16-7 多数の記述子の割当て

- 16-8 記述子の配列のを割当て

- 17-1 source_locソース・ロケータの割当て

- 17-2 dest_loc宛先ロケータのの割当て

- 17-3 単純なローカル・トランザクションでのOCITransCommit()の使用

- 17-4 様々なブランチで動作するシングル・セッションでのOCITransStart()の使用

- 17-5 同じトランザクションを共有する複数のブランチで動作するシングル・セッションでのOCITransStart()の使用

- 17-6 OCIErrorGet()を使用したエラー・チェック

- 19-1 コレクション要素へのポインタへの新しい参照の割当て

- 19-2 OCINumberAssign()コールのプロトタイプ

- 19-3 指定した日付以降の指定した曜日の日付の取得

- 19-4 ネストした表からの要素の削除

- 19-5 ネストした表から削除された要素を含めたすべての要素のカウントの取得

- 20-1 OCIExtProcAllocCallMemory()を使用した1024バイトのメモリーの割当て

- 20-2 OCIFormatString()を使用した、2つの方法での2つの国の日付のフォーマット

図一覧

- 2-1基本的なOCIプログラムの流れ

- 2-2 サービス・コンテキストのコンポーネント

- 2-3 文ハンドル

- 2-4 ダイレクト・パス・ハンドル

- 4-1 SQL文の処理におけるステップ

- 5-1 OCIBindByName()を使用したプレースホルダとプログラム変数の関連付け

- 5-2 スキップ・パラメータの決定

- 5-3 ピース単位挿入の実行

- 5-4 ピース単位フェッチの実行

- 6-1 OCIDescribeAny()の表記述

- 8-1 複数の密結合ブランチ

- 8-2 複数のブランチで動作するセッション

- 9-1 OCI接続プーリング

- 9-2 パブリッシュ・サブスクライブのモデル

- 11-1 基本的なオブジェクト操作のフロー

- 13-1 ダイレクト・パス・ロード

- 13-2 Person型の列の継承階層

- 14-1 オブジェクト・キャッシュ

- 14-2 person_tインスタンスのオブジェクト・グラフ

- 15-1 OCIアプリケーションでのOTTの使用方法

- 18-1 インスタンスの型と存続期間による分類

表一覧

- 1-1 使用されなくなったOCI関数

- 1-2 サポートされないOCI関数

- 1-3 OCI Instant Client共有ライブラリ

- 1-4 OCI Instant Client Light共有ライブラリ

- 2-1 OCIハンドル・タイプ

- 2-2 記述子タイプ

- 2-3 OCIリターン・コード

- 2-4 リターン・コードとエラー・コード

- 2-5 Oracle予約済ネームスペース

- 3-1 Oracle Database内部データ型

- 3-2 外部データ型とそのコード

- 3-3 VARNUMの例

- 3-4 DATEデータ型の書式

- 3-5 データ変換

- 3-6 LOBのデータ変換

- 3-7 日時および時間隔データ型のデータ変換

- 3-8 外部データ型から内部数値データ型へのデータ変換

- 3-9 内部データ型から外部数値データ型へのデータ変換

- 3-10 OCITypeCodeの値とデータ型

- 3-11 OCI_TYPECODEからSQLTへのマップ

- 4-1 OCI_ATTR_STMT_TYPE値および文の種類

- 5-1 バインド・タイプの情報の概要

- 6-1 すべてのパラメータの属性

- 6-2 表またはビューの属性

- 6-3 表に特有の属性

- 6-4 プロシージャまたはファンクションの属性

- 6-5 パッケージ・サブプログラムに特有の属性

- 6-6 パッケージの属性

- 6-7 型の属性

- 6-8 型属性の属性

- 6-9 型メソッドの属性

- 6-10 コレクション型の属性

- 6-11 シノニムの属性

- 6-12 順序の属性

- 6-13 表またはビューの列の属性

- 6-14 引数および結果の属性

- 6-15 リスト属性

- 6-16 スキーマ固有の属性

- 6-17 データベース固有の属性

- 6-18 ルールに特有の属性

- 6-19 ルール・セットに特有の属性

- 6-20 評価コンテキストに特有の属性

- 6-21 表別名に特有の属性

- 6-22 変数型に特有の属性

- 6-23 名前/値ペアに特有の属性

- 7-1 LOB関数の互換性および移行

- 8-1 グローバル・トランザクション識別子

- 8-2 1フェーズ・コミット

- 8-3 2フェーズ・コミット

- 8-4 読取り専用トランザクションの更新失敗

- 8-5 読取り専用トランザクション

- 8-6 初期化マルチスレッド関数および終了マルチスレッド関数

- 8-7 非アクティブなスレッドの基本形

- 8-8 アクティブなスレッドの基本形

- 9-1 各種クライアント・シナリオで使用されるデフォルト

- 9-2 時間およびイベント

- 9-3 AQ関数

- 9-4 エンキュー・パラメータ

- 9-5 デキュー・パラメータ

- 9-6 リスニング・パラメータ

- 9-7 配列エンキュー・パラメータ

- 9-8 配列デキュー・パラメータ

- 9-9 エージェント・パラメータ

- 9-10 メッセージ・プロパティ

- 9-11 エンキュー・オプション属性

- 9-12 デキュー・オプション属性

- 9-13 パブリッシュ・サブスクライブの関数

- 10-1 DDL表の結果キャッシュ注釈モード

- 10-2 有効な結果キャッシュ表モード

- 10-3 クライアント側結果キャッシュとサーバー結果キャッシュの設定

- 11-1 永続オブジェクトのメタ属性

- 11-2 設定およびチェック関数

- 11-3 一時メタ属性

- 11-4 新しいオブジェクトの属性値

- 12-1 関数の接頭辞の例

- 12-2 日時および時間隔データ型のバインドと定義

- 12-3 日時関数

- 12-4 時間隔関数

- 12-5 文字列関数

- 12-6 ロー関数

- 12-7 コレクション関数

- 12-8 コレクション・スキャン関数

- 12-9 ネストした表の関数

- 12-10 REF操作関数

- 12-11 記述子オブジェクト

- 12-12 バインドおよび定義用のデータ型マッピング

- 13-1 ダイレクト・パス・コンテキストの関数

- 13-2 ダイレクト・パス列配列の関数

- 14-1 リフレッシュ操作後のオブジェクト属性

- 14-2 割当て時間および確保継続時間の例

- 14-3 確保関数、解放関数および確保解除関数

- 14-4 フラッシュおよびリフレッシュ関数

- 14-5 マークおよびマーク解除関数

- 14-6 オブジェクトのメタ属性関数

- 14-7 その他のオブジェクト関数

- 15-1 オブジェクト型属性のオブジェクト・データ型マッピング

- 16-1 パラメータのモード

- 16-2 接続関数、認証関数および初期化関数

- 16-3 ハンドル関数および記述子関数

- 16-4 バインド関数、定義関数および記述関数

- 17-1 文関数

- 17-2 LOB関数

- 17-3 アドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数

- 17-4 ダイレクト・パス・ロード関数

- 17-5 スレッド管理関数

- 17-6 トランザクション関数

- 17-7 その他の関数

- 17-8 OCI関数コード

- 17-9 OCI関数コードの続き(97以降)

- 18-1 インスタンスの型と存続期間

- 18-2 ナビゲーショナル関数の戻り値

- 18-3 OCIナビゲーショナル関数エラー・コード

- 18-4 フラッシュまたはリフレッシュ関数

- 18-5 リフレッシュ後のオブジェクトの状態

- 18-6 オブジェクトおよびキャッシュへのマークまたはマーク解除関数

- 18-7 オブジェクト・ステータス取得関数

- 18-8 その他のオブジェクト関数

- 18-9 作成されるインスタンス

- 18-10 確保関数、確保解除関数および解放関数

- 18-11 型情報アクセッサ関数

- 19-1 関数戻り値

- 19-2 コレクションおよびイテレータ関数

- 19-3 要素ポインタ

- 19-4 日付関数

- 19-5 OCIDateCheck()の有効なパラメータによって戻されるエラー・ビット

- 19-6 比較結果

- 19-7 OCIDateTimeCheck()の有効なパラメータによって戻されるエラー・ビット

- 19-8 OCIDateTimeCompare()のresultパラメータによって戻される比較結果

- 19-9 OCIIntervalCheck()の有効なパラメータによって戻されるエラー・ビット

- 19-10 OCIIntervalCompare()のresultパラメータによって戻される比較結果

- 19-11 NUMBER関数

- 19-12 OCINumberCmp()のresultパラメータによって戻される比較結果

- 19-13 結果の値

- 19-14 ロー関数

- 19-15 REF関数

- 19-16 文字列関数

- 19-17 表関数

- 20-1 外部プロシージャ関数

- 20-2 メモリー・サービス関数

- 20-3 コンテキストのメンテナンス関数

- 20-4 パラメータ・マネージャ・インタフェース関数

- 20-5 ファイルI/Oインタフェース関数

- 20-6 文字列のフォーマット関数

- 20-7 フォーマット修飾子フラグ

- 20-8 文字列中の引数のフォーマット方法を指定する書式コード

- 21-1 関数戻り値

- 21-2 型インタフェース関数

- 21-3 任意データ関数

- 21-4 データ型および属性値

- 21-5 データ型および属性値

- 21-6 任意データ・セット関数

- 22-1 関数戻り値

- 22-2 OCIロケール関数

- 22-3 OCIロケールマッピング関数

- 22-4 OCI文字列操作関数

- 22-5 OCI文字分類関数

- 22-6 OCIキャラクタ・セット変換関数

- 22-7 OCIメッセージ関数

- 23-1 関数戻り値

- 23-2 OCI XML DB関数

- A-1 SQLコマンド・コード

- B-1 OCIデモ・プログラム

- C-1 リレーショナル操作用のサーバー・ラウンドトリップ

- C-2 OCILobコール用のサーバー・ラウンドトリップ

- C-3 オブジェクト関数およびキャッシュ関数用のサーバー・ラウンドトリップ

- C-4 記述操作用のサーバー・ラウンドトリップ

- C-5 データ型の操作関数用のサーバー・ラウンドトリップ

- C-6 任意型関数および任意データ関数のサーバー・ラウンドトリップ

- C-7 ローカルに処理される関数

- D-1 ORACLE_HOMEディレクトリと内容

- D-2 Oracle XAコンポーネント

- D-3 リンク・ライブラリ

- E-1 非推奨のOCI関数

- E-2 非推奨の初期化関数

- E-3 非推奨の文関数

- E-4 非推奨のLOB関数

- E-5 OCILobRead()のamtpの文字数またはバイト数

- E-6 OCILobWrite()のamtpの文字数またはバイト数

- E-7 OCILobWriteAppend()のamtpの文字数またはバイト数

- E-8 非推奨のStreamsアドバンスト・キューイング関数

はじめに

Oracle Call Interface (OCI)は、CまたはC++で記述されたアプリケーションがOracle Databaseと対話するためのアプリケーション・プログラミング・インタフェース(API)です。OCIにより、SQL文の処理、オブジェクト操作などOracle Databaseで使用可能なすべてのデータベース操作を実行する機能がプログラムに提供されます。

対象読者

このマニュアルは、Oracle Database環境で実行するための新規アプリケーションの開発または既存のアプリケーションの変換を行うプログラマを対象としています。OCIについて包括的に説明しているため、システム・アナリストやプロジェクト・マネージャをはじめ、データベース・アプリケーションの開発に関心のある他のユーザーにも役に立ちます。

このマニュアルを使用するには、C言語を使用したアプリケーション・プログラミングの実務に関する知識が必要です。また、リレーショナル・データベース・システムの情報にアクセスする構造化問合せ言語(SQL)を理解している必要があります。さらに、一部の項では、オブジェクト指向プログラミングの基本的な概念に関する知識も必要です。

関連項目:

- SQLの詳細は、『Oracle Database SQL言語リファレンス』および『Oracle Database管理者ガイド』を参照してください。

- 『Oracle Database概要』

- Standard EditionとEnterprise Editionの違いおよび使用可能なすべての機能とオプションの詳細は、『Oracle Database新機能ガイド』を参照してください。

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

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

Oracle Supportへのアクセス

Oracleサポート・サービスでは、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 Databaseのインストール時に基本インストール・オプションを選択した場合にデフォルトでインストールされるサンプル・スキーマを使用しています。これらのスキーマの作成方法および使用方法については、『Oracle Databaseサンプル・スキーマ』を参照してください。

リリース・ノート、インストール関連ドキュメント、ホワイト・ペーパーまたはその他の関連ドキュメントは、OTN (Oracle Technology Network)から、無償でダウンロードできます。OTNを使用するには、オンラインでの登録が必要です。登録は、次の場所から無償で行えます。

http://www.oracle.com/technetwork/community/join/overview/

すでにOTNのユーザー名およびパスワードを取得している場合は、次の場所でOTN Webサイトのドキュメントのセクションに直接接続できます。

http://www.oracle.com/technetwork/indexes/documentation/

『Oracle Call Interfaceプログラマーズ・ガイド』では、Oracle Database Standard Edition製品およびEnterprise Edition製品に組み込まれているOCIの特性および機能がすべて説明されているわけではありません。OCIの追加情報は、次のドキュメントを参照してください。

- 『Oracle Databaseデータ・カートリッジ開発者ガイド』には、カートリッジ・サービスおよびデータ・カートリッジの開発に関連するOCIコールの詳細が記載されています。

- 『Oracle Databaseグローバリゼーション・サポート・ガイド』には、NLS設定およびグローバリゼーション・サポートに関連するOCIコールについて記載されています。

- 『Oracle Streamsアドバンスト・キューイング・ユーザーズ・ガイド』には、アドバンスト・キューイングに関連するOCIコールの詳細が記載されています。.

- 『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』には、XAライブラリでOCIを使用する方法が記載されています。

- 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』には、OCIコールを使用したLOBの操作の詳細およびコード例が記載されています。

- 『Oracle Databaseオブジェクト・リレーショナル開発者ガイド』には、オブジェクト型の詳しい説明が記載されています。

Oracle Databaseの追加情報は、次のドキュメントを参照してください。

- 『Oracle Database インストレーション・ガイド for Microsoft Windows』

- 『Oracle Database リリース・ノート for Microsoft Windows』

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

- 『Oracle Database新機能ガイド』

- 『Oracle Database概要』

- 『Oracle Databaseリファレンス』

- 『Oracle Databaseエラー・メッセージ』

Oracle C++ Call Interfaceは、C++プログラム用のOCI機能を提供し、プログラマはユーザー定義型のデータベース・オブジェクトをC++オブジェクトとして操作できます。C++用のOCI機能の詳細は、『Oracle C++ Call Interfaceプログラマーズ・ガイド』を参照してください。

表記規則

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

規則

意味

太字

太字は、操作に関連するグラフィカル・ユーザー・インタフェース要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

イタリック

イタリックは、ユーザーが特定の値を指定するプレースホルダ変数を示します。

固定幅

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

Oracle Call Interfaceの新機能

この章では、次の各項でOracle Call Interfaceの新機能について説明します。

- Oracle Call Interfaceリリース11.2の新機能

- Oracle Call Interfaceリリース11.1の新機能

Oracle Call Interfaceリリース11.2の新機能

このリリースには、次の新機能または拡張機能が含まれています。

- クライアントとサーバーでは、異なるタイムゾーン・ファイルを使用できます。
「異なるバージョンのタイムゾーン・ファイルで操作するクライアントとサーバー」を参照してください。

- Editionベースの再定義により、アプリケーションのパッチ適用が改善されます。
「Editionベースの再定義」を参照してください。

- OCIでは64ビット・ホスト・データ型をサポートします。
「64ビット整数ホスト・データ型」を参照してください。

- 新規属性により、IPアドレス形式をIPv4またはIPv6のいずれかとして指定できます。
「OCI_ATTR_SUBSCR_HOSTADDR」、「OCI_ATTR_SUBSCR_IPADDR」および「データベースへのパブリッシュ・サブスクライブの直接登録」を参照してください。

- SecureFilesのコンテンツ・タイプが階層ストレージで使用されます。
「OCILobGetContentType()」および「OCILobSetContentType()」参照してください。

- 新規ダイレクト・パス・ロード属性があります。
「OCI_ATTR_DIRPATH_NO_INDEX_ERRORS」を参照してください。

- クライアント結果キャッシュ機能には、表注釈が付くようになり、ビューに対する問合せのキャッシュがサポートされます。また、クライアント・キャッシュがデータベース常駐プーリングとともに使用できない制約がなくなりました。
「クライアント結果キャッシュ」を参照してください。

- データ共有ライブラリとzipおよびRPMファイルを再生成するプロセスは、Instant Client用に変わりました。
「データ共有ライブラリ、zipおよびRPMファイルの再生成」を参照してください。

- OCIを使用して、Oracle TimesTen In-Memory DatabaseおよびOracle In-Memory Database Cacheにアクセスできます。
『Oracle TimesTen In-Memory Database C開発者ガイド』のTimesTenでのOracle Call Interfaceのサポートに関する章を参照してください。

Oracle Call Interfaceリリース11.1の新機能

Oracle Call Interfaceのリリース11.1では、次の新機能および拡張機能が導入されました。

- ランタイム・ロード・バランシングが自動的に使用可能であり、パフォーマンスが向上します。
「実行時接続ロード・バランシング」を参照してください。

- パフォーマンス向上のために、バインドと定義により読取りと書込みに不連続バッファを使用できます (バインドおよび定義用の散布および収集)。
「複数バッファのバインドと定義」を参照してください。

- SELECT ... FOR UPDATE文を使用してROWIDを暗黙的にフェッチします。
「ROWIDの暗黙的フェッチ」を参照してください。

- 記述子の配列を使用することでパフォーマンスが向上します。
「OCIArrayDescriptorAlloc()」を参照してください。

- クライアント結果キャッシュ機能によるパフォーマンス向上が可能です。
「クライアント結果キャッシュ」を参照してください。

- データベース管理者用に提供される新規設定により、OCIがよりセキュアになります。
「OCIセキュリティ拡張機能」を参照してください。

- XML DBおよびXDK文書に対するサポートが拡張され、バイナリXMLが含まれています。
「OCIでのXMLのサポート」を参照してください。

- OCIアプリケーションで小さいLOBの長さ、チャンク・サイズおよびデータのフェッチを最適化できます。
「LOBデータ、長さおよびチャンク・サイズのプリフェッチ」を参照してください。

- SecureFile LOB。暗号化、重複除外および圧縮を含むLOBの新機能です。このリリースには新しいOCI関数が組み込まれています。これらの新規関数および機能は、新規SecureFile LOBでのみ使用可能です。
「SecureFiles LOBのオプション」を参照してください。

- データベース常駐接続プーリング。このプールは、異なるスレッド間のみでなくプロセス間にまたがります。その結果、アプリケーションの効率が向上します。
「データベース常駐接続プーリング」を参照してください。

- 既存の機能に、問合せ結果セットの変更に関するデータベース変更通知拡張機能が追加されています。
「連続問合せ通知」を参照してください。

- Oracle Streamsアドバンスト・キューイング・イベント通知では、適切な間隔を置いた通知がサポートされるようになります。
「OCIでのパブリッシュ・サブスクライブの通知」を参照してください。

- 障害診断サブディレクトリ構造により、ユーザーはOCIで生成されたインシデントを管理しやすくなります。
「OCIでの障害診断」を参照してください。

- クライアント・ドライバ・レイヤー名を読み取るか書き込んでOCIの障害診断を高めるには、次の関連項目で説明する属性をセッション・ハンドルで使用します。
「OCI_ATTR_DRIVER_NAME」を参照してください。

- OCIアプリケーションの新しいバージョンの互換性について説明しています。
「静的にリンクされたアプリケーションと動的にリンクされたアプリケーションのバージョンの互換性」を参照してください。

1 OCI: 概要およびアップグレード

この章は、次の項目で構成されています。

- OCIの概要

- 互換性およびアップグレード

- OCI Instant Client

OCIの概要

Oracle Call Interface (OCI)はApplication Program Interface (API)の1つで、これを使用すると、関数コールを使用してOracle Databaseにアクセスし、SQL文の実行のすべてのフェーズを制御するアプリケーションを作成できます。OCIでは、C言語とC++言語のデータ型、コール規則、構文およびセマンティックをサポートします。

関連項目:

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

- 「関連ドキュメント」

OCIは次の機能を備えています。

- システム・メモリーおよびネットワーク接続の効率的な使用によるパフォーマンスと拡張性の向上

- 2層クライアント/サーバーまたは複数層環境での動的セッションおよびトランザクション管理に適した一貫性のあるインタフェース

- N層認証

- Oracle Databaseオブジェクトを使用したアプリケーション開発の包括的サポート

- 外部データベースへの接続

- ハードウェアへの追加投資をすることなく、ユーザー数および要求数の増加をサポートするアプリケーション

OCIでは、Cプログラミング言語を使用してOracle Database内のデータおよびスキーマを操作できます。また、標準的なデータベース・アクセスと検索機能のライブラリが動的ランタイム・ライブラリ(OCIライブラリ)の形で用意されており、実行時にアプリケーションにリンクできます。

OCIを使用して、Oracle TimesTen In-Memory DatabaseおよびOracle In-Memory Database Cacheにアクセスできます。『Oracle TimesTen In-Memory Database C開発者ガイド』を参照してください。

OCIは多くの新機能を備えており、主に次のように分類できます。

- カプセル化された、または不透明なインタフェース(実装の詳細は見えない)

- ユーザー認証およびパスワード管理の簡易化

- アプリケーションのパフォーマンスおよび拡張性を向上させる拡張機能

- トランザクション管理に適した一貫性のあるインタフェース

- クライアント側からのOracleオブジェクトに対するアクセスをサポートするOCI拡張機能

OCIの利点

Oracle Databaseに接続する場合、OCIには次のような他の方法よりも大きな利点があります。

- アプリケーション設計のあらゆる側面におけるきめ細かい制御

- プログラム実行に対する高度な制御

- 使い慣れた第三世代言語プログラミング手法およびブラウザやデバッガなどのアプリケーション開発ツールの使用

- スケーラブルなアプリケーション作成を可能にする接続プーリング、セッション・プーリングおよび文キャッシュ

- 動的SQLのサポート

- 様々なオペレーティング・システムに対応したOracleプログラム・インタフェースの可用性

- コールバックを使用した動的バインドおよび定義

- サーバー・メタデータのレイヤーを公開する記述機能

- 登録されたクライアント・アプリケーションへの非同期イベント通知

- 配列の挿入、更新、削除を行うための高度な配列データ操作言語(DML)機能

- コミット要求の実行への関連付けによるラウンドトリップ回数の削減

- 透過的プリフェッチ・バッファを使用した問合せの最適化によるラウンドトリップ回数の削減

- OCIハンドルに対する相互排他ロック(mutex)を不要にするスレッド・セーフティ

OCIアプリケーションの構築

OCIプログラムは非データベース・アプリケーションと同様の方法でコンパイルおよびリンクできます。処理前のステップやプリコンパイル・ステップを別途行う必要はありません。

Oracle Databaseでは、一般に普及しているほとんどのサード・パーティのコンパイラをサポートしています。OCIプログラムのリンクの詳細は、システムによって異なります。一部のオペレーティング・システムでは、OCIプログラムを正常にリンクさせるために、OCIライブラリに加えて他のライブラリの組込みが必要になる場合があります。オペレーティング・システムでのOCIアプリケーションのコンパイルとリンクの詳細は、使用システムに関するOracle Databaseマニュアルとインストレーション・ガイドを参照してください。

関連項目:
付録D「OCI for Windowsスタート・ガイド」

OCIの分類

OCIは次の機能を備えています。

- 多数のユーザーを安全にサポートできるスケーラブルなマルチスレッド・アプリケーションを設計するためのAPI

- データベース・アクセスの管理、SQL文の処理およびOracle Databaseから取り出したオブジェクトの操作を行うためのSQLアクセス関数

- Oracle型のデータ属性を操作するためのデータ型マッピングおよび操作関数

- SQL文を使用せずにデータベースにデータを直接ロードするためのデータ・ロード関数

- PL/SQLからC言語のコールバックを書き込むための外部プロシージャ関数

手続き型および非手続き型要素

OCIを使用すると、SQLの非手続き型データ・アクセス機能と、CやC++言語の手続き型機能をあわせ持つ複数層アーキテクチャ上で、スケーラブルなマルチスレッド・アプリケーションを開発できます。

- 非手続き型言語のプログラムでは、操作対象となる一連のデータが指定されますが、実行する操作の種類や操作の方法は指定されません。SQLは非手続き型であるため、データベース・トランザクションの実行用として簡単に覚えやすく使用しやすい言語です。また、先進のリレーショナル・データベース・システムおよびオブジェクト・リレーショナル・データベース・システムのデータに対するアクセスや操作に使用する標準言語となっています。

- 手続き型言語のプログラムでは、大部分の文の実行は、前または後続の文、およびループや条件ブランチなどSQLでは利用できない制御構造に依存しています。手続き型という性質上、このような言語はSQLよりも複雑ですが、柔軟性に富み、非常に強力です。

OCIプログラムでは、非手続き型言語と手続き型言語の要素が組み合されているため、構造化プログラミング環境でOracle Databaseに容易に接続できます。

OCIでは、Oracle Databaseを通じて使用可能なSQLのデータ定義、データ操作、問合せおよびトランザクション制御の機能をすべてサポートしています。たとえば、OCIプログラムでは、Oracle Databaseに対する問合せを実行できます。問合せ文では、次の例のように、入力(バインド)変数を使用して、データベースにデータを渡すようにプログラムに対して指示できます。

SELECT name FROM employees WHERE empno = :empnumber;

前述のSQL文の:empnumberは、アプリケーションが指定する値に対するプレースホルダです。

また、Oracleが開発したSQLの手続き型拡張要素であるPL/SQLも利用できます。PL/SQLにより、SQLのみで作成されたアプリケーションよりも、さらに強力で柔軟性のあるアプリケーションを開発できます。OCIは、データベース内のオブジェクトに対するアクセスおよび操作のための機能も提供します。

オブジェクトのサポート

OCIには、オブジェクト型とオブジェクトを処理する機能があります。オブジェクト型は、ユーザー定義のデータ構造体で、現実社会の実体を抽象的に表します。たとえば、データベースにperson (個人)というオブジェクトの定義が含まれているとします。このオブジェクトは、個人を識別するための特徴を表した属性—first_name、last_nameおよびageを持つことができます。

オブジェクト型の定義は、オブジェクト型のインスタンスを表すオブジェクトの作成の基礎となり、オブジェクト型を構造的な定義として使用することで、personオブジェクトを属性値 'John'、'Bonivento'および'30'で作成できます。オブジェクト型には、メソッド、つまりそのオブジェクト型の動作を表すプログラム関数を含めることもできます。

関連項目:

- 『Oracle Database概要』

- 『Oracle Databaseオブジェクト・リレーショナル開発者ガイド』。

OCIには、Oracle Database内のオブジェクト処理用にOCIの機能を拡張した関数が組み込まれています。これらの機能には次のものが含まれます。

- オブジェクト・データとスキーマ情報を操作するSQL文の実行

- SQL文の入力変数としてオブジェクト参照およびオブジェクトのインスタンスを渡す機能

- SQL文の出力を受け取る変数として、オブジェクト参照およびオブジェクトのインスタンスの宣言

- データベースからオブジェクト参照およびオブジェクトのインスタンスのフェッチ

- オブジェクトのインスタンスと参照を戻すSQL文のプロパティの記述

- オブジェクト・パラメータまたは結果を指定したPL/SQLプロシージャまたはファンクションの記述

- オブジェクトとリレーショナル機能を同期化するための、コミット・コールとロールバック・コールの拡張

その他のOCIコールは、SQL文を通してアクセスされた後、オブジェクトの操作をサポートするために提供されます。詳細は、「カプセル化されたインタフェース」を参照してください。

SQL文

OCIアプリケーションの主なタスクの1つは、SQL文を処理することです。SQL文の種類が異なると、プログラムでは異なる処理ステップが必要になります。OCIアプリケーションをコーディングする際には、そのことを考慮に入れることが重要です。Oracle Databaseでは、次の種類のSQL文を認識します。

- データ定義言語 (DDL)

- 制御文

- トランザクション制御

- セッション制御

- システム制御

- データ操作言語 (DML)

- 問合せ

注意:
多くの場合、問合せはDML文として分類されますが、OCIアプリケーションでは異なる方法で問合せを処理するため、ここでは両者を別個に考慮しています。

- PL/SQL

- 埋込みSQL

関連項目:
第4章「OCIでのSQL文の使用」

データ定義言語

データ定義言語(DDL)文は、データベース内のスキーマ・オブジェクトを管理します。DDL文は、新規の表を作成し、古い表を削除し、その他のスキーマ・オブジェクトを設定します。また、スキーマ・オブジェクトに対するアクセスを制御します。

表を作成し、その表へのアクセスを指定する例を次に示します。

CREATE TABLE employees
(name       VARCHAR2(20),
ssn        VARCHAR2(12),
empno      NUMBER(6),
mgr        NUMBER(6),
salary     NUMBER(6));

GRANT UPDATE, INSERT, DELETE ON employees TO donna;
REVOKE UPDATE ON employees FROM jamie;

DDL文によって、オブジェクト表を作成する次の一連の文のように、Oracle Database内のオブジェクトを操作することもできます。

CREATE TYPE person_t AS OBJECT (
name     VARCHAR2(30),
ssn      VARCHAR2(12),
address  VARCHAR2(50));

CREATE TABLE person_tab OF person_t;

制御文

OCIアプリケーションでは、トランザクション制御文、セッション制御文およびシステム制御文を、それらがDML文であるかのように処理します。

関連項目:
これらの種類の文の詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

データ操作言語

データ操作言語(DML)文は、データベース表にあるデータを変更できます。たとえば、DML文を使用して次の処理を実行します。

- 表に新しい行を挿入します。

- 既存の行の列値を更新します。

- 表から行を削除します。

- データベース内の表をロックします。

- SQL文の実行計画を説明します。

- 入力(バインド)変数を使用して、データベースにデータを渡すようにアプリケーションに対して指示します。

関連項目:
入力バインド変数の詳細は、「OCIのプレースホルダのバインド」を参照してください。

また、DML文ではOracle Database内のオブジェクトを操作でき、次の例では、person_t型のインスタンスがオブジェクト表person_tabに挿入されています。

INSERT INTO person_tab
VALUES (person_t('Steve May','987-65-4320','146 Winfield Street'));

問合せ

問合せは、データベースからデータを取り出すための文です。1つの問合せで、0、1行および複数行のデータを戻すことができます。すべての問合せは、次の例のように、SQLキーワードSELECTで始まります。

SELECT dname FROM dept
WHERE deptno = 42;

問合せは、表の中のデータにアクセスするため、多くの場合DML文として分類されます。ただし、OCIアプリケーションでは問合せの処理方法が異なるため、このマニュアルでは問合せを別個のものとして扱います。

問合せ文では入力(バインド)変数を使用して、データベースにデータを渡すようにプログラムに指示できます。たとえば次のとおりです。

SELECT name
FROM employees
WHERE empno = :empnumber;

前述のSQL文の:empnumberは、アプリケーションが指定する値に対するプレースホルダです。

問合せを処理する際、OCIアプリケーションでは、戻される結果を受け取るための出力変数も定義する必要があります。前述の文では、問合せから戻されるnameの値を受け取るために出力変数を定義する必要があります。

関連項目:

- 入力バインド変数の詳細は、「OCIでのバインドの概要」を参照してください。

- 出力変数の定義の詳細は、「OCIでの定義の概要」を参照してください。

- OCIプログラムでのSQL文の処理方法の詳細は、第4章を参照してください。

PL/SQL

PL/SQLは、Oracleが開発したSQL言語の手続き型拡張機能です。PL/SQLは、単純な問合せやSQLデータ操作言語文よりも複雑なタスクを処理します。PL/SQLを使用すると、いくつかの構文を単一のブロックにグループ化し、1つの単位として実行できます。これらの単位には次の部分が含まれます。

- 1つまたは複数のSQL文

- 変数宣言

- 代入文

- プロシージャ型制御文(IF...THEN...ELSE文とループ)

- 例外処理

OCIプログラムでPL/SQLブロックを使用すると、次の処理を実行できます。

- Oracle Databaseストアド・プロシージャおよびストアド・ファンクションのコール

- 手続き型制御文を複数のSQL文と結合し、1つの単位として実行

- レコード、表、カーソルFORループ、例外処理などの特殊なPL/SQL機能へのアクセス

- カーソル変数の使用

- Oracle Database内のオブジェクトへのアクセスおよび操作

次のPL/SQL例では、特定の従業員番号をキーにして、従業員表から値を取り出すSQL文が発行されます。この例は、PL/SQL文でのプレースホルダの使用方法も示しています。

BEGIN
SELECT ename, sal, comm INTO :emp_name, :salary, :commission
FROM emp
WHERE empno = :emp_number;
END;

この文のプレースホルダは、PL/SQL変数ではないことに注意してください。これらは、文の処理時に、データベースに渡される入力値を示しています。これらのプレースホルダは、プログラム内でC言語変数にバインドする必要があります。

関連項目:

- PL/SQLブロックのコーディングの詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。

- PL/SQLでのプレースホルダの使用方法の詳細は、「PL/SQLのプレースホルダのバインド」を参照してください。

埋込みSQL

OCIは、アプリケーションが実行時にデータベースに渡すテキスト文字列としてSQL文を処理します。Oracleプリコンパイラ(Pro*C/C++、Pro*COBOL、Pro*FORTRAN)を使用することによって、SQL文をアプリケーション・コードに直接埋め込むことができます。その後、実行可能なアプリケーションを生成するために別個のプリコンパイル・ステップが必要です。

OCIコールと埋込みSQLはプリコンパイラ・プログラムでは混在できます。

関連項目:
『Pro*C/C++プログラマーズ・ガイド』

SQL用のOCIの特殊用語

このマニュアルでは、SQL文の様々な部分を参照するために特殊な用語を使用しています。たとえば、次のSQL文があるとします。

SELECT customer, address
FROM customers
WHERE bus_type = 'SOFTWARE'
AND sales_volume = :sales;

ここには次の要素があります。

- SQLコマンド - SELECT

- 2つの選択リスト項目 - customerおよびaddress

- FROM句内の表名 - customers

- WHERE句内の2つの列名 - bus_typeおよびsales_volume

- WHERE句内のリテラル入力値 - 'SOFTWARE'

- WHERE句内の入力変数のプレースホルダ - :sales

OCIアプリケーションを開発する際は、プログラムの入出力変数のアドレス(位置)をOracle Databaseに指定しているルーチンをコールします。このマニュアルでは、データ入力用のプレースホルダ変数のアドレスを指定することをバインド操作と呼びます。また、選択リスト項目を受け取るための変数のアドレスを指定することを定義操作と呼びます。

PL/SQLでは、入力の指定も出力の指定もバインド操作と呼びます。これらの用語と操作の詳細は、第4章を参照してください。

カプセル化されたインタフェース

OCIコールで使用されるすべてのデータ構造は、ハンドルと呼ばれる不透明なインタフェースの形にカプセル化されます。ハンドルとは、OCIライブラリによって割り当てられる記憶領域を指す不透明なポインタで、SQL文またはPL/SQL文のコンテキスト情報、接続情報、エラー情報またはバインド情報を格納します。クライアントでは、特定の種類のハンドルを割り当て、正しく定義されたインタフェースを通じて1つ以上のハンドルを移入し、それらのハンドルを使用してサーバーに要求を送信します。その結果、アプリケーションは、アクセッサ関数を使用してそのハンドルに含まれている特定の情報にアクセスできます。

OCIライブラリでは、ハンドルの階層が管理されます。これらのハンドルを使用してOCIインタフェースをカプセル化することには、アプリケーション開発者にとって次のような利点があります。

- 保持する必要があるサーバー側の状態情報が少なくなり、サーバー側のメモリー使用量を削減できます。

- グローバル変数を使用する必要がなくなること、エラー・レポートを作成しやすくなること、OCI変数のアクセスおよび使用方法に一貫性を保てることにより、生産性が向上します。

- アプリケーションに影響を与えずに基礎となる構造を変更できます。

ユーザー認証およびパスワード管理の簡易化

OCIでは、アプリケーション開発者が、次のような簡易化されたユーザー認証およびパスワード管理を実行できます。

- 単一のOCIアプリケーションで、複数のユーザーを認証およびメンテナンスできます。

- OCIアプリケーションで、ユーザーのパスワードを更新でき、認証の処理でパスワード期限切れのメッセージが戻された場合に特に役立ちます。

OCIでは、次の2種類のログイン・セッションをサポートします。

- シングル・ユーザーがログイン名とパスワードを使用してデータベースに接続するセッションのための、簡易ログイン関数。

- ログイン・セッション(ユーザーがOracle Databaseにログインするときに作成されるセッション)をユーザー・セッション(ユーザーが作成したその他すべてのセッション)から分離することにより、単一のOCIアプリケーションで複数のセッションの認証とメンテナンスを行うメカニズム。

アプリケーションのパフォーマンスおよび拡張性を改善する拡張機能

OCIには、アプリケーションのパフォーマンスおよび拡張性を改善する、いくつかの拡張機能があります。クライアントとサーバー間のラウンドトリップ回数を減らすことにより、アプリケーションのパフォーマンスが改善され、さらにサーバー側で保持する必要がある状態情報の量を減らすことにより拡張性も向上しています。これらの機能には、次のものがあります。

- クライアント側の処理の増加、およびサーバー側の問合せ要求の削減

- 記述のラウンドトリップをなくし、ラウンドトリップ回数およびメモリー使用量を削減する、SELECT文結果セットの暗黙的なプリフェッチ

- オープン・カーソルとクローズ・カーソルのラウンドトリップの排除

- マルチスレッド環境のサポートの改善

- 接続上のセッション多重化

- 標準の2層クライアント/サーバー構成、サーバー/サーバー・トランザクション調整、3層TPモニター構成など、様々な構成に対する一貫したサポート

- XAインタフェースのTM_JOIN操作のサポートを含む、ローカル・トランザクションおよびグローバル・トランザクションに対する一貫したサポート

- 接続中のユーザー接続、処理およびセッションを集結する機能を提供し、グローバル・トランザクションのブランチごとに個別のセッションを作成する必要性をなくしたことによる、拡張性の向上

- アプリケーションによる複数のユーザーの認証、および複数のユーザーのためのトランザクションの開始

OCIによるオブジェクトのサポート

OCIは、Oracle Databaseのオブジェクト機能を使用するプログラマに、包括的なアプリケーション・プログラミング・インタフェースを提供します。その機能は、次の主要なカテゴリに分類できます。

- クライアント側のオブジェクト・キャッシュ

- オブジェクトへのアクセスおよび操作のためのアソシエイティブ・インタフェースおよびナビゲーショナル・インタフェース

- オブジェクト用のOCIランタイム環境

- オブジェクト型に関する情報にアクセスし、Oracle型のデータ属性を制御するための型管理(マッピングおよび操作関数)

- Oracle Database内部スキーマ情報をクライアント側の言語バインド変数にマッピングするObject Type Translator(OTT)ユーティリティ

クライアント側のオブジェクト・キャッシュ

オブジェクト・キャッシュは、オブジェクトの参照とメモリー管理をサポートするクライアント側のメモリー・バッファです。オブジェクト・キャッシュは、OCIアプリケーションがサーバーからクライアント側にフェッチしたオブジェクト・インスタンスを格納し、追跡します。オブジェクト・キャッシュは、OCI環境を初期化するときに作成されます。同じサーバーに対して複数のアプリケーションを実行する際には、それぞれに専用のオブジェクト・キャッシュがあります。オブジェクト・キャッシュは、メモリーに現在あるオブジェクトの追跡、オブジェクトへの参照のメンテナンス、自動オブジェクト・スワッピングの管理、オブジェクトのメタ属性または型情報の追跡を行います。また、オブジェクト・キャッシュには、OCIアプリケーションに対する次の機能が備えられています。

- オブジェクトのフェッチおよび操作に必要なクライアント/サーバー間のラウンドトリップ回数の削減によるアプリケーションのパフォーマンスの改善

- クライアント側のキャッシュからのオブジェクト・スワッピングのサポートによる拡張性の向上

- オブジェクト・レベルのロックのサポートによる同時実行性の向上

アソシエイティブ・インタフェースおよびナビゲーショナル・インタフェース

OCIを使用したアプリケーションでは、次のような様々な種類のインタフェースを介して、Oracle Database内のオブジェクトにアクセスできます。

- SQLのSELECT文、INSERT文およびUPDATE文の使用

- 対応するスマート・ポインタまたはREFを横断することによりクライアント側のキャッシュ内のオブジェクトにアクセスする、Cスタイルのポインタ追跡スキームの使用

OCIは、SQLのSELECT、INSERTおよびUPDATE文を使用したオブジェクトの操作をサポートするための一連の拡張子付き関数を提供します。Oracle Databaseオブジェクトにアクセスする場合、これらのSQL文では、リレーショナル表にアクセスするような一貫した一連のステップが使用されます。また、OCIには、オブジェクトにアクセスするのに必要な次の関数セットも用意されています。

- オブジェクト型のインスタンスと参照をSQL文の入出力変数としてバインドおよび定義します。

- オブジェクト型のインスタンスと参照を含むSQL文を実行します。

- オブジェクト型のインスタンスと参照をフェッチします。

- Oracleオブジェクト型の選択リスト項目を記述します。

OCIでは、対応するスマート・ポインタまたはREFを横断することにより、クライアント側のキャッシュ内にフェッチされているオブジェクトに、Cスタイルのポインタ追跡スキームを使用してアクセスする一連の関数も提供しています。このナビゲーショナル・インタフェースでは、関数が次の目的で使用されます。

- 参照可能な永続オブジェクト(つまり、クライアント側のキャッシュ内のオブジェクトIDを持つ永続オブジェクト)のコピーをスマート・ポインタまたはREFを確保することによりインスタンス化します。

- あるオブジェクトから別のオブジェクトを指し示すREFを横断することにより、お互いに接続されているオブジェクトの順序を横断します。

- オブジェクト属性の値を動的に取得し、設定します。

オブジェクト用のOCIランタイム環境

OCIでは、Oracle Databaseオブジェクトのクライアント側での使用方法を管理するオブジェクト用の関数を提供します。これらの関数は、次の目的で使用されます。

- セッションの初期化、データベース・サーバーへのログイン、接続の登録などのオブジェクト機能にアクセスするための、Oracle Databaseサーバーへの接続

- クライアント側のオブジェクト・キャッシュの設定およびそのパラメータのチューニング

- エラーおよび警告メッセージの取得

- データベース内のオブジェクトにアクセスするトランザクションの制御

- SQLによるオブジェクトへの結合アクセス

- パラメータまたは結果がOracle型であるPL/SQLプロシージャまたはファンクションの記述

型管理: マッピングおよび操作関数

OCIでは、Oracle Databaseオブジェクトを操作するための2つの関数セットを提供します。

- 型マッピング関数を使用すると、アプリケーションで、Oracle内部データ型としてサーバーで表されているOracleスキーマの属性を、対応するホスト言語型にマップできます。

- 型操作関数を使用すると、ホスト言語のアプリケーションで、Oracleスキーマの個別の属性を操作できます。属性の値を設定および取得したりサーバーにフラッシュできます。

また、OCIDescribeAny()関数を使用すると、データベース内に格納されたオブジェクトの情報を取得できます。

Object Type Translator

Object Type Translator (OTT)ユーティリティは、Oracleオブジェクト型に関するスキーマ情報を、ホスト言語変数のクライアント側言語バインディングに翻訳します(構造など)。OTTは、Oracleスキーマ・オブジェクトに関するメタデータ情報を含むintypeファイルを入力として使用します。また、outtypeファイル、ヘッダー・ファイルおよび実装ファイルを生成します。これらは、オブジェクト・スキーマに対して実行されるC言語アプリケーションに含まれている必要があります。OCIアプリケーションとPro*C/C++プリコンパイラ・アプリケーションの両方に、OTTが生成したコードが含まれている場合があります。次の理由により、OTTは非常に便利です。

- アプリケーション開発者の生産性が向上します。OTTを使用すると、アプリケーション開発者はスキーマ・オブジェクトに対応するホスト言語変数をコーディングする必要がなくなります。

- SQLを、選択したデータ定義言語としてメンテナンスします。OTTでは、SQLを使用して作成したOracleスキーマ・オブジェクトをホスト言語変数に自動的にマップできるため、SQLがデータ定義言語として使用しやすくなります。その結果、Oracle Databaseによって、データの一貫したモデルをサポートできます。

- オブジェクト型のスキーマ展開を容易にします。OTTでは、スキーマが変更されたときにインクルードされたヘッダー・ファイルを再生成できるため、Oracleアプリケーションでスキーマ展開をサポートできます。

通常、OTTは、コマンドラインからintypeファイル、outtypeファイルおよび特定のデータベース接続を指定することにより起動されます。Oracle Databaseでは、OTTにより、OCIプログラムとPro*C/C++プリコンパイラ・プログラムのどちらでも使用できるC構造体のみを生成できます。

OCIでのOracle Streams Advanced Queuingのサポート

OCIでは、Oracle Streams Advanced Queuing (Streams AQ)機能へのインタフェースを提供します。Streams AQは、Oracle Databaseと統合されたメッセージ・キューイングです。Streams AQでは、キューイング・システムをデータベースに統合することによりこの機能を実現しており、その結果メッセージ対応データベースが作成されます。Streams AQでは、統合されたソリューションを提供することにより、開発者がメッセージ交換インフラストラクチャを構築する必要をなくし、特定のビジネス・ロジックに専念できるようにします。

関連項目:
「OCIおよびStreamsアドバンスト・キューイング」

XAライブラリ・サポート

OCIは、Oracle XAライブラリをサポートしています。xa.hヘッダー・ファイルは、他のすべてのOCIヘッダー・ファイルと同じ場所にあります。LinuxまたはUNIXの場合、パスは$ORACLE_HOME/rdbms/publicです。LinuxまたはUNIXでdemo_rdbms.mkファイルを使用しているユーザーが影響を受けないのは、$ORACLE_HOME/rdbms/publicディレクトリがすでにこのMakefileに記載されているためです。

Windowsの場合、パスはORACLE_BASE\ORACLE_HOME¥oci¥includeです。

関連項目:

- WindowsおよびXAアプリケーションの詳細は、「Oracle XAライブラリ」を参照してください。

- Oracle XAによるアプリケーションの開発の詳細は、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』を参照してください。

互換性およびアップグレード

次の各項では、異なるリリースのOCIクライアントとサーバー間での互換性の問題、OCIライブラリ・ルーチンの変更点およびOCIリリース7.xからこのリリースのOCIへのアプリケーションのアップグレードについて説明します。

静的にリンクされたアプリケーションと動的にリンクされたアプリケーションのバージョンの互換性

次に、新規リリースで再リンクする場合の規則を示します。

- 静的にリンクされたOCIアプリケーションの場合:
静的にリンクされたOCIアプリケーションが、メジャー・リリース番号とマイナー・リリース番号の両方について再リンクする必要があるのは、Oracle Databaseのクライアント側のライブラリ・コードが、アップグレードされたOracleホーム内のエラー・メッセージと互換性がないためです。たとえば、エラー・メッセージが追加パラメータで更新された場合、そのエラー・メッセージは、静的にリンクされたコードとは互換性がなくなります。

- 動的にリンクされたOCIアプリケーションの場合:
Oracle Database 10g以降のリリースの動的にリンクされたOCIアプリケーションは、再リンクする必要はありません。つまり、Oracle Databaseのクライアント側の動的ライブラリには、以前のバージョンのライブラリに対して上位互換性があります。Oracle Universal Installerにより、現行バージョンに解決される以前のバージョンのライブラリ用にシンボリック・リンクが作成されます。したがって、以前のバージョンのOracle Databaseのクライアント側動的ライブラリと動的にリンクされたアプリケーションは、現行バージョンのOracle Databaseのクライアント側ライブラリで動作するために再リンクする必要はありません。

注意:
アプリケーションがランタイム・ライブラリ検索パス(Linuxの-rpathなど)とリンクされている場合、アプリケーションはリンクされているOracle Databaseのクライアント側ライブラリのバージョンでまだ動作する可能性があります。現行バージョンのOracle Databaseのクライアント側ライブラリで動作するためには、再リンクする必要があります。

関連項目:

- 互換性およびアップグレードの詳細は、『Oracle Databaseアップグレード・ガイド』を参照してください。

- 現在サポートされているサーバー・バージョンは、ノート207303.1のMy Oracle Supportに記載されています。次のWebサイトを参照してください。
https://support.oracle.com/

既存OCIリリース7アプリケーションのアップグレードの簡易化

OCIでは、OCIリリース7以降の多くの機能が大幅に改善されました。OCIリリース7.xのクライアントと現行リリースのOracle Database、および現行リリースのクライアントとOracle Databaseリリース7.xにはそれぞれ相互運用性があるため、OCIリリース7.xを使用するように作成したアプリケーションは、現行リリースのOCIに容易に移行できます。

具体的には次のとおりです。

- OCIリリース7.3 APIを使用していたアプリケーションは、現行リリースのOracle Databaseに対して通常どおり動作します。これらのアプリケーションは、現行のクライアント・ライブラリにリンクする必要があります。

- OCIリリース7.xおよびこのリリースのOCIのコールは、同じ文の実行で混在させないかぎり、同一アプリケーションおよび同一トランザクション内で使用できます。

このため、既存のOCIバージョン7のアプリケーションを移行する場合は、次の2つの方法があります。

- 現行のOCIクライアントにアップグレードしますが、アプリケーションは修正しません。Oracleリリース7 OCIクライアントから現行リリースのOCIクライアントにアップグレードする場合は、新規バージョンのOCIライブラリにリンクするだけでよく、アプリケーションを再コンパイルする必要はありません。再リンクしたOracle Databaseリリース7のOCIアプリケーションは、現行Oracle Databaseに対して通常どおり動作します。

- 現行のOCIクライアントにアップグレードして、アプリケーションを修正します。ただし、新しいOCIで提供されるパフォーマンスと拡張性の利点を活用するには、新しいOCIプログラミング・パラダイムを使用できるように既存のアプリケーションを修正して、そのアプリケーションを現行のOCIライブラリに再リンクし、現行リリースのOracle Databaseに対して実行する必要があります。

現行リリースのOracle Databaseのオブジェクト機能を使用する必要がある場合は、クライアントを現行リリースのOCIにアップグレードする必要があります。

使用されなくなったOCIルーチン

OCIリリース8.0では、リリース7.3で利用できなかった新しい関数セットを導入しました。このリリース7.3の関数は、引き続きサポートされています。以前のリリース7.xコールの多くを使用できますが、パフォーマンスを向上し、機能性を高めるために、新しいアプリケーションで新しいコールを使用することをお薦めします。

表1-1は、リリース7.xのOCIコールおよび以降のリリースでの等価コールのリストです。OCIコールの詳細は、このマニュアルの関数の説明を参照してください。リリース7.xコールの詳細は、『Oracle Call Interfaceプログラマーズ・ガイド リリース7.3』を参照してください。このような7.xのコールは非推奨になったため、新しいコールに置き換えられています。非推奨のコールは現在もサポートされていますが、将来のリリースのOCIではサポートされなくなる場合があります。

注意:
多くの場合、新規または現行のOCIルーチンはリリース7.xのルーチンに直接マッピングを行わないため、関数コールとパラメータ・リストを単純に別のものに置き換えることがほとんどできない場合があります。この場合、新規または現行のコールを作成する前後に、追加のプログラム・ロジックが必要になります。詳細は、このマニュアルの残りの章、特に第2章「OCIプログラミングの基本」を参照してください。

表1-1 使用されなくなったOCI関数

7.xのOCIルーチン

以降のリリースでの等価または類似のOCIルーチン

obindps()、obndra()、obndrn()、obndrv()

OCIBindByName()、OCIBindByPos() (注意: 一部のデータ型には追加のバインド・コールが必要です。)

obreak()

OCIBreak()

ocan()

なし

oclose()

注意: リリース8.x以降では、カーソルは使用されていません。

ocof()、ocon()

OCI_COMMIT_ON_SUCCESSモードでのOCIStmtExecute()

ocom()

OCITransCommit()

odefin()、odefinps()

OCIDefineByPos() (注意: 一部のデータ型には追加の定義コールが必要です。)

odescr()

注意: スキーマ・オブジェクトはOCIDescribeAny()で記述されます。通常、記述は、リリース7.xで使用されているように、SQL文の実行後にOCIAttrGet()を文ハンドルでコールすることにより行われます。

odessp()

OCIDescribeAny()

oerhms()

OCIErrorGet()

oexec()、oexn()

OCIStmtExecute()

oexfet()

OCIStmtExecute()、OCIStmtFetch() (注意: 結果セット行は暗黙的にプリフェッチできます。)

ofen()、ofetch()

OCIStmtFetch()

oflng()

なし

ogetpi()

OCIStmtGetPieceInfo()

olog()

OCILogon()

ologof()

OCILogoff()

onbclr()、onbset()、onbtst()

注意: 非ブロック化モードは、OCIAttrSet()またはOCIAttrGet()をサーバー・コンテキスト・ハンドルまたはサービス・コンテキスト・ハンドルでコールすることにより、設定またはチェックすることができます。

oopen()

注意: リリース8.x以上では、カーソルは使用されていません。

oopt()

なし

oparse()

OCIStmtPrepare()。ただし、すべてローカル。

opinit()

OCIEnvCreate()

orol()

OCITransRollback()

osetpi()

OCIStmtSetPieceInfo()

sqlld2()

SQLSvcCtxGetまたはSQLEnvGet

sqllda()

SQLSvcCtxGetまたはSQLEnvGet

odsc()

注意: 前述のodescr()を参照してください。

oermsg()

OCIErrorGet()

olon()

OCILogon()

orlon()

OCILogon()

oname()

注意: 前述のodescr()を参照してください。

osql3()

注意: 前述のoparse()を参照してください。

サポートされないOCIルーチン

OCIの以前のバージョンで使用可能だったOCIルーチンの一部は、現行リリースではサポートされません。それらは表1-2に記載されています。

表1-2 サポートされないOCI関数

OCIルーチン

以降のリリースでの等価または類似のOCIルーチン

obind()

OCIBindByName()、OCIBindByPos() (注意: 一部のデータ型には追加のバインド・コールが必要です。)

obindn()

OCIBindByName()、OCIBindByPos() (注意: 一部のデータ型には追加のバインド・コールが必要です。)

odfinn()

OCIDefineByPos() (注意: 一部のデータ型には追加の定義コールが必要です。)

odsrbn()

注意: 表1-1のodescr()を参照してください。

ologon()

OCILogon()

osql()

注意: 表1-1のoparse()を参照してください。

異なるリリースのOCIおよびサーバー間の互換性

この項では、異なるリリースのOCIおよびOracle Database間の互換性について説明します。

リリース7.x以上の新しいコールを使用していない既存の7.xアプリケーションは、現行のクライアント側ライブラリに再リンクする必要があります。

このアプリケーションでは、Oracle8i以降のオブジェクト機能が使用できず、これらのOCIリリースで提供されるパフォーマンスや拡張性も利用できません。

OCIのアップグレード

プログラマがリリース7.x以上の機能を既存のOCIアプリケーションに取り込む場合は、次の2つの選択肢があります。

- アプリケーションを完全にリライトして、現行のOCIコールのみを使用(推奨)

- リリース7.x以上の現行OCIコールをアプリケーションに取り込む一方で、一部の操作にはリリース7.xコールを使用

このマニュアルでは、既存のアプリケーションをリライトして現行のOCIコールのみを使用するために必要な情報を提供しています。

リリース7.x以上のOCIコールのリリース7.xアプリケーションへの追加

次のガイドラインは、プログラマが現行のOCIコールを使用し現行のOracleのデータ型および機能を取り込む一方で、一部の操作にはリリース7.xコールを使用する場合に適用されます。

- 既存のログインを変更して、olog()(または他のログイン・コール)のかわりにOCILogon()を使用します。サービス・コンテキスト・ハンドルは、現行のOCIコールで使用できるか、リリース7.xのOCIコールで使用されるLda_Defに変換できます。

関連項目:
複数のセッションをメンテナンスしているアプリケーションに必要なログイン・コールの詳細は、「OCIServerAttach()」および「OCISessionBegin()」の説明を参照してください。

- サーバー・コンテキスト・ハンドルを初期化した後は、リリース7.x以上のOCIコールで使用できます。

- リリース7 OCIコールを使用するには、OCISvcCtxToLda()を使用してサーバー・コンテキスト・ハンドルをLda_Defに変換し、結果のLda_Defをリリース7.xコールに渡します。

注意:
同じサーバー・ハンドルを共有する複数のサービス・コンテキストがある場合、Oracle Databaseリリース7.xモードでは常に1つのサービス・コンテキストのみが可能です。

- リリース7.x以上のOCIコールの使用を再開する場合は、アプリケーションでOCILdaToSvcCtx()を使用してLda_Defをサーバー・コンテキスト・ハンドルに変換しなおす必要があります。

- アプリケーションでは、必要に応じて、Lda_Defとサーバー・コンテキストを切り替えることができます。

このアプローチを行うと、アプリケーションで、単一の接続で2つの異なるAPIを使用して異なるタスクを達成できます。

リリース7.xのOCIコールとリリース7.x以上のOCIコールを混在させることは、トランザクション内では可能ですが、文内ではできません。これにより、あるSQL文またはPL/SQL文をリリース7.xのOCIコールで実行し、そのトランザクション内で、次のSQL文またはPL/SQL文を7.x以上のOCIコールで実行できます。

注意:
OCI 7.xのコールでカーソルをオープンし、解析することはできないため、リリース7.x以上のコールで文を実行してください。

OCI Instant Client

Instant Client機能により、Oracleホームの必要がなくなることで、OCI、OCCI、ODBCおよびJDBC OCIに基づくカスタマ・アプリケーションのデプロイが簡略化されます。Instant Clientモードで実行されるOCIアプリケーションの記憶領域の所要量は、クライアント側の完全インストールで実行される同じアプリケーションに比べて、大幅に少なくなります。Instant Client共有ライブラリは、クライアント側の完全インストールのディスク領域のうち、4分の1のみを使用します。

READMEは、Instant Clientインストールに付属しています。このファイルには、Instant Clientが生成されたバージョン、日時およびオペレーティング・システムが記載されています。

表1-3に、OCIアプリケーションのデプロイに必要なOracle Databaseのクライアント側ファイルを示します。

表1-3 OCI Instant Client共有ライブラリ

LinuxおよびUNIX

LinuxおよびUNIXでの説明

Microsoft Windows

Microsoft Windowsでの説明

libclntsh.so.11.1

クライアント・コード・ライブラリ

oci.dll

アプリケーションがリンクする転送機能

libociei.so

OCI Instant Clientデータの共有ライブラリ

oraociei11.dll

データとコード

libnnz11.so

セキュリティ・ライブラリ

orannzsbb11.dll

セキュリティ・ライブラリ

oci.sym、oraociei11.sym、orannzsbb11.sym

記号表

動的リンク・ライブラリ(DLL)ごとに1つの.symファイルが提供されます。.symがDLLと同じ場所にある場合、WindowsでOCIに障害が発生した際に、関数名を含むスタック・トレースが生成されます。

関連項目:
「OCIでの障害診断」

この表では、Oracle Database 11gリリース1のライブラリ名を使用しています。

Microsoft ODBCおよびOLEDBドライバを使用するには、ociw32.dllをORACLE_HOME\binディレクトリからコピーする必要があります。

Instant Clientの利点

Instant Clientを使用するのはなぜか。

- インストールの際にコピーされるファイルの数が少なくてすみます。

- Oracle Databaseのクライアント側で必要なファイル数およびディスク領域の合計が、大幅に少なくなります。

- Instant Clientモードでデプロイされたアプリケーションで、機能またはパフォーマンスが損なわれることはありません。

- 独立したソフトウェア・ベンダーは、アプリケーションを簡単にパッケージ化できます。

OCI Instant Clientのインストール・プロセス

Instant Clientライブラリは、Oracle Universal InstallerからInstant Clientオプションを選択するか、次のOracle Technology NetworkのWebサイトのOCIページ(OCIページの下部にあるInstant Clientのリンク)からInstant Clientライブラリをダウンロードしてインストールするかのいずれかでインストールできます。

http://www.oracle.com/technology/tech/oci/instantclient/index.html

Oracle Technology NetworkのWebサイトからInstant Clientライブラリをダウンロードしてインストールするには、次のようにします。

1. Instant Client共有ライブラリをOracle Databaseリリース11.2用の空のディレクトリ(instantclient_11_2など)にダウンロードし、インストールします。基本パッケージを選択します。

2. オペレーティング・システム共有ライブラリ・パス環境変数を、手順1のディレクトリに設定します。たとえば、LinuxまたはUNIXでは、LD_LIBRARY_PATHをinstantclient_11_2ディレクトリに設定します。Windowsでは、PATHをinstantclient_11_1ディレクトリに設定します。

3. 必要ならば、NLS_LANG環境変数を設定して、クライアント・アプリケーションとそのアプリケーションでオープンされたデータベース接続で使用される言語と地域、およびクライアントのキャラクタ・セット(クライアント・プログラムで入力または表示されるデータ用のキャラクタ・セット)を指定します。NLS_LANGは、UNIXプラットフォームでは環境変数として設定され、Windowsプラットフォームではレジストリで設定されます。NLS_LANG環境変数設定の詳細は、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

前述の手順を完了すると、OCIアプリケーションを実行できるようになります。

オペレーティング・システムのライブラリ・パス変数によってOCI共有ライブラリにアクセスできる場合、OCIアプリケーションは、Instant Clientモードで動作します。このモードでは、Oracleホームへの依存性はなく、Oracleホームに指定された他のコードおよびデータファイルは、OCIでは不要です(後で説明するtnsnames.oraファイルを除きます)。

Oracle Universal InstallerからInstant Clientをインストールするには、次のようにします。

1. Oracle Universal Installerを起動し、Instant Clientオプションを選択します。

2. Instant Client共有ライブラリをリリース11.2用の空のディレクトリ(instantclient_11_2など)にインストールします。

3. LD_LIBRARY_PATHをインスタント・クライアント・モードで動作するようにインスタント・クライアント・ディレクトリに設定します。

4. 必要ならば、NLS_LANG環境変数を設定して、クライアント・アプリケーションとそのアプリケーションでオープンされたデータベース接続で使用される言語と地域、およびクライアントのキャラクタ・セット(クライアント・プログラムで入力または表示されるデータ用のキャラクタ・セット)を指定します。NLS_LANGは、UNIXプラットフォームでは環境変数として設定され、Windowsプラットフォームではレジストリで設定されます。NLS_LANG環境変数設定の詳細は、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

クライアントの完全インストールを行った場合(Oracle Universal InstallerでAdminオプションを選択)、Instant Client共有ライブラリもインストールされます。クライアントの完全インストールにおけるInstant Client共有ライブラリの場所は、次のとおりです。

LinuxまたはUNIXの場合:

libociei.soライブラリは、$ORACLE_HOME/instantclientにあります。

libclntsh.so.11.1およびlibnnz11.soは、$ORACLE_HOME/libにあります。

Windowsの場合:

oraociei11.dllライブラリは、ORACLE_HOME¥instantclientにあります。

oci.dll、ociw32.dllおよびorannzsbb11.dllは、ORACLE_HOME¥binにあります。

OCIアプリケーションをInstant Clientモードで実行できるようするには、前述のライブラリを別のディレクトリにコピーして、オペレーティング・システム共有ライブラリ・パスをこのディレクトリがある場所に設定します。

注意:
すべてのライブラリを同じOracleホームからコピーして、同じディレクトリに配置する必要があります。Instant Clientライブラリへのsymlinkの関連付けは、ライブラリの物理的な関連付けに代わるものではありません。
オペレーティング・システムのLibrary Path変数に存在するOracleライブラリは1セットのみである必要があります。つまり、Instant Clientライブラリを含むディレクトリが複数ある場合、それらのディレクトリの1つのみをオペレーティング・システムのLibrary Path上に記載する必要があります。

同様に、Oracleホームベースのインストールを同じシステムに行う場合、オペレーティング・システムのLibrary PathにORACLE_HOME/libとInstant Clientディレクトリの両方を記載しないでください(Library Path上での順序も無関係です)。つまり、オペレーティング・システムのLibrary Path変数には、ORACLE_HOME/libディレクトリ(非Instant Clientモードで操作する場合)またはInstant Clientディレクトリ(Instant Clientモードで操作する場合)のいずれかを記載します。

OCCIやJDBC OCIなどのその他の機能を有効にするには、いくつかの追加ファイルをコピーする必要があります。OCCIを有効にするには、OCCIライブラリ(LinuxまたはUNIXではlibocci.so.11.1、Windowsではoraocci11.dll)をInstant Clientディレクトリにインストールする必要があります。JDBC OCIドライバの場合、3つのOCI共有ライブラリ以外に、OCI JDBCライブラリ(LinuxまたはUNIXではlibocijdbc11.so、Windowsではocijdbc11.dllなど)もダウンロードする必要があります。すべてのライブラリをInstant Clientディレクトリに配置します。

注意:
Sparc64などのハイブリッド・プラットフォームでは、JDBC OCIドライバをInstant Clientモードで動作させるために、libociei.soライブラリをORACLE_HOME/instantclient32ディレクトリからInstant Clientディレクトリにコピーします。JDBC OCI Instant Clientに必要なその他すべてのSparc64ライブラリを、ORACLE_HOME/lib32ディレクトリからInstant Clientディレクトリにコピーします。

Instant Clientを使用する場合

Instant Clientはデプロイメント用の機能であるため、本番アプリケーションの実行に使用します。一般的に、Instant Clientモードがクライアント側動作専用でないかぎり、Instant Clientモードで実行されているアプリケーションではすべてのOCI機能を使用できます。したがって、サーバー側の外部プロシージャは、Instant Clientモードでは動作しません。

開発には、Instant Client SDKを使用することもできます。

関連項目:

- 「Instant Client SDK」

- 「OCIでの障害診断」

LinuxまたはUNIXでのInstant Client共有ライブラリへのパッチの適用

Instant Clientはデプロイメント用の機能であるため、OCIアプリケーションの実行に必要なファイルの数およびサイズ(クライアント・フットプリント)が減らされました。したがって、Instant Client共有ライブラリにパッチを適用するために必要なファイルは、Instant Clientのデプロイメントですべて入手できるわけではありません。Instant Client共有ライブラリにパッチを適用するには、Oracleホームをベースとした完全なクライアント・インストールが必要です。opatchユーティリティを使用して、Instant Client共有ライブラリにパッチを適用します。

Oracleホーム環境にパッチを適用した後、「OCI Instant Clientのインストール・プロセス」の説明に従って、表1-3に記載されているファイルをInstant Clientディレクトリにコピーします。

個々のファイルをコピーするかわりに、「データ共有ライブラリ、zipおよびRPMファイルの再生成」の説明に従って、OCIとOCCI、JDBCおよびSQL*Plus用のInstant Client zipおよびRPMファイルを生成できます。次に、「OCI Instant Clientのインストール・プロセス」の説明に従って、zipおよびRPMファイルをターゲット・システムにコピーして解凍します。

opatchユーティリティによって、ORACLE_HOMEインストールのパッチ適用情報がlibclntsh.soに格納されます。この情報を取り出すには、次のコマンドを使用します。

genezi -v

Instant Clientのデプロイメント・システムにgeneziユーティリティがない場合、ORACLE_HOME/binディレクトリからそれをコピーできます。

注意:
opatchユーティリティは、Windowsでは使用できません。

データ共有ライブラリ、zipおよびRPMファイルの再生成

データ共有ライブラリとzipおよびRPMファイルを再生成するプロセスは、リリース11.2以上用に変わりました。データ共有ライブラリ、zipおおよびRPMファイルを作成するために、別々のターゲットが個々にまたは一度に追加されます。以前のリリースでは、データ共有ライブラリ、zipおよびRPMファイルの作成のために、1つのターゲットilibocieiが提供されました。ilibocieiでは、zipおよびRPMファイルのみが作成されるようになりました。データ共有ライブラリの再生成には、コンパイラとリンカーの両方が必要で、これらはすべてのインストールで使用可能というわけではありません。したがって、データ共有ライブラリの再生成のために、別々のターゲットが追加されています。

注意:
再生成されたInstant Clientバイナリには、再生成を行ったOracle Client AdministratorホームでインストールされたInstant Clientファイルのみが含まれます。そのため、再生成環境に存在するエラー・メッセージ、キャラクタ・セット・エンコーディングおよびタイムゾーン・ファイルは、データ共有ライブラリにパッケージされているもののみです。エラー・メッセージ、キャラクタセット・エンコーディングおよびタイムゾーン・ファイルは、Oracle Client Administratorホームのインストールで選択された各国語に依存します。

データ共有ライブラリlibociei.soの再生成

OCI Instant Clientデータ共有ライブラリ(libociei.so)は、ORACLE_HOMEの管理者インストールで次のコマンドを使用することで再生成できます。

cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk igenlibociei

新しく再生成されたlibociei.soは、ORACLE_HOME/instantclientディレクトリに置かれます。同じディレクトリにある元の既存のlibociei.soは、libociei.so0に名前が変更されます。

データ共有ライブラリlibociicus.soの再生成

Instant Client Lightデータ共有ライブラリ(libociicus.so)を再生成するには、次のコマンドを使用します。

mkdir -p $ORACLE_HOME/rdbms/install/instantclient/light
cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk igenlibociicus

新しく再生成されたlibociicus.soは、ORACLE_HOME/instantclient/lightディレクトリに置かれます。同じディレクトリにある元の既存のlibociicus.soは、libociicus.so0に名前が変更されます。

データ共有ライブラリlibociei.soおよびlibociicus.soの同時再生成

データ共有ライブラリlibociei.soとlibociicus.soを再生成するには、次のコマンドを使用します。

mkdir -p $ORACLE_HOME/rdbms/install/instantclient/light
cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk igenliboci

新しく再生成されたlibociei.soは、ORACLE_HOME/instantclientディレクトリに置かれます。同じディレクトリにある元の既存のlibociei.soは、libociei.so0に名前が変更されます。

新しく再生成されたlibociicus.soは、ORACLE_HOME/instantclient/lightディレクトリに置かれます。同じディレクトリにある元の既存のlibociicus.soは、libociicus.so0に名前が変更されます。

基本パッケージ用のzipおよびRPMファイルの再生成

基本パッケージ用にzipおよびRPMファイルを再生成するには、次のコマンドを使用します。

cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ic_basic_zip

基本軽量パッケージ用のzipおよびRPMファイルの再生成

基本軽量パッケージ用にzipおよびRPMファイルを再生成するには、次のコマンドを使用します。

cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ic_basiclite_zip

JDBCパッケージ用のzipおよびRPMファイルの再生成

JDBCパッケージ用にzipおよびRPMファイルを再生成するには、次のコマンドを使用します。

cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ic_jdbc_zip

ODBCパッケージ用のzipおよびRPMファイルの再生成

ODBCパッケージ用にzipおよびRPMファイルを再生成するには、次のコマンドを使用します。

cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ic_odbc_zip

SQL*Plusパッケージ用のzipおよびRPMファイルの再生成

SQL*Plusパッケージ用にzipおよびRPMファイルを再生成するには、次のコマンドを使用します。

cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ic_sqlplus_zip

ツール・パッケージ用のzipおよびRPMファイルの再生成

ツール・パッケージ用にzipおよびRPMファイルを再生成するには、次のコマンドを使用します。

cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ic_tools_zip

全パッケージ用のzipおよびRPMファイルの再生成

全パッケージ用にzipおよびRPMファイルを再生成するには、次のコマンドを使用します。

cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ilibociei

新しいzipおよびRPMファイルが次のディレクトリに生成されます。

$ORACLE_HOME/rdbms/install/instantclient

データ共有ライブラリ、zipおよびRPMファイルの再生成は、Windowsプラットフォームでは使用できません。

OCI Instant Clientのデータベース接続文字列

OCI Instant Clientからは、通常のSQLクライアントで可能なすべての方法で、リモート・データベースに接続できます。ただし、Instant ClientにはOracleホーム環境およびディレクトリ構造がないため、一部のデータベース・ネーミング・メソッドには追加の構成手順が必要です。

(tnsnames.oraまたはsqlnet.oraなどの構成ファイルを検索するために) ORACLE_HOMEまたはTNS_ADMINを使用する必要のない、すべてのOracle Netネーミング・メソッドは、Instant Clientモードで動作します。特に、OCIServerAttach()コールのconnect_identifierは、次の形式で指定できます。

- SQL接続URL文字列のフォームは、次のようになります。

[//]host[:port][/service name]

たとえば、次のようにします。

//dlsun242:5521/bjava21

- Oracle Net接続記述子。たとえば、次のようにします。

"(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=dlsun242) (PORT=5521))
(CONNECT_DATA=(SERVICE_NAME=bjava21)))"

- サイトがLDAPサーバー・ディレクトリ用に構成されているディレクトリ・ネーミングを通じて解決される接続名。

tnsnamesなどのネーミング・メソッドやディレクトリ・ネーミングを使用するには、TNS_ADMIN環境変数を設定する必要があります。

関連項目:
接続記述子の詳細は、『Oracle Database Net Services管理者ガイド』の「ネーミング・メソッドの構成」を参照してください。

TNS_ADMIN環境変数が設定されていない場合に、inst1などのTNSNAMESエントリを使用するときは、ORACLE_HOME変数を設定する必要があります。また、構成ファイルは$ORACLE_HOME/network/adminディレクトリに存在する必要があります。

この場合、ORACLE_HOME変数は、Oracle Net構成ファイルの検索のみに使用され、クライアント・コード・ライブラリの他のコンポーネント(OCI、NLSなど)は、ORACLE_HOMEの値を使用しません。

OCIServerAttach()コールで接続文字列としてNULL文字列""を使用する場合、TWO_TASK環境変数をconnect_identifierに設定できます。Windowsオペレーティング・システムでは、TWO_TASKのかわりにLOCAL環境変数を使用します。

同様に、SQL*PlusなどのOCIコマンド・ライン・アプリケーションには、TWO_TASK (WindowsではLOCAL)環境変数をconnect_identifierに設定できます。この環境変数には、通常の接続文字列上で'@'より右側であれば、任意の値を指定できます。

Instant Client接続識別子の例

SQL*PlusをInstant Clientモードで使用するには、接続識別子を次のように指定します。

Oracle Databaseのlistener.oraファイルに次の記述が含まれる場合:

LISTENER = (ADDRESS_LIST=
(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))
)

SID_LIST_LISTENER = (SID_LIST=
(SID_DESC=(SID_NAME=rdbms3)(GLOBAL_DBNAME=rdbms3.server6.us.alchemy.com)
(ORACLE_HOME=/home/dba/rdbms3/oracle))
)

SQL*Plus接続識別子は次のようになります。

"(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))(CONNECT_DATA=
(SERVICE_NAME=rdbms3.server6.us.alchemy.com)))"

接続識別子は次のように指定することもできます。

"//server6:1573/rdbms3.server6.us.alchemy.com"

または、TWO_TASK環境変数を任意の以前の接続識別子に設定し、接続識別子を新規に指定せずに接続することもできます。たとえば、次のようにします。

setenv TWO_TASK "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))
(CONNECT_DATA=(SERVICE_NAME=rdbms3.server6.us.alchemy.com)))"

TWO_TASK環境変数を次のように指定することもできます。

setenv TWO_TASK //server6:1573/rdbms3.server6.us.alchemy.com

その後、空の接続識別子でSQL*Plusを起動できます(パスワードの入力を求められます)。

sqlplus user

接続記述子は、tnsnames.oraファイルにも指定できます。たとえば、tnsnames.oraファイルに次の接続記述子が記載され、

conn_str = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))(CONNECT_DATA=
(SERVICE_NAME=rdbms3.server6.us.alchemy.com)))

tnsnames.oraファイルが/home/webuser/instantclientディレクトリにある場合、変数TNS_ADMIN (WindowsではLOCAL)を次のように設定できます。

setenv TNS_ADMIN /home/webuser/instantclient

その後、接続識別子conn_strを使用して、SQL*Plusを起動するか、OCI接続を行うことができます。

注意:
TNS_ADMINには、tnsnames.oraファイルを配置するディレクトリを指定します。TNS_ADMINはtnsnames.oraファイルのフル・パスではありません。

前述のtnsnames.oraファイルがインストールが行われたOracleホームの、/network/server6/home/dba/oracle/network/adminディレクトリにある場合、ORACLE_HOME環境変数を次のように設定して、前と同様にSQL*Plusを識別子conn_strを使用して起動できます。

setenv ORACLE_HOME /network/server6/home/dba/oracle

最後に、tnsnames.oraがTNS_ADMINまたはORACLE_HOMEにあれば、TWO_TASK環境変数を次のように設定して、接続識別子なしでSQL*Plusを起動できます。

setenv TWO_TASK conn_str

OCI Instant Clientの環境変数

ORACLE_HOME環境変数は、NLS、COREおよびエラー・メッセージ・ファイルの場所を決定しなくなりました。OCI専用アプリケーションでは、ORACLE_HOMEを設定しないでください。ただし、設定されていても、OCIには影響はありません。OCIは、データ共有ライブラリからデータを常に取得します。データ共有ライブラリが使用できない場合のみORACLE_HOMEが使用され、クライアントの完全インストールとみなされます。ORACLE_HOMEを設定する必要がなくても、設定する場合には、ディレクトリを識別する有効なオペレーティング・システム・パス名に設定する必要があります。

動的ユーザー・コールバック・ライブラリをロードする場合は、このマニュアルで指定されているように、ORACLE_HOME/lib (WindowsではORACLE_HOME¥bin)にコールバック・パッケージが存在する必要があります。この場合、ORACLE_HOMEを設定します。

Instant Clientモードでは、環境変数ORA_NLS10およびORA_NLS_PROFILE33は無視されます。

Instant Clientモードでは、ORA_TZFILE変数が設定されていない場合、データ共有ライブラリのより大きいデフォルトのtimezlrg_n.datファイルが使用されます。データ共有ライブラリのより小さいtimezone_n.datファイルが使用される場合は、絶対パス名または相対パス名を使用せずに、ORA_TZFILE環境変数をファイルの名前に設定します。

LinuxまたはUNIXの場合:

setenv ORA_TZFILE timezone_n.dat

Windowsの場合:

set ORA_TZFILE=timezone_n.dat

これらの場合、nはタイムゾーン・データ・ファイルのバージョン番号です。

Instant Clientデータ共有ライブラリにパッケージされている大小のタイムゾーン・ファイルのバージョンを特定するには、次のコマンドを入力して、geneziユーティリティを実行します。

genezi -v

(データ共有ライブラリが使用できないために) OCIがInstant Clientモードで動作していない場合、以前のOracle Databaseのリリースと同様に、ORA_TZFILE変数(設定されている場合)は、完全なパス名を付けます。

TNSNAMESエントリが使用されている場合は、前述したように、TNS_ADMINディレクトリにはTNSNAMES構成ファイルを含める必要があります。TNS_ADMINが設定されていない場合は、ORACLE_HOME/network/adminディレクトリにOracle Net Services構成ファイルを含める必要があります。

Instant Client Light(English)

Instant ClientのInstant Client Light (English)バージョンでは、クライアントのインストールに必要なディスク領域が削減されています。英語以外の言語のエラー・メッセージ・ファイルを削除し、サポートされるキャラクタ・セット定義を約250の中からわずかな数のみ残すことで、ライブラリのサイズが削減されました。

このInstant Client Lightバージョンは、US7ASCII、WE8DEC、WE8ISO8859P1、WE8MSWIN1252またはUnicodeキャラクタ・セットのいずれかを使用するアプリケーション向けです。NLS_LANG設定のLANGUAGEおよびTERRITORYフィールドに制限がないため、Instant Client Lightはあらゆる言語および地域設定で動作します。Instant Client Lightでは英語のエラー・メッセージのみ提供されているため、NLS_LANGがAMERICAN以外の言語に設定されている場合でも、Net接続エラーなどのクライアント側で生成されたエラー・メッセージは常に英語でレポートされます。データベース・インスタンスのOracleホームに適切な翻訳済メッセージ・ファイルがインストールされている場合、SQL文の構文エラーなどのデータベース側で生成されたエラー・メッセージは、選択した言語となります。

グローバリゼーション設定

Instant Client Lightは、次のクライアント・キャラクタ・セットをサポートします。

シングルバイト

- US7ASCII

- WE8DEC

- WE8MSWIN1252

- WE8ISO8859P1

Unicode

- UTF8

- AL16UTF16

- AL32UTF8

Instant Client Lightは、次のいずれかのデータベース・キャラクタ・セットを使用するデータベースに接続できます。

- US7ASCII

- WE8DEC

- WE8MSWIN1252

- WE8ISO8859P1

- WE8EBCDIC37C

- WE8EBCDIC1047

- UTF8

- AL32UTF8

Instant Client Lightは、前述のリストにないキャラクタ・セットがクライアントまたはデータベースのキャラクタ・セットとして使用された場合に、エラーを戻します。

Instant Client Lightは、OCI_UTF16モードで作成されたOCI環境ハンドルを使用しても動作できます。

関連項目:
各国語サポート(NLS)の詳細は、 『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

Instant Client Lightの動作

OCIアプリケーションは、デフォルトで、OCIデータ共有ライブラリlibociei.so(WindowsではOraociei11.dll)をLD_LIBRARY_PATH(WindowsではPATH)から検索し、アプリケーションがInstant Clientモードで動作するかどうかを判断します。このライブラリが見つからない場合、OCIではInstant Client Lightデータ共有ライブラリ(表1-4を参照)libociicus.so(WindowsではOraociicus11.dll)のロードを試みます。Instant Client Lightのライブラリが見つかった場合、アプリケーションはInstant Client Lightモードで動作します。それ以外の場合は、Oracleホームでの完全インストールが想定されます。

表1-4 OCI Instant Client Light共有ライブラリ

LinuxおよびUNIX

LinuxおよびUNIXでの説明

Windows

Windowsでの説明

libclntsh.so.11.1

クライアント・コード・ライブラリ

oci.dll

アプリケーションがリンクする転送機能

libociicus.so

OCI Instant Client Lightデータの共有ライブラリ

oraociicus11.dll

データとコード

libnnz11.so

セキュリティ・ライブラリ

orannzsbb11.dll

セキュリティ・ライブラリ

oci.sym、oraociicus11.sym、orannzsbb11.sym

記号表

Instant Client Lightのインストール

Instant Client Lightのインストールは、次のいずれかの方法で行うことができます。

- OTNから
Oracle Technology Network WebサイトのOCI URL(OCIページの下部にあるInstant Clientのリンク)からInstant Clientリンクに移動します。

http://www.oracle.com/technology/software/tech/oci/instantclient/

Instant Client Lightの場合、basiclite.zipパッケージを空のinstantclient_11_2ディレクトリにダウンロードし、解凍します。

- クライアントの完全(Adminオプション)インストールから
ORACLE_HOME/instantclient/lightサブディレクトリから、libociicus.so (WindowsではOraociicus11.dll)をコピーします。LD_LIBRARY_PATH (WindowsではPATH)のInstant Clientディレクトリに、サイズの大きいOCI Instant Clientデータ共有ライブラリlibociei.so (WindowsではOraociei11.dll)のかわりに、Instant Client Lightデータ共有ライブラリlibociicus.so (WindowsではOraociicus11.dll)を格納します。

- Oracle Universal Installerから
Oracle Universal InstallerでInstant Clientオプションを選択した場合、libociei.so (WindowsではOraociei11.dll)はインストールのベース・ディレクトリにインストールされ、これらのファイルがLD_LIBRARY_PATH (WidowsではPATH)に置かれることになります。

Instant Light Clientデータ共有ライブラリlibociicus.so (WindowsではOraociicus11.dll)は、ベース・ディレクトリのlightサブディレクトリにインストールされ、デフォルトでは無効です。したがって、Instant Client Lightモードを使用するには、OCIデータ共有ライブラリlibociei.so (WindowsではOraociei11.dll)を削除するか名前を変更し、Instant Client Lightのライブラリをその環境のlightサブディレクトリからベース・ディレクトリにコピーする必要があります。

たとえば、Oracle Universal InstallerでInstant ClientをLD_LIBRARY_PATH (WindowsではPATH)のmy_oraic_11_2ディレクトリにインストールした場合、Instant Client Lightモードを使用するには、次を実行する必要があります。

cd my_oraic_11_2
rm libociei.so
mv light/libociicus.so .

注意:
インストールに互換性のないバイナリが存在しないように、常に空のディレクトリにInstant Clientのファイルをコピーしインストールしてください。

Instant Client SDK

SDKは、次のOracle Technology Network WebサイトのOCI URL上のInstant Clientリンク(Instant ClientリンクはOCIページの下部にあります)からダウンロードできます。

http://www.oracle.com/technology/tech/oci/instantclient/

- Instant Client SDKパッケージには、CおよびC++のヘッダー・ファイルと、Instant Client環境でOCIおよびOCCIアプリケーションを開発するためのMakefileが含まれています。開発したアプリケーションは、あらゆるクライアント環境にデプロイできます。

- SDKには、CおよびC++のデモ・プログラムが含まれています。

- Windowsの場合、OCIまたはOCCIアプリケーションをリンクするために必要なライブラリも含まれています。デモをビルドするための、Make.batが提供されています。

- UNIXまたはLinuxの場合、デモをビルドするにはmakefile demo.mkを指定します。アプリケーションをリンクする前に、LD_LIBRARY_PATHにinstantclient_11_2ディレクトリを必ず定義します。OCIおよびOCCIプログラムでは、instantclient_11_2ディレクトリにシンボリック・リンクlibclntsh.soおよびlibocci.soを配置する必要があります。リンク・ステップの前に、demo.mkによりこれらのリンクが作成されます。これらのシンボリック・リンクは、シェルで作成することもできます。

cd instantclient_11_2
ln -s libclntsh.so.11.1 libclntsh.so
ln -s libocci.so.11.1 libocci.so

- また、SDKには、アプリケーション・ヘッダー・ファイルを生成するための、Object Type Translator (OTT)ユーティリティとそのクラスが含まれます。

2 OCIプログラミングの基本

この章では、OCIを使用してプログラムを作成する際に必要となる概念および手順について説明します。この章を読み終えると、基本的なOCIアプリケーションの作成に必要なツールについてほとんど習得したことになります。

この章は、次の主要な項で構成されています。

- ヘッダー・ファイルおよびMakefileの場所

- OCIプログラムのプログラミングの概要

- OCIデータ構造

- OCIプログラミング・ステップ

- OCIでのエラー処理

- その他のコーディング・ガイドライン

- OCIプログラムでのPL/SQL使用方法

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

新規ユーザーは、この章の情報に特に注意してください。この章は、以降の章を理解する基本となります。以降の章の内容は、この章の内容を補足しています。

関連項目:

- 多言語環境に適用されるOCI関数の詳細は、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

- カートリッジ・サービスに適用されるOCI関数の詳細は、『Oracle Databaseデータ・カートリッジ開発者ガイド』を参照してください。

ヘッダー・ファイルおよびMakefileの場所

LinuxおよびUNIXオペレーティング・システムでOCIおよびOCCIクライアント・アプリケーションの開発に必要なOCIおよびOCCIヘッダー・ファイルは、$ORACLE_HOME/rdbms/publicディレクトリにあります。これらのファイルは、Oracle Databaseサーバー環境でも、Oracle Databaseクライアント管理およびカスタム環境でも使用できます。

すべてのデモ・プログラムとそれらの関連ヘッダー・ファイルは、引き続き$ORACLE_HOME/rdbms/demoディレクトリにあります。これらのデモ・ファイルは、Examplesメディアからのみインストールできます。これらのプログラムの名前とその目的の詳細は、付録Bを参照してください。

demoディレクトリに複数のMakefileが用意されています。各Makefileには、OCI実行可能ファイルを作成する際の指示のコメントが含まれています。コンパイル・エラーとリンク・エラーを回避するために、できるかぎりこれらのデモ用Makefileを使用することをお薦めします。

demo_rdbms.mkファイルは、demoディレクトリにあるサンプルMakefileです。コメントには、デモ用OCIプログラムのビルド方法が含まれています。demo_rdbms.mkファイルには、$ORACLE_HOME/rdbms/publicディレクトリが含まれています。独自のカスタマイズMakefileで、INCLUDEパスに$ORACLE_HOME/rdbms/publicディレクトリがあることを確認してください。

ociucb.mkファイルは、demoにあるコールバック共有ライブラリ作成用Makefileです。

OCIプログラムのプログラミングの概要

OCIアプリケーションの全般的な目標は、マルチ・ユーザーのために稼働することです。N層構造では、マルチ・ユーザーがクライアント・アプリケーションにHTTP要求を送信します。クライアント・アプリケーションでは、データ交換やデータ処理など、いくつかのデータ操作を実行する必要があります。

OCIでは、次の基本的なプログラム・フローを使用しています。

1. OCIプログラミング環境およびスレッドの初期化により環境を作成します。

2. 必要なハンドルの割当て、およびサーバー接続とユーザー・セッションの確立。

3. サーバー上でのSQL文の実行、データベース・サーバーとの間でのデータ交換、必要なアプリケーション・データ処理の実行。

4. プリペアド文の実行、または新規に実行する文の準備

5. ユーザー・セッションを終了し、サーバー接続から切断します。

6. ハンドルおよびデータ構造を解放します。

図2-1は、OCIアプリケーションのステップの流れを示しています。「OCIプログラミング・ステップ」では、各ステップをより詳細に説明しています。

図2-1基本的なOCIプログラムの流れ

図およびステップ・リストは、OCIプログラミングのステップを簡潔に表したものです。さらに、プログラムの機能性に応じて様々なバリエーションが考えられます。複数セッションおよび複数トランザクションの管理やオブジェクトの使用など、より高度な機能が組み込まれるOCIアプリケーションには、追加のステップが必要です。

すべてのOCI関数コールは、ある環境のコンテキスト内で実行されます。1つのOCIプロセス内に複数の環境が存在することが可能です。環境でプロセスレベルの初期化が必要になった場合には、自動的に実行されます。

注意:
OCIアプリケーションには、複数のアクティブな接続および文を含めることができます。

関連項目:
オブジェクトに対するアクセスおよび操作の詳細は、第11章から第15章を参照してください。

OCIデータ構造

ハンドルと記述子は、OCIアプリケーションで定義された不透明なデータ構造体です。ハンドルと記述子は、特定の割当てコールによって直接割り当てるか、あるいはOCI関数を使用して暗黙的に割り当てることができます。

7.xアップグレードの注意:
リリース7.x OCIのアプリケーション作成の経験を持つプログラマは、大部分のOCIコールに使用されているこれらのデータ構造に慣れる必要があります。

ハンドルおよび記述子を使用して、データ、接続またはアプリケーション動作に関係する情報を格納します。ハンドルについては、次の項で詳しく定義します。記述子の詳細は、「OCI記述子」を参照してください。

ハンドル

ほとんどすべてのOCIコールには、パラメータ・リストに1つ以上のハンドルを含めることができます。ハンドルは、OCIライブラリによって割り当てられる記憶域への不透明なポインタです。ハンドルを使用して、コンテキストまたは接続情報を格納するか(たとえば、環境ハンドルまたはサービス・コンテキスト・ハンドル)、またはOCI関数やデータに関する情報を格納します(たとえば、エラー・ハンドルまたは記述ハンドル)。ハンドルを使用すると、アプリケーションではなくライブラリにこのデータが保持されるため、プログラミングが簡単になります。

ほとんどのOCIアプリケーションでは、ハンドルに格納されている情報へのアクセスが必要となります。この情報にアクセスして設定するには、属性の入手および設定のためのOCIコールであるOCIAttrGet()およびOCIAttrSet()を使用します。

関連項目:
「ハンドル属性」

表2-1は、OCI用に定義されているハンドルを示しています。それぞれのハンドル・タイプについて、OCIコールでハンドル・タイプを識別するために使用される、Cデータ型およびハンドル・タイプ定数をリストしています。

表2-1 OCIハンドル・タイプ

説明

Cデータ型

ハンドル・タイプ定数

OCI環境ハンドル

OCIEnv

OCI_HTYPE_ENV

OCIエラー・ハンドル

OCIError

OCI_HTYPE_ERROR

OCIサービス・コンテキスト・ハンドル

OCISvcCtx

OCI_HTYPE_SVCCTX

OCI文ハンドル

OCIStmt

OCI_HTYPE_STMT

OCIバインド・ハンドル

OCIBind

OCI_HTYPE_BIND

OCI定義ハンドル

OCIDefine

OCI_HTYPE_DEFINE

OCI記述ハンドル

OCIDescribe

OCI_HTYPE_DESCRIBE

OCIサーバー・ハンドル

OCIServer

OCI_HTYPE_SERVER

OCIユーザー・セッション・ハンドル

OCISession

OCI_HTYPE_SESSION

OCI認証情報ハンドル

OCIAuthInfo

OCI_HTYPE_AUTHINFO

OCI接続プール・ハンドル

OCICPool

OCI_HTYPE_CPOOL

OCIセッション・プール・ハンドル

OCISPool

OCI_HTYPE_SPOOL

OCIトランザクション・ハンドル

OCITrans

OCI_HTYPE_TRANS

OCI複合オブジェクト検索(COR)ハンドル

OCIComplexObject

OCI_HTYPE_COMPLEXOBJECT

OCIスレッド・ハンドル

OCIThreadHandle

該当なし

OCIサブスクリプション・ハンドル

OCISubscription

OCI_HTYPE_SUBSCRIPTION

OCIダイレクト・パス・コンテキスト・ハンドル

OCIDirPathCtx

OCI_HTYPE_DIRPATH_CTX

OCIダイレクト・パス関数コンテキスト・ハンドル

OCIDirPathFuncCtx

OCI_HTYPE_DIRPATH_FN_CTX

OCIダイレクト・パス列配列ハンドル

OCIDirPathColArray

OCI_HTYPE_DIRPATH_COLUMN_ARRAY

OCIダイレクト・パス・ストリーム・ハンドル

OCIDirPathStream

OCI_HTYPE_DIRPATH_STREAM

OCIプロセス・ハンドル

OCIProcess

OCI_HTYPE_PROC

OCI管理ハンドル

OCIAdmin

OCI_HTYPE_ADMIN

OCI HAイベント・ハンドル

OCIEvent

該当なし

ハンドルの割当てと解放

アプリケーションでは、すべてのハンドル(バインド・ハンドル、定義ハンドルおよびスレッド・ハンドルは除く)が、特定の環境ハンドルに対して割り当てられます。環境ハンドルをパラメータの1つとして、ハンドル割当てコールに渡します。こうして、割り当てられたハンドルは、その特定の環境に固有のものとなります。

バインド・ハンドルおよび定義ハンドルは、文ハンドルを親として割り当てられ、そのハンドルによって表される文についての情報を含みます。

注意:
バインド・ハンドルおよび定義ハンドルは、OCIライブラリによって暗黙的に割り当てられるため、ユーザーによる割当ては不要です。

環境ハンドルはOCIEnvCreate()またはOCIEnvNlsCreate()のコールによって割り当てられ、初期化され、このいずれかのコールがすべてのOCIアプリケーションで必要です。

ユーザー割当てハンドルは、すべてOCIハンドル割当てコールOCIHandleAlloc()によって初期化されます。

ハンドルのタイプには、セッション・プール・ハンドル、ダイレクト・パス・コンテキスト・ハンドル、スレッド・ハンドル、CORハンドル、サブスクリプション・ハンドル、記述ハンドル、文ハンドル、サービス・コンテキスト・ハンドル、エラー・ハンドル、サーバー・ハンドル、接続プール・ハンドル、イベント・ハンドルおよび管理ハンドルがあります。

スレッド・ハンドルは、OCIThreadHndInit()コールによって割り当てられます。

アプリケーションは、ハンドルが不要になった時点で全ハンドルを解放する必要があります。すべてのハンドルはOCIHandleFree()関数によって解放されます。

注意:
親ハンドルが解放されると、それに対応付けられた子ハンドルもすべて解放され、それ以降使用できなくなります。たとえば、文ハンドルが解放されると、それに関連付けられたバインド・ハンドルおよび定義ハンドルも解放されます。

ハンドルにより、グローバル変数を使用する必要性が少なくなります。また、エラー・レポートが簡単になります。エラー・ハンドルは、エラーと診断情報を戻すために使用します。

関連項目:
OCIハンドルの割当ておよび使用方法を説明するサンプル・コードは、付録Bに示されたサンプル・プログラムを参照してください。

環境ハンドル

環境ハンドルは、すべてのOCI関数を起動させるコンテキストを定義します。各環境ハンドルにはメモリー・キャッシュがあり、これによってメモリー・アクセスが高速になります。環境ハンドルに基づくメモリーの割当ては、このキャッシュで行われます。キャッシュへのアクセスは、複数のスレッドが同じ環境ハンドルに基づいてメモリーの割当てを試行する場合にシリアライズされます。複数のスレッドで単一の環境ハンドルを共有する場合、スレッドはキャッシュへのアクセスをブロックすることがあります。

環境ハンドルは、parentパラメータとしてOCIHandleAlloc()コールに渡され、その他のすべてのハンドル・タイプを割り当てます。バインド・ハンドルと定義ハンドルは、暗黙的に割り当てられます。

エラー・ハンドル

エラー・ハンドルは、大部分のOCIコールにパラメータとして渡されます。エラー・ハンドルは、OCI操作中に発生したエラーについての情報をメンテナンスします。コールでエラーが発生した場合、エラー・ハンドルをOCIErrorGet()に渡して、発生したエラーに関する追加情報を取得することができます。

ほとんどのOCIコールではパラメータとしてエラー・ハンドルが必要であるため、エラー・ハンドルの割当ては、OCIアプリケーションの最初のステップの1つです。

関連項目:
「スレッド・セーフティの実装」

サービス・コンテキスト・ハンドルとそれに対応付けられたハンドル

サービス・コンテキスト・ハンドルは、サーバーに対するOCIコールの操作コンテキストを決定する属性を定義します。サービス・コンテキスト・ハンドルには、サーバー接続、ユーザー・セッションおよびトランザクションを表す属性として3つのハンドルが含まれています。これらの属性は、図2-2で説明されています。

図2-2 サービス・コンテキストのコンポーネント

- サーバー・ハンドルは、データベースへの接続を識別します。これは、接続指向のトランスポート・メカニズムによって物理接続に変換されます。

- ユーザー・セッション・ハンドルは、ユーザーのロールと権限(ユーザーのセキュリティ・ドメインとも呼ばれる)およびコールを実行するための操作コンテキストを定義します。

- トランザクション・ハンドルは、SQL操作を実行するトランザクションを定義します。トランザクション・コンテキストには、フェッチ状態やパッケージのインスタンス化などの、ユーザー・セッション状態の情報が含まれています。

この方法によるサービス・コンテキスト・ハンドルの分析は、拡張性を提供し、プログラマは、洗練された複数層のアプリケーションとトランザクション処理(TP)モニターを作成して、複数のアプリケーション・サーバーと異なるトランザクション・コンテキスト上の複数のユーザーの要求を実行できます。

サービス・コンテキスト・ハンドルを使用する際は、その前にOCIHandleAlloc()、OCILogon()またはOCILogon2()によって、割当てと初期化を行う必要があります。サービス・コンテキスト・ハンドルは、OCIHandleAlloc()によって明示的に割り当てられます。また、サーバー・ハンドル、セッション・ハンドルおよびトランザクション・ハンドルでは、OCIAttrSet()を使用して初期化できます。サービス・コンテキスト・ハンドルがOCILogon()によって暗黙的に割り当てられている場合には、すでに初期化されています。

データベース接続ごとに常時シングル・ユーザー・セッションのみをメンテナンスするアプリケーションでは、OCILogon()をコールして、初期化されたサービス・コンテキスト・ハンドルを取得できます。

より複雑なセッション管理を必要とするアプリケーションでは、サービス・コンテキスト・ハンドルを明示的に割り当てる必要があり、サーバー・ハンドルおよびユーザー・セッション・ハンドルは、サービス・コンテキスト・ハンドルに明示的に設定する必要があります。OCIServerAttach()コールとOCISessionBegin()コールは、サーバー・ハンドルとユーザー・セッション・ハンドルを初期化します。

グローバル・トランザクションの場合、あるいはセッションに対してアクティブなトランザクションが複数存在する場合、アプリケーションではトランザクションを明示的に定義するのみです。また、アプリケーションでは、データベースの内容を変更した際にOCIによって自動的に作成された暗黙的トランザクションを正しく処理できます。

関連項目:

- 「OCIでのトランザクションのサポート」

- サーバー接続およびユーザー・セッションの確立の詳細は、「OCI環境の初期化」および「パスワードおよびセッションの管理」を参照してください。

文ハンドル、バインド・ハンドルおよび定義ハンドル

文ハンドルは、図2-3に示すように、SQL文またはPL/SQL文と、それぞれに関連付けられた属性を識別するコンテキストです。

図2-3 文ハンドル

入力および出力バインド変数に関する情報は、バインド・ハンドルに格納されています。OCIライブラリでは、OCIBindByName()またはOCIBindByPos()関数でバインドされた各プレースホルダのバインド・ハンドルが割り当てられます。ユーザーはバインド・ハンドルを割り当てることはできません。バインド・ハンドルは、バインド・コールによって暗黙的に割り当てられます。

問合せ(select文)によって戻されたフェッチ済データは、定義ハンドルの仕様に従って変換され、取得されます。またOCIライブラリによって、OCIDefineByPos()で定義された各出力変数の定義ハンドルが割り当てられます。ユーザーは定義ハンドルを割り当てることはできません。定義ハンドルは、定義コールによって暗黙的に割り当てられます。

バインド・ハンドルおよび定義ハンドルはOCIライブラリによって暗黙的に割り当てられ、バインド操作または定義操作が繰り返されると、透過的に再利用されます。バインド・ハンドルまたは定義ハンドルの実際の値は、第5章で説明する拡張バインド操作または定義操作のためにアプリケーションで必要とされます。ハンドルが解放されるのは、文ハンドルが解放されたとき、または文ハンドルに新しい文が準備されたときです。バインド・ハンドルまたは定義ハンドルを明示的に割り当てると、メモリー・リークが発生する可能性があります。バインド・ハンドルまたは定義ハンドルを明示的に解放すると、プログラムが異常終了する可能性があります。

関連項目:

- 「OCIでの拡張バインド操作」

- 「OCIでの拡張定義操作」

記述ハンドル

記述ハンドルは、OCI記述コールであるOCIDescribeAny()によって使用されます。このコールは、ファンクションやプロシージャなど、データベース内のスキーマ・オブジェクトに関する情報を取得します。このコールでは、記述されているオブジェクトに関する情報とともに、パラメータの1つとして記述ハンドルが使用されます。コールが完了すると、記述ハンドルには、そのオブジェクトに関する情報が含まれています。OCIアプリケーションでは、パラメータ記述子の属性を通して記述情報を取得します。

関連項目:
OCIDescribeAny()関数の使用方法の詳細は、第6章を参照してください。

複合オブジェクト検索ハンドル

複合オブジェクト検索(COR)ハンドルは、Oracle Database内のオブジェクトを操作する一部のOCIアプリケーションによって使用されます。このハンドルにはCOR記述子が含まれており、これは別のオブジェクトによって参照されるオブジェクトを取得する手順を提供します。

関連項目
「複合オブジェクト検索」

スレッド・ハンドル

マルチスレッド・アプリケーションで使用されているスレッド・ハンドルの詳細は、「OCIThreadパッケージ」を参照してください。

サブスクリプション・ハンドル

サブスクリプション・ハンドルは、登録およびサブスクライブを行うOCIクライアント・アプリケーションによって使用され、データベース・イベントまたはAQネームスペース内のイベントの通知を受け取るために使用されます。サブスクリプション・ハンドルは、クライアントからの登録に関するすべての情報をカプセル化します。

関連項目:
「OCIでのパブリッシュ・サブスクライブの通知」

ダイレクト・パス・ハンドル

ダイレクト・パス・ハンドルは、Oracle Database内でダイレクト・パス・ロード・エンジンを利用するOCIアプリケーションに必要です。ダイレクト・パス・ロード・インタフェースを使用して、アプリケーションからOracle Databaseのダイレクト・ブロック・フォーマッタにアクセスできます。図2-4では、各種ダイレクト・パス・ハンドルを示しています。

図2-4 ダイレクト・パス・ハンドル

関連項目:

- 「ダイレクト・パス・ロードの概要」

- 「ダイレクト・パス・ロード・ハンドル属性」

接続プール・ハンドル

接続プール・ハンドルは、特定のOCI関数をコールして物理接続を仮想接続にプールするアプリケーションで使用されます。

関連項目:
「OCIでの接続プーリング」

ハンドル属性

すべてのOCIハンドルには、そのハンドルに格納されているデータを表す属性があります。ハンドル属性は、属性取得コールOCIAttrGet()を使用して読み取ることができ、属性設定コールOCIAttrSet()を使用して変更することもできます。

たとえば、例2-1の文では、OCI_ATTR_USERNAME属性に書き込むことで、セッション・ハンドルにユーザー名を設定しています。

例2-1 セッション・ハンドルでユーザー名を設定するためのOCI_ATTR_USERNAME属性の使用

text username[] = "hr";
err = OCIAttrSet ((void *) mysessp, OCI_HTYPE_SESSION, (void *)username,
(ub4) strlen((char *)username), OCI_ATTR_USERNAME, (OCIError *) myerrhp);

コールの前に特定のハンドル属性を設定することが必要なOCI関数もあります。たとえば、ユーザーのログイン・セッションを確立するためにOCISessionBegin()をコールする場合は、コールの実行前にユーザー名とパスワードをユーザー・セッション・ハンドルに設定する必要があります。

完了後、ハンドル属性に有用なデータを戻すOCI関数もあります。たとえば、OCIStmtExecute()をコールしてSQL問合せを実行した場合は、例2-2で示すように、選択リスト項目に関する記述情報が文ハンドルに戻されます。

例2-2 選択リスト項目に関する記述情報の文ハンドルへの戻り

ub4 parmcnt;
/* get the number of columns in the select list */
err = OCIAttrGet ((void  *)stmhp, (ub4)OCI_HTYPE_STMT, (void  *)
&parmcnt, (ub4 *) 0, (ub4)OCI_ATTR_PARAM_COUNT, errhp);

関連項目:

- 多数の記述子の割当て方法を示す例は、「OCIArrayDescriptorAlloc()」の説明を参照してください。

- 付録A「ハンドルおよび記述子の属性」

OCI記述子

OCI記述子およびロケータは、データ固有の情報を保持する不透明なデータ構造です。表2-2では、これらとそのCデータ型、およびその型の記述子をOCIDescriptorAlloc()のコール内で割り当てるOCI型定数を示しています。OCIDescriptorFree()関数は、記述子とロケータを解放します。「OCIArrayDescriptorAlloc()」関数および「OCIArrayDescriptorFree()」関数も参照してください。

表2-2 記述子タイプ

説明

Cデータ型

OCI型定数

スナップショット記述子

OCISnapshot

OCI_DTYPE_SNAP

結果セット記述子

OCIResult

OCI_DTYPE_RSET

LOBデータ型ロケータ

OCILobLocator

OCI_DTYPE_LOB

BFILEデータ型ロケータ

OCILobLocator

OCI_DTYPE_FILE

読取り専用パラメータ記述子

OCIParam

OCI_DTYPE_PARAM

ROWID記述子

OCIRowid

OCI_DTYPE_ROWID

ANSI DATE記述子

OCIDateTime

OCI_DTYPE_DATE

TIMESTAMP記述子

OCIDateTime

OCI_DTYPE_TIMESTAMP

TIMESTAMP WITH TIME ZONE記述子

OCIDateTime

OCI_DTYPE_TIMESTAMP_TZ

TIMESTAMP WITH LOCAL TIME ZONE記述子

OCIDateTime

OCI_DTYPE_TIMESTAMP_LTZ

INTERVAL YEAR TO MONTH記述子

OCIInterval

OCI_DTYPE_INTERVAL_YM

INTERVAL DAY TO SECOND記述子

OCIInterval

OCI_DTYPE_INTERVAL_DS

ユーザー・コールバック記述子

OCIUcb

OCI_DTYPE_UCB

登録要求でのデータベース・サーバーの識別名

OCIServerDNs

OCI_DTYPE_SRVDN

複合オブジェクト記述子

OCIComplexObjectComp

OCI_DTYPE_COMPLEXOBJECTCOMP

アドバンスト・キューイング・エンキュー・オプション

OCIAQEnqOptions

OCI_DTYPE_AQENQ_OPTIONS

アドバンスト・キューイング・デキュー・オプション

OCIAQDeqOptions

OCI_DTYPE_AQDEQ_OPTIONS

アドバンスト・キューイング・メッセージ・プロパティ

OCIAQMsgProperties

OCI_DTYPE_AQMSG_PROPERTIES

アドバンスト・キューイング・エージェント

OCIAQAgent

OCI_DTYPE_AQAGENT

アドバンスト・キューイング通知

OCIAQNotify

OCI_DTYPE_AQNFY

アドバンスト・キューイング・リスニング・オプション

OCIAQListenOpts

OCI_DTYPE_AQLIS_OPTIONS

アドバンスト・キューイング・メッセージ・プロパティ

OCIAQLisMsgProps

OCI_DTYPE_AQLIS_MSG_PROPERTIES

変更通知

なし

OCI_DTYPE_CHDES

表の変更

なし

OCI_DTYPE_TABLE_CHDES

行の変更

なし

OCI_DTYPE_ROW_CHDES

注意:
OCILobLocatorに対するC型は1つのみですが、このロケータは内部LOBおよび外部LOBに対しては異なるOCI型定数で割り当てられます。「LOBおよびBFILEロケータ」ではこの違いについて説明します。

次のリストでは、各記述子型の主な目的について説明しています。その後の各項では、各記述子型をより詳細に説明しています。

- OCISnapshot: 文の実行時に使用

- OCILobLocator: LOBコール(OCI_DTYPE_LOB)またはBFILEコール(OCI_DTYPE_FILE)で使用

- OCIParam: 記述コールで使用

- OCIRowid: ROWID値のバインドまたは定義で使用

- OCIDateTimeおよびOCIInterval: 日時および時間隔データ型で使用

- OCIComplexObjectComp: 複合オブジェクト検索で使用

- OCIAQEnqOptions、OCIAQDeqOptions、OCIAQMsgProperties、OCIAQAgent: アドバンスト・キューイングで使用

- OCIAQNotify: パブリッシュ・サブスクライブ通知で使用

- OCIServerDNs: LDAPベースのパブリッシュ・サブスクライブ通知で使用

スナップショット記述子

スナップショット記述子は、実行コールOCIStmtExecute()のオプション・パラメータです。この記述子は、データベース・スナップショットに対する問合せが実行されることを示します。データベース・スナップショットは、ある特定の時点におけるデータベースの状態を表します。

スナップショット記述子は、OCIDescriptorAlloc()のコールで、OCI_DTYPE_SNAPをtypeパラメータとして渡すことによって割り当てられます。

関連項目:
OCIStmtExecute()およびデータベース・スナップショットの詳細は、「実行スナップショット」を参照してください。

LOBおよびBFILEロケータ

ラージ・オブジェクト(LOB)は、バイナリ・ラージ・オブジェクト(BLOB)またはキャラクタ・ラージ・オブジェクト(CLOB)データを保持できるOracleデータ型です。データベースでは、LOBロケータと呼ばれる不透明なデータ構造が、データベース行のLOB列、またはオブジェクトのLOB属性のかわりに格納されます。このロケータは、別の位置に格納されている実際のLOB値を指すポインタとして機能します。

注意:
アプリケーションによって、LOBロケータを使用する場合と使用しない場合があります。LOBのデータ・インタフェースを使用できますが、このインタフェースはLOBロケータを必要としません。このインタフェースでは、CLOB列の文字データ、またはBLOB列のRAWデータをバインドまたは定義できます。

関連項目:

- 「LOBデータのバインド」

- 「LOBデータの定義」

OCI LOBロケータは、LOB (BLOBまたはCLOB)またはFILE (BFILE)に対するOCI操作の実行に使用されます。OCILobXXX関数では、LOB値のかわりにLOBロケータがパラメータとして使用されます。OCI LOB関数では、パラメータとして実際のLOBデータは使用されません。この関数では、パラメータとしてLOBロケータを使用し、LOBロケータによって参照されるLOBデータを操作します。

LOBロケータは、OCIDescriptorAlloc()のコールで、BLOBまたはCLOBのtypeパラメータとしてのOCI_DTYPE_LOB、およびBFILEのOCI_DTYPE_FILEを渡すことによって割り当てられます。

注意:
LOBロケータの2つのタイプは代替可能ではありません。BLOBかCLOBをバインドまたは定義するとき、アプリケーションでは、OCI_DTYPE_LOBを使用してロケータが適切に割り当てられるようにする必要があります。同様に、BFILEをバインドまたは定義するとき、アプリケーションでは、OCI_DTYPE_FILEを使用してロケータが割り当てられるようにする必要があります。

OCIアプリケーションでは、選択リストの要素としてLOB列または属性を含むSQL文を発行することによって、Oracle DatabaseからLOBロケータを取り出せます。その場合、アプリケーションは最初にLOBロケータを割り当て、次にそれを使用して出力変数を定義します。同様に、LOBロケータは、SQL文でLOBとプレースホルダとの間の関連付けを行うバインド操作の一部として使用できます。

関連項目:

- 第7章「LOBおよびBFILEの操作」

- 「LOBデータのバインド」

- 「LOBデータの定義」

パラメータ記述子

OCIアプリケーションはパラメータ記述子を使用して、選択リスト列またはスキーマ・オブジェクトに関する情報を取得します。この情報は、記述操作を通して取得されます。

このパラメータ記述子は、OCIDescriptorAlloc()を使用して割り当てられることのない記述子タイプです。パラメータ記述子は、OCIParamGet()コールを使用してパラメータの位置を指定することによって、記述ハンドル、文ハンドル、または複合オブジェクト検索ハンドルの属性としてのみ取得できます。

関連項目:
パラメータ記述子の取得と使用の詳細は、第6章および「選択リスト項目の記述」を参照してください。

ROWID記述子

ROWID記述子(OCIRowid)は、Oracle ROWIDを取り出して使用する必要があるアプリケーションで使用されます。ROWIDを操作するために、アプリケーションではSQL選択リスト内のROWIDの位置に対応するROWID記述子を定義し、その記述子内のROWIDを検索できます。この同じ記述子を、後でINSERT文またはWHERE句の入力変数にバインドできます。

また、文の実行操作後に文ハンドルでOCIAttrGet()を使用し、ROWIDを記述子にリダイレクトできます。

日付、日時および時間隔の記述子

日付、日時および時間隔の記述子は、日付、日時または時間隔データ型(OCIDate、OCIDateTimeおよびOCIInterval)を使用するアプリケーションにより使用されます。これらの記述子は、バインドおよび定義で使用され、メモリーの割当ておよび解放を行う関数OCIDescriptorAlloc()およびOCIDescriptorFree()にパラメータとして渡されます。

関連項目:

- これらのデータ型の詳細は、第3章を参照してください。

- これらのデータ型で動作する関数の詳細は、第19章を参照してください。

複合オブジェクト記述子

オブジェクトの処理時に、複合オブジェクト検索(COR)を使用すると、アプリケーションのパフォーマンスが向上する場合があります。

関連項目:
複合オブジェクト記述子およびその使用方法の詳細は、「複合オブジェクト検索」を参照してください。

アドバンスト・キューイング記述子

Oracle Streams アドバンスト・キューイングは、Oracle Databaseと統合されたメッセージ・キューイングです。

関連項目:

- 「OCIおよびStreamsアドバンスト・キューイング」

- 「OCIでのパブリッシュ・サブスクライブの登録関数」

ユーザー・メモリーの割当て

OCIDescriptorAlloc()コールには、そのパラメータ・リストにxtramem_szパラメータが含まれています。このパラメータは、記述子またはロケータとともに割り当てるユーザー・メモリー量を指定するために使用します。

通常、アプリケーションは、このパラメータを使用して、記述子またはロケータと同じ存続期間を持つアプリケーション定義の構造体を割り当てます。この構造体は、アプリケーション・ブックキーピングまたはコンテキスト情報の格納に使用できます。

xtramem_szパラメータを使用すると、アプリケーションでは、各記述子またはロケータを割り当てたり、割当て解除するたびに、メモリーを明示的に割り当てたり、割当て解除する必要がありません。メモリーは記述子またはロケータとともに割り当てられるため、記述子またはロケータを解放すると(OCIDescriptorFree()により)、ユーザーのデータ構造も解放されます。

OCIHandleAlloc()コールには、ハンドルと同じ存続期間を持つユーザー・メモリーを割り当てるための同様のパラメータがあります。

OCIEnvCreate()コール(および非推奨のOCIEnvInit()コール)には、環境ハンドルと同じ存続期間を持つユーザー・メモリーを割り当てるための同様のパラメータがあります。

OCIプログラミング・ステップ

次の各項では、OCIアプリケーション開発の各ステップを詳細に説明します。いくつかのステップは、オプションです。たとえば、文が問合せでない場合には、選択リスト項目を記述または定義する必要はありません。

関連項目:

- SQL文の処理でのOCIコールの使用方法を示す例は、付録Bの最初のサンプル・プログラムを参照してください。

- 実行時に動的にデータを提供する特殊な場合の詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

- 構造体配列を必要とする操作に対する特別な考慮事項については、「OCIでの構造体配列のバインドと定義」を参照してください。

- OCIプログラム内でのSQL文の処理に必要なステップのアウトラインは、「OCIでのエラー処理」を参照してください。

- OCIを使用したマルチスレッド・アプリケーションのプログラミングの詳細は、「OCIマルチスレッド開発の概要」を参照してください。

- SQL文の種類の詳細は、「SQL文」を参照してください。

次の各項では、OCIのアプリケーションで必要なステップについて説明します。

- OCI環境の初期化

- OCIでのSQL文の処理

- 操作のコミットまたはロールバック

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

- OCIでのエラー処理

また、OCI関数のいずれか、またはすべてのステップ間で、アプリケーション固有の処理も発生します。

OCI環境の初期化

この項では、OCI環境を初期化してサーバーとの接続を確立し、ユーザーがデータベースに対してアクションを実行できるように許可する方法を説明します。

次の3つの項では、OCI環境を初期化するための3つの主要なステップについて説明します。

- 「OCI環境の作成」

- 「ハンドルおよび記述子の割当て」

- 「アプリケーションの初期化、接続およびセッション作成」

OCI環境の作成

各OCI関数コールは、OCIEnvCreate()コールで作成された環境のコンテキスト内で実行されます。このコールは、他のOCIコールの実行よりも先に行う必要があります。唯一の例外は、OCI共有モードのプロセスレベルの属性を設定する場合です。

OCIEnvCreate()のmodeパラメータは、OCIライブラリ関数をコールするアプリケーションが次のことを行えるどうか指定します。

- スレッド化環境での実行(mode = OCI_THREADED)。

- オブジェクト(mode = OCI_OBJECT)の使用。AQサブスクリプション登録で使用します。

- サブスクリプションの使用(mode = OCI_EVENTS)。

これらのモードは、環境ごとに設定できます。

アプリケーションがオブジェクトのバインドおよび定義を行う場合、またはOCIのオブジェクト・ナビゲーション・コールを使用する場合は、オブジェクト・モードでの初期化が必要です。また、アプリケーションでこれらの機能をすべて使用しないようにしたり(mode = OCI_DEFAULT)、縦線で区切って組み合せて使用することもできます。たとえば、mode = (OCI_THREADED | OCI_OBJECT)を指定すると、アプリケーションはスレッド化環境で動作し、オブジェクトを使用します。

OCI環境ごとにユーザー定義のメモリー管理関数を指定できます。

関連項目:

- 初期化コールの詳細は、「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()"」(非推奨)を参照してください。

- 「OCIマルチスレッド開発の概要」

- 第11章、第12章、第13章、第14章および第15章

- 「OCIでのパブリッシュ・サブスクライブの通知」

ハンドルおよび記述子の割当て

Oracle Databaseは、ハンドルと記述子の割当ておよび割当て解除をするためのOCI関数を提供します。ハンドルは、OCIHandleAlloc()を使用して割り当てた後、OCIコールに渡す必要があります(OCIBindByPos()のように、OCIコールがユーザーにかわってハンドルを割り当てる場合は除きます)。

OCIHandleAlloc()を使用して、表2-1にリストされた種類のハンドルを割り当てることができます。 アプリケーションの機能に応じて、これらのハンドルのいくつかまたはすべてを割り当ててください。

アプリケーションの初期化、接続およびセッション作成

アプリケーションでは、OCIEnvNlsCreate()をコールしてOCI環境ハンドルを初期化する必要があります。既存のアプリケーションで、OCIEnvCreate()が使用されていた可能性があります。

アプリケーションで、このステップに従ってOracle Database接続を確立し、ユーザー・セッションを開始する場合、いくつかのオプションがあります。

これらの方法には次のものが含まれます。

- シングル・ユーザー、単一接続

- プロキシ経由のクライアント・アクセス

- プロキシを介さない複数のセッションまたは接続

注意:
OCIInitialize()およびOCIEnvInit()コールのかわりに、OCIEnvCreate()またはOCIEnvNlsCreate()を使用する必要があります。OCIInitialize()およびOCIEnvInit()コールは、下位互換性を保つためにサポートされています。

シングル・ユーザー、単一接続

シングル・ユーザー、単一接続オプションは、単純化されたログイン方法で、アプリケーションで常にデータベース接続ごとにシングル・ユーザー・セッションのみを維持する場合に使用できます。

アプリケーションからOCILogon2()またはOCILogon()をコールすると、OCIライブラリは、渡されたサービス・コンテキスト・ハンドルを初期化し、要求を行ったユーザーが指定したOracle Databaseへの接続を作成します。

例2-3では、シングル・ユーザー・セッション(ユーザー名hr、パスワードhrおよびデータベースoracledb)を開始するためのOCILogon2()コールを示しています。

例2-3 シングル・ユーザー・セッションのためのOCILogon2コールの使用

OCILogon2(envhp, errhp, &svchp, (text *)"hr", (ub4)strlen("hr"), (text *)"hr",
(ub4)strlen("hr"), (text *)"oracledb", (ub4)strlen("oracledb"),
OCI_DEFAULT);

このコールのパラメータには、接続を確立するために使用するサービス・コンテキスト・ハンドル(初期化済)、ユーザー名、ユーザーのパスワードおよびデータベース名を含めることができます。このコールでは、最後のパラメータmodeをOCI_DEFAULTに設定することで、旧OCILogon()コールと同じ結果が得られます。新しいアプリケーションでは、OCILogon2()を使用します。この関数によって、サーバー・ハンドルおよびユーザー・セッション・ハンドルが暗黙的に割り当てられます。

アプリケーションがこのログイン方法を使用する場合、サービス・コンテキスト、サーバーおよびユーザー・セッション・ハンドルはすべて読取り専用となります。つまり、OCIAttrSet()コールを使用してサービス・コンテキスト・ハンドルの該当する属性を変更することにより、アプリケーションがセッションまたはトランザクションを切り替えることはできません。

アプリケーションでOCILogon2()を使用してセッションおよび認可を初期化した場合は、OCILogoff()を使用してそれらを終了する必要があります。

注意:
この機能を簡単に示すため、この例ではデプロイされたシステムが通常使用するパスワード管理手法は実行していません。本番環境では、Oracle Databaseパスワード管理ガイドラインに従い、サンプルのアカウントを無効にしてください。パスワード管理ガイドラインおよび他のセキュリティに関する推奨事項については、『Oracle Databaseセキュリティ・ガイド』を参照してください。

親プロセスによって作成された状態を子プロセスが再利用できるプロセス生成の機能を提供するオペレーティング・システムについては、「オペレーティング・システムの考慮事項」を参照してください。この項では、子プロセスが親によって作成されたものと同じデータベース接続を使用できない理由を説明します。

プロキシ経由のクライアント・アクセス

プロキシ認証は、ファイアウォールなどの中間層を伴う環境で一般的に使用されるプロセスで、エンド・ユーザーは中間層に対して認証を行い、中間層はエンド・ユーザーのプロキシとして、ユーザーのかわりにデータベースに対して認証を行います。中間層は、データベースにプロキシ・ユーザーとしてログインします。プロキシ・ユーザーは識別情報を切り替えることができ、データベースにログインするとエンド・ユーザーの識別情報に切り替わります。プロキシ・ユーザーは、特定のエンド・ユーザーに適した認可を使用して、そのエンド・ユーザーにかわって操作を実行できます。

注意:
Oracle 11gのリリース1では、受入れ可能なパスワードの基準が大幅に上げられ、セキュリティが向上しました。この項で示すパスワードの例は誤りです。パスワードには8文字以上使用する必要があります。詳細は、『Oracle Databaseセキュリティ・ガイド』のパスワード保護のガイドラインを参照してください。

データベース・ユーザーのプロキシは、OCIと次のBNF構文を持つALTER USER文でサポートされます。

ALTER USER <targetuser> GRANT CONNECT THROUGH <proxy> [AUTHENTICATION REQUIRED];

ALTER USER文は、アプリケーションで一度のみ使用されます。以降は、何回でも接続できます。OCIでは、接続文字列または関数OCIAttrSet() (パラメータOCI_ATTR_PROXY_CLIENT付き)を使用できます。

プロキシの切替えが行われると、現在接続しているユーザーがプロキシのターゲット・ユーザーになります。元のユーザーの識別情報は、権限の計算対象としては使用されません。元のユーザーはローカル・ユーザーまたは外部ユーザーになります。

例2-4から例2-11までは、OCILogon2() (mode = OCI_DEFAULTを設定)、OCILogon()、OCIAttrSet() (セッション・ハンドルの属性OCI_ATTR_USERNAMEを渡す)を指定したOCISessionBegin()などの関数で使用できる接続文字列を示しています。

例2-4では、DilbertとJoeが2人のローカル・データベース・ユーザーです。DilbertがJoeの代理ユーザーの役割を果たせるようにするには、例2-4に示すSQL文を使用します。

例2-4 ローカル・ユーザーに別のユーザーの代理の役割を付与

ALTER USER joe GRANT CONNECT THROUGH dilbert;

ユーザー名dilbertをjoeの代理にするには、例2-5に示す接続文字列を使用します。(ユーザー名dilbertにはパスワードtiger123があります)。

例2-5 代理ユーザー用に使用する接続文字列

dilbert[joe]/tiger123@db1

左と右のカッコ([ と ]) は、接続文字列に入力します。

例2-6では、"Dilbert"と"Joe"が2人のローカル・データベース・ユーザーです。名前には大文字と小文字の区別があり、二重引用符で囲む必要があります。Dilbert"が"Joe"の代理ユーザーの役割を果たせるようにするには、例2-6に示すSQL文を使用します。

例2-6 ローカル・ユーザーに別のユーザーの代理の役割を付与する際の大文字と小文字の区別の維持

ALTER USER "Joe" GRANT CONNECT THROUGH "Dilbert";

"Dilbert"を"Joe"の代理にするには、例2-7に示す接続文字列を使用します。必ず二重引用符(")を付けてください。

例2-7 接続文字列での大文字と小文字の区別の維持

"Dilbert"["Joe"]/tiger123@db1

代理ユーザーが "dilbert[mybert]"として作成される場合、データベースに接続するには例2-8に示す接続文字列を使用します。(左と右のカッコ([ と ])は、接続文字列に入力します。)

例2-8 接続文字列での"dilbert[mybert]"の使用

"dilbert[mybert]"/tiger123

rem the user was already created this way:
rem CREATE USER "dilbert[mybert]" IDENTIFIED BY tiger123;

例2-9では、dilbert[mybert]とjoe[myjoe]は、左右のカッコ([ と ])を含む2人のデータベース・ユーザーです。dilbert[mybert]がjoe[myjoe]の代理となるには、例2-9で示す接続文字列を使用します。

例2-9 接続文字列での"dilbert[mybert]"["joe[myjoe]"]の使用

"dilbert[mybert]"["joe[myjoe]"]/tiger123

例2-10では、ALTER USER文を使用することによりターゲット・ユーザー名を設定できます。

例2-10 ターゲット・ユーザー名の設定

ALTER USER joe GRANT CONNECT THROUGH dilbert;

次に、例2-11で示すように、OCIプログラムで、OCIAttrSet()コールを使用して属性OCI_ATTR_PROXY_CLIENTとプロキシdilbertを設定します。プログラム内で次の各文を使用して複数回接続を行います。

例2-11 OCIを使用したOCI_ATTR_PROXY_CLIENT属性および代理dilbertの設定

OCIAttrSet(session, OCI_HTYPE_SESSION, (void  *)"dilbert",
(ub4)strlen("dilbert"), OCI_ATTR_USERNAME,
error_handle);
OCIAttrSet(session, OCI_HTYPE_SESSION, (void  *)"tiger123",
(ub4)strlen("tiger123"), OCI_ATTR_PASSWORD,
error_handle);
OCIAttrSet(session, OCI_HTYPE_SESSION, (void  *)"joe",
(ub4)strlen("joe"), OCI_ATTR_PROXY_CLIENT,
error_handle);

関連項目:

- 「OCI_ATTR_PROXY_CLIENT」

- プロキシ認証の詳細は、『Oracle Databaseセキュリティ・ガイド』を参照してください。

- 「パスワードおよびセッションの管理」

- 「OCIAttrSet()」

注意:
プロキシを介したクライアント・アクセスには互換性の問題があります。この機能は、Oracle Databaseリリース10.2で導入されたため、10.2より前のクライアントはこの機能を備えていません。新しいクライアントが10.2より前のOracle Databaseでこの機能を使用すると、接続は失敗し、データベースのリリース・レベルのチェック後にクライアントがエラーを戻します。

プロキシを介さない複数のセッションまたは接続

プロキシを介さない複数のセッションまたは接続のオプションでは、明示的なアタッチ・コールおよびセッション開始コールを使用して、データベース接続で複数のユーザー・セッションおよび接続を維持します。Oracle Databaseにアタッチし、セッションを開始するための具体的なコールは、次のとおりです。

- OCIServerAttach(): OCI操作用のOracle Databaseへのアクセス・パスを作成します。

- OCISessionBegin(): 特定のOracle Databaseに対するユーザーのセッションを確立します。ユーザーがOracle Databaseに対する操作を実行するには、このコールが必須です。

異なるサービス・コンテキスト・ハンドルおよびセッション・コンテキスト・ハンドルを使用するOCISessionBegin()への後続コールは、前のユーザーをログオフするため、エラーを引き起こします。移行不可能な2つの同時セッションを実行するには、2番目のOCISessionBegin()コールに、同じサービス・コンテキスト・ハンドルおよび新しいセッション・コンテキスト・ハンドルを使用する必要があります。

これらのコールにより、データベースに対してSQL文およびPL/SQL文を実行できる操作環境が設定されます。

関連項目:

- 「接続関数、認証関数および初期化関数」

- 複数のセッション、トランザクションおよび接続の維持の詳細は、第9章を参照してください。

- OCIEnvNlsCreate()の使用方法の詳細は、「OCIからのクライアント・キャラクタ・セットの制御」を参照してください。

例2-12は、OCI環境の作成および初期化を示しています。

- サーバー・コンテキストを作成し、それをサービス・ハンドルに設定します。

- 次に、ユーザー・セッション・ハンドルを作成し、データベース・ユーザー名とパスワードを使用してそれを初期化します。

- 簡単にするために、エラー・チェックは含まれていません。

例2-12 OCI環境の作成および初期化

#include <oci.h>
...
main()
{
...
OCIEnv     *myenvhp;    /* the environment handle */
OCIServer  *mysrvhp;    /* the server handle */
OCIError   *myerrhp;    /* the error handle */
OCISession *myusrhp;    /* user session handle */
OCISvcCtx  *mysvchp;    /* the  service handle */
...
/* initialize the mode to be the threaded and object environment */
(void) OCIEnvCreate(&myenvhp, OCI_THREADED|OCI_OBJECT, (void  *)0,
0, 0, 0, (size_t) 0, (void  **)0);

/* allocate a server handle */
(void) OCIHandleAlloc ((void  *)myenvhp, (void  **)&mysrvhp,
OCI_HTYPE_SERVER, 0, (void  **) 0);

/* allocate an error handle */
(void) OCIHandleAlloc ((void  *)myenvhp, (void  **)&myerrhp,
OCI_HTYPE_ERROR, 0, (void  **) 0);

/* create a server context */
(void) OCIServerAttach (mysrvhp, myerrhp, (text *)"inst1_alias",
strlen ("inst1_alias"), OCI_DEFAULT);

/* allocate a service handle */
(void) OCIHandleAlloc ((void  *)myenvhp, (void  **)&mysvchp,
OCI_HTYPE_SVCCTX, 0, (void  **) 0);

/* set the server attribute in the service context handle*/
(void) OCIAttrSet ((void  *)mysvchp, OCI_HTYPE_SVCCTX,
(void  *)mysrvhp, (ub4) 0, OCI_ATTR_SERVER, myerrhp);

/* allocate a user session handle */
(void) OCIHandleAlloc ((void  *)myenvhp, (void  **)&myusrhp,
OCI_HTYPE_SESSION, 0, (void  **) 0);

/* set user name attribute in user session handle */
(void) OCIAttrSet ((void  *)myusrhp, OCI_HTYPE_SESSION,
(void  *)"hr", (ub4)strlen("hr"),
OCI_ATTR_USERNAME, myerrhp);

/* set password attribute in user session handle */
(void) OCIAttrSet ((void  *)myusrhp, OCI_HTYPE_SESSION,
(void  *)"hr", (ub4)strlen("hr"),
OCI_ATTR_PASSWORD, myerrhp);

(void) OCISessionBegin ((void  *) mysvchp, myerrhp, myusrhp,
OCI_CRED_RDBMS, OCI_DEFAULT);

/* set the user session attribute in the service context handle*/
(void) OCIAttrSet ((void  *)mysvchp, OCI_HTYPE_SVCCTX,
(void  *)myusrhp, (ub4) 0, OCI_ATTR_SESSION, myerrhp);
...
}

demoディレクトリ内のデモ・プログラムcdemo81.cは、このプロセスとエラー・チェックを例示しています。

OCIでのSQL文の処理

第4章では、OCIでのSQL文の処理に含まれる特定のステップについて説明します。

操作のコミットまたはロールバック

アプリケーションは、OCITransCommit()をコールすることにより、データベースへの変更をコミットします。このコールは、サービス・コンテキストをパラメータの1つとして使用します。トランザクションは、変更がコミットされるサービス・コンテキストに対応付けられています。このトランザクションは、アプリケーションで明示的に作成されたか、または、アプリケーションがデータベースを変更したときに暗黙的に作成された可能性があります。

注意:
OCIStmtExecute()コールのOCI_COMMIT_ON_SUCCESSモードを使用すると、各文の実行後にトランザクションを実行するかどうかをアプリケーションで選択できるため、ラウンドトリップを節約できます。

トランザクションをロールバックするには、OCITransRollback()コールを使用します。

通常のログオフ以外のなんらかの方法でアプリケーションとOracle Databaseの接続が切断された場合(ネットワークとの接続が切れるなど)、OCITransCommit()をコールしていないと、アクティブ・トランザクションはすべて自動的にロールバックされます。

関連項目:

- 「サービス・コンテキスト・ハンドルとそれに対応付けられたハンドル」

- 「OCIでのトランザクションのサポート」

アプリケーションの終了

OCIアプリケーションは、終了する前に、次の3つのステップの実行が必要です。

1. 各セッションに対してOCISessionEnd()をコールし、ユーザー・セッションを終了します。

2. 各データ・ソースに対してOCIServerDetach()をコールし、データ・ソースへのアクセスを終了します。

3. 各ハンドルに対してOCIHandleFree()をコールし、明示的に全ハンドルの割当てを解除します。

4. 環境ハンドルを削除し、環境ハンドルに関連付けられたその他のハンドルの割当てをすべて解除します。

注意:
OCIの親ハンドルが解放されると、それに対応付けられた子ハンドルもすべて自動的に解放されます。

OCIServerDetach()およびOCISessionEnd()のコールは、必須ではありませんが、お薦めします。アプリケーションがOCITransCommit() (トランザクション・コミット)をコールしないで終了すると、保留状態のトランザクションはすべて自動的にロールバックされます。

関連項目:
アプリケーションの終了時に解放されるハンドルを示す例は、付録Bの最初のサンプル・プログラムを参照してください。

注意:
アプリケーションでOCILogon2()の単純化されたログイン方法を使用する場合は、OCILogoff()をコールするとセッションが終了し、Oracle Databaseとの接続が切断され、サービス・コンテキスト・ハンドルとそれに関連付けられたハンドルが解放されます。ただし、アプリケーションにより割り当てた他のハンドルは、そのアプリケーションから解放してください。

OCIでのエラー処理

OCI関数コールには、表2-3に記載された一連のリターン・コードが用意されており、これらにより、コールの成功または失敗(OCI_SUCCESS、OCI_ERRORなど)や、アプリケーションが必要とするその他の情報(OCI_NEED_DATA、OCI_STILL_EXECUTINGなど)が示されます。大部分のOCIコールは、これらのコードの1つを戻します。

サーバーへの接続がOCI_ERRORで終了しないように、アプリケーションでは、サーバー・ハンドル内の属性OCI_ATTR_SERVER_STATUSの値をチェックできます。属性の値がOCI_SERVER_NOT_CONNECTEDの場合、サーバーへの接続およびユーザー・セッションを再確立する必要があります。

関連項目:

- 例外は、「その他の値を戻す関数」を参照してください。

- 使用方法の詳細および例については、「OCIErrorGet()」を参照してください。

- 「サーバー・ハンドル属性」

表2-3 OCIリターン・コード

OCIリターン・コード

値

説明

OCI_SUCCESS

0

関数は正常に終了しました。

OCI_SUCCESS_WITH_INFO

1

関数は正常に終了しました。OCIErrorGet()をコールすると、追加診断情報が戻されます。これには、警告が含まれる場合があります。

OCI_NO_DATA

100

関数が終了しました。これ以上データはありません。

OCI_ERROR

-1

関数が失敗しました。OCIErrorGet()をコールすると、エラーの追加情報が戻されます。

OCI_INVALID_HANDLE

-2

無効なハンドルがパラメータとして渡されたか、ユーザー・コールバックで無効なハンドルまたは無効なコンテキストが渡されました。追加診断情報はありません。

OCI_NEED_DATA

99

アプリケーションで、ランタイム・データを提供する必要があります。

OCI_STILL_EXECUTING

-3123

サービス・コンテキストが非ブロック化モードで確立されたため、現行の操作は即時完了できませんでした。この操作を完了するには、これを再度コールする必要があります。OCIErrorGet()がエラー・コードとしてORA-03123を戻します。

OCI_CONTINUE

-24200

このコードはコールバック関数からのみ戻されます。これは、コールバック関数が、OCIライブラリの標準処理再開を示唆していることを示します。

OCI_ROWCBK_DONE

-24201

このコードはコールバック関数からのみ戻されます。これは、コールバック関数がユーザー行のコールバックにより実行されていることを示します。

エラーが発生したことがリターン・コードに示されている場合、アプリケーションではOCIErrorGet()をコールして、Oracle Database固有のエラー・コードおよびメッセージを取り出せます。OCIErrorGet()へのパラメータの1つは、エラーが発生したコールに渡されたエラー・ハンドルです。

注意:
レコードがなくなる(OCI_NO_DATAが戻される)まで、繰り返しOCIErrorGet()をコールすると、複数の診断レコードを取り出すことができます。OCIErrorGet()は、最大1個の診断レコードを戻します。

データのリターン・コードおよびエラー・コード

表2-4に、フェッチされたデータが正常、NULL、または切捨ての場合の、OCIリターン・コード、エラー番号、標識変数および列リターン・コードを示します。

関連項目:
「標識変数」

表2-4 リターン・コードとエラー・コード

データの状態

リターン・コード

インジケータ － 戻さない場合

インジケータ － 戻す場合

NULL、切捨て以外

戻さない場合

OCI_SUCCESS

エラー = 0

OCI_SUCCESS

エラー = 0

インジケータ = 0

NULL、切捨て以外

戻す場合

OCI_SUCCESS

エラー = 0

リターン・コード = 0

OCI_SUCCESS

エラー = 0

インジケータ = 0

リターン・コード = 0

NULLデータ

戻さない場合

OCI_ERROR

エラー = 1405

OCI_SUCCESS

エラー = 0

インジケータ = -1

NULLデータ

戻す場合

OCI_ERROR

エラー = 1405

リターン・コード = 1405

OCI_SUCCESS

エラー = 0

インジケータ = -1

リターン・コード = 1405

切捨てデータ

戻さない場合

OCI_ERROR

エラー = 1406

OCI_ERROR

エラー = 1406

インジケータ = data_len

切捨てデータ

戻す場合

OCI_SUCCESS_WITH_INFO

エラー = 24345

リターン・コード = 1405

OCI_SUCCESS_WITH_INFO

エラー = 24345

インジケータ = data_len

リターン・コード = 1406

切捨てデータの場合、data_lenは、長さがSB2MAXVAL以下であった場合に切り捨てられたデータの実際の長さです。この値を超えていれば、インジケータが-2に設定されます。

その他の値を戻す関数

一部の関数では、表2-3にリストされているOCIエラー・コード以外の値を戻します。これらの関数を使用する場合、OUTパラメータからではなく、関数コールから直接値が戻ります。それぞれの関数と戻り値の詳細は、該当する章を参照してください。

その他のコーディング・ガイドライン

この項では、OCIアプリケーションをコーディングするときのその他の問題について説明します。

オペレーティング・システムの考慮事項

オペレーティング・システムでは、子プロセスで親プロセスによって作成された状態を再利用できるプロセス生成機能が提供されている場合があります。子プロセスの生成後、この子プロセスでは、親によって作成されたものと同じデータベース接続を使用できません。親と同じデータベース接続を子プロセスのために使用しようとすると、Oracle Netでは、データベースへの1つの接続を使用できるのは1つのユーザー・プロセスのみであるため、好ましくない接続障害が発生して、間欠的なORA-03137エラーが生じる可能性があります。

複数の同時接続が必要な場合、使用プラットフォームでスレッド・パッケージがサポートされていれば、スレッドの使用を検討します。シングル・スレッドまたはマルチ・スレッドのいずれのアプリケーションでも、同時接続はサポートされます。

関連項目:

- 「OCIマルチスレッド開発の概要」

- 「OCIThreadパッケージ」

同時にオープンされる多数の接続によるパフォーマンス向上のため、それらのプーリングを検討してください。

関連項目:

- 「OCIでのセッション・プーリング」

- 「接続プーリングまたはセッション・プーリングの使用/不使用の判断」

パラメータの型

OCI関数には整数、ハンドル、文字列など、多様なデータ型のパラメータを使用することができます。パラメータの型によっては注意事項があり、以降の項で説明します。

関連項目:
パラメータのデータ型、およびパラメータを渡す際の規則の詳細は、「接続関数、認証関数および初期化関数」を参照してください。

アドレス・パラメータ

アドレス・パラメータは、変数のアドレスをOracle Databaseに渡すために使用されます。Cでは、通常スカラー・パラメータを値で渡すので、Cで開発する場合は注意してください。

整数パラメータ

2進整数およびshort型2進整数パラメータは、サイズがシステムによって異なる数値です。システムでのこれらの整数のサイズは、ご使用のオペレーティング・システム用のOracle Databaseドキュメントを参照してください。

文字列パラメータ

文字列は、アドレス・パラメータの特殊な型です。文字列をパラメータとして渡すことができる各OCIルーチンには、文字列長のパラメータもあります。このパラメータで文字列の長さを設定する必要があります。

7.xアップグレードの注意:
OCIのこれまでのバージョンとは異なり、NULLで終了する文字列の文字列長パラメータに-1を渡すことはできません。

列へのNULLの挿入

データベース列にNULLを挿入する方法はいくつかあります。

- 1つは、INSERT文またはUPDATE文のテキストの中でリテラルNULLを使用する方法です。たとえば、SQL文によりENAME列はNULLになります。

INSERT INTO emp1 (ename, empno, deptno)
VALUES (NULL, 8010, 20)

- OCIバインド・コールでは、標識変数を使用します。「標識変数」を参照してください。

- バッファ長パラメータと最大長パラメータの両方をバインド・コールで0 (ゼロ)に設定するには、NULLを挿入します。

注意:
対応する標識変数が定義コールで指定されていない変数に、NULL選択リスト項目をフェッチしようとすると、Oracle DatabaseはSQL標準要件に従いエラーを戻します。

標識変数

各バインドと定義OCIコールには、標識変数または標識変数の配列をDML文、PL/SQL文または問合せに関連付けるパラメータがあります。

C言語にはNULL値という概念がないため、標識変数を入力変数に関連付けることにより、関連するプレースホルダがNULLであるかどうかを指定します。データがOracle Databaseに渡されると、この標識変数の値により、データベース・フィールドにNULLが割り当てられるかどうかが決定されます。

出力変数では、標識変数によって、Oracleから戻された値がNULLまたは切り捨てられた値であるかどうかが判断されます。OCIStmtFetch2()コールでのNULLフェッチ、またはOCIStmtExecute()コールでの切捨ての場合は、OCIコールによりOCI_SUCCESS_WITH_INFOが戻されます。出力標識変数が設定されます。

標識変数のデータ型はsb2です。標識変数の配列の場合、各配列要素の型はsb2です。

入力

入力ホスト変数については、OCIアプリケーションは次の値を標識変数に割り当てることができます。

入力インジケータ値

Oracle Databaseからのアクション

-1

Oracle DatabaseはNULLを列に割り当て、入力変数の値は無視します。

>=0

入力変数の値を列に割り当てます。

出力

出力については、Oracle Databaseは次の値を標識変数に割り当てます。

出力インジケータ値

意味

-2

項目の長さが出力変数の長さよりも長いため、項目を切り捨てます。さらに、元の長さが、sb2標識変数で戻せる最大長より長くなっています。

-1

選択された値がNULLで、出力変数の値は変更されません。

0

完全な値をホスト変数に割り当てます。

>0

項目の長さが出力変数の長さよりも長いため、項目を切り捨てます。標識変数に戻された正の値は、切捨て前の実際の長さです。

名前付きデータ型用およびREF用の標識変数

リリース8.0より後に導入されたデータ型の標識変数は、前述の説明どおりに機能します。例外はSQLT_NTY (名前付きデータ型)です。SQLT_NTY型のデータの場合、標識変数はインジケータ構造体へのポインタである必要があります。SQLT_REF型のデータでは、他の変数型と同様に、標準のスカラー・インジケータを使用します。

Object Type Translator (OTT)を使用してデータベース型をC構造体に変換すると、各オブジェクト型についてNULLインジケータ構造体が生成されます。この構造体には、アトミックNULLインジケータと各オブジェクト属性のインジケータが含まれます。

関連項目:

- NULLインジケータ構造体の詳細は、第15章のOTT関連の記述、および「NULLインジケータ構造体」を参照してください。

- 名前付きデータ型およびREFのインジケータ・パラメータ設定の詳細は、「バインド関数、定義関数および記述関数」のOCIBindByName()とOCIBindByPos()の説明、「名前付きデータ型およびREFバインドの情報」および「名前付きデータ型、REF定義およびPL/SQL OUTバインドの情報」の項を参照してください。

コールの取消し

ほとんどのオペレーティング・システムでは、キーボードからオペレーティング・システムの割込み文字(通常は[Ctrl] + [C]キー)を入力することで、長時間実行されたり繰り返されているOCIコールを取り消すことができます。

注意:
これを、nrowsパラメータを0 (ゼロ)に設定し、OCIStmtFetch2()をコールして行うカーソルの取消しと混同しないように注意してください。

長時間実行されたり繰り返されているコールをオペレーティング・システムへの割込みにより取り消した場合は、エラー・コードORA-01013(「ユーザーによって現行の操作の取消しが要求されました」)が戻されます。

特定のサービス・コンテキスト・ポインタまたはサーバー・コンテキスト・ポインタを指定すると、OCIBreak()関数は、サーバーに関連付けられている現在実行中のOCI関数をすべて即時(非同期)に停止します。これは通常、サーバーで長時間実行されている処理中のOCIコールを停止するために使用します。OCIReset()関数は、OCIアプリケーションがOCIBreak()で機能を停止した後で、非ブロック化接続に対してプロトコル同期化を実行するために必要です。

注意:
OCIBreak()はWindowsシステムで動作します。

長時間実行する可能性のあるコールは、非ブロック化コールを使用することによりステータスを監視できます。新しいアプリケーションでは、マルチスレッドを使用します。

関連項目:

- 「OCIマルチスレッド開発の概要」

- 「OCIThreadパッケージ」

位置指定の更新および削除

SELECT...FOR UPDATE OF...文に関連付けられたROWIDを、後のUPDATE文またはDELETE文に使用できます。ROWIDは、文ハンドルに対してOCIAttrGet()をコールして取り出すことができ、これによりこのハンドルのOCI_ATTR_ROWID属性を取り出せます。

たとえば、次のようなSQL文があるとします。

SELECT ename FROM emp1 WHERE empno = 7499 FOR UPDATE OF sal

この場合、フェッチが実行されると、ハンドルのROWID属性には選択された行の行識別子が入ります。次のコードのようにOCIAttrGet()をコールして、プログラムのバッファにROWIDを取り出すことができます。

OCIRowid *rowid;   /* the rowid in opaque format */
/* allocate descriptor with OCIDescriptorAlloc() */
status = OCIDescriptorAlloc ((void  *) envhp, (void  **) &rowid,
(ub4) OCI_DTYPE_ROWID, (size_t) 0, (void  **) 0);
status = OCIAttrGet ((void *) mystmtp, OCI_HTYPE_STMT,
(void *) rowid, (ub4 *) 0, OCI_ATTR_ROWID, (OCIError *) myerrhp);

その後、保存されたROWIDをDELETE文またはUPDATE文で使用できます。たとえば、rowidが行識別子が保存されているバッファである場合、新規給与をプレースホルダ:1にバインドし、rowidをプレースホルダ:2にバインドすることで、次のようなSQL文を後から処理できます。

UPDATE emp1 SET sal = :1 WHERE rowid = :2

rowidを:2にバインドする場合は、必ずデータ型コード104 (ROWID記述子、表3-2を参照)を使用してください。

プリフェッチを使用することで、後続のバッチ更新で使用するためにROWIDの配列を選択できます。

関連項目:

- ROWIDの詳細は、「UROWID」および「DATE」を参照してください。

- 外部データ型およびコードの表は、「外部データ型」を参照してください。

予約語

一部のワードはOracleによって確保されています。つまり、それらのワードはOracleにとって特別な意味を持っており、再定義できません。このため、それらのワードを使用して、列、表、索引などのデータベース・オブジェクトに名前を付けることはできません。

関連項目:
SQLおよびPL/SQLのOracleキーワードまたは予約語のリストを参照するには、『Oracle Database SQL言語リファレンス』および『Oracle Database PL/SQL言語リファレンス』を参照してください。

Oracle予約済ネームスペース

表2-5は、Oracleによって予約されているネームスペースのリストです。Oracleライブラリ内の関数名の最初の文字列は、このリストの文字列に制限されています。名前が競合する可能性があるため、これらの文字列で始まる関数名を付けないでください。

表2-5 Oracle予約済ネームスペース

ネームスペース

ライブラリ

XA

XAアプリケーション専用の外部関数

SQ

OracleのプリコンパイラおよびSQL*Moduleアプリケーションで使用される外部SQLLIB関数

O、OCI

外部OCI関数、内部OCI関数

UPI、KP

Oracle UPIレイヤーの関数名

NA

NC

ND

NL

NM

NR

NS

NT

NZ

OSN

TTC

Oracle Netネイティブ・サービス・プロダクト

Oracle Net RPCプロジェクト

Oracle Netディレクトリ

Oracle Netネットワーク・ライブラリ・レイヤー

Oracle Net管理プロジェクト

Oracle Netインターチェンジ

Oracle Netトランスペアレント・ネットワーク・サービス

Oracle Netドライバ

Oracle Netセキュリティ・サービス

Oracle Net V1

Oracle Net 2タスク

GEN、L、ORA

コア・ライブラリ関数

LI、LM、LX

Oracleグローバリゼーション・サポート・レイヤーの関数名

S

システム依存ライブラリの関数名

KO

カーネル・オブジェクト

特定のネームスペースのすべての関数リストは、該当するOracleライブラリに対応したドキュメントを参照してください。

OCIでのポーリング・モード操作

OCIには、完了をポーリングするコールがあります。そのようなポーリング・コードのコールの例は、次のとおりです。

- 非ブロック化モードでのOCIコール

- OCILobRead2()およびOCILobWrite2()などのピース単位のLOBデータで動作するOCIコール

- OCIStmtSetPieceInfo()およびOCIStmtGetPieceInfo()で使用されるOCIStmtExecute()およびOCIStmtFetch2()

このような場合、OCIでは、アプリケーションで必ず同じOCIコールがその接続で繰り返され、その間にその接続でそれ以外のことが行われないようにする必要があります。そのような接続でその他のOCIコールを実行すると(OCIが制御をコール元に戻した場合)、予期しない動作が生じる可能性があります。

したがって、コール元は、そのようなポーリング・モードのOCIコールにより、同じコールがその接続で繰り返され、そのコールが完了するまで他のことが行われないようにする必要があります。

OCIBreak()およびOCIReset()は、このルールに対する例外です。これらのコールは、開始されたOCIコールをコール元が停止できるように使用されます。

OCIでの非ブロック化モード

注意:
非ブロック化モードでは、コール元はコールが完了するまで、同じコールを繰り返す必要があるため、CPUの使用率が増加します。かわりに、マルチスレッド・モードを使用します。

関連項目:

- 「OCIマルチスレッド開発の概要」

- 「OCIThreadパッケージ」

OCIでは、ブロック化モードまたは非ブロック化モードでサーバー接続を確立できます。接続がブロック化モードで行われた場合、結果が正常かエラーかにかかわらずコールが完了した場合にのみ、OCIコールはコントロールをOCIクライアント・アプリケーションに戻します。非ブロック化モードでは、コールが完了せずコールからOCI_STILL_EXECUTINGの値が戻されても、コントロールはただちにOCIプログラムに戻されます。

非ブロック化モードでは、アプリケーションで各OCI関数のリターン・コードをテストし、OCI_STILL_EXECUTINGが戻されるかどうかを確認する必要があります。この場合、OCIクライアントはこのOCIコールのサーバーでの再試行を待つ間、プログラム・ロジックの処理を継続できます。このモードは、グラフィカル・ユーザー・インタフェース(GUI)アプリケーション、リアルタイム・アプリケーションおよび分散環境の場合に特に有用です。

非ブロック化モードは非割込み駆動で、むしろポーリング・パラダイムに基づいています。これは、保留状態のコールがサーバーで終了したかどうかを、同一パラメータでそのコールを再び実行することにより、クライアント・アプリケーションでチェックする必要があることを意味します。

次の機能および関数は、非ブロック化モードではサポートされません。

- ダイレクト・パス・ロード

- LOBバッファリング

- オブジェクト

- 問合せキャッシュ

- スクロール・カーソル

- 透過的アプリケーション・フェイルオーバー(TAF)

- OCIAQEnqArray()

- OCIAQDeqArray()

- OCIDescribeAny()

- OCILobArrayRead()

- OCILobArrayWrite()

- OCITransStart()

- OCITransDetach()

ブロック化モードの設定

アプリケーションのブロック化状態は、attrtypeパラメータをOCI_ATTR_NONBLOCKING_MODEに設定して、サーバー・コンテキスト・ハンドルでOCIAttrSet()をコールして状態を設定するか、OCIAttrGet()をコールして状態を読み取ることにより、変更またはチェックすることができます。この属性を設定できるのは、OCISessionBegin()またはOCILogon2()がコールされた後でのみです。それ以外の場合はエラーが戻されます。

関連項目:
「サーバー・ハンドル属性」

注意:
パラメータとしてサーバー・コンテキスト・ハンドルまたはサービス・コンテキスト・ハンドルを持つ関数のみが、OCI_STILL_EXECUTINGを戻します。

非ブロック化コールの取消し

OCIコールの実行中にOCIBreak()関数を使用することにより、長時間実行しているOCIコールを取り消すことができます。その後、OCIReset()コールを発行して、非同期操作およびプロトコルをリセットする必要があります。

OCIプログラムでのPL/SQL使用方法

PL/SQLは、Oracleが開発したSQL言語の手続き型拡張機能です。PL/SQLは、単純な問合せやSQLデータ操作言語(DML)文よりも複雑なタスクをサポートします。PL/SQLを使用すると、複数の構文を単一のブロックにグループ化し、それを1単位として実行できます。次のような構文があります。

- 1つまたは複数のSQL文

- 変数宣言

- 代入文

- IF...THEN...ELSE文やループなどのプロシージャ型制御文

- 例外処理

OCIプログラムでPL/SQLブロックを使用して、次の操作ができます。

- Oracleストアド・プロシージャおよびストアド・ファンクションのコール

- 手続き型制御文を複数のSQL文と結合し、1つの単位として実行

- 表、CURSOR FORループ、例外処理など、特殊なPL/SQL機能へのアクセス

- カーソル変数の使用

- サーバー内のオブジェクトの操作

注意:

- OCIで直接処理できるのは無名ブロックのみであり、名前付きパッケージまたは名前付きプロシージャは処理できないのに対し、プログラマは常にパッケージ・コールまたはプロシージャ・コールを無名ブロック内に入れ、そのブロックを処理できます。

- OCIでPL/SQLの開始/終了ブロックを実行する前に、インジケータを-1に設定するかまたは実際の長さを0に設定して、すべてのOUT変数をNULLに初期化する必要があることに注意してください。

- OCIでは、PL/SQL RECORDデータ型はサポートされていません。

- OCIでPL/SQL VARCHAR2変数をバインドする場合、制御構造のオーバーヘッドにより、バインド変数の最大サイズは32512バイトです。

注意:
PL/SQLコードの作成時には、パーサーにより一対のハイフン「--」と改行文字との間のすべてがコメントとして処理されることを覚えておいてください。「--」を使用してコメントを各行に示した場合、Cコンパイラでは各行に改行「¥n」が挿入されず、すべての行がPL/SQLブロックで単一行として連結されます。この特定のケースでは、ある行がコメントで終わっている場合、パーサーは次の行のPL/SQLコード抽出に失敗してしまいます。この問題を回避するには、各「--」コメントの後に「\n」を入れ、そこでコメントが必ず終了するようにしてください。

関連項目:
PL/SQLブロックのコーディングの詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。

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

次の項では、ロケール情報の導出、文字列の操作、キャラクタ・セット変換、OCIメッセージなど、グローバリゼーションに使用されるOCI関数について説明します。これらの関数には複数の目的および機能があるため、詳細は、このマニュアルの他の章を参照してください。

OCIからのクライアント・キャラクタ・セットの制御

OCIEnvNlsCreate()関数は、NLS_LANGおよびNLS_NCHARの設定とは関係なく、アプリケーションでキャラクタ・セット情報を設定できます。様々なクライアント側キャラクタ・セットIDおよび各国語キャラクタ・セットIDを使用して、同じシステム環境内で初期化した複数の環境ハンドルを1つのアプリケーションで使用できます。たとえば、次のようにします。

OCIEnvNlsCreate(OCIEnv **envhpp, ..., csid, ncsid);

この例では、csidはキャラクタ・セットIDの値で、ncsidは各国語キャラクタ・セットIDの値です。いずれの値も0 (ゼロ)またはOCI_UTF16IDに設定できます。両方とも0 (ゼロ)の場合は、OCIEnvCreate()を使用するのと同じになります。その他の引数は、OCIEnvCreate()コールの引数と同じです。

OCIEnvNlsCreate()は、OCI_UTF16IDを検証するため、キャラクタ・セットをプログラムによって制御するための拡張機能です。

OCIEnvNlsCreate()関数を使用してキャラクタ・セットIDを設定すると、NLS_LANGおよびNLS_NCHARの設定値が置換されます。OCIEnvNlsCreate()関数では、各国語サポート・ランタイム・ライブラリ(NLSRTL)でサポートされるすべてのキャラクタ・セット以外に、OCI_UTF16IDをキャラクタ・セットIDとして設定できます(このIDは、NLS_LANGまたはNLS_NCHARでは無効となります)。

AL16UTF16を除くすべてのOracleキャラクタ・セットIDは、OCIEnvNlsCreate()関数を使用して指定され、メタデータのエンコーディング、SQL CHARデータおよびSQL NCHARデータを指定できます。

NLS_LANGおよびNLS_NCHARのキャラクタ・セットは、関数のOCINlsEnvironmentVariableGet()を使用して取得できます。

関連項目:

- 「OCIEnvNlsCreate()」

- これらのコールの使用例を示す擬似コード・フラグメントは、「OCIでのクライアント・キャラクタ・セットの設定」 を参照してください。

文字制御とOCIインタフェース

OCINlsGetInfo()関数は、OCI_UTF16IDがOCIEnvNlsCreate()で使用されている場合に、この値に関する情報を戻します。

OCIAttrGet()関数は、OCIEnvNlsCreate()に渡されたキャラクタ・セットIDおよび各国語キャラクタ・セットIDを戻します。これは、OCI_ATTR_ENV_CHARSET_IDおよびOCI_ATTR_ENV_NCHARSET_IDを取得するために使用されます。これには、値OCI_UTF16IDが含まれます。

OCIEnvNlsCreate()を使用してcharsetおよびncharsetパラメータにNULLが設定されている場合は、NLS_LANGおよびNLS_NCHARのキャラクタ・セットIDが戻されます。

この関数を使用してOCI_ATTR_CHARSET_FORMがリセットされる場合、OCIAttrSet()関数は文字IDをデフォルトとして設定します。OCIEnvNlsCreate()がcharsetまたはncharsetとして渡される場合、有効なキャラクタ・セットIDにはOCI_UTF16IDが含まれます。

OCIBindByName()およびOCIBindByPos()関数は、OCIEnvNlsCreate()コールのデフォルトのキャラクタ・セット(OCI_UTF16IDを含む)を使用して変数をバインドします。OCIEnvNlsCreate()を使用する場合、実際の長さと戻される長さは常にバイト単位で表されます。

OCIDefineByPos()関数は、OCIEnvNlsCreate()のcharsetの値(OCI_UTF16IDを含む)を持つ変数をデフォルトとして定義します。OCIEnvNlsCreate()を使用する場合、実際の長さと戻される長さは常にバイト単位で表されます。バインド・ハンドルおよび定義ハンドルのこの動作は、OCIEnvCreate()を使用する場合とは異なり、OCI_UTF16IDはバインド・ハンドルおよび定義ハンドル用のキャラクタ・セットIDになります。

OCIでの文字長セマンティクス

OCIは、サーバーとクライアント間のトランスレータとして機能し、制約チェックを行うための文字情報を渡します。

キャラクタ・セットには、可変幅と固定幅の2種類があります。(シングルバイト・キャラクタ・セットは、各バイトが1文字を表す固定幅キャラクタ・セットの特殊なケースです。)

固定幅キャラクタ・セットの場合、バイト数は文字数の倍数であるため、制約チェックが簡単です。したがって、固定幅キャラクタ・セットでは、文字数を調べるために文字列全体をスキャンする必要がありません。これに対して、可変幅キャラクタ・セットでは、文字列全体をスキャンして文字数を調べる必要があります。

OCIでのキャラクタ・セットのサポート

OCIでのキャラクタ・セットのサポートの詳細は、「記述操作での文字長セマンティクスのサポート」および「OCIバインドおよび定義における文字変換」を参照してください。

その他のOCIグローバリゼーション・サポート関数

グローバリゼーション・サポート関数は、環境ハンドルまたはユーザー・セッション・ハンドルを受け入れます。OCI環境ハンドルは、クライアントのNLS環境変数に関連付けられます。ALTER SESSION文がサーバーに発行された場合、この環境は変更されません。環境ハンドルに関連付けられたキャラクタ・セットは、クライアント・キャラクタ・セットです。OCIセッションハンドル(OCISessionBegin()によって戻されます)は、サーバー・セッション環境に関連付けられます。ALTER SESSION文でセッション環境が変更された場合、NLS設定も変更されます。セッション・ハンドルに関連付けられたキャラクタ・セットは、データベース・キャラクタ・セットです。

セッションで最初のトランザクションが開始されるまで、OCIセッション・ハンドルには、関連付けられたNLS設定がないことに注意してください。SELECT文では、トランザクションは開始されません。

関連項目:

- 第22章「OCIグローバリゼーション・サポート関数」

- Unicodeを使用したOCIプログラミングの詳細は、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

OCIでのロケール情報の取得

Oracle Databaseロケールは、言語、地域およびキャラクタ・セット定義で構成されます。ロケールは、曜日と月の名前、および日付、時刻、数値、通貨の書式などの表記規則を決定します。グローバル化されたアプリケーションは、ユーザーのロケール設定および文化の規則に対応しています。たとえば、ロケールをドイツに設定すると、月日の名前がドイツ語で表示されます。

関連項目:

- 「OCIロケール関数」

- 「OCINlsEnvironmentVariableGet()」

OCINlsGetInfo()関数を使用して、次の情報を取得できます。

- 曜日(翻訳済)

- 曜日の略称(翻訳済)

- 月名(翻訳済)

- 月名の略称(翻訳済)

- はい/いいえ(翻訳済)

- AM/PM (翻訳済)

- AD/BC (翻訳済)

- 数値書式

- 借方/貸方

- 日付書式

- 通貨書式

- デフォルトの言語

- デフォルトの地域

- デフォルト・キャラクタ・セット

- デフォルトの言語ソート

- デフォルト・カレンダ

例2-13のコードでは、ロケール情報を取得し、エラーをチェックします。

例2-13 OCIでのロケール情報取得

sword MyPrintLinguisticName(envhp, errhp)
OCIEnv   *envhp;
OCIError *errhp;
{
OraText  infoBuf[OCI_NLS_MAXBUFSZ];
sword ret;

ret = OCINlsGetInfo(envhp,                           /* environment handle */
errhp,                                 /* error handle */
infoBuf,                         /* destination buffer */
(size_t) OCI_NLS_MAXBUFSZ,              /* buffer size */
(ub2) OCI_NLS_LINGUISTIC_NAME);                /* item */

if (ret != OCI_SUCCESS)
{
checkerr(errhp, ret, OCI_HTYPE_ERROR);
ret = OCI_ERROR;
}
else
{
printf("NLS linguistic: %s\n", infoBuf);
}
return(ret);
}

OCIでの文字列の操作

文字列操作では、マルチバイト文字列およびワイド・キャラクタ文字列がサポートされています。

マルチバイト文字列は、システム固有のOracleキャラクタ・セットでエンコードされています。マルチバイト文字列で動作する関数は、バイト単位で計算された文字列の長さを使用して、文字列全体を1つの単位として使用します。ワイドキャラクタ(wchar)文字列関数を使用すると、より柔軟に文字列を操作できます。これは、文字に基づいた操作および文字列に基づいた操作をサポートし、長さは文字列の長さを文字で計算した数値です。

ワイドキャラクタ・データ型OCIWcharはOracle固有のもので、ANSI/ISO C標準で定義されているwchar_tデータ型と混同しないでください。Oracleのワイドキャラクタ・データ型はすべてのオペレーティング・システムで常に4バイトですが、wchar_tのサイズは実装およびオペレーティング・システムによって異なります。Oracleワイド・キャラクタ・データ型は、マルチバイト文字を正規化するため、統一された固定幅になり、処理が簡単になります。これにより、Oracleのワイドキャラクタ・セットとシステム固有のキャラクタ・セット間でのラウンドトリップ変換の際、データが失われません。

文字列操作は、次のカテゴリに分類できます。

- マルチバイト・キャラクタとワイド・キャラクタ間の文字列変換

- 文字の分類

- 大/小文字の変換

- 表示長の計算

- 比較、連結、検索などの一般的な文字列操作

関連項目:
「OCI文字列操作関数」

例2-14では、単純な文字列操作の例を示します。

例2-14 OCIでの基本的な文字列操作

size_t MyConvertMultiByteToWideChar(envhp, dstBuf, dstSize, srcStr)
OCIEnv     *envhp;
OCIWchar   *dstBuf;
size_t      dstSize;
OraText    *srcStr;                         /* null terminated source string */
{
sword  ret;
size_t dstLen = 0;
size_t srcLen;

/* get length of source string */
srcLen = OCIMultiByteStrlen(envhp, srcStr);

ret = OCIMultiByteInSizeToWideChar(envhp,            /* environment handle */
dstBuf,                               /* destination buffer */
dstSize,                         /* destination buffer size */
srcStr,                                    /* source string */
srcLen,                          /* length of source string */
&dstLen);                  /* pointer to destination length */

if (ret != OCI_SUCCESS)
{
checkerr(envhp, ret, OCI_HTYPE_ENV);
}
return(dstLen);
}

OCI文字分類関数については、「OCI文字分類関数」で詳しく説明します。

例2-15では、OCIでの文字の分類方法を示します。

例2-15 OCIでの文字列分類

boolean MyIsNumberWideCharString(envhp, srcStr)
OCIEnv   *envhp;
OCIWchar *srcStr;                                 /* wide char source string */
{
OCIWchar *pstr = srcStr;                        /* define and init pointer */
boolean status = TRUE;            /* define and initialize status variable */

/* Check input */
if (pstr == (OCIWchar*) NULL)
return(FALSE);

if (*pstr == (OCIWchar) NULL)
return(FALSE);

/* check each character for digit */
do
{
if (OCIWideCharIsDigit(envhp, *pstr) != TRUE)
{
status = FALSE;
break;                                  /* non-decimal digit character */
}
} while ( *++pstr != (OCIWchar) NULL);

return(status);
}

OCIでのキャラクタ・セットの変換

Oracleキャラクタ・セットとUnicode (16ビット、固定幅のUnicodeエンコーディング)間の変換がサポートされています。UnicodeからOracleキャラクタ・セットへの文字のマッピングが存在しない場合、置換文字が使用されます。したがって、変換して元のキャラクタ・セットに戻す場合、データが失われる可能性があります。

Unicodeキャラクタ・セットに関連するキャラクタ・セット変換関数では、データのバインド・バッファおよび定義バッファをub2アドレスで揃える必要があり、揃っていない場合、エラーが発生します。

例2-16では、Unicodeへの単純な変換を示します。

関連項目:
「OCIキャラクタ・セット変換関数」

例2-16 OCIでのキャラクタ・セットの変換

/* Example of Converting Character Sets in OCI
--------------------------------------------*/

size_t MyConvertMultiByteToUnicode(envhp, errhp, dstBuf, dstSize, srcStr)
OCIEnv   *envhp;
OCIError *errhp;
ub2 *dstBuf;
size_t dstSize;
OraText *srcStr;
{
size_t dstLen = 0;
size_t srcLen = 0;
OraText tb[OCI_NLS_MAXBUFSZ];   /* NLS info buffer */
ub2    cid;                     /* OCIEnv character set ID */

/* get OCIEnv character set */
checkerr(errhp, OCINlsGetInfo(envhp, errhp, tb, sizeof(tb),
OCI_NLS_CHARACTER_SET));
cid = OCINlsCharSetNameToId(envhp, tb);

if (cid == OCI_UTF16ID)
{
ub2    *srcStrUb2 = (ub2*)srcStr;
while (*srcStrUb2++) ++srcLen;
srcLen *= sizeof(ub2);
}
else
srcLen = OCIMultiByteStrlen(envhp, srcStr);

checkerr(errhp,
OCINlsCharSetConvert(
envhp,       /* environment handle */
errhp,       /* error handle */
OCI_UTF16ID, /* Unicode character set ID */
dstBuf,      /* destination buffer */
dstSize,     /* size of destination buffer */
cid,         /* OCIEnv character set ID */
srcStr,      /* source string */
srcLen,      /* length of source string */
&dstLen));   /* pointer to destination length */

return dstLen/sizeof(ub2);
}

OCIメッセージ関数

ユーザー・メッセージAPIは、カートリッジ開発者が、独自のメッセージおよびOracle Databaseメッセージを取得するための単純なインタフェースを提供します。

関連項目:

- 『Oracle Databaseデータ・カートリッジ開発者ガイド』

- 「OCIメッセージ関数」

例2-17では、メッセージ・ハンドルを作成し、impus.msgからメッセージを取得するために初期化してメッセージ番号128を取得し、メッセージ・ハンドルをクローズします。この例では、OCI環境ハンドル、OCIセッション・ハンドル、製品、機能およびキャッシュ・サイズが正しく初期化されていることを想定しています。

例2-17 テキスト・メッセージ・ファイルからのメッセージ取得

OCIMsg msghnd;                                              /* message handle */
/* initialize a message handle for retrieving messages from impus.msg*/
err = OCIMessageOpen(hndl,errhp, &msghnd, prod,fac,OCI_DURATION_SESSION);
if (err != OCI_SUCCESS)
/* error handling */
...
/* retrieve the message with message number = 128 */
msgptr = OCIMessageGet(msghnd, 128, msgbuf, sizeof(msgbuf));
/* do something with the message, such as display it */
...
/* close the message handle when there are no more messages to retrieve */
OCIMessageClose(hndl, errhp, msghnd);

lmsgenユーティリティ

lmsgenユーティリティは、テキストベースのメッセージ・ファイル(.msg)をバイナリ形式(.msb)に変換し、これにより、ユーザーが提供したOracleメッセージおよびOCIメッセージを、希望する言語でOCI関数に戻すことができます。

ImsgenユーティリティのBNF構文は、次のとおりです。

lmsgen text_file product facility [language]

前述の構文の要素:

- text_fileは、メッセージ・テキスト・ファイルです。

- productは、製品の名前です。

- facilityは、機能の名前です。

- languageは、NLS_LANGパラメータで指定された言語に対応する、オプションのメッセージ言語です。メッセージ・ファイルに言語のタグが正しく付いていない場合は、言語パラメータが必要です。

テキスト・メッセージ・ファイルのガイドライン

テキスト・メッセージ・ファイルは、次のガイドラインに従う必要があります。

- "/"および"//"で始まる行は、内部コメントとみなされるため、無視されます。

- メッセージ・ファイルに特定の言語のタグを付けるには、次のような行を含めます。

#   CHARACTER_SET_NAME= Japanese_Japan.JA16EUC

- 各メッセージには、3つのフィールドがあります。

message_number, warning_level, message_text

- メッセージ番号は、メッセージ・ファイル内で一意であることが必要です。

- 警告レベルは、現在使用されていません。0に設定します。

- メッセージ・テキストは、76バイトより長くできません。

Oracle Databaseメッセージ・テキスト・ファイルの例を次に示します。

/ Copyright (c) 2001 by the Oracle Corporation.  All rights reserved.
/ This is a test us7ascii message file
# CHARACTER_SET_NAME= american_america.us7ascii
/
00000, 00000, "Export terminated unsuccessfully\n"
00003, 00000, "no storage definition found for segment(%lu, %lu)"

テキスト・メッセージ・ファイルからのバイナリ・メッセージ・ファイル作成の例

次の表は、lmsgenパラメータのサンプル値を示します。

lmsgenパラメータ

値

product

$HOME/myApplication

facility

imp

language

AMERICAN

text_file

impus.msg

テキスト・メッセージ・ファイルの場所は、次のとおりです。

$HOME/myApp/mesg/impus.msg

テキスト・メッセージ・ファイル内の1行は、次のとおりです。

00128,2, "Duplicate entry %s found in %s"

lmsgenユーティリティは、テキスト・メッセージ・ファイル(impus.msg)をバイナリ形式に変換します。これにより、impus.msbというファイルが作成されます。

% lmsgen impus.msg $HOME/myApplication imp AMERICAN

出力結果は、次のようになります。

Generating message file impus.msg -->
/home/scott/myApplication/mesg/impus.msb

NLS Binary Message File Generation Utility: Version 9.2.0.0.0 -Production

Copyright (c) Oracle Corporation 1979, 2001.  All rights reserved.

CORE    9.2.0.0.0       Production

3 データ型

この章は、OCIアプリケーションで使用するOracle外部データ型についてのリファレンスです。この章では、Oracleデータ型、および独自に作成したプログラムとOracle Databaseの間でデータを転送する場合に行われる、データの内部表現と外部表現の変換についても説明します。

この章は、次の項目で構成されています。

- Oracleデータ型

- 内部データ型

- 外部データ型

- データ変換

- 型コード

- oratypes.hの定義

関連項目:
Oracle内部データ型の詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

Oracleデータ型

OCIプログラムの重要な機能の1つは、Oracle Databaseと通信を行うことです。OCIアプリケーションでは、SQL SELECTを使用した問合せによってデータベースの表からデータを取り出すか、INSERT、UPDATEまたはDELETE文を使用して表内の既存データを変更します。

データベース内では、値は表の列に格納されています。内部的には、Oracleは内部データ型という特別な形式でデータを表現します。内部データ型の例として、NUMBER、CHAR、DATEなどがあります(表3-1を参照)。

一般的に、OCIアプリケーションではデータの内部データ型表現を処理しませんが、そのアプリケーションが作成された言語によって事前定義されたホスト言語のデータ型が処理されます。OCIクライアント・アプリケーションとデータベースの表の間でデータが転送されるとき、OCIライブラリによって、内部データ型と外部データ型の間でデータ変換が行われます。

外部データ型は、OCIヘッダー・ファイル内に定義されているホスト言語型です。OCIアプリケーションで入力変数をバインドするとき、バインド・パラメータの1つで変数の外部データ型コード(またはSQLTコード)を指示します。同様に、定義コールで出力変数を指定するとき、取り出されるデータの外部表現を指定する必要があります。

外部データ型が内部データ型と類似している場合もあります。外部型を使用すると、専用データ形式ではなくホスト言語の型を操作できるので、プログラマにとって便利です。

注意:
一部の外部データ型は内部データ型に類似していますが、OCIアプリケーションが内部データ型にバインドされることはありません。ここでは、内部データ型がどのように外部データ型にマップされるかを理解するために説明します。

OCIでは、Oracle DatabaseとOCIアプリケーションとの間でデータを転送する際、様々なデータ型変換を実行できます。Oracle内部データ型より多くのOCI外部データ型があります。単一の外部型を1つの内部型にマップする場合もあり、複数の外部型を単一の内部型にマップする場合もあります。

一部のデータ型が多対1の関係でマッピングされることによって、OCIプログラマは柔軟性が得られます。たとえば、次のSQL文を処理しているとします。

SELECT sal FROM emp WHERE empno = :employee_number

給与を、2進浮動小数点形式ではなく、文字データとして戻す必要があります。そのため、sal列に対するOCIDefineByPos()コールで、dtyパラメータのVARCHAR2 (コード= 1)またはCHAR (コード= 96)など、Oracle Database外部文字列データ型を指定します。また、プログラムで文字列変数を宣言し、そのアドレスをvaluepパラメータで指定する必要があります。詳細は、表3-2を参照してください。

ただし、給与情報を2進数浮動小数点値として戻す場合は、FLOAT (コード= 4)外部データ型を指定します。また、valuepパラメータに適切な型の変数を定義する必要があります。

ほとんどのデータ変換が透過的に実行されます。また、ほとんどすべての外部データ型を指定できるため、特殊なタスクを実行できます。たとえば、DATE外部データ型を使用すると、文字変換を行わずに純粋なバイナリ形式でDATE値を入出力できます。詳細は、「DATE」の外部データ型の説明を参照してください。

データ変換を制御するには、適切な外部データ型コードをバインド・ルーチンおよび定義ルーチンで使用する必要があります。OCIプログラム内の入力変数または出力変数の位置、および変数のデータ型と長さをOracle Databaseに対して指定する必要があります。

また、OCIでは、オブジェクト型属性のデータ型を表すためにOracle Databaseの型管理システムで使用する一連のOCI型コードも用意されています。これらの型コードを表すには、一連の事前定義定数を使用できます。各定数には接頭辞OCI_TYPECODEが含まれます。

要約すると、OCIプログラマは、次の各種のデータ型またはデータ表現について認識する必要があります。

- 内部Oracleデータ型は、Oracle Databaseの表の列で使用されます。これらには、PL/SQLで使用され、Oracle Databaseの列では使用されないデータ型も含まれます(たとえば、索引付き表、ブール、レコード)。

関連項目:
「内部データ型」

- 外部OCIデータ型は、Oracleデータのホスト言語表現を指定するために使用されます。

関連項目:
「外部データ型」および「外部データ型コードの使用」

- OCI_TYPECODE値は、Oracle Databaseでオブジェクト型属性の型情報を表現するために使用されます。

関連項目:
「型コード」および「SQLT値およびOCI_TYPECODE値の関係」

列の内部データ型についての情報は、内部データ型コードの形式でアプリケーションに送られます。戻されるデータ型についてのこの情報により、アプリケーションでは出力データの変換および書式設定の方法を判断できます。Oracle内部データ型コードのリストは、「内部データ型」を参照してください。

関連項目:

- Oracle内部データ型の詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

- 問合せでの選択リスト項目の記述の詳細は、「選択リスト項目の記述」を参照してください。

外部データ型コードの使用

外部データ型コードによって、プログラムでのホスト変数のデータ表現方法が指定されます。これによって、プログラムの出力変数にデータが戻されるときの変換方法、または入力(バインド)変数からOracle Databaseの列値へのデータ変換方法が決まります。たとえば、Oracle Database列のNUMBERを可変長文字配列に変換する場合は、出力変数を定義するOCIDefineByPos()コールでVARCHAR2外部データ型コードを指定します。

バインド変数をOracle Database列の値に変換するには、バインド変数の型に対応する外部データ型コードを指定します。たとえば、02-FEB-65などの文字列をDATE列に入力する場合は、データ型を文字列として指定し、文字列長パラメータを9に設定します。

使用する値を変換可能にするのは、常にプログラマの責任です。文字列"MY BIRTHDAY"をDATE列に挿入する文を実行すると、エラーが発生します。

関連項目:
外部データ型およびデータ型コードの完全なリストは、表3-2を参照してください。

内部データ型

表3-1は、Oracle Database内部(組込み)データ型を各型の最大内部長およびデータ型コードとともに示しています。

表3-1 Oracle Database内部データ型

Oracle Database内部データ型

最大内部長

データ型コード

VARCHAR2、NVARCHAR2

4000バイト

1

NUMBER

21バイト

2

LONG

2^31-1バイト(2GB)

8

DATE

7バイト

12

RAW

2000バイト

23

LONG RAW

2^31-1バイト

24

ROWID

10バイト

69

CHAR、NCHAR

2000バイト

96

BINARY_FLOAT

4バイト

100

BINARY_DOUBLE

8バイト

101

ユーザー定義型(オブジェクト型、VARRAY、nested table)

該当なし

108

REF

該当なし

111

CLOB、NCLOB

128TB

112

BLOB

128TB

113

BFILE

オペレーティング・システムの最大ファイル・サイズまたはUB8MAXVAL

114

TIMESTAMP

11バイト

180

TIMESTAMPWITHTIMEZONE

13バイト

181

INTERVALYEARTOMONTH

5バイト

182

INTERVALDAYTOSECOND

11バイト

183

UROWID

3950バイト

208

TIMESTAMPWITHLOCALTIMEZONE

11バイト

231

関連項目:
これらの組込みデータ型の詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

LONG、RAW、LONG RAW、VARCHAR2

OCIBindByName()、OCIBindByPos()、OCIDefineByPos()、OCIStmtGetPieceInfo()およびOCIStmtSetPieceInfo()によって提供されるピース単位機能を使用すると、LONG、RAW、LONG RAWおよびVARCHAR2データ型の列データを扱う挿入、更新またはフェッチを実行できます。

文字列およびバイト配列

文字またはバイト配列を含む列を指定する場合は、CHAR、VARCHAR2、RAW、LONGおよびLONG RAWの5つのOracle Database内部データ型を使用できます。

注意:
LOBには文字を、BFILEにはバイナリ・データを含めることができます。これらは、他の型とは異なる処理がされるので、ここでは説明しません。これらのデータ型の詳細は、第7章を参照してください。

通常、CHAR列、VARCHAR2列およびLONG列には文字データが入ります。RAWおよびLONG RAWには、文字として解釈されないバイト(ビットマップ化された画像のピクセル値など)が入ります。ネットワーク間のゲートウェイを介して文字データを渡すと、文字データが変形する可能性があります。1文字を表現するバイト数が異なる別々の言語を使用しているマシン間で文字データを渡すと、長さが大きく変わる可能性があります。RAWデータがこのように変換されることはありません。

表の列ごとに適切なOracle内部データ型を選択するのは、データベースの設計者の責任です。OCIプログラマは、文字データおよびバイト配列データの表現方法、およびOCIプログラムの変数とOracle Database表の間でのデータの変換方法を多数知っておく必要があります。

配列に文字が入っている場合、OCIコール内の配列の長さを示すパラメータは、常に文字単位ではなくバイト単位で渡され、バイト単位で戻されます。

UROWID

ユニバーサルROWID(UROWID)は、Oracle Database表の論理ROWIDおよび物理ROWIDを格納するデータ型です。論理ROWIDは、索引構成表(IOT)の行に対する主キー・ベースの論理識別子です。

UROWIDデータ型の列を使用するには、COMPATIBLE初期化パラメータの値をリリース8.1以上に設定する必要があります。

次のホスト変数を、ユニバーサルROWIDにバインドできます。

- SQLT_CHR(VARCHAR2)

- SQLT_VCS(VARCHAR)

- SQLT_STR (NULL文字で終了する文字列)

- SQLT_LVC(LONG VARCHAR)

- SQLT_AFC(CHAR)

- SQLT_AVC(CHARZ)

- SQLT_VST (OCI文字列)

- SQLT_RDD (ROWID記述子)

BINARY_FLOATおよびBINARY_DOUBLE

BINARY_FLOATデータ型およびBINARY_DOUBLEデータ型は、単精度浮動小数点値および倍精度浮動小数点値を表現し、主に、浮動小数点演算のIEEE754標準に準拠しています。

リリース10.1でこれらのデータ型が追加される前は、Oracle Database内の数値はすべて、Oracle NUMBER書式で格納されていました。これらの新しいバイナリ浮動小数点型は、Oracle NUMBERを置換するものではありません。Oracle NUMBERの代替として機能するため、ディスク領域の使用量が少なくて済むという利点があります。

この内部型は、次のコードで表現されます。

- BINARY_FLOATはSQLT_IBFLOAT

- BINARY_DOUBLEはSQLT_IBDOUBLE

次のホスト変数はすべて、BINARY_FLOATデータ型およびBINARY_DOUBLEデータ型にバインドできます。

- SQLT_BFLOAT (システム固有のfloat)

- SQLT_BDOUBLE (システム固有のdouble)

- SQLT_INT(integer)

- SQLT_FLT(float)

- SQLT_NUM(Oracle NUMBER)

- SQLT_UIN(unsigned)

- SQLT_VNU(VARNUM)

- SQLT_CHR(VARCHAR2)

- SQLT_VCS(VARCHAR)

- SQLT_STR (NULL文字で終了する文字列)

- SQLT_LVC(LONG VARCHAR)

- SQLT_AFC(CHAR)

- SQLT_AVC(CHARZ)

- SQLT_VST (OCIString)

最適なパフォーマンスを得るために、BINARY_FLOATデータ型およびBINARY_DOUBLEデータ型とともに、外部型SQLT_BFLOATとSQLT_BDOUBLEを使用します。

外部データ型

表3-2は、外部データ型のデータ型コードを示しています。この表ではデータ型ごとに、Oracle Database内部データの変換元または変換先となる、Cのプログラム変数の型を示しています。

表3-2 外部データ型とそのコード

外部データ型

コード

プログラム変数脚注 1

OCI定義の定数

VARCHAR2

1

char[n]

SQLT_CHR

NUMBER

2

unsigned char[21]

SQLT_NUM

8ビット符号付きINTEGER

3

signed char

SQLT_INT

16ビット符号付きINTEGER

3

signed short、signed int

SQLT_INT

32ビット符号付きINTEGER

3

signed int、signed long

SQLT_INT

64ビット符号付きINTEGER

3

signed long、signed long long

SQLT_INT

FLOAT

4

float、double

SQLT_FLT

NULL文字で終了するSTRING

5

char[n+1]

SQLT_STR

VARNUM

6

char[22]

SQLT_VNU

LONG

8

char[n]

SQLT_LNG

VARCHAR

9

char[n+sizeof(short integer)]

SQLT_VCS

DATE

12

char[7]

SQLT_DAT

VARRAW

15

unsigned char[n+sizeof(short integer)]

SQLT_VBI

システム固有のfloat

21

float

SQLT_BFLOAT

システム固有のdouble

22

double

SQLT_BDOUBLE

RAW

23

unsigned char[n]

SQLT_BIN

LONG RAW

24

unsigned char[n]

SQLT_LBI

UNSIGNED INT

68

unsigned

SQLT_UIN

LONG VARCHAR

94

char[n+sizeof(integer)]

SQLT_LVC

LONG VARRAW

95

unsigned char[n+sizeof(integer)]

SQLT_LVB

CHAR

96

char[n]

SQLT_AFC

CHARZ

97

char[n+1]

SQLT_AVC

ROWID記述子

104

OCIRowid *

SQLT_RDD

名前付きデータ型

108

struct

SQLT_NTY

REF

110

OCIRef

SQLT_REF

キャラクタLOB記述子

112

OCILobLocator脚注 2

SQLT_CLOB

バイナリLOB記述子

113

OCILobLocator脚注 2

SQLT_BLOB

バイナリFILE記述子

114

OCILobLocator

SQLT_FILE

OCI STRING型

155

OCIString

SQLT_VST脚注 3

OCI DATE型

156

OCIDate*

SQLT_ODT脚注 3

ANSI DATE記述子

184

OCIDateTime *

SQLT_DATE

TIMESTAMP記述子

187

OCIDateTime *

SQLT_TIMESTAMP

TIMESTAMP WITH TIME ZONE記述子

188

OCIDateTime *

SQLT_TIMESTAMP_TZ

INTERVAL YEAR TO MONTH記述子

189

OCIInterval *

SQLT_INTERVAL_YM

INTERVAL DAY TO SECOND記述子

190

OCIInterval *

SQLT_INTERVAL_DS

TIMESTAMP WITH LOCAL TIME ZONE記述子

232

OCIDateTime *

SQLT_TIMESTAMP_LTZ

脚注 1 データ長がnとなっている場合、nは可変で、プログラム(ROWIDの場合はオペレーティング・システム)の要件に依存します。

脚注 2 OTTで生成したデータ型マッピングを使用しているアプリケーションでは、CLOBはOCIClobLocatorとしてマッピングされ、BLOBはOCIBlobLocatorとしてマッピングされます。詳細は、第15章を参照してください。

脚注 3 これらのデータ型の使用方法の詳細は、第12章を参照してください。

次の2つの型はPL/SQLに対する内部型で、OCIでは値として戻すことができません。

- ブール、SQLT_BOL

- レコード、SQLT_REC

VARCHAR2

VARCHAR2データ型は、最大長4000バイトの可変長文字列です。

注意:
Oracle Databaseオブジェクトを使用する場合は、一連の事前定義済OCI関数を使用することにより、特殊なOCIString外部データ型を扱うことができます。このデータ型の詳細は、第12章を参照してください。

入力

OCIBindByName()またはOCIBindByPos()コールでは、value_szパラメータによって長さが決まります。

value_szパラメータが0 (ゼロ)より大きい場合は、指定のバイト数のみがプログラムのバッファ・アドレスの先頭から読み取られて、バインド変数値が取得されます。後続の空白は削除され、結果の値はSQL文またはPL/SQLブロックで使用されます。INSERT文の場合、結果の値がデータベース列で定義された長さより長いと、INSERTは失敗しエラーが戻されます。

注意:
後続のNULLは除去されません。変数はNULL文字で終了させずに、空白埋めをする必要があります。

value_szパラメータが0 (ゼロ)の場合、バインド変数は、実際の内容とは無関係にNULLとして処理されます。NULLは、SQL文のバインド変数値として使用できます。NOT NULL整合性制約付きの列にNULLを挿入しようとすると、エラーとなり、行は挿入されません。

Oracle内部(列)データ型がNUMBERの場合、数値の文字表現が含まれている文字列からの入力は有効です。入力文字列は内部数値形式に変換されます。VARCHAR2文字列に無効な変換文字が含まれている場合、エラーが戻され、値はデータベースに挿入されません。

出力

OCIDefineByPos()コールのvalue_szパラメータで、または、PL/SQLブロックの場合はOCIBindByName()またはOCIBindByPos()のvalue_szパラメータで、戻り値の希望の長さを指定します。長さとしてゼロを指定した場合、データは戻されません。

OCIDefineByPos()のrlenpパラメータを省略すると、戻される値はバッファ長に達するまで空白が埋め込まれ、空白文字の文字列としてNULLが戻されます。rlenpを指定した場合、戻り値は空白埋めされません。かわりに、実際の長さがrlenpパラメータに戻されます。

NULLが戻されたかどうか、または文字の切捨てが発生したかどうかをチェックするには、OCIDefineByPos()コールにインジケータ・パラメータを指定します。NULLがフェッチされた場合に、インジケータ・パラメータが-1に設定され、戻り値が切り捨てられている場合は、インジケータ・パラメータが元の列長に設定されます。それ以外の場合は、0 (ゼロ)が設定されます。インジケータ・パラメータを指定していない場合、NULLが選択されると、フェッチ・コールでエラー・コードOCI_SUCCESS_WITH_INFOが戻されます。エラーについての診断情報の取出しでは、ORA-1405が戻されます。

関連項目:
「標識変数」

NUMBER

NUMBERを外部データ型として使用する必要はありません。使用すると、21バイトの内部バイナリ形式で数値が戻され、入力時にこの形式が必要になります。完全な情報が必要な場合は、次の説明を参照してください。

注意:
Oracle Databaseでオブジェクトを使用する場合は、一連の事前定義済OCI関数を使用して、特殊なOCINumberデータ型を扱うことができます。このデータ型の詳細は、「Number (OCINumber)」を参照してください。

Oracle Databaseでは、NUMBERデータ型の値を可変長形式で格納します。最初のバイトは指数で、その後は1から20バイトの仮数です。指数バイトの上位1ビットは符号ビットで、正数の場合はセットされ、負数の場合はクリアされます。下位7ビットは指数を表し、100の位を底とし、オフセットは65です。

10進数の指数を計算するには、基本100の指数に65を加算し、数値が正数の場合はさらに128を加算します。数値が負数の場合も同様に計算しますが、後でビットが反転されます。たとえば、-5の場合は、基本100の指数 = 62 (0x3e)になります。したがって、10進数の指数は、(~0x3e)-128 - 65 = 0xc1 -128 -65 = 193 -128 -65 = 0になります。

各仮数バイトは基本100で範囲1から100の数字です。正数の場合は、それに1を加算した数字となります。したがって、値5に対する仮数は6となります。負数の場合、1を加算するかわりに、その数字が101から減算されます。つまり、値-5に対する仮数は96 (101-5)となります。負数には、102が含まれているバイトがデータ・バイトの後に追加されます。ただし、20個の仮数バイトを持つ負数には、102のバイトは後続しません。仮数バイトは基本100であるため、各バイトは2桁の10進数値を表すことができます。仮数は正規化され、先行する0 (ゼロ)は格納されません。

仮数を表すために最大20個のデータ・バイトを使用できます。ただし、精度が保証されているのは19個のみです。19個のデータ・バイトは、それぞれ基本100を表し、Oracle NUMBERに対して38桁の最大精度を提供します。

OCIDefineByPos()コールのdtyパラメータにデータ型コード2を指定すると、プログラムではこのOracle内部形式で数値データを受け取ります。出力変数は、可能な最大の数値を格納できる21バイトの配列である必要があります。数値を表すバイトのみが戻されることに注意してください。空白埋めまたはNULL文字終了はありません。戻されたバイト数を調べる場合は、NUMBERではなくVARNUM外部型を使用します。

関連項目:

- 「OCINumberの例」

- 内部NUMBER書式の説明は、「VARNUM」を参照してください。

64ビット整数ホスト・データ型

リリース11.2以降、OCIでは、OCIアプリケーションで64ビットのネイティブ・ホスト変数および外部データ型としてのSQLT_INTまたはSQLT_UINを使用することにより、32ビット・サイズを超える(9桁以上の精度の)整数値をNUMBER列に対してフェッチおよ挿入できます。

この機能により、アプリケーションでは、すべてのプラットフォームでOCIバインドおよび定義関数コールにSQLT_INTまたはSQLT_UIN外部データ型を使用して、8バイトのネイティブ・ホスト変数をバインドおよび定義できます。OCIDefineByPos()、OCIBindByName()およびOCIBindByPos()関数コールでは、8バイトの整数データ型ポインタをvaluepパラメータとして指定できます。この機能により、大きい整数値(精度が最大18桁の10進数値)を、ネイティブ・ホスト変数に対して直接挿入およびフェッチし、これらの整数値に対してフリー演算を実行できます。

64ビット整数のOCIバインドおよび定義

例3-1は、エラーなく実行されるコードのフラグメントを示しています。

例3-1 64ビット整数のOCIバインドおよび定義のサポート

...
/* Variable declarations */
orasb8    sbigval1, sbigval2, sbigval3; // Signed 8-byte variables.
oraub8    ubigval1, ubigval2, ubigval3; // Unsigned 8-byte variables.
...
/* Bind Statements */
OCIBindByPos(..., (void *) &sbigval1, sizeof(sbigval1), ..., SQLT_INT, ...);
OCIBindByPos(..., (void *) &ubigval1, sizeof(ubigval1), ..., SQLT_UIN, ...);
OCIBindByName(...,(void *) &sbigval2, sizeof(sbigval2), ..., SQLT_INT, ...);
OCIBindByName(...,(void *) &ubigval2, sizeof(ubigval2), ..., SQLT_UIN, ...);
...
/* Define Statements */
OCIDefineByPos(..., (void *) &sbigval3, sizeof(sbigval3), ..., SQLT_INT, ...);
OCIDefineByPos(..., (void *) &ubigval3, sizeof(ubigval3), ..., SQLT_UIN, ...);
...

文を戻すOUTバインドDMLのサポート

例3-2は、文を戻すDMLのOUTバインドの8バイト整数データ型のバインドを説明するコード・フラグメントを示しています。

例3-2 文を戻すDMLのOUTバインドの8バイト整数データ型のバインド

...
/* Define SQL statements to be used in program. */
static text *dml_stmt = (text *) " UPDATE emp SET sal = sal + :1
WHERE empno = :2
RETURNING sal INTO :out1";
...

/* Declare all handles to be used in program. */
OCIStmt    *stmthp;
OCIError   *errhp;
OCIBind    *bnd1p   = (OCIBind *) 0;
OCIBind    *bnd2p   = (OCIBind *) 0;
OCIBind    *bnd3p   = (OCIBind *) 0;
...

/* Bind variable declarations */
orasb8    sbigval;   // OUT bind variable (8-byte size).
sword     eno, hike; // IN bind variables.
...

/* get values for IN bind variables */
...

/* Bind Statements */
OCIBindByPos(stmthp, &bnd1p, errhp, 1, (dvoid *) &hike,
(sb4) sizeof(hike), SQLT_INT, (dvoid *) 0,
(ub2 *) 0, (ub2 *) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT);
OCIBindByPos(stmthp, &bnd2p, errhp, 2, (dvoid *) &eno,
(sb4) sizeof(eno), SQLT_INT, (dvoid *) 0,
(ub2 *) 0, (ub2 *) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT);
OCIBindByName(stmthp, &bnd3p, errhp, (text *) ":out1", -1,
(dvoid *) &sbigval, sizeof(sbigval), SQLT_INT, (dvoid *) 0,
(ub2 *) 0, (ub2 *) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT);
...

/* Use the returned OUT bind variable value */
...

INTEGER

INTEGERデータ型では数値を変換します。外部INTEGERは符号付きの2進数で、バイト単位のサイズはシステムによって異なります。変数内のバイトの順序は、ホスト・システム・アーキテクチャによって決まります。長さ指定は、入力でも出力でも必須です。Oracle Databaseから戻される数値が整数でない場合、小数部分は廃棄され、エラーやその他の情報は戻されません。戻される数値がシステムの符号付きINTEGERで表現できない場合は、「変換時にオーバーフローが発生しました(overflow on conversion)」エラーが戻されます。

FLOAT

FLOATデータ型は、小数部分のある数値、またはINTEGERでは表現できない数値を処理します。数値はホスト・システムの浮動小数点書式で表されます。通常、長さは4バイトか8バイトのいずれかです。長さ指定は、入力および出力の両方について必要です。

Oracle Databaseの数値の内部形式は10進数で、大部分の浮動小数点は2進数であるため、数値を浮動小数点で表現するよりもより高い精度で表現できます。

注意:
FLOATおよびNUMBER間の変換時には丸め処理のエラーが発生する場合もあります。問合せでバインド変数としてFLOATを使用すると、ORA-1403エラーが戻されることがあります。この状況を回避するには、FLOATをSTRINGに変換し、VARCHAR2またはNULL終了文字列を設定します。

STRING

NULL文字で終了するSTRING形式は、文字列にNULL終端文字が必要であることを除けば、VARCHAR2形式と同じように動作します。このデータ型は、特にC言語のプログラムで有用です。

入力

OCIBindByName()またはOCIBindByPos()コールで供給される文字列の長さによって、NULL終端文字があるかどうかのスキャンの範囲が制限されます。NULL終端文字が指定された中で見つからなかった場合は、次のエラーとなります。

ORA-01480: STRバインド値に終了のNULLがありません。

バインド・コールで長さが指定されていない場合、OCIは、文字列の暗黙の最大長の4000を使用します。

文字列の最小の長さは2バイトです。最初の文字がNULL終端文字であり、長さが2と指定されている場合、許可されていればNULLが列に挿入されます。VARCHAR2型およびCHAR型とは異なり、空白のみを含む文字列は入力時にNULLとして扱われるのではなく、そのまま挿入されます。

注意:
NULLで終了する文字列の文字列長パラメータに、-1を渡すことはできません。

出力

NULL終端文字は、最後の文字が戻された後に配置されます。文字列が指定のフィールド長より長い場合、文字列は切り捨てられ、出力変数の最後の文字の位置にNULL終端文字が入ります。

NULL選択リスト項目は、最初の文字の位置にNULL終端文字を戻します。ORA-01405エラーが発生する可能性もあります。

VARNUM

VARNUMデータ型は、最初のバイトに数値表現の長さが記述されることを除けば、外部NUMBERデータ型と同じです。この長さには、長さを記述するバイト自体は含まれません。最大長のVARNUMに備えて、22バイトを確保してください。VARNUM値をOracle Databaseに送信するときは、長さを記述するバイトを設定します。

表3-3に、表の数値に戻されるVARNUM値の例をいくつか示します。

表3-3 VARNUMの例

10進数

長さバイト

指数バイト

仮数バイト

終了文字バイト

0

1

128

該当なし

該当なし

5

2

193

6

該当なし

-5

3

62

96

102

2767

3

194

28, 68

該当なし

-2767

4

61

74, 34

102

100000

2

195

11

該当なし

1234567

5

196

2, 24, 46, 68

該当なし

LONG

LONGデータ型では、4001バイト以上の文字列を格納します。LONG列には、最大2GB (2^31-1バイト)を格納できます。この列の型は、長い文字列の格納およびフェッチにのみ使用します。関数、式またはWHERE句では使用できません。一般的に、LONG列値の変換は、文字列との間で行われます。

LONG列を使用した表を作成しないでください。かわりに、LOB列(CLOB、NCLOBまたはBLOB)を使用してください。LONG列は、下位互換性のためにサポートされています。

既存のLONG列をLOB列に変換することもお薦めします。LOB列の制限の数は、LONG列の制限の数よりも、かなり少なくなっています。さらに、LOB機能はすべてのリリースで拡張されていますが、LONG機能は複数のリリースで変更されていません。

VARCHAR

VARCHARデータ型では、可変長の文字列が格納されます。先頭の2バイトには文字列の長さが記述され、残りのバイトには文字列が含まれます。バインド・コールまたは定義コールで指定する文字列の長さには、この2バイトを含める必要があるため、送受信可能なVARCHAR文字列の最大長は、65535バイトではなく、65533バイトになります。

DATE

DATEデータ型では、Oracle内部日付バイナリ形式を使用して、日付の値の更新、挿入または検索を行うことができます。バイナリ形式の日付は、表3-4に示すとおり7バイトです。

表3-4 DATEデータ型の書式

バイト

1

2

3

4

5

6

7

意味

世紀

年

月

日

時

分

秒

例(1992年11月30日午後3時17分)

119

192

11

30

16

18

1

世紀と年を表すバイト(1と2)は、100を加算した表記です。最初のバイトには、年の値(1992)を100で除算して100を加算した整数値119が格納されます。2番目のバイトには、年のモジュロ100に100を加算した192が格納されます。BCE (西暦紀元前)の日付は99以下です。紀元は01-JAN-4712 BCE、つまりユリウス日1から始まります。この日付では、世紀バイトは53、年号バイトは88です。時間、分および秒のバイトは1を加えた表記です。時間のバイトの範囲は1から24で、分と秒のバイトの範囲は1から60です。日付が作成された際に時刻が指定されていない場合、時刻のデフォルト値は午前0時です(1、1、1)。

DATE外部データ型を使用してバイナリ形式で日付を入力する場合、データベースでは一貫性または範囲のチェックは行いません。この形式になっているすべてのデータは、入力前に注意して検証する必要があります。

注意:
日常のデータベース操作で、Oracle外部DATEデータ型が必要になることはほとんどありません。一般にプログラムではDD-MON-YYなどのように文字形式でデータを扱うため、DATEは文字形式に変換した方がはるかに便利です。

DATE列はプログラム内で文字列に変換されるとき、使用中セッションのデフォルトの書式マスク、またはINIT.ORAファイルでの指定に従って戻されます。

Oracle Databaseでオブジェクトを使用する場合は、一連の事前定義済OCI関数を使用して、特殊なOCIDateデータ型を扱うことができます。

関連項目:

- OCIDateデータ型の詳細は、「日付(OCIDate)」 を参照してください。

- DATETIMEおよびINTERVALデータ型の詳細は、「日時および時間隔データ型記述子」を参照してください。

RAW

RAWデータ型は、たとえば図形文字列の格納など、Oracle Databaseで解釈されないバイナリ・データまたはバイト列で使用されます。RAW列の最大長は2000バイトです。

関連項目:
『Oracle Database SQL言語リファレンス』

Oracle Database表内のRAWデータがプログラムで文字列に変換される場合、データは16進文字コードで表されます。RAWデータの各バイトは、それぞれの値を示す'00'〜'FF'の2文字で戻されます。プログラムの文字列をOracle Database表内のRAW列に入力する場合は、この16進コードを使用して文字列のデータをコード化する必要があります。

OCIDefineByPos()、OCIBindByName()、OCIBindByPos()、OCIStmtGetPieceInfo()およびOCIStmtSetPieceInfo()によって提供されるピース単位機能を使用すると、RAW列(またはLONG RAW列)を扱う挿入、更新またはフェッチを実行できます。

Oracle Databaseでオブジェクトを使用する場合は、一連の事前定義済OCI関数を使用して、特殊なOCIRawデータ型を扱うことができます。このデータ型の詳細は、「Raw (OCIRaw)」を参照してください。

VARRAW

VARRAWデータ型は、RAWデータ型に類似しています。ただし、先頭の2バイトにはデータの長さが記述されます。バインド・コールまたは定義コールで指定する文字列の長さには、この2バイトを含める必要があるため、送受信可能なVARRAW文字列の最大長は、65535バイトではなく、65533バイトになります。これより長い文字列を変換する場合は、LONG VARRAW外部データ型を使用します。

LONG RAW

LONG RAWデータ型は、最大2GB (2^31-1バイト)のRAWデータを格納できるということを除けば、RAWデータ型と同じです。

UNSIGNED

UNSIGNEDデータ型は、符号なし2進整数に対して使用されます。バイト単位のサイズは、システムによって異なります。ワード内のバイトの順序は、ホスト・システムのアーキテクチャによって決まります。長さ指定は、入力でも出力でも必須です。Oracle Databaseから出力される数値が整数でない場合、小数部分は廃棄され、エラーやその他の情報は戻されません。戻される数値がシステムの符号なし整数より大きくて表現できない場合、「変換時にオーバーフローが発生しました(overflow on conversion)」というエラーが戻されます。

LONG VARCHAR

LONG VARCHARデータ型は、Oracle DatabaseのLONG列からデータを格納する場合、またはこの列にデータを格納する場合に使用します。LONG VARCHARの先頭の4バイトには項目の長さが記述されます。したがって、格納される項目の最大長は、2^31-5バイトです。

LONG VARRAW

LONG VARRAWデータ型は、Oracle Database LONG RAW列からデータを格納する場合、またはこの列にデータを格納する場合に使用します。長さは、先頭の4バイトに記述されます。最大長は、2^31-5バイトです。

CHAR

CHARデータ型は、最大長2000バイトの可変長文字列です。CHAR文字列は空白埋め比較セマンティクスで比較されます。

関連項目:
『Oracle Database SQL言語リファレンス』

入力

長さは、OCIBindByName()またはOCIBindByPos()コールのvalue_szパラメータによって決まります。

注意:
バッファの全内容(value_szの文字数)は、後続の空白またはNULLもすべて含めてデータベースに渡されます。

value_szパラメータが0 (ゼロ)の場合、バインド変数は、実際の内容とは無関係にNULLとして処理されます。NULLは、SQL文のバインド変数値として使用できます。NOT NULL整合性制約付きの列にNULLを挿入しようとすると、エラーとなり、行は挿入されません。

CHARの場合、value_szパラメータには負の値を使用できません。

Oracle内部(列)データ型がNUMBERの場合、数値の文字表現が含まれている文字列からの入力は有効です。入力文字列は内部数値形式に変換されます。CHAR文字列に無効な変換文字が含まれている場合、エラーが戻され、値は挿入されません。数値変換は、使用しているシステムのグローバリゼーション・サポートの設定値によって規定される規則に従って行われます。たとえば、システムが、ピリオドではなくカンマを小数点として認識するように構成されている場合もあります。

出力

OCIDefineByPos()コールのvalue_szパラメータで、戻り値の希望の長さを指定します。長さとしてゼロを指定した場合、データは戻されません。

OCIDefineByPos()のrlenpパラメータを省略すると、戻される値はバッファ長に達するまで空白が埋め込まれ、空白文字の文字列としてNULLが戻されます。rlenpを指定した場合、戻り値は空白埋めされません。かわりに、実際の長さがrlenpパラメータに戻されます。

NULLが戻されたかどうか、または文字の切捨てが発生したかどうかをチェックするには、OCIDefineByPos()コールにインジケータ・パラメータまたはインジケータ・パラメータの配列を指定します。インジケータ・パラメータには、NULLがフェッチされた場合は-1が設定され、値が切り捨てられて戻された場合は元の列の長さが設定されます。それ以外の場合は、0 (ゼロ)が設定されます。インジケータ・パラメータを指定していない場合、NULLが選択されると、フェッチ・コールでORA-01405エラーが戻されます。

関連項目:
「標識変数」

内部NUMBERデータ型から文字列への出力を要求することもできます。数値変換は、使用しているシステムのグローバリゼーション・サポートの設定値によって規定される規則に従って行われます。たとえば、システムが、ピリオド(.)ではなくカンマ(,)を小数点として認識するように構成されている場合もあります。

CHARZ

CHARZ外部データ型は、入力時に文字列がNULL文字で終了していること、および出力時にOracle Databaseによって文字列の最後にNULL終端文字が配置されることを除けば、CHARデータ型と同じです。NULL終端文字は入出力時に文字列を区切るためのもので、表のデータの一部ではありません。

入力時に、長さのパラメータは、NULL終端文字も含めた正確な長さを示す必要があります。たとえば、Cの配列が次のように宣言されたとすると、my_numのバインド時の長さのパラメータは7になっている必要があります。この例で他の値を指定すると、エラーが戻されます。

char my_num[] = "123.45";

次の新しい外部データ型は、リリース8.0から導入されました。これらのデータ型は、Oracle7 Serverへ接続した場合にはサポートされません。

注意:
内部データ型および外部データ型は、いずれもそれぞれのデータ型コードに対応するOracle定義の定数値(SQLT_NTY、SQLT_REFなど)を含んでいます。この章に出てくるすべての型についての定数は示していませんが、この項では新しいOracleデータ型を説明する際に、それらの定数を使用します。また、データ型定数は、これらの新しい型を参照するときに、このマニュアルの他の章でも使用されます。

名前付きデータ型: オブジェクト、VARRAY、ネストした表

名前付きデータ型は、SQLのCREATE TYPEコマンドで指定するユーザー定義の型です。例として、オブジェクト型、VARRAY、NESTED TABLEなどがあります。OCIでは、名前付きデータ型は型のホスト言語による表現を意味します。SQLT_NTYデータ型コードは、名前付きデータ型をバインドまたは定義する際に使用します。

Cアプリケーションでは、名前付きデータ型はC構造体として表されます。このような構造体は、データベース内に格納された型からObject Type Translatorを使用して生成されます。これらの型は、OCI_TYPECODE_OBJECTに対応します。

関連項目:

- OCIでの名前付きデータ型の処理の詳細は、「オブジェクト型情報の格納およびアクセス」を参照してください。

- 名前付きデータ型のC構造体としての表現方法の詳細は、第15章を参照してください。

REF

これは名前付きデータ型への参照です。REFのC言語表現は、OCIRef *型として宣言された変数です。SQLT_REFデータ型コードは、REFをバインドまたは定義する際に使用します。

REFにアクセスできるのは、OCIアプリケーションをオブジェクト・モードで初期化した場合のみです。サーバーからREFが取り出されると、REFはクライアント側のオブジェクト・キャッシュに格納されます。

アプリケーションで使用するREFを割り当てるには、変数をREFへのポインタとして宣言し、OCI_TYPECODE_REFをtypecodeパラメータとして渡すOCIObjectNew()をコールします。

関連項目:
OCIでのREFの操作の詳細は、第14章を参照してください。

ROWID記述子

ROWIDデータ型は、データベースの表の特定の行を識別するために使用されます。ROWIDは、次のように、問合せの選択リスト項目になっている場合があります。

SELECT ROWID, ename, empno FROM emp

このケースでは、戻されたROWIDを後続のDELETE文で使用できます。

SELECT FOR UPDATEを実行する場合、ROWIDは暗黙的に戻されます。文ハンドルでOCIAttrGet()を使用して、このROWIDをユーザーが割り当てたROWID記述子に読み取り、後続のUPDATE文で使用できます。プリフェッチ操作ではSELECT FOR UPDATEのすべてのROWIDがフェッチされるため、プリフェッチを使用してから単一行フェッチを行います。

ROWIDへのアクセスはROWID記述子を使用して行い、この記述子はバインド変数または定義変数として使用できます。

関連項目:
ROWID記述子の使用方法の詳細は、「OCI記述子」および「位置指定の更新および削除」を参照してください。

LOB記述子

LOB (ラージ・オブジェクト)には、長さが最大128TBのバイナリ・データまたは文字データを格納できます。バイナリ・データはBLOB (バイナリLOB)に格納され、文字データは、CLOB (キャラクタLOB)またはNCLOB (各国語キャラクタLOB)に格納されます。

LOB値は、データベースの行データとともに、インラインに格納される場合とされない場合があります。いずれの場合も、LOBは、Oracle Databaseのトランザクションを完全にサポートしています。データベース表にはLOBロケータが格納され、これは別の記憶領域にあるLOB値を指し示します。

OCIアプリケーションで選択リストにLOB列または属性を含むSQL問合せを発行した場合、問合せ結果のフェッチでは、実際のLOB値ではなくロケータが戻されます。OCIでは、LOBロケータはOCILobLocator型の変数にマッピングされます。

注意:
アプリケーションによって、LOBロケータを使用する場合と使用しない場合があります。LOBのデータ・インタフェースを使用できますが、このインタフェースはLOBロケータを必要としません。このインタフェースでは、CLOB列の文字データ、またはBLOB列のRAWデータをバインドまたは定義できます。

関連項目:

- LOBロケータを含む記述子の詳細は、「OCI記述子」を参照してください。

- LOBの詳細は、『Oracle Database SQL言語リファレンス』および『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

- 「LOBデータのバインド」

- 「LOBデータの定義」

LOBに対するOCI関数は、LOBロケータを引数の1つとして受け取ります。LOBにデータが含まれているかどうかに関係なく、OCI関数はそのLOBを指すロケータがすでに作成済であるとみなします。

バインド操作および定義操作は、OCIDescriptorAlloc()関数で割り当てられるLOBロケータ上で実行されます。

SQLまたはOCIObjectPin()を使用して、常に最初にロケータをフェッチしてから、ロケータを使用して操作を実行します。OCI関数が実際のLOB値をパラメータとして受け取ることはありません。

関連項目:
OCI LOB関数の詳細は、第7章を参照してください。

LOBをバインドまたは定義するために使用できるデータ型コードは、次のとおりです。

- SQLT_BLOB: バイナリLOBデータ型

- SQLT_CLOB: 文字LOBデータ型

NCLOBは、次の要件を伴うCLOBの特殊型です。

- NCLOBに対する書込みおよび読取りを行うには、キャラクタ・セット・フォーム(csfrm)パラメータをSQLCS_NCHARに設定する必要があります。

- CLOBおよびNCLOBを含むコールのamount (amtp)パラメータは常に、バイトではなく固定幅キャラクタ・セットの文字として解釈されます。

関連項目:
「OCIのLOB関数およびBFILE関数」

BFILE

Oracle Databaseでは、バイナリ・ファイル(BFILE)へのアクセスをサポートします。BFILEデータ型は、Oracle Database外部のファイル・システムに格納されているLOBにアクセスできます。

BFILEの列または属性には、サーバーのファイル・システムにあるバイナリ・ファイルへのポインタとして機能するファイルLOBロケータが格納されます。このロケータにより、ディレクトリのオブジェクトとファイル名が維持されます。BFILEの最大サイズは、使用しているオペレーティング・システムの最大ファイル・サイズまたはUB8MAXVALのいずれか小さい方になります。

バイナリ・ファイルLOBは、トランザクションでは使用されません。ファイルの完全性および永続性は、ベースとなるオペレーティング・システムにより提供されます。

データベース管理者は、ファイルが存在していること、およびOracle Databaseプロセスがそのファイルに対してオペレーティング・システムの読取り権限を持っていることを確認する必要があります。

BFILEデータ型では、大きなバイナリ・ファイルの読取り専用サポートが可能ですが、Oracle Databaseからファイルを変更することはできません。Oracle Databaseには、ファイル・データにアクセスするためのAPIが備わっています。

BFILEのバインドまたは定義に使用可能なデータ型コードは、SQLT_BFILE (バイナリFILE LOBデータ型)です。

関連項目:
ディレクトリ別名の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

BLOB

BLOBデータ型には、非構造化バイナリ・ラージ・オブジェクトが格納されます。BLOBは、キャラクタ・セットのセマンティクスを持たないビット・ストリームと考えられます。BLOBには、最大128TBのバイナリ・データを格納できます。

BLOBはトランザクションを完全にサポートしており、OCIを通じて行った変更は、完全にトランザクションで使用できます。BLOB値に対して行った操作は、コミットまたはロールバックできます。1つのトランザクション内で変数のBLOBロケータを保存し、次にそれを別のトランザクションまたはセッションで使用することはできません。

CLOB

CLOBデータ型には固定幅または可変幅の文字データが格納されます。CLOBには、最大128TBの文字データを格納できます。

CLOBはトランザクションを完全にサポートしており、OCIを通じて行った変更は、完全にトランザクションで使用できます。CLOB値に対して行った操作は、コミットまたはロールバックできます。1つのトランザクション内で変数のCLOBロケータを保存し、次にそれを別のトランザクションまたはセッションで使用することはできません。

NCLOB

NCLOBは、CLOBの各国語キャラクタ・バージョンです。これは、固定幅、シングルバイト、マルチバイトの各国語キャラクタ・セット(NCHAR)、または可変幅のキャラクタ・セットのデータを格納します。NCLOBには、最大128TBの文字データを格納できます。

NCLOBはトランザクションを完全にサポートしており、OCIを通じて行った変更は、完全にトランザクションで使用できます。NCLOB値に対して行った操作は、コミットまたはロールバックできます。1つのトランザクション内で変数にNCLOBロケータを保存し、次にそれを別のトランザクションまたはセッションで使用することはできません。

日時および時間隔のデータ型記述子

ここでは、日時および時間隔のデータ型記述子について簡単に説明します。

関連項目:
『Oracle Database SQL言語リファレンス』

ANSI DATE

ANSI DATEデータ型はDATEデータ型が基本になっていますが、時間部分は含まれていません。タイム・ゾーンもありません。ANSI DATEは、DATEデータ型のANSI仕様に従います。ANSI DATEをDATEデータ型またはTIMESTAMPデータ型に割り当てると、OracleのDATEやTIMESTAMPの時間部分は0(ゼロ)に設定されます。DATEデータ型またはTIMESTAMPデータ型をANSI DATEに割り当てると、時間部分は無視されます。

ANSI DATEデータ型を使用するかわりに、日付と時間の両方を含むTIMESTAMPデータ型の使用をお薦めします。

TIMESTAMP

TIMESTAMPデータ型は、DATEデータ型の拡張機能です。DATEデータ型の年、月および日に加えて、時、分および秒の値を格納します。タイム・ゾーンはありません。TIMESTAMPデータ型の形式は次のとおりです。

TIMESTAMP(fractional_seconds_precision)

この書式では、オプションのfractional_seconds_precisionで、SECOND日時フィールドの小数部分の桁数を指定し、桁数は0から9を指定できます。デフォルトは6です。

TIMESTAMP WITH TIME ZONE

TIMESTAMP WITH TIME ZONE (TSTZ)データ型はTIMESTAMPの改良型で、その値に明示的なタイム・ゾーン置換が含まれています。タイム・ゾーン置換は、現地時間とUTC (協定世界時、以前はグリニッジ平均時)との差異(時分による)です。TIMESTAMP WITH TIME ZONEデータ型の書式は次のとおりです。

TIMESTAMP(fractional_seconds_precision) WITH TIME ZONE

この書式では、オプションのfractional_seconds_precisionで、SECOND日時フィールドの小数部分の桁数を指定し、桁数は0から9を指定できます。デフォルトは6です。

2つのTIMESTAMP WITH TIME ZONEの値がUTCで同じ時刻を表している場合は、データに格納されているTIME ZONEオフセットに関係なく同一とみなされます。

TIMESTAMPWITHLOCALTIMEZONE

TIMESTAMP WITH LOCAL TIME ZONE (TSLTZ)データ型はTIMESTAMPの別の改良型で、その値にタイム・ゾーン置換が含まれています。格納される値の形式はTIMESTAMPと同じです。このデータ型とTIMESTAMP WITH TIME ZONEとの違いは、データベースに格納されるデータがデータベース・タイム・ゾーンに正規化されること、およびタイム・ゾーン置換が列データの一部として格納されないことです。データを取り出すと、データは、ユーザーのローカル・セッションのタイム・ゾーンで戻されます。

タイム・ゾーン置換は、現地時間とUTC (協定世界時、以前はグリニッジ平均時)との差異(時分による)です。TIMESTAMP WITH LOCAL TIME ZONEデータ型の書式は次のとおりです。

TIMESTAMP(fractional_seconds_precision) WITH LOCAL TIME ZONE

この書式では、オプションのfractional_seconds_precisionで、SECOND日時フィールドの小数部分の桁数を指定し、桁数は0から9を指定できます。デフォルトは6です。

INTERVALYEARTOMONTH

INTERVAL YEAR TO MONTHデータ型には、YEARおよびMONTH日時フィールドを使用した期間が格納されます。INTERVAL YEAR TO MONTHデータ型の書式は次のとおりです。

INTERVAL YEAR(year_precision) TO MONTH

この書式では、オプションのyear_precisionで、YEAR日時フィールドの桁数を指定します。year_precisionのデフォルト値は2です。

INTERVALDAYTOSECOND

INTERVAL DAY TO SECONDデータ型には、日、時間、分および秒による期間が格納されます。INTERVAL DAY TO SECONDデータ型の書式は次のとおりです。

INTERVAL DAY (day_precision) TO SECOND(fractional_seconds_precision)

この書式の要素:

- day_precisionは、DAY日時フィールドの桁数です。これはオプションです。指定できる値は0から9です。デフォルト値は2です。

- fractional_seconds_precisionは、SECOND日時フィールドの小数部の桁数です。指定できる値は0から9です。デフォルトは6です。

日時を使用する際の予期しない結果の回避

注意:
日時データのデータ操作言語(DML)の操作での予期しない結果を回避するために、組込みSQL関数のDBTIMEZONEとSESSIONTIMEZONEを問い合せて、データベースとセッションのタイム・ゾーンを確認できます。タイム・ゾーンを手動で設定していない場合、デフォルトでオペレーティング・システムのタイム・ゾーンが使用されます。オペレーティング・システムのタイム・ゾーンが有効なOracle Databaseタイム・ゾーンでない場合、UTCがデフォルト値として使用されます。

システム固有のfloatおよびdouble

システム固有のfloat (SQLT_BFLOAT)およびシステム固有のdouble(SQLT_BDOUBLE)データ型は、単精度浮動小数点値および倍精度浮動小数点値を表現します。これらは、システムに固有の書式、つまりホスト・システムの浮動小数点書式で表されます。

これらの外部型は、BINARY_FLOATおよびBINARY_DOUBLE内部データ型を外部で表すために、リリース10.1で追加されました。したがって、内部型は、外部型のシステム固有のfloatおよびdoubleとともにそれぞれ使用したときに、最適なパフォーマンスが得られます。これにより、浮動小数点値の既存の表現(SQLT_FLT)とこれらの型は、明確に区別されます。

Cオブジェクト・リレーショナル・データ型マッピング

OCIでは、ユーザー定義のデータ型をC表現にマッピングするために使用される、Oracle定義のCデータ型がサポートされています(OCINumber、OCIArrayなど)。OCIには、これらのデータ型で動作し、これらのデータ型をOCI外部データ型とともに、バインド操作および定義操作で使用する一連のOCIコールが用意されています。

関連項目:
これらのOracle定義のCデータ型の使用方法の詳細は、第12章を参照してください。

データ変換

表3-5は、リリース7.3で使用可能な全データ型についてサポートされている、内部データ型から外部データ型、および外部データ型から内部列表現への変換を示しています。リリース7.3より後に追加された新しいデータ型のデータ変換の詳細は、次のとおりです。

- データベースに格納されているREFは、出力時にSQLT_REFに変換されます。

- SQLT_REFは、入力時にREFの内部表現に変換されます。

- データベースに格納されている名前付きデータ型は、出力時にSQLT_NTYに変換されます(アプリケーション内ではC構造体で表現されます)。

- SQLT_NTY (アプリケーション内ではC構造体で表現されます)は、入力時に、対応する型の内部表現に変換されます。

表の幅が限られているため、LOBについては表3-6にリストされています。

関連項目:
OCIString、OCINumberおよびその他の新しいデータ型の詳細は、第12章を参照してください。

表3-5 データ変換

NA脚注 1

内部データ型->

NA

NA

NA

NA

NA

NA

NA

NA

外部データ型

VARCHAR2

NUMBER

LONG

ROWID

UROWID

DATE

RAW

LONG RAW

CHAR

VARCHAR2

I/O脚注 2

I/O

I/O

I/O脚注 3

I/O脚注 3

I/O脚注 4

I/O脚注 5

I/O脚注 5

NA

NUMBER

I/O脚注 6

I/O

I脚注 7

NA

NA

NA

NA

NA

I/O脚注 6

INTEGER

I/O脚注 6

I/O

I

NA

NA

NA

NA

NA

I/O脚注 6

FLOAT

I/O脚注 6

I/O

I

NA

NA

NA

NA

NA

I/O脚注 6

STRING

I/O

I/O

I/O

I/O脚注 3

I/O脚注 3

I/O脚注 4

I/O脚注 5

I/O脚注 8

I/O

VARNUM

I/O脚注 6

I/O

I

NA

NA

NA

NA

NA

I/O脚注 6

DECIMAL

I/O脚注 6

I/O

I

NA

NA

NA

NA

NA

I/O脚注 6

LONG

I/O

I/O

I/O

I/O脚注 3

I/O脚注 3

I/O脚注 4

I/O脚注 5

I/O脚注 8

I/O

VARCHAR

I/O

I/O

I/O

I/O脚注 3

I/O脚注 3

I/O脚注 4

I/O脚注 5

I/O脚注 8

I/O

DATE

I/O

NA

I

NA

NA

I/O

NA

NA

I/O

VARRAW

I/O脚注 9

NA

I脚注 9

NA

NA

NA

I/O

I/O

I/O脚注 9

RAW

I/O脚注 9

NA

I脚注 9

NA

NA

NA

I/O

I/O

I/O脚注 9

LONG RAW

O脚注 9

NA

I脚注 9

NA

NA

NA

I/O

I/O

O脚注 9

UNSIGNED

I/O脚注 6

I/O

I

NA

NA

NA

NA

NA

I/O脚注 6

LONG VARCHAR

I/O

I/O

I/O

I/O脚注 3

I/O脚注 3

I/O脚注 4

I/O脚注 5

I/O脚注 8

I/O

LONG VARRAW

I/O脚注 9

NA

I脚注 9

NA

NA

NA

I/O

I/O

I/O脚注 9

CHAR

I/O

I/O

I/O

I/O脚注 3

I/O脚注 3

I/O脚注 4

I/O脚注 5

I脚注 5

I/O

CHARZ

I/O

I/O

I/O

I/O脚注 3

I/O脚注 3

I/O脚注 4

I/O脚注 5

I脚注 5

I/O

ROWID記述子

I脚注 3

NA

NA

I/O

I/O

NA

NA

NA

I脚注 3

脚注 1 NAは、該当なしを意味します。

脚注 2 I/O = 入力時または出力時に有効な変換。

脚注 3 入力時、ホスト文字列はOracle ROWID/UROWID形式であることが必要です。出力時、列値はOracle ROWID/UROWID形式で戻されます。

脚注 4 入力時、ホスト文字列はOracle DATE文字形式であることが必要です。出力時、列値はOracle DATE形式で戻されます。

脚注 5 入力時、ホスト文字列は16進フォーマットであることが必要です。出力時、列値は16進フォーマットで戻されます。

脚注 6 出力時、列値が有効な数値を表している必要があります。

脚注 7 I = 入力時のみ有効な変換。

脚注 8 長さは2000以下であることが必要です。

脚注 9 入力時、列値は16進フォーマットで格納されます。出力時、列値は16進フォーマットであることが必要です。

脚注 10 O = 出力時のみ有効な変換。

LOBデータ型記述子のデータ変換

表3-6では、LOBのデータ変換を示しています。たとえば、外部文字データ型(VARCHAR、CHAR、LONGおよびLONG VARCHAR)は、内部CLOBデータ型に変換されるのに対して、外部RAWデータ型(RAW、VARRAW、LONG RAWおよびLONG VARRAW)は、内部BLOBデータ型に変換されます。

表3-6 LOBのデータ変換

外部データ型

内部CLOB

内部BLOB

VARCHAR

I/O脚注 1

NA脚注 2

CHAR

I/O

NA

LONG

I/O

NA

LONG VARCHAR

I/O

NA

RAW

NA

I/O

VARRAW

NA

I/O

LONG RAW

NA

I/O

LONG VARRAW

NA

I/O

脚注 1 I/O = 入力時または出力時に有効な変換。

脚注 2 NAは、該当なしを意味します。

日時および時間隔データ型のデータ変換

文字データ型のいずれかを、日時列または時間隔列のフェッチ操作または挿入操作で使用するホスト変数に対して使用することもできます。Oracle Databaseでは、文字データ型と日時データ型または時間隔データ型との間の変換が行われます(表3-7を参照)。

表3-7 日時および時間隔データ型のデータ変換

外部データ型/内部データ型

VARCHAR、CHAR

DATE

TS

TSTZ

TSLTZ

INTERVALYEARTOMONTH

INTERVALDAYTOSECOND

VARCHAR2、CHAR

I/O脚注 1

I/O

I/O

I/O

I/O

I/O

I/O

DATE

I/O

I/O

I/O

I/O

I/O

NA脚注 2

NA

OCI DATE

I/O

I/O

I/O

I/O

I/O

NA

NA

ANSI DATE

I/O

I/O

I/O

I/O

I/O

NA

NA

TIMESTAMP(TS)

I/O

I/O

I/O

I/O

I/O

NA

NA

TIMESTAMP WITH TIME ZONE(TSTZ)

I/O

I/O

I/O

I/O

I/O

NA

NA

TIMESTAMP WITH LOCAL TIME ZONE(TSLTZ)

I/O

I/O

I/O

I/O

I/O

NA

NA

INTERVALYEARTOMONTH

I/O

NA

NA

NA

NA

I/O

NA

INTERVALDAYTOSECOND

I/O

NA

NA

NA

NA

NA

I/O

脚注 1 I/O = 入力時または出力時に有効な変換。

脚注 2 NAは、該当なしを意味します。

代入に関する注意

タイム・ゾーンがあるソースを、タイム・ゾーンのないターゲットに割り当てると、ソースのタイム・ゾーン部分は無視されます。タイム・ゾーンのないソースを、タイム・ゾーンがあるターゲットに割り当てると、ターゲットのタイム・ゾーンには、セッションのデフォルト・タイム・ゾーンが設定されます。

Oracle Database DATEをTIMESTAMPに割り当てると、DATEのTIME部分がTIMESTAMPにコピーされます。TIMESTAMPをOracle Database DATEに割り当てると、割当て後のDATEのTIME部分には0 (ゼロ)が設定されます。これは、Oracle Database DATEからANSI準拠のDATETIMEデータ型へのアップグレードを容易にするために行われます。

ANSI DATEをOracle DATEまたはTIMESTAMPに割り当てると、Oracle Database DATEのTIME部分とTIMESTAMPには0 (ゼロ)が設定されます。Oracle Database DATEまたはTIMESTAMPをANSI DATEに割り当てると、TIME部分は無視されます。

DATETIMEを文字列に割り当てると、DATETIMEは、セッションのデフォルトのDATETIME形式によって変換されます。文字列をDATETIMEに割り当てる場合は、その文字列にセッションのデフォルトのDATETIME形式に基づく有効なDATETIME値が含まれていることが必要です。

文字列をINTERVALに割り当てる場合、その文字列が有効なINTERVAL文字形式であることが必要です。

日時および時間隔型のデータ変換に関する注意

TSLTZからCHAR、DATE、TIMESTAMPおよびTSTZに変換すると、値はセッションのタイム・ゾーンに合せて調整されます。

CHAR、DATEおよびTIMESTAMPをTSLTZに変換すると、セッションのタイム・ゾーンはメモリー内に格納されます。

TSLTZをANSI DATEに変換すると、TIME部分には0 (ゼロ)が設定されます。

TSTZから変換すると、タイム・スタンプを含むタイム・ゾーンはメモリー内に格納されます。

文字列をINTERVALに割り当てる場合、その文字列が有効なINTERVAL文字形式であることが必要です。

日時および日付のアップグレード規則

OCIでは、日時列および日付列について、クライアント・アプリケーションとOracle Database間の完全な上位互換性および下位互換性を備えています。

9.0より前のクライアントと9.0以上のサーバー

9.0より前のアプリケーションで使用できる日時データ型は、DATEデータ型のSQLT_DATのみです。バッファをSQLT_DATに定義した9.0より前のクライアントでTSLTZ列からデータを取得しようとすると、値の日付部分のみがクライアントに戻されます。

9.0より前のサーバーと9.0以上のクライアント

9.0より前のサーバーを9.0以上のクライアントとともに使用する場合、クライアントにSQLT_TIMESTAMP_LTZ型のバインド・バッファまたは定義バッファがある場合があります。この場合は、次の互換性が維持されます。

クライアント・アプリケーションで、SQLT_TIMESTAMP_LTZ (または新しい日時データ型)をDATE列に挿入しようとすると、データが失われる可能性があるため、エラーが発生します。

クライアントにSQLT_TIMESTAMP_LTZデータ型のOUTバインド・バッファまたは定義バッファがあり、サーバー側の基礎となるSQLバッファまたは列がDATE型の場合は、セッションのタイム・ゾーンが割り当てられます。

OCIでのBINARY_FLOATおよびBINARY_DOUBLEのデータ変換

表3-8に、内部数値データ型と関連するすべての外部型の間でサポートされている変換を示します。(I)は変換が入力のみ(バインド)に有効であることを示し、(O)は変換が出力のみ(定義)に有効であることを示します。(I/O)は変換が入力と出力(バインドおよび定義)の両方に有効であることを示します。

表3-8 外部データ型から内部数値データ型へのデータ変換

外部データ型/内部データ型

BINARY_FLOAT

BINARY_DOUBLE

VARCHAR

I/O脚注 1

I/O

VARCHAR2

I/O

I/O

NUMBER

I/O

I/O

INTEGER

I/O

I/O

FLOAT

I/O

I/O

STRING

I/O

I/O

VARNUM

I/O

I/O

LONG

I/O

I/O

UNSIGNED INT

I/O

I/O

LONG VARCHAR

I/O

I/O

CHAR

I/O

I/O

BINARY_FLOAT

I/O

I/O

BINARY_DOUBLE

I/O

I/O

脚注 1 (I/O)は変換が入力と出力(バインドおよび定義)に有効であることを示します。

表3-9に、関連するすべての内部型と外部数値データ型の間でサポートされている変換を示します。(I)は変換が入力のみ(バインドの場合のみ)に有効であることを示し、(O)は変換が出力のみ(定義の場合のみ)に有効であることを示します。(I/O)は変換が入力と出力(バインドおよび定義)の両方に有効であることを示します。

表3-9 内部データ型から外部数値データ型へのデータ変換

内部データ型/外部データ型

システム固有のfloat

システム固有のdouble

VARCHAR2

I/O脚注 1

I/O

NUMBER

I/O

I/O

LONG

I脚注 2

I

CHAR

I/O

I/O

BINARY_FLOAT

I/O

I/O

BINARY_DOUBLE

I/O

I/O

脚注 1 (I/O)は変換が入力と出力(バインドおよび定義)に有効であることを示します。

脚注 2 (I)は変換が入力のみ(バインドの場合のみ)に有効であることを示します。

型コード

固有の型コードは、Oracle Databaseのスカラー、コレクション、参照またはオブジェクトの各型に関連付けられています。型コードは型を識別し、オブジェクト型属性に関する情報を管理するためにOracle Databaseが使用します。この型コード・システムは、汎用および拡張可能として設計されています。Oracleデータ型への1対1直接マッピングには関連付けられていません。次のSQL文について考えてみます。

CREATE TYPE my_type AS OBJECT
( attr1    NUMBER,
attr2    INTEGER,
attr3    SMALLINT);

CREATE TABLE my_table AS TABLE OF my_type;

これらの文により、オブジェクト型およびオブジェクト表が作成されます。作成されると、my_tableにはすべてOracle NUMBER型の3つの列が生成されますが、これはSMALLINTおよびINTEGERが内部的にNUMBERにマップされるためです。ただし、my_typeの属性の内部表現には、3つの属性のデータ型間の違いが保持されています。つまり、attr1はOCI_TYPECODE_NUMBER、attr2はOCI_TYPECODE_INTEGERおよびattr3はOCI_TYPECODE_SMALLINTです。アプリケーションでmy_typeを記述すると、これらの型コードが返されます。

OCITypeCodeは、型コードのCデータ型です。型コードは、OCIObjectNew()などの一部のOCI関数で使用され、作成するオブジェクトの型を決定するのに役に立ちます。また、オブジェクトを記述した際に一部の属性の値としても返されます。たとえば、型のOCI_ATTR_TYPECODE属性を問い合せるとOCITypeCode値を返します。

表3-10は、OCITypeCodeに可能な値を示しています。各Oracleデータ型に対応する値があります。

表3-10 OCITypeCodeの値とデータ型

値

データ型

OCI_TYPECODE_REF

REF

OCI_TYPECODE_DATE

DATE

OCI_TYPECODE_TIMESTAMP

TIMESTAMP

OCI_TYPECODE_TIMESTAMP_TZ

TIMESTAMPWITHTIMEZONE

OCI_TYPECODE_TIMESTAMP_LTZ

TIMESTAMPWITHLOCALTIMEZONE

OCI_TYPECODE_INTERVAL_YM

INTERVALYEARTOMONTH

OCI_TYPECODE_INTERVAL_DS

INTERVALDAYTOSECOND

OCI_TYPECODE_REAL

単精度実数

OCI_TYPECODE_DOUBLE

倍精度実数

OCI_TYPECODE_FLOAT

浮動小数点

OCI_TYPECODE_NUMBER

Oracle NUMBER

OCI_TYPECODE_BFLOAT

BINARY_FLOAT

OCI_TYPECODE_BDOUBLE

BINARY_DOUBLE

OCI_TYPECODE_DECIMAL

10進数

OCI_TYPECODE_OCTET

8進数

OCI_TYPECODE_INTEGER

INTEGER

OCI_TYPECODE_SMALLINT

SMALL INT

OCI_TYPECODE_RAW

RAW

OCI_TYPECODE_VARCHAR2

ANSI SQLの可変文字列、すなわちVARCHAR2

OCI_TYPECODE_VARCHAR

Oracle SQLの可変文字列、すなわちVARCHAR

OCI_TYPECODE_CHAR

SQL内部の固定長文字列、すなわちSQL CHAR

OCI_TYPECODE_VARRAY

可変長配列(VARRAY)

OCI_TYPECODE_TABLE

多重集合

OCI_TYPECODE_CLOB

キャラクタ・ラージ・オブジェクト(CLOB)

OCI_TYPECODE_BLOB

バイナリ・ラージ・オブジェクト(BLOB)

OCI_TYPECODE_BFILE

バイナリ・ラージ・オブジェクト・ファイル(BFILE)

OCI_TYPECODE_OBJECT

名前付きオブジェクト型、またはSYS.XMLType

OCI_TYPECODE_NAMEDCOLLECTION

ドメイン(名前付き基本型)

SQLT値およびOCI_TYPECODE値の関係

2種類のデータ型コード値のセットを認識します。これらのセットの1つはSQLT_接頭辞、もう1つはOCI_TYPECODE_接頭辞によって区別されます。

SQLT型コードは、バインド操作または定義操作でデータ型を指定するためにOCIで使用され、これにより、Oracle DatabaseとOCIクライアント・アプリケーション間のデータ変換を制御できます。OCI_TYPECODE型は、ユーザー定義型を操作または作成する際に、Oracleの型システムで事前定義済の型を参照または記述するために使用します。

多くの場合、SQLT値とOCI_TYPECODE値の間で、ダイレクト・マッピングがあります。ただし、1対1のダイレクト・マッピングがない場合もあります。たとえば、OCI_TYPECODE_SIGNED8、OCI_TYPECODE_SIGNED16、OCI_TYPECODE_SIGNED32、OCI_TYPECODE_INTEGER、OCI_TYPECODE_OCTETおよびOCI_TYPECODE_SMALLINTはすべて、SQLT_INT型にマップされます。

表3-11では、SQLT型とOCI_TYPECODE型の間のマッピングを示します。

表3-11 OCI_TYPECODEからSQLTへのマップ

Oracle型システムの型名

Oracle型システムの型

等価SQLT型

BFILE

OCI_TYPECODE_BFILE

SQLT_BFILE

BLOB

OCI_TYPECODE_BLOB

SQLT_BLOB

CHAR

OCI_TYPECODE_CHAR(n)

SQLT_AFC(n)脚注 1

CLOB

OCI_TYPECODE_CLOB

SQLT_CLOB

COLLECTION

OCI_TYPECODE_NAMEDCOLLECTION

SQLT_NCO

DATE

OCI_TYPECODE_DATE

SQLT_DAT

TIMESTAMP

OCI_TYPECODE_TIMESTAMP

SQLT_TIMESTAMP

TIMESTAMPWITHTIMEZONE

OCI_TYPECODE_TIMESTAMP_TZ

SQLT_TIMESTAMP_TZ

TIMESTAMPWITHLOCALTIMEZONE

OCI_TYPECODE_TIMESTAMP_LTZ

SQLT_TIMESTAMP_LTZ

INTERVALYEARTOMONTH

OCI_TYPECODE_INTERVAL_YM

SQLT_INTERVAL_YM

INTERVALDAYTOSECOND

OCI_TYPECODE_INTERVAL_DS

SQLT_INTERVAL_DS

FLOAT

OCI_TYPECODE_FLOAT (b)

SQLT_FLT (8)脚注 2

DECIMAL

OCI_TYPECODE_DECIMAL (p)

SQLT_NUM (p, 0)脚注 3

DOUBLE

OCI_TYPECODE_DOUBLE

SQLT_FLT (8)

BINARY_FLOAT

OCI_TYPECODE_BFLOAT

SQLT_BFLOAT

BINARY_DOUBLE

OCI_TYPECODE_BDOUBLE

SQLT_BDOUBLE

INTEGER

OCI_TYPECODE_INTEGER

SQLT_INT (i)脚注 4

NUMBER

OCI_TYPECODE_NUMBER(p, s)

SQLT_NUM (p, s)脚注 5

OCTET

OCI_TYPECODE_OCTET

SQLT_INT (1)

POINTER

OCI_TYPECODE_PTR

<なし>

RAW

OCI_TYPECODE_RAW

SQLT_LVB

REAL

OCI_TYPECODE_REAL

SQLT_FLT (4)

REF

OCI_TYPECODE_REF

SQLT_REF

OBJECTまたはSYS.XMLType

OCI_TYPECODE_OBJECT

SQLT_NTY

SIGNED(8)

OCI_TYPECODE_SIGNED8

SQLT_INT (1)

SIGNED(16)

OCI_TYPECODE_SIGNED16

SQLT_INT (2)

SIGNED(32)

OCI_TYPECODE_SIGNED32

SQLT_INT (4)

SMALLINT

OCI_TYPECODE_SMALLINT

SQLT_INT (i)脚注 4

TABLE脚注 6

OCI_TYPECODE_TABLE

<なし>

UNSIGNED(8)

OCI_TYPECODE_UNSIGNED8

SQLT_UIN (1)

UNSIGNED(16)

OCI_TYPECODE_UNSIGNED16

SQLT_UIN (2)

UNSIGNED(32)

OCI_TYPECODE_UNSIGNED32

SQLT_UIN (4)

VARRAY脚注 6

OCI_TYPECODE_VARRAY

<なし>

VARCHAR

OCI_TYPECODE_VARCHAR (n)

SQLT_CHR (n)脚注 1

VARCHAR2

OCI_TYPECODE_VARCHAR2 (n)

SQLT_VCS (n)脚注 1

脚注 1 nはバイト単位の文字列です。

脚注 2 これらは浮動小数点で、精度は2進数での桁数です。 bは、2進数数値の精度です。

脚注 3 これは小数点以下の数値を伴わないNUMBERと等価です。

脚注 4 iはバイト単位の数値で、OCIコールの一部として設定されます。

脚注 5 pは10進数での数値の精度で、sは10進数で数値のスケールです。

脚注 6 名前付きコレクション型の一部としてのみ可能です。

oratypes.hの定義

このマニュアルでは、全体を通してub2、sb4などのデータ型、またはUB4MAXVALなどの定数について言及しています。これらの型は、publicディレクトリにあるoratypes.hヘッダー・ファイルで定義されます。正確な内容は、使用しているオペレーティング・システムによって異なります。

注意:
oratypes.hでのデータ型の使用は、OCIにパラメータを渡す手段としてサポートされています。

4 OCIでのSQL文の使用

この章では、Oracle Call Interfaceを使用したSQL文の処理に関する概念およびステップを説明します。

この章は、次の項目で構成されています。

- SQL文の処理の概要

- 文の準備

- OCIのプレースホルダのバインド

- 文の実行

- 選択リスト項目の記述

- OCIでの出力変数の定義

- 結果のフェッチ

- OCIでのスクロール・カーソルの使用

SQL文の処理の概要

第2章では、OCIアプリケーションに含まれる基本ステップについて説明しました。この章では、OCIプログラムでSQL文を処理するときの特定の作業について、さらに詳細に説明します。

OCIプログラムの最も一般的なタスクの1つは、SQL文の受入れと処理です。この項では、この処理に含まれる特定のステップの概要を説明します。

必要なハンドルを割り当て、Oracle Databaseに接続したら、図4-1で説明されているステップに従います。

図4-1 SQL文の処理におけるステップ

1. 文を準備します。OCIStmtPrepare2()またはOCIStmtPrepare()を使用してアプリケーション要求を定義します。OCIStmtPrepare2()は、文キャッシュのサポートのために導入されたOCIStmtPrepare()の拡張バージョンです。

2. 必要な場合は、プレースホルダをバインドします。入力変数のあるDML文および問合せの場合、次の1つ以上のバインド・コールを実行して、各入力変数(またはPL/SQL出力変数)または配列のアドレスを、文内の各プレースホルダにバインドします。

- OCIBindByPos()

- OCIBindByName()

- OCIBindObject()

- OCIBindDynamic()

- OCIBindArrayOfStruct()

3. OCIStmtExecute()をコールして文を実行します。DDL文の場合は、これ以降のステップは必要ありません。

4. 必要な場合は、OCIParamGet()およびOCIAttrGet()を使用して、選択リスト項目を記述します。このステップはオプションで、選択リスト項目の数および各項目の属性(長さやデータ型など)がコンパイル時にわかっている場合には、必要ありません。

5. 必要な場合、出力変数を定義します。問合せの場合は、OCIDefineByPos()、OCIDefineObject()、OCIDefineDynamic()またはOCIDefineArrayOfStruct()の定義コールを1つ以上実行して、SQL文の各選択リスト項目に対して出力変数を定義します。無名PL/SQLブロックの出力変数の定義には定義コールを使用しないように注意してください。これは、データのバインド時に行いました。

6. 必要な場合は、OCIStmtFetch2()をコールして、問合せの結果をフェッチします。

これらのステップの完了後、アプリケーションでは割り当てたハンドルを解放し、次にサーバーとの接続を解除するか、追加の文を処理できます。

7.xアップグレードの注意:
OCIプログラムでは明示的な解析ステップが不要になりました。文を解析する必要がある場合、このステップは実行時に発生します(リリース8.0以上のアプリケーションでは、DML文とDDL文の両方の実行コマンドを発行する必要があるということです)。

各ステップの詳細は、これ以降の項で説明します。

注意:
ステップの順序には、いくつかのバリエーションがあります。たとえば、コンパイル時にデータ型と戻される値の長さがわかっている場合には、実行ステップの前に定義ステップを処理できます。

アプリケーションで次のいずれかを行う場合には、前述のステップの他に追加ステップが必要です。

- 複数トランザクションの開始および管理

- 実行の複数スレッドの管理

- ピース単位の挿入、更新またはフェッチの実行

関連項目:
「OCIでの文キャッシュ」

文の準備

SQL文およびPL/SQL文は、文の準備コールおよび必要なバインド・コールを使用して、実行の準備をします。このフェーズでは、アプリケーションはSQL文またはPL/SQL文を指定し、文中の関連付けられたプレースホルダをデータにバインドして実行できるようにします。クライアント側ライブラリによって、実行準備の完了した文をメンテナンスするための記憶域が割り当てられます。

アプリケーションでは、OCIStmtPrepare2()またはOCIStmtPrepare2()コールを使用して、SQL文またはPL/SQL文の実行準備を要求し、事前に割り当てられている文ハンドルをこのコールに渡します。これは、完全なローカル・コールであるため、サーバーへのラウンドトリップは必要ありません。この時点では、文と特定のサーバーとの関連付けは行われません。

要求コールの後、アプリケーションでは、文ハンドルでOCIAttrGet()をコールし、attrtypeパラメータへOCI_ATTR_STMT_TYPEを渡すことにより、準備されたSQL文の種類を判断できます。可能な属性値とそれに対応する文の種類は、表4-1に記載されています。

表4-1 OCI_ATTR_STMT_TYPE値および文の種類

属性値

文の種類

OCI_STMT_SELECT

SELECT文

OCI_STMT_UPDATE

UPDATE文

OCI_STMT_DELETE

DELETE文

OCI_STMT_INSERT

INSERT文

OCI_STMT_CREATE

CREATE文

OCI_STMT_DROP

DROP文

OCI_STMT_ALTER

ALTER文

OCI_STMT_BEGIN

BEGIN... (PL/SQL)

OCI_STMT_DECLARE

DECLARE... (PL/SQL)

関連項目:

- 「OCIプログラムでのPL/SQL使用方法」

- 「OCIStmtPrepare2()」または「OCIStmtPrepare()」

プリペアド文を複数のサーバーで使用する方法

文ハンドルとサーバーの個々のサービス・コンテキスト・ハンドルの再関連付けによって、準備完了アプリケーション要求を実行時に複数のサーバーに対して実行できます。新たな関連付けが行われると、現行のサービス・コンテキスト・ハンドルと文ハンドル間の関連付けについての情報はすべて失われます。

たとえば、複数のサーバーを管理するネットワーク・マネージャのようなアプリケーションを考えてみます。多くの場合、情報を取り出して表示するには、同一のSELECT文を複数のサーバーに対して実行する必要があります。OCIによって、ネットワーク・マネージャ・アプリケーションでは、一度準備したSELECT文を複数のサーバーに対して実行できます。準備した文を次のサーバーに再度関連付けする前に、各サーバーから必要なすべての行をフェッチしておく必要があります。

注意:
プリペアド文を同じサーバーで頻繁に再実行する必要がある場合は、別のサービス・コンテキスト用に新しい文を準備すると効率的です。

OCIのプレースホルダのバインド

大部分のDML文と一部の問合せ(WHERE句を使用した問合せなど)では、プログラムでデータをSQLまたはPL/SQL文の一部としてOracle Databaseに渡す必要があります。このデータは、プログラムのコンパイル時にわかっている定数またはリテラル・データです。たとえば、次のSQL文は従業員をデータベースへ追加するものですが、これには'BESTRY'および2365などのリテラルがいくつか含まれています。

INSERT INTO emp VALUES
(2365, 'BESTRY', 'PROGRAMMER', 2000, 20)

このように文をアプリケーション内にコーディングすると、その使用範囲が非常に限定されます。データベースに新しい従業員を追加するたびに、文を変更してプログラムを再コンパイルする必要があります。ユーザーが実行時に入力データを指定できるようにすれば、プログラムにもっと柔軟性を持たせることができます。

実行時に提供する入力データを含むSQL文またはPL/SQLブロックを準備する場合は、SQL文またはPL/SQLブロック内のプレースホルダを使用して、データの提供場所にマークを付ける必要があります。たとえば、次のSQL文に最初がコロンで始まる5つのプレースホルダ(:enameなど)が含まれており、プログラムによって入力データが提供される場所を示しているとします。

INSERT INTO emp VALUES
(:empno, :ename, :job, :sal, :deptno)

入力変数のプレースホルダは、DELETE文、INSERT文、SELECT文、UPDATE文またはPL/SQLブロックで、式またはリテラル値を使用できる位置であれば文中の任意の位置で使用できます。PL/SQLでは、出力変数にもプレースホルダを使用できます。

プレースホルダを、表などの他のOracleオブジェクトを表すために使用することはできません。たとえば、次に示すのは、empプレースホルダの正しい使用方法ではありません。

INSERT INTO :emp VALUES
(12345, 'OERTEL', 'WRITER', 50000, 30)

SQL文またはPL/SQLブロックの各プレースホルダに対して、プログラム内の変数のアドレスをプレースホルダにバインドするOCIルーチンをコールする必要があります。文を実行すると、プログラムで入力変数またはバインド変数に入れたデータが読み取られ、それがSQL文でサーバーに渡されます。

バインドは、問合せ以外の操作では入力変数と出力変数の両方に使用されます。例4-1では、変数empno_out、ename_out、job_out、sal_outおよびdeptno_outをバインドする必要があります。これらは、(通常のインバインドとは対照的な)アウトバインドです。

例4-1 問合せ以外の操作での入力変数と出力変数両方のバインド

INSERT INTO emp VALUES
(:empno, :ename, :job, :sal, :deptno)
RETURNING
(empno, ename, job, sal, deptno)
INTO
(:empno_out, :ename_out, :job_out, :sal_out, :deptno_out)

関連項目:
バインド操作実行の詳細は、第5章を参照してください。

プレースホルダのルール

プレースホルダ形成に関するルールは次のとおりです。

- 先頭の文字はコロン(:)です。

- コロンの後には、アンダースコア(_)、AからZ、aからz、0から9のいずれかの組合せが続きます。ただし、コロンの後の最初の文字はアンダースコアにできません。

- 文字は英語のアルファベットから始める必要があり、意味を持つのはコロンの後の最初の30文字のみです。名前は大/小文字の区別があります。

- プレースホルダは、コロンの後、数字のみで構成できます。数字のみの場合、プレースホルダは65536未満である必要があります。数字で名前が始まる場合、使用できるのは数字のみです。

- ハイフン(-)は使用できません。

文の実行

OCIアプリケーションは、OCIStmtExecute()を使用して、プリペアド文を個別に実行します。

OCIアプリケーションで問合せを実行すると、問合せ指定に一致するデータをOracle Databaseから受け取ります。データベース内では、データはOracle独自の形式で格納されています。戻された結果に対して、OCIアプリケーションでは、データを特定のホスト言語形式に変換し、それを特定の出力変数またはバッファ内に格納することを要求できます。

問合せの各選択リスト項目に対し、問合せの結果を受け取るため、OCIアプリケーションで出力変数を定義してください。定義ステップでは、バッファのアドレスおよび取り出すデータの型を指示します。

注意:
OCIStmtExecute()コール前に出力変数がSELECT文に対して定義されている場合は、itersパラメータで指定した行数が定義済の出力バッファに直接フェッチされ、プリフェッチ・カウントと同じ数の追加行がプリフェッチされます。追加行がない場合、フェッチはOCIStmtFetch2()をコールしないで完了します。

問合せ以外の場合、配列操作中の文の実行回数はiters - rowoffと等しくなり、rowoffはバインド済配列のオフセットであり、OCIStmtExecute()コールのパラメータでもあります。

たとえば、10項目の配列がINSERT文の1個のプレースホルダにバインドされていて、itersが10と設定されている場合は、rowoffが0 (ゼロ)であれば、10項目すべてが1回の実行コールで挿入されます。rowoffに2が設定されていれば、挿入されるのは8項目のみです。

関連項目:
「OCIでの出力変数の定義」

実行スナップショット

OCIStmtExecute()コールを使用すると、データベースのコミット済データの一貫した同一スナップショット上で、複数のサービス・コンテキストが確実に動作します。これは、特定の OCIStmtExecute()コールのsnap_outパラメータの内容を読み取り、その値を次のOCIStmtExecute()コールのsnap_inパラメータとして渡すことによって実現されます。

注意:
同じスナップショットを使用している場合でも、1つのサービス・コンテキスト内でコミットされていないデータは、他のコンテキストでは認識されません。

snap_outおよびsnap_inパラメータのデータ型は、どちらもOCISnapshotです。OCISnapshotは、OCIDescriptorAlloc()関数によって割り当てられるOCIスナップショット記述子です。

関連項目:
「OCI記述子」

OCIStmtExecute()をコールする際には、スナップショットを指定する必要はありません。次のサンプル・コードは、snapshotパラメータがNULLとして渡される基本的な実行例です。

checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4) 0,
(OCISnapshot *)NULL, (OCISnapshot *) NULL, OCI_DEFAULT));

注意:
ユーザーが開発したcheckerr()関数によって、OCIアプリケーションからのリターン・コードが評価されます。

OCIStmtExecute()の実行モード

OCIStmtExecute()コールのために、いくつかのモードを指定できます。この項では、OCIStmtExecute()コールについて説明します。パラメータmodeのその他の値については、「OCIStmtExecute()」を参照してください。

バッチ・エラー・モード

OCIでは、配列DML操作を実行できます。たとえば、アプリケーションでは、INSERT文、UPDATE文またはDELETE文の配列を1回の文実行で処理できます。一意性制約違反などのサーバーからのエラーのために操作のいずれかが失敗すると、配列操作は終了し、OCIはエラーを戻します。その場合、配列内の残りの行はすべて無視されます。このため、アプリケーションでは残りの配列を再実行する必要があり、さらにエラーが発生した場合は、この処理全体を再度繰り返すことが必要で、これによって追加のラウンドトリップが発生します。

配列DML操作を容易に処理するために、OCIではバッチ・エラー・モード(拡張DML配列機能とも呼ばれます)が用意されています。このモードはOCIStmtExecute()コールに指定するもので、1つ以上のエラーが発生する場合のDML配列処理を単純化します。このモードでは、OCIはすべての行の挿入、更新または削除を試行し、発生したエラーに関する情報を収集します。次に、アプリケーションでエラー情報を取り出し、最初のコールで失敗した任意のDML操作を再実行できます。この方法では、配列内のすべてのDML操作が最初のコールで試行され、失敗した操作を2番目のコールで再発行できます。

注意:
この機能は、リリース8.1以上のサーバーに対して実行中のリリース8.1以上のOCIライブラリにリンクされているアプリケーションでのみ使用可能です。また、この項で説明している新しいプログラム・ロジックを反映するために、アプリケーションを再コーディングする必要があります。

このモードは次のように使用します。

1. OCIStmtExecute()コールのmodeパラメータとしてOCI_BATCH_ERRORSを指定します。

2. OCIStmtExecute()で配列DML操作を実行した後、アプリケーションでは、例4-2に示すように、文ハンドルでOCIAttrGet()をコールしてOCI_ATTR_NUM_DML_ERRORS属性を取り出すことにより、操作中に発生したエラー数を取り出すことができます。

例4-2 配列DML操作中に発生したエラー数を取り出すためのOCIAttrGet()のコール

ub4   num_errs;
OCIAttrGet(stmtp, OCI_HTYPE_STMT, &num_errs, 0, OCI_ATTR_NUM_DML_ERRORS,
errhp);

3. アプリケーションでは、OCIParamGet()を使用して、OCIStmtExecute()コールに渡されたエラー・ハンドルから各エラーを行情報とともに抽出します。この情報を取り出すには、アプリケーションでOCIParamGet()コール用の追加の新しいエラー・ハンドルを割り当てる必要があり、この新しいエラー・ハンドルには、バッチとして記録されたエラー情報が含まれています。アプリケーションでは、OCIErrorGet()で各エラーの構文を取得し、新しいエラー・ハンドルでOCIAttrGet()をコールすることにより、エラーが発生した行のDML配列内のオフセットを取得します。
たとえば、num_errsの結果が取り出された後で、アプリケーションから次のコールが例4-3に示すように発行される可能性があります。

例4-3 配列のDML操作後の各エラーに関する情報の取出し

OCIError errhndl, errhp2;
for (i=0; i<num_errs; i++)
{
OCIParamGet(errhp, OCI_HTYPE_ERROR, errhp2, (void **)&errhndl, i);
OCIAttrGet(errhndl, OCI_HTYPE_ERROR, &row_offset, 0,
OCI_ATTR_DML_ROW_OFFSET, errhp2);
OCIErrorGet(..., errhndl, ...);

この操作の後に、アプリケーションではバッチとして記録されたエラーから取り出された診断情報を使用し、配列内の該当するエントリのバインド情報を修正できます。該当するバインド・バッファが修正または更新されると、アプリケーションでそれに対応するDML文を再実行できます。

最初の実行でエラーの原因となる行をコンパイル時に特定できないため、後続のDMLのバインドは、実行時に該当するバッファを渡すことにより、動的に実行する必要があります。最初のDML操作での配列バインドで使用されたバインド・バッファを再利用できます。

バッチ・エラー・モードの例

例4-4は、バッチ・エラー実行モードがどのように使用されるかの例を示しています。この例では、表に5つの行を(NUMBERおよびCHAR型の2つの列とともに)挿入するアプリケーションがあるものとします。さらに、2つの行(1および3)のみが最初のDML操作で正常に挿入されるものとします。ユーザーは次に、データ(最初の操作で挿入された誤ったデータ)を修正し、修正したデータのUPDATEを発行します。ユーザーは文ハンドルstmtp1およびstmtp2を使用して、INSERT文およびUPDATE文をそれぞれ発行します。

例4-4 バッチ・エラー実行モードの使用

OCIBind *bindp1[2], *bindp2[2];
ub4 num_errs, row_off[MAXROWS], number[MAXROWS] = {1,2,3,4,5};
char grade[MAXROWS] = {'A','B','C','D','E'};
OCIError *errhp2;
OCIError *errhndl[MAXROWS];
...
/* Array bind all the positions */
OCIBindByPos (stmtp1,&bindp1[0],errhp,1,(void *)&number[0],
sizeof(number[0]),SQLT_INT,(void *)0, (ub2 *)0,(ub2 *)0,
0,(ub4 *)0,OCI_DEFAULT);
OCIBindByPos (stmtp1,&bindp1[1],errhp,2,(void *)&grade[0],
sizeof(grade[0]),SQLT_CHR,(void *)0, (ub2 *)0,(ub2 *)0,0,
(ub4 *)0,OCI_DEFAULT);
/* execute the array INSERT */
OCIStmtExecute (svchp,stmtp1,errhp,5,0,0,0,OCI_BATCH_ERRORS);
/* get the number of errors. A different error handler errhp2 is used so that
* the state of errhp is not changed */
OCIAttrGet (stmtp1, OCI_HTYPE_STMT, &num_errs, 0,
OCI_ATTR_NUM_DML_ERRORS, errhp2);
if (num_errs) {
/* The user can do one of two things: 1) Allocate as many  */
/* error handles as number of errors and free all handles  */
/* at a later time; or 2) Allocate one err handle and reuse */
/* the same handle for all the errors */
for (i = 0; i < num_errs; i++) {
OCIHandleAlloc( (void *)envhp, (void **)&errhndl[i],
(ub4) OCI_HTYPE_ERROR, 0, (void *) 0);
OCIParamGet(errhp, OCI_HTYPE_ERROR, errhp2, &errhndl[i], i);
OCIAttrGet (errhndl[i], OCI_HTYPE_ERROR, &row_off[i], 0,
OCI_ATTR_DML_ROW_OFFSET, errhp2);
/* get server diagnostics */
OCIErrorGet (..., errhndl[i], ...);
}
}
/* make corrections to bind data */
OCIBindByPos (stmtp2,&bindp2[0],errhp,1,(void *)0,sizeof(grade[0]),SQLT_INT,
(void *)0, (ub2 *)0,(ub2 *)0,0,(ub4 *)0,OCI_DATA_AT_EXEC);
OCIBindByPos (stmtp2,&bindp2[1],errhp,2,(void *)0,sizeof(number[0]),SQLT_DAT,
(void *)0, (ub2 *)0,(ub2 *)0,0,(ub4 *)0,OCI_DATA_AT_EXEC);
/* register the callback for each bind handle, row_off and position
* information can be passed to the callback function by means of context
* pointers.
*/
OCIBindDynamic (bindp2[0],errhp,ctxp1,my_callback,0,0);
OCIBindDynamic (bindp2[1],errhp,ctxp2,my_callback,0,0);
/* execute the UPDATE statement */
OCIStmtExecute (svchp,stmtp2,errhp,num_errs,0,0,0,OCI_BATCH_ERRORS);
...

例4-4では、どの行がエラーとともに戻されるかコンパイル時にはわからないため、OCIBindDynamic()コールバックとともに使用しています。コールバックでは、row_offに格納されたエラーを含む行の番号をコールバック・コンテキストを通じて渡し、更新または修正の必要がある行のみを送信できます。INSERT文の実行とUPDATE文の実行では、同じバインド・バッファを共有できます。

選択リスト項目の記述

OCIアプリケーションで問合せを処理する場合には、選択リスト項目に関して詳細な情報を取得する必要があります。実行時まで問合せの内容がわからない動的問合せの場合は、特にそうです。そのような場合、プログラムでは、選択リスト項目のデータ型および列の長さに関する情報を取得する必要があります。この情報は、問合せの結果を受け取る出力変数を定義するために必要です。

たとえば、プログラムにはemployees表の列についての事前情報を持たない問合せについて考えてみます。

SELECT * FROM employees

使用可能な記述の種類には、暗黙的および明示的の2つがあります。

暗黙的記述では、情報にアクセスするためには特別なコールが必要ですが、サーバーからの記述情報を取得するためには特別なコールは必要ありません。暗黙的記述では、特定の記述コールを実行せずに文を実行した後、アプリケーションは文ハンドルの属性として選択リスト情報を取得できます。これは、記述コールが不要なため、暗黙的と呼ばれます。記述情報は、文の実行により解放されます。

明示的な記述は、サーバーから記述情報を取得するために、アプリケーションから特定の関数をコールする必要があります。アプリケーションでは、選択リスト(問合せ)を暗黙的にも明示的にも記述できます。その他のスキーマ要素は、明示的に記述する必要があります。

OCIStmtExecute()のモードとしてOCI_DESCRIBE_ONLYを指定することで(文は実行されませんが、選択リスト記述は戻されます)、問合せを実行前に明示的に記述できます。パフォーマンス向上のためには、標準的な文の実行で自動的に得られる暗黙的記述をアプリケーションで使用することをお薦めします。

OCIDescribeAny()コールを使用した明示的な記述では、選択リストではなく、スキーマ・オブジェクトに関する情報を取得します。

すべての場合において、列およびデータ型に関する特定の情報は、ハンドル属性を読み取ることによって検索されます。

関連項目:
スキーマ・オブジェクトに関連するメタデータを取得するためのOCIDescribeAny()の使用方法の詳細は、第6章を参照してください。

暗黙的記述

SQL文を実行した後、文ハンドルの属性として選択リストに関する情報を取得できます。明示的な記述コールは必要ありません。

複数の選択リスト項目に関する情報を取り出すには、最初にposパラメータを1と設定したOCIParamGet()をコールし、次にposの値を反復して、ORA-24334のOCI_ERRORが戻されるまでOCIParamGet()コールを繰り返します。また、アプリケーションでは、列をランダムに取得するために、位置nを指定できます。

アプリケーションでは、選択リストの位置のパラメータ記述子を割り当てた後、パラメータ記述子についてOCIAttrGet()をコールすることによって、特定の情報を取り出せます。パラメータ記述子から取得できる情報として、データ型とパラメータの最大サイズがあります。

例4-5暗黙的記述 - 選択リストは文ハンドルの属性として取得可能のサンプル・コードは、問合せ実行後に、問合せに対応する列名およびデータ型を取り出すループを示しています。この問合せは、事前にOCIStmtPrepare2()またはOCIStmtPrepare()のコールによって文ハンドルと関連付けられています。

例4-5 暗黒的記述 - 選択リストは文ハンドルの属性として取得可能

...
OCIParam     *mypard = (OCIParam *) 0;
ub2          dtype;
text         *col_name;
ub4          counter, col_name_len, char_semantics;
ub2          col_width;
sb4          parm_status;

text *sqlstmt = (text *)"SELECT * FROM employees WHERE employee_id = 100";

checkerr(errhp, OCIStmtPrepare(stmthp, errhp, (OraText *)sqlstmt,
(ub4)strlen((char *)sqlstmt),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));

checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, 0, 0, (OCISnapshot *)0, (OCISnapshot *)0, OCI_DEFAULT));

/* Request a parameter descriptor for position 1 in the select list */
counter = 1;
parm_status = OCIParamGet((void *)stmthp, OCI_HTYPE_STMT, errhp,
(void **)&mypard, (ub4) counter);

/* Loop only if a descriptor was successfully retrieved for
current position, starting at 1 */

while (parm_status == OCI_SUCCESS) {
/* Retrieve the data type attribute */
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void*) &dtype,(ub4 *) 0, (ub4) OCI_ATTR_DATA_TYPE,
(OCIError *) errhp  ));

/* Retrieve the column name attribute */
col_name_len = 0;
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void**) &col_name, (ub4 *) &col_name_len, (ub4) OCI_ATTR_NAME,
(OCIError *) errhp ));

/* Retrieve the length semantics for the column */
char_semantics = 0;
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void*) &char_semantics,(ub4 *) 0, (ub4) OCI_ATTR_CHAR_USED,
(OCIError *) errhp  ));
col_width = 0;
if (char_semantics)
/* Retrieve the column width in characters */
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void*) &col_width, (ub4 *) 0, (ub4) OCI_ATTR_CHAR_SIZE,
(OCIError *) errhp  ));
else
/* Retrieve the column width in bytes */
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void*) &col_width,(ub4 *) 0, (ub4) OCI_ATTR_DATA_SIZE,
(OCIError *) errhp  ));

/* increment counter and get next descriptor, if there is one */
counter++;
parm_status = OCIParamGet((void *)stmthp, OCI_HTYPE_STMT, errhp,
(void **)&mypard, (ub4) counter);
} /* while */
...

例4-5のcheckerr()関数は、エラー処理に使用します。完全なリストは、付録Bの最初のサンプル・アプリケーションを参照してください。

OCIAttrGet()およびOCIParamGet()のコールは、文の実行後すべての選択リスト情報がクライアント側にキャッシュされるために、ネットワーク・ラウンドトリップを必要としないローカル・コールです。

関連項目:

- 「OCIParamGet()」

- 「OCIArrayDescriptorAlloc()」

- OCIArrayDescriptorAlloc()で読み取ることができるパラメータ記述子の特定の属性のリストは、「パラメータ属性」を参照してください。

問合せの明示的記述

OCIStmtExecute()のモードとしてOCI_DESCRIBE_ONLYを指定することで(文は実行されませんが、選択リスト記述は戻されます)、問合せを実行前に明示的に記述できます。

注意:
パフォーマンスを最大にするために、アプリケーションではデフォルト・モードで文を実行し、実行に伴う暗黙的な記述を使用することをお薦めします。

例4-6のコードは、列に関する情報を戻すための選択リストでの明示的記述の使用を説明しています。

例4-6 明示的記述 - 列ごとに選択リストの記述を戻す

...
int i = 0;
ub4 numcols = 0;
ub2 type = 0;
OCIParam *colhd = (OCIParam *) 0;   /* column handle */

text *sqlstmt = (text *)"SELECT * FROM employees WHERE employee_id = 100";

checkerr(errhp, OCIStmtPrepare(stmthp, errhp, (OraText *)sqlstmt,
(ub4)strlen((char *)sqlstmt),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));

/* initialize svchp, stmhp, errhp, rowoff, iters, snap_in, snap_out */
/* set the execution mode to OCI_DESCRIBE_ONLY. Note that setting the mode to
OCI_DEFAULT does an implicit describe of the statement in addition to executing
the statement */

checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, 0, 0,
(OCISnapshot *) 0, (OCISnapshot *) 0, OCI_DESCRIBE_ONLY));

/* Get the number of columns in the query */
checkerr(errhp, OCIAttrGet((void *)stmthp, OCI_HTYPE_STMT, (void *)&numcols,
(ub4 *)0, OCI_ATTR_PARAM_COUNT, errhp));

/* go through the column list and retrieve the data type of each column.
Start from pos = 1 */
for (i = 1; i <= numcols; i++)
{
/* get parameter for column i */
checkerr(errhp, OCIParamGet((void *)stmthp, OCI_HTYPE_STMT, errhp, (void **)&colhd, i));

/* get data-type of column i */
type = 0;
checkerr(errhp, OCIAttrGet((void *)colhd, OCI_DTYPE_PARAM,
(void *)&type, (ub4 *)0, OCI_ATTR_DATA_TYPE, errhp));
}
...

OCIでの出力変数の定義

問合せ文は、データベースのデータをアプリケーションに戻します。問合せを処理するときには、データを検索する選択リストの各項目について、出力変数または出力変数の配列を定義する必要があります。定義ステップでは、戻される結果の格納場所と格納形式を判断する関連付けを行います。

たとえば、次の文を処理するには、通常は2つの出力変数を定義します。1つはname列から戻される値を受け取るための変数、もう1つはssn列から戻される値を受け取るための変数です。

SELECT name, ssn FROM employees
WHERE empno = :empnum

関連項目:
第5章「OCIでのバインドおよび定義」

結果のフェッチ

OCIアプリケーションで問合せを処理した場合は通常、文の実行が完了した後にOCIStmtFetch2()を使用して、結果をフェッチする必要があります。OCIStmtFetch2()関数では、スクロール・カーソルをサポートします。

関連項目:
「OCIでのスクロール・カーソルの使用」

フェッチされたデータは、定義操作で指定した出力変数に格納されます。

注意:
OCIStmtExecute()のコール前にSELECT文に出力変数を定義した場合は、itersパラメータで指定した行数が、定義されている出力バッファに直接フェッチされます。

関連項目:

- 前述のこれらの文により、「OCIの定義に使用するステップ」のサンプル・コードに関連したデータがフェッチされます。詳細は、例を参照してください。

- 出力変数の定義の詳細は、「OCIでの定義の概要」を参照してください。

LOBデータのフェッチ

LOB列または属性が選択リストの一部である場合、そのLOB列または属性は、ユーザーの定義方法に応じて、LOBロケータまたは実際のLOB値として戻すことができます。LOBロケータがフェッチされると、アプリケーションでは、OCILobXXX関数を介してそれらのロケータに対してさらに操作を実行できます。

関連項目:

- OCIでのLOBロケータの処理の詳細は、第7章を参照してください。

- ロケータを使用せずにLOBデータを選択する方法および例は、「LOB出力変数の定義」を参照してください。

プリフェッチ・カウントの設定

サーバー・ラウンドトリップを最小限にし、パフォーマンスを最適化するために、OCIでは問合せの実行時に結果セット行をプリフェッチできます。ユーザーは、OCIAttrSet()関数を使用して、文ハンドルのOCI_ATTR_PREFETCH_ROWS属性またはOCI_ATTR_PREFETCH_MEMORY属性を設定することにより、このプリフェッチをカスタマイズできます。属性は次のように使用します。

- OCI_ATTR_PREFETCH_ROWSは、プリフェッチする行数を設定します。この属性が設定されていない場合、デフォルト値は1です。OCIStmtExecute()のitersパラメータが0で、プリフェッチが使用可能な場合、OCIStmtFetch2()のコール中に行がバッファされます。プリフェッチ値は、実行後およびフェッチ中に変更できます。

- OCI_ATTR_PREFETCH_MEMORYは、プリフェッチする行に割り当てられたメモリーを設定します。その後、アプリケーションでは、メモリーの容量が許すかぎりの行数をフェッチします。

これらの属性を設定すると、OCIでは、OCI_ATTR_PREFETCH_MEMORYで設定した最大メモリーに到達しないかぎり、OCI_ATTR_PREFETCH_ROWSで設定した行数まで行をプリフェッチし、この場合OCIは、OCI_ATTR_PREFETCH_MEMORYのバッファ・サイズに入る行数を戻します。

デフォルトでは、プリフェッチは有効で、プリフェッチが問合せに対してサポートできない場合を除き、OCIでは1行余分にフェッチします(この後の注意を参照)。プリフェッチをオフにするには、OCI_ATTR_PREFETCH_ROWS属性およびOCI_ATTR_PREFETCH_MEMORY属性の両方に0 (ゼロ)を設定します。

OCI_ATTR_PREFETCH_ROWS属性とOCI_ATTR_PREFETCH_MEMORY属性の両方が明示的に設定されている場合、OCIでは2つの制限のうちより厳しい方を使用して、プリフェッチする行数を決めます。

メモリー制約に基づいて排他的にプリフェッチするには、OCI_ATTR_PREFETCH_MEMORY属性を設定し、OCI_ATTR_PREFETCH_ROWS属性をゼロに設定して(1行のデフォルト設定をオーバーライドするため)必ず無効にします。

行数制約に基づいて排他的にプリフェッチするには、OCI_ATTR_PREFETCH_ROWS属性を設定し、OCI_ATTR_PREFETCH_MEMORY属性をゼロに設定して(明示的にゼロ以外の値に設定されている場合)無効にします。

プリフェッチは、REF CURSORおよびネストされたカーソル列で可能です。デフォルトでは、プリフェッチはREF CURSORに対して有効になっていません。REF CURSORに対してプリフェッチを有効にするには、REF CURSORから行をフェッチする前に、OCI_ATTR_PREFETCH_ROWS属性またはOCI_ATTR_PREFETCH_MEMORY属性を設定します。REF CURSORがOCIアプリケーションとPL/SQLとの間で複数回渡され、OCIとPL/SQLでREF CURSORに対するフェッチが実行されると、OCIでプリフェッチ(有効な場合)された行が原因で、アプリケーションは、PL/SQLで適切でない行がフェッチされているかのように動作します。そのような場合、OCIプリフェッチはREF CURSORに対して有効にすべきではありません。

注意:
LONG、LOBまたは不透明型の列(XMLTypeなど)が問合せに含まれている場合、プリフェッチは無効になります。

関連項目:
「文ハンドル属性」

OCIでのスクロール・カーソルの使用

カーソルは、結果セット内での現在の位置です。カーソルを実行すると、問合せの結果は結果セットと呼ばれる行セットに格納され、連続的または非連続的にフェッチできます。非連続のフェッチでは、カーソルはスクロール・カーソルと呼ばれます。

スクロール・カーソルは、結果セットに対する絶対的または相対的な行番号のオフセットが使用することで、指定した位置から結果セットへの前後方向へのアクセスをサポートします。

行番号は1から始まります。スクロール・カーソルの場合は、以前にフェッチした行、結果セットのn番目の行、あるいは現在の位置からn番目の行をフェッチできます。クライアント側で結果セットの一部または全部をキャッシュすると、サーバーへのコールが制限されるためパフォーマンスが向上します。

スクロール・カーソルでのDML操作はサポートしていません。選択リストにLONGデータ型が含まれている場合、カーソルはスクロール可能にできません。

さらに、スクロール可能な文ハンドルからのフェッチは、実行時のスナップショットに基づいています。OCIクライアント・プリフェッチは、OCIスクロール・カーソルと連動します。クライアント・プリフェッチ・キャッシュのサイズは、既存のOCI属性であるOCI_ATTR_PREFETCH_ROWSとOCI_ATTR_PREFETCH_MEMORYによって制御できます。

注意:
スクロール・カーソルは、多くのサーバー・リソースを使用し、スクロール不可カーソルより応答時間が長くなる場合があるため、この機能を必要としないかぎり使用しないでください。

OCIStmtExecute()コールには、スクロール・カーソル用の実行モードであるOCI_STMT_SCROLLABLE_READONLYが用意されています。文ハンドルのデフォルトはスクロール不可で、前方への順次アクセスに限られ、モードはOCI_FETCH_NEXTです。この実行モードは、文ハンドルを実行するたびに設定する必要があります。

文ハンドル属性OCI_ATTR_CURRENT_POSITIONは、OCIAttrGet()を使用することによってのみ取得できます。この属性はアプリケーションでは設定できず、結果セット内の現在の位置を示します。

スクロール不可カーソルの場合、OCI_ATTR_ROW_COUNTは、この文ハンドルの実行後にOCIStmtFetch2()コールでユーザー・バッファにフェッチされた行の合計数です。スクロール不可カーソルは前方への順次アクセスのみであるため、OCI_ATTR_ROW_COUNTは、アプリケーションで検出できる最大行数も表します。

スクロール・カーソルの場合、OCI_ATTR_ROW_COUNTは、ユーザー・バッファにフェッチされた行の最大(絶対)数を表します。アプリケーションでは、任意の位置でフェッチを行うことができるため、これは、(スクロール可能な)文の実行後にユーザーのバッファにフェッチされた行の合計数である必要はありません。

文ハンドルのOCI_ATTR_ROWS_FETCHED属性は、前回のフェッチ・コールまたは実行で、ユーザーのバッファに正常にフェッチされた行数を表します。これは、スクロール・カーソルとスクロール不可カーソルの両方で使用されます。

OCIStmtFetch()コールのかわりに、下位互換性が保持されているOCIStmtFetch2()コールを使用します。スクロール・カーソルが使用されていない場合でも、すべての新規アプリケーションでOCIStmtFetch2()を使用することをお薦めします。このコールはスクロール不可カーソルでも動作しますが、OCI_DEFAULTまたはOCI_FETCH_NEXT以外の方向が渡された場合にエラーが発生することがあります。

リモートでマップされた問合せでは、スクロール・カーソルがサポートされています。スクロール・カーソルでは、透過的アプリケーション・フェイルオーバー(TAF)がサポートされています。

注意:
nrowsパラメータに0 (ゼロ)を設定してOCIStmtFetch2()をコールした場合は、カーソルが取り消されます。

関連項目:

- 「OCIStmtFetch2()」

- 「プリフェッチ・カウントの設定」

スクロール・カーソルのパフォーマンスの向上

OCIのクライアント側プリフェッチ・バッファを使用すると、応答時間が短縮します。スクロール・カーソルに対してOCIStmtExecute()をコールした後、OCI_FETCH_LASTを使用してOCIStmtFetch2()をコールし、結果セットのサイズを取得します。次に、OCI_ATTR_PREFETCH_ROWSをそのサイズの約20%に設定し、結果セットで大量のメモリーを使用している場合はOCI_PREFETCH_MEMORYを設定します。

スクロール・カーソルでのアクセスの例

次のSQL問合せにより結果セットが戻され、表EMPに14行あるとします。

SELECT empno, ename FROM emp

スクロール・カーソルの使用方法の1つを例4-7に示します。

例4-7 スクロール・カーソルでのアクセス

...
/* execute the scrollable cursor in the scrollable mode */
OCIStmtExecute(svchp, stmthp, errhp, (ub4)0, (ub4)0, (CONST OCISnapshot *)NULL,
(OCISnapshot *) NULL, OCI_STMT_SCROLLABLE_READONLY );

/* Fetches rows with absolute row numbers 6, 7, 8. After this call,
OCI_ATTR_CURRENT_POSITION = 8, OCI_ATTR_ROW_COUNT = 8 */
checkprint(errhp, OCIStmtFetch2(stmthp, errhp, (ub4) 3,
OCI_FETCH_ABSOLUTE, (sb4) 6, OCI_DEFAULT);

/* Fetches rows with absolute row numbers 6, 7, 8. After this call,
OCI_ATTR_CURRENT_POSITION = 8, OCI_ATTR_ROW_COUNT = 8 */
checkprint(errhp, OCIStmtFetch2(stmthp, errhp, (ub4) 3,
OCI_FETCH_RELATIVE, (sb4) -2, OCI_DEFAULT);

/* Fetches rows with absolute row numbers 14. After this call,
OCI_ATTR_CURRENT_POSITION = 14, OCI_ATTR_ROW_COUNT = 14 */
checkprint(errhp, OCIStmtFetch2(stmthp, errhp, (ub4) 1,
OCI_FETCH_LAST, (sb4) 0, OCI_DEFAULT);

/* Fetches rows with absolute row number 1. After this call,
OCI_ATTR_CURRENT_POSITION = 1, OCI_ATTR_ROW_COUNT = 14 */
checkprint(errhp, OCIStmtFetch2(stmthp, errhp, (ub4) 1,
OCI_FETCH_FIRST, (sb4) 0, OCI_DEFAULT);

/* Fetches rows with absolute row numbers 2, 3, 4. After this call,
OCI_ATTR_CURRENT_POSITION = 4, OCI_ATTR_ROW_COUNT = 14 */
checkprint(errhp, OCIStmtFetch2(stmthp, errhp, (ub4) 3,
OCI_FETCH_NEXT, (sb4) 0, OCI_DEFAULT);

/* Fetches rows with absolute row numbers 3,4,5,6,7. After this call,
OCI_ATTR_CURRENT_POSITION = 7, OCI_ATTR_ROW_COUNT = 14. It is assumed
the user's define memory is allocated. */
checkprint(errhp, OCIStmtFetch2(stmthp, errhp, (ub4) 5,
OCI_FETCH_PRIOR, (sb4) 0, OCI_DEFAULT);
...
}
checkprint (errhp, status)
{
ub4 rows_fetched;
/* This checks for any OCI errors before printing the results of the fetch call
in the define buffers */
checkerr (errhp, status);
checkerr(errhp, OCIAttrGet((CONST void *) stmthp, OCI_HTYPE_STMT,
(void *) &rows_fetched, (uint *) 0, OCI_ATTR_ROWS_FETCHED, errhp));
}
...

5 OCIでのバインドおよび定義

この章は、次の項目で構成されています。

- OCIでのバインドの概要

- OCIでの拡張バインド操作

- OCIでの定義の概要

- OCIでの拡張定義操作

- OCIでの構造体配列のバインドと定義

- 複数バッファのバインドと定義

- OCIでのRETURNING句を使用したDML

- OCIバインドおよび定義における文字変換

- OCIでのPL/SQL REF CURSORおよびNESTED TABLE

- OCIでのランタイム・データ割当てとピース単位操作

OCIでのバインドの概要

この章では、バインドと定義の基本概念をもう一度取り上げ、OCIアプリケーションで使用できる様々な種類のバインドと定義を詳しく説明します。さらに、構造体配列の使用方法、およびバインド、定義、文字変換における諸問題についても説明します。

たとえば、次のようなINSERT文があるとします。

INSERT INTO emp VALUES
(:empno, :ename, :job, :sal, :deptno)

次の変数宣言を行います。

text     *ename, *job;
sword    empno, sal, deptno;

バインド・ステップでは、プレースホルダ名とプログラム変数のアドレス間の関連付けを行います。また、図5-1に示すように、バインドでは、プログラム変数のデータ型と長さを指定します。

関連項目:
この例が実装されているコードは、「OCIバインドで使用するステップ」を参照してください。

図5-1 OCIBindByName()を使用したプレースホルダとプログラム変数の関連付け

バインド変数の値のみを変更した場合は、文を再実行するために再バインドする必要はありません。バインドは参照によるため、変数のアドレスおよびハンドルが有効であるかぎり、再バインドせずに、変数を参照する文を再実行できます。

注意:
インタフェース・レベルの場合は、バインド変数はすべてINであるとみなされるため、適切に初期化する必要があります。変数が純OUTバインド変数の場合は、この変数を0 (ゼロ)に設定できます。また、NULLインジケータを使用して、そのインジケータを-1 (NULL)に設定することもできます。

Oracle Databaseでは、名前付きデータ型、REFおよびLOB用のデータ型が実装されおり、これらは、SQL文中でプレースホルダとしてバインドできます。

注意:
記述子やロケータなど、サイズが不明で不透明なデータ型の場合は、記述子またはロケータ・ポインタのアドレスを渡してください。サイズ・パラメータに、適切なデータ構造のサイズ(sizeof(structure))を設定します。

名前付きバインドおよび定位置バインド

図5-1のSQL文は、名前付きバインドの例です。文の各プレースホルダには、'ename'や'sal'などの名前が関連付けられています。この文を準備し、プレースホルダをアプリケーションの値に関連付けるときは、OCIBindByName()コールのplaceholderパラメータでプレースホルダの名前を渡し、プレースホルダの名前による関連付けを行います。

2番目のタイプのバインドは、位置指定バインドと呼ばれます。定位置バインドでは、プレースホルダは名前ではなく文中の位置によって参照されます。このバインドでは、OCIBindByPos()コールを使用して、入力値とプレースホルダの位置との間の関連付けを行います。

前の項に示した例を定位置バインドに使用すると、次のようになります。

INSERT INTO emp VALUES
(:empno, :ename, :job, :sal, :deptno)

5つのプレースホルダは、OCIBindByPos()をコールし、positionパラメータでプレースホルダの位置番号を渡すことによって、それぞれバインドされます。たとえば、OCIBindByPos()をコールすることによって、:empnoプレースホルダは位置1に、:enameは位置2にというようにバインドされます。

重複バインドでは、1つのバインド・コールのみが必要です。次のSQL文について考えてみます。このSQL文は、コミッションと給料の両方が指定の金額よりも高い従業員をデータベースで問い合せます。

SELECT empno FROM emp
WHERE sal > :some_value
AND comm > :some_value

OCIアプリケーションでは、OCIBindByName()を1回コールするのみで、:some_valueプレースホルダを名前によってバインドし、この文のバインドを完了できます。この場合、:some_valueのすべてのバインド・プレースホルダには、OCIBindByName()コールで指定したのと同じ値が割り当てられます。

次に、重複する6つ目のプレースホルダが追加される場合を考えてみます。たとえば、:enameを6つ目のプレースホルダとして前の最初の例に追加します。

INSERT INTO emp VALUES
(:empno, :ename, :job, :sal, :deptno, :ename)

OCIBindByName()コールを使用している場合、両方の:enameプレースホルダをバインドするには1つのバインド・コールで十分です。文中のすべての:enameは、同じ値にバインドされます。さらに、新しいバインド・プレースホルダが、既存のバインド・プレースホルダのバインド位置が変わった結果として追加される場合、バインド位置を更新するために、既存のバインド・コールを変更する必要はありません。これは、プログラムが文のテキストにさらに多くのバインド変数を追加するようになった場合に、OCIBindByName()コールを使用する上で明らかに有利な点です。

ただし、OCIBindByPos()コールを使用していれば、重複するバインドパラメータのバインドに関しては、それが必要な場合、柔軟性が高まります。バインド・パラメータの重複をどれでも別々にバインドするオプションがあります。バインドを解除された重複パラメータは、同じ名前を持つ最初のバインド・パラメータから値を継承します。最初のものは、明示的にバインドする必要があります。

SQL文のコンテキストでは、位置nは、n番目の位置にあるバインド・パラメータを示します。ただし、PL/SQL文のコンテキストでは、OCIBindByPos()での位置パラメータの解釈が異なります。つまり、バインド・コールでの位置nは、文を左から右にスキャンしたときのn番目の一意のパラメータ名のバインドを示します。

前の例と同じSQL文のテキストを使用すると、6番目の位置を単独でバインドする場合、位置6でOCIBindByPos()をコールすることにより、:enameプレースホルダがバインドされます。バインド解除のままの場合は、:enameは、同じ名前を持つ最初のパラメータ、この場合は位置2の:enameから値を継承することになります。

OCI配列インタフェース

Oracle Databaseにデータを渡すには、様々な方法があります。

OCIStmtExecute()ルーチンを使用してSQL文を繰り返し実行し、反復のたびに異なる入力値を指定することもできます。

Oracle配列インタフェースを使用すると、単一の文とOCIStmtExecute()のコール1回のみで、多数の値を入力できます。その場合、配列を入力プレースホルダにバインドし、itersパラメータで制御して配列全体を同時に渡すことができます。

配列インタフェースを使用すると、大量のデータを更新または挿入する場合に、データベースとのラウンドトリップの回数を大幅に削減できます。この削減により、通信量の多いクライアント/サーバー環境では、大きなパフォーマンスの向上につながります。たとえば、データベースに10行挿入するアプリケーションを考えてみます。OCIStmtExecute()を10回、それぞれ1個の値を指定してコールすると、すべてのデータの挿入にネットワーク・ラウンドトリップが10回必要です。入力配列を使用すると、OCIStmtExecute()を1回コールするのみで同じ結果が得られ、ネットワーク・ラウンドトリップは1回ですみます。

注意:
OCI配列インタフェースを使用して挿入を行う場合は、各行が挿入されるたびに、データベース内の行トリガーが起動されます。
配列DML文で使用できる最大行数は、40億 -1 (3,999,999,999)です。

PL/SQLのプレースホルダのバインド

PL/SQLブロックの処理は、単一のSQL文の場合と同じようにそのブロックを文字列変数に入れて、任意の変数をバインドし、ブロックを含む文を実行して行います。

PL/SQLブロックのプレースホルダをプログラム変数にバインドする場合は、OCIBindByName()またはOCIBindByPos()を使用して、スカラーまたは配列のいずれかのホスト変数に対して基本バインドを行います。

次の短いPL/SQLブロックには2つのプレースホルダが含まれ、従業員番号と新規給与額に基づき、従業員の給与を更新するプロシージャへのINパラメータを表します。

char plsql_statement[] = "BEGIN\
RAISE_SALARY(:emp_number, :new_sal);\
END;" ;

これらのプレースホルダは、SQL文のプレースホルダと同じ方法で入力変数にバインドできます。

PL/SQL文を処理するとき、出力変数もまたバインド・コールを使用してプログラム変数に関連付けられます。

たとえば、次のPL/SQLブロックがあるとします。

BEGIN
SELECT ename,sal,comm INTO :emp_name, :salary, :commission
FROM emp
WHERE empno = :emp_number;
END;

このブロックでは、OCIBindByName()を使用して、変数を:emp_name、:salaryおよび:commissionの各出力プレースホルダにバインドし、入力プレースホルダ:emp_numberにも変数をバインドします。

注意:
バインド・コールでッファ長を0 (ゼロ)に設定するか、あるいは対応するインジケータを-1に設定して、純OUTバッファの場合も含め、すべてのババッファを初期化する必要があります。

関連項目:
PL/SQLプレースホルダのバインドの詳細は、「名前付きデータ型およびREFバインドの情報」を参照してください。

OCIバインドで使用するステップ

プレースホルダは複数のステップでバインドされます。単純なスカラー・バインドまたは配列バインドの場合は、OCIBindByName()またはOCIBindByPos()を使用して、プレースホルダとデータとの関連付けを指定するのみです。

バインドが完了すると、SQL文の実行時には、入力データの位置やPL/SQL出力データを入れる位置がOCIライブラリに対して明らかになります。プログラム入力データは、プログラム変数をプレースホルダにバインドする際にプログラム変数内に存在している必要はありませんが、文を実行する際には存在している必要があります。

次の例5-1のコード例は、SQL文の各プレースホルダのハンドル割当てとバインドを示しています。

例5-1 SQL文の各プレースホルダのハンドル割当てとバインド

...
/* The SQL statement, associated with stmthp (the statement handle)
by calling OCIStmtPrepare() */
text *insert = (text *) "INSERT INTO emp(empno, ename, job, sal, deptno)\
VALUES (:empno, :ename, :job, :sal, :deptno)";
...

/*  Bind the placeholders in the SQL statement, one per bind handle. */
checkerr(errhp, OCIBindByName(stmthp, &bnd1p, errhp, (text *) ":ENAME",
strlen(":ENAME"), (ub1 *) ename, enamelen+1, SQLT_STR, (void *) 0,
(ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT));
checkerr(errhp, OCIBindByName(stmthp, &bnd2p, errhp, (text *) ":JOB",
strlen(":JOB"), (ub1 *) job, joblen+1, SQLT_STR, (void *)
&job_ind, (ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT));
checkerr(errhp, OCIBindByName(stmthp, &bnd3p, errhp, (text *) ":SAL",
strlen(":SAL"), (ub1 *) &sal, (sword) sizeof(sal), SQLT_INT,
(void *) &sal_ind, (ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0,
OCI_DEFAULT));
checkerr(errhp, OCIBindByName(stmthp, &bnd4p, errhp, (text *) ":DEPTNO",
strlen(":DEPTNO"), (ub1 *) &deptno,(sword) sizeof(deptno), SQLT_INT,
(void *) 0, (ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT));
checkerr(errhp, OCIBindByName(stmthp, &bnd5p, errhp, (text *) ":EMPNO",
strlen(":EMPNO"), (ub1 *) &empno, (sword) sizeof(empno), SQLT_INT,
(void *) 0, (ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0,OCI_DEFAULT));

注意:
checkerr()関数によって、OCIアプリケーションからのリターン・コードが評価されます。この関数のコードは、「OCIErrorGet()」の例にあります。

OCIプログラムでのPL/SQLブロック

OCI中のPL/SQLブロックで最もよく使用されるのは、おそらくストアド・プロシージャまたはストアド・ファンクションのコールです。データベースに格納されたRAISE_SALARYというプロシージャがあり、そのプロシージャに対するコールを無名PL/SQLブロックに埋め込み、PL/SQLブロックを処理するとします。

次に示すプログラムの一部分は、ストアド・プロシージャ・コールをOCIアプリケーションに埋め込む方法の例です。このプログラムでは、raise_salaryというストアド・プロシージャへの入力として、従業員番号と新しい給与が渡されます。

raise_salary (employee_num IN, sal_increase IN, new_salary OUT);

このプロシージャでは、指定された従業員給与に指定された額が上乗せされます。増額された給与はストアド・プロシージャの変数new_salaryに戻され、この値がプログラムで表示されます。

PL/SQL OUT変数をバインドする必要がありますが、PL/SQLプロシージャ引数new_salaryが未定義であることに注意してください。これについては、「PL/SQL出力変数の定義」および「名前付きデータ型、REF定義およびPL/SQL OUTバインドの情報」を参照してください。

例5-2は、単一バインド・コールのみが必要な単純なスカラー・バインドを実行する方法を示しています。場合によっては、特定のバインド・データ型または実行モードについて属性を定義するために、追加のバインド・コールが必要です。

例5-2 OCIで使用されるPL/SQL文の定義

/* Define PL/SQL statement to be used in program. */
text *give_raise = (text *) "BEGIN\
RAISE_SALARY(:emp_number,:sal_increase, :new_salary);\
END;";
OCIBind  *bnd1p = NULL;                      /* the first bind handle */
OCIBind  *bnd2p = NULL;                     /* the second bind handle */
OCIBind  *bnd3p = NULL;                      /* the third bind handle */

static void checkerr();
sb4 status;

main()
{
sword    empno, raise, new_sal;
void     *tmp;
OCISession *usrhp = (OCISession *)NULL;
...
/* attach to Oracle database, and perform necessary initializations
and authorizations */
...
/* allocate a statement handle */
checkerr(errhp, OCIHandleAlloc( (void *) envhp, (void **) &stmthp,
OCI_HTYPE_STMT, 100, (void **) &tmp));

/* prepare the statement request, passing the PL/SQL text
block as the statement to be prepared */
checkerr(errhp, OCIStmtPrepare(stmthp, errhp, (text *) give_raise, (ub4)
strlen(give_raise), OCI_NTV_SYNTAX, OCI_DEFAULT));

/* bind each of the placeholders to a program variable */
checkerr( errhp, OCIBindByName(stmthp, &bnd1p, errhp, (text *) ":emp_number",
-1, (ub1 *) &empno,
(sword) sizeof(empno), SQLT_INT, (void *) 0,
(ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT));

checkerr( errhp, OCIBindByName(stmthp, &bnd2p, errhp, (text *) ":sal_increase",
-1, (ub1 *) &raise,
(sword) sizeof(raise), SQLT_INT, (void *) 0,
(ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT));

/* remember that PL/SQL OUT variables are bound, not defined */

checkerr( errhp, OCIBindByName(stmthp, &bnd3p, errhp, (text *) ":new_salary",
-1, (ub1 *) &new_sal,
(sword) sizeof(new_sal), SQLT_INT, (void *) 0,
(ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT));

/* prompt the user for input values */
printf("Enter the employee number: ");
scanf("%d", &empno);
/* flush the input buffer */
myfflush();

printf("Enter employee's raise: ");
scanf("%d", &raise);
/* flush the input buffer */
myfflush();

/* execute PL/SQL block*/
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4) 0,
(OCISnapshot *) NULL, (OCISnapshot *) NULL, OCI_DEFAULT));

/* display the new salary, following the raise */
printf("The new salary is %d\n", new_sal);
}

OCIでの拡張バインド操作

「OCIのプレースホルダのバインド」では、OCIBindByName()またはOCIBindByPos()を使用して、SQL文のプレースホルダとプログラム変数間の関連付けを行うための基本バインド操作の方法について説明しました。この項では、マルチステップ・バインド、名前付きデータ型のバインド、REFのバインドなどの拡張バインド操作について説明します。

場合によっては、特定のバインド・データ型または特定の実行モードについて特定の属性を定義するために、追加のバインド・コールが必要です。

次の各項ではこの特別なケースについて説明し、バインドの詳細は、表5-1にまとめてあります。

表5-1 バインド・タイプの情報の概要

バインドのタイプ

バインド・データ型

注意

スカラー

スカラー・データ型

OCIBindByName()またはOCIBindByPos()を使用して、単一のスカラーをバインドします。

スカラーの配列

スカラー・データ型

OCIBindByName()またはOCIBindByPos().を使用して、スカラーの配列をバインドします。

名前付きデータ型

SQLT_NTY

次の2つのバインド・コールが必要です。

- OCIBindByName()またはOCIBindByPos()

- OCIBindObject()

REF

SQLT_REF

次の2つのバインド・コールが必要です。

- OCIBindByName()またはOCIBindByPos()

- OCIBindObject()

LOB

BFILE

SQLT_BLOB

SQLT_CLOB

OCIDescriptorAlloc()を使用してLOBロケータを割り当て、次にLOBデータ型の1つを使用して、そのアドレス(OCILobLocator **)をOCIBindByName()またはOCIBindByPos()とバインドします。

構造体の配列または静的配列

変化

次の2つのバインド・コールが必要です。

- OCIBindByName()またはOCIBindByPos()

- OCIBindArrayOfStruct()

ピース単位挿入

変化

OCIBindByName()またはOCIBindByPos()が必要です。また、ピース単位コールバックを登録するために、アプリケーションでOCIBindDynamic()コールが必要な場合もあります。

REF CURSOR変数

SQLT_RSET

文ハンドル、OCIStmtを割り当ててから、SQLT_RSETデータ型を使用して、その文ハンドルのアドレスOCIStmt **をバインドします。

関連項目:

- 名前付きデータ型(オブジェクト)のバインドの詳細は、「名前付きデータ型のバインド」を参照してください。

- 「REFのバインド」

LOBのバインド

LOBをバインドするには、次の2つの方法があります。

- 実際のLOB値ではなく、LOBロケータをバインドします。この場合、LOB値の書込みや読取りは、LOBロケータをOCI LOB関数に渡すことによって行われます。

- LOBロケータを使用せず、LOB値を直接バインドします。

LOBロケータのバインド

単一のバインド・コール内で、単一のロケータをバインドすることも、ロケータの配列をバインドすることもできます。いずれの場合も、アプリケーションは、ロケータ自体ではなく、LOBロケータのアドレスを渡す必要があります。たとえば、アプリケーションにより、one_lobがLOB列に対応するバインド変数である次のSQL文が準備されたとします。

INSERT INTO some_table VALUES (:one_lob)

アプリケーションでは、次の宣言を行います。

OCILobLocator * one_lob;

例5-3のコールは、プレースホルダをバインドし、文を実行するために使用されます。

例5-3 単一のロケータを挿入するためのプレースホルダのバインドと文の実行

/* initialize single locator */
one_lob = OCIDescriptorAlloc(...OCI_DTYPE_LOB...);
...
/* pass the address of the locator */
OCIBindByName(...,(void *) &one_lob,... SQLT_CLOB, ...);
OCIStmtExecute(...,1,...)                /* 1 is the iters parameter */

また、同一のSQL INSERT文を使用して、配列の挿入ができます。この場合、アプリケーションには、例5-4で示すコードが含まれます。

例5-4 ロケータ配列を挿入するためのプレースホルダのバインドと文の実行

OCILobLocator * lob_array[10];
...
for (i=0; i<10, i++)
lob_array[i] = OCIDescriptorAlloc(...OCI_DTYPE_LOB...);
/* initialize array of locators */
...
OCIBindByName(...,(void *) lob_array,...);
OCIStmtExecute(...,10,...);               /* 10 is the iters parameter */

記述子は、使用する前にOCIDescriptorAlloc()関数によって割り当てる必要があります。ロケータの配列では、OCIDescriptorAlloc()を使用して、各配列要素を初期化する必要があります。BLOB、CLOBおよびNCLOBを割り当てる場合は、OCI_DTYPE_LOBをtypeパラメータとして使用します。BFILEを割り当てる場合は、OCI_DTYPE_FILEを使用します。

LOBロケータのバインドに対する制限

LOBロケータをバインドする際には、次の制限を守ってください。

- INSERTまたはUPDATEのピース単位操作およびコールバック操作は、サポートされていません。

- FILEロケータをINSERT文またはUPDATE文のバインド変数として使用する場合は、INSERT文またはUPDATE文を発行する前に、OCILobFileSetName()を使用してディレクトリ・オブジェクトおよびファイル名で、ロケータを初期化する必要があります。

関連項目:
OCI LOB関数の詳細は、第7章を参照してください。

LOBデータのバインド

0 (ゼロ)以外のあらゆるサイズのLOBでINSERTとUPDATEに対するバインドが可能です。OCIBindByPos()、OCIBindByName()およびPL/SQLのバインドを使用すると、データをLOB列にバインドできます。

4KBを超えるデータをLOB列にバインドする場合は、一時表領域の一部を使用します。一時表領域が少なくともLOBバインドの長さの合計値に等しい量のデータを格納できる大きさであることを確認してください。一時表領域が拡張可能であれば、既存の領域が一杯になると自動的に拡張されます。次のコマンドを使用して、拡張できる一時表領域を作成します。

CREATE TABLESPACE ... AUTOEXTEND ON ... TEMPORARY ...;

LOBデータのバインドに対する制限

LOBデータをバインドする際には、次の制限を守ってください。

- 表にLONG列とLOB列の両方がある場合は、LONG列とLOB列のどちらに対しても4KBを超えるデータのバインドが可能ですが、同一の文で両方を実行することはできません。

- INSERT AS SELECT操作で、LOB列に対するデータのバインドはできません。

- LONGまたはLOBのどちらでもないが、SQL文でLOBまたはLONGバインド変数の後にあるバインド変数の最大サイズについて、特別な配慮が必要です。そのようなバインド変数の最大サイズが4000バイトを超えると、ORA-24816エラーが発生します。このエラーを回避するには、キャラクタ・セットの変換後、サーバー側で最大サイズが4000バイトを超えるバインドに対して、OCI_ATTR_MAXDATA_SIZEを4000バイトに設定する必要があります。または、そのようなバインドがバインド・リスト内でLONGまたはLOBの前に置かれるように、バインドの順番を変更します。

関連項目:
「OCI_ATTR_MAXDATA_SIZE属性の使用」

- 4000バイトを超えるデータに対しては、HEXからRAW、RAWからHEXなどの暗黙的な変換は行われません。例5-5のPL/SQLコードではこれを説明しています。

例5-5 実行できない一部の暗黙的変換の説明

create table t (c1 clob, c2 blob);
declare
text   varchar(32767);
binbuf raw(32767);
begin
text := lpad ('a', 12000, 'a');
binbuf := utl_raw.cast_to_raw(text);

-- The following works:
insert into t values (text, binbuf);

-- The following does not work because Oracle dpes not do implicit
-- hex to raw conversion.
insert into t (c2) values (text);

-- The following does not work because Oracle does not do implicit
-- raw to hex conversion.
insert into t (c1) values (binbuf);

-- The following does not work because you cannot combine the
-- utl_raw.cast_to_raw() operator with the >4k bind.
insert into t (c2) values (utl_raw.cast_to_raw(text));

end;
/

- 4000バイトを超えるデータをBLOBまたはCLOBにバインドし、データがSQL演算子によってフィルタされる場合は、結果のサイズが制限されて4000バイト以下になります。
たとえば、次のようにします。

create table t (c1 clob, c2 blob);
-- The following command inserts only 4000 bytes because the result of
-- LPAD is limited to 4000 bytes
insert into t(c1) values (lpad('a', 5000, 'a'));

-- The following command inserts only 2000 bytes because the result of
-- LPAD is limited to 4000 bytes, and the implicit hex to raw conversion
-- converts it to 2000 bytes of RAW data.
insert into t(c2) values (lpad('a', 5000, 'a'));

LOBデータのバインドの例

例5-6から例5-13まででは、次のSQL文が使用されています。

CREATE TABLE foo (a INTEGER );
CREATE TYPE lob_typ AS OBJECT (A1 CLOB );
CREATE TABLE lob_long_tab (C1 CLOB, C2 CLOB, CT3 lob_typ, L LONG);

例5-6 可能: C1、C2およびL列に、それぞれサイズが最大8000、8000および2000バイトのバインド可変データ値を挿入

void insert()                 /* A function in an OCI program */
{
/* The following is allowed */
ub1 buffer[8000];
text *insert_sql = (text *) "INSERT INTO lob_long_tab (C1, C2, L) \
VALUES (:1, :2, :3)";
OCIStmtPrepare(stmthp, errhp, insert_sql, strlen((char*)insert_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[0], errhp, 1, (void *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[1], errhp, 2, (void *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[2], errhp, 3, (void *)buffer, 2000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT);
}

例5-7 可能: C1およびL列に、それぞれサイズが最大2000および8000バイトのバインド可変データ値を挿入

void insert()
{
/* The following is allowed */
ub1 buffer[8000];
text *insert_sql = (text *) "INSERT INTO lob_long_tab (C1, L) \
VALUES (:1, :2)";
OCIStmtPrepare(stmthp, errhp, insert_sql, strlen((char*)insert_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[0], errhp, 1, (void *)buffer, 2000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[1], errhp, 2, (void *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT);
}

例5-8 可能: C1、C2およびL列を、それぞれサイズが最大8000、8000および2000バイトのバインド可変データ値に更新

void update()
{
/* The following is allowed, no matter how many rows it updates */
ub1 buffer[8000];
text *update_sql = (text *)"UPDATE lob_long_tab SET \
C1 = :1, C2=:2, L=:3";
OCIStmtPrepare(stmthp, errhp, update_sql, strlen((char*)update_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[0], errhp, 1, (void *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[1], errhp, 2, (void *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[2], errhp, 3, (void *)buffer, 2000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT);
}

例5-9 可能: C1、C2およびL列を、それぞれサイズが最大2000、2000および8000バイトのバインド可変データ値に更新

void update()
{
/* The following is allowed, no matter how many rows it updates */
ub1 buffer[8000];
text *update_sql = (text *)"UPDATE lob_long_tab SET \
C1 = :1, C2=:2, L=:3";
OCIStmtPrepare(stmthp, errhp, update_sql, strlen((char*)update_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[0], errhp, 1, (void *)buffer, 2000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[1], errhp, 2, (void *)buffer, 2000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[2], errhp, 3, (void *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT);
}

例5-10 可能: ピース単位、コールバックおよび配列挿入または更新の操作

void insert()
{
/* Piecewise, callback and array insert/update operations similar to
* the allowed regular insert/update operations are also allowed */
}

例5-11 不可能: LOB列とLONG列の両方に4000バイトを超えるデータを同じINSERT文を使用して挿入

void insert()
{
/* The following is NOT allowed because you cannot insert >4000 bytes
* into both LOB and LONG columns */
ub1 buffer[8000];
text *insert_sql = (text *)"INSERT INTO lob_long_tab (C1, L) \
VALUES (:1, :2)";
OCIStmtPrepare(stmthp, errhp, insert_sql, strlen((char*)insert_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[0], errhp, 1, (void *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[1], errhp, 2, (void *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT);
}

例5-12 可能: CT3 LOB列にサイズが最大2000バイトのバインド変数データ値を挿入

void insert()
{
/* Insert of data into LOB attributes is allowed */
ub1 buffer[8000];
text *insert_sql = (text *)"INSERT INTO lob_long_tab (CT3) \
VALUES (lob_typ(:1))";
OCIStmtPrepare(stmthp, errhp, insert_sql, strlen((char*)insert_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[0], errhp, 1, (void *)buffer, 2000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT);
}

例5-13 不可能: 選択操作としての挿入で任意の長さのデータをLOB列にバインド

void insert()
{
/* The following is NOT allowed because you cannot do insert as
* select character data into LOB column */
ub1 buffer[8000];
text *insert_sql = (text *)"INSERT INTO lob_long_tab (C1) SELECT \
:1 from FOO";
OCIStmtPrepare(stmthp, errhp, insert_sql, strlen((char*)insert_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[0], errhp, 1, (void *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT);
}

OCI_DATA_AT_EXECモードでのバインド

OCIBindByName()またはOCIBindByPos()コールのmodeパラメータがOCI_DATA_AT_EXECに設定されているとき、アプリケーションで実行時にデータを提供するコールバック方式を使用する場合は、追加のOCIBindDynamic()コールが必要です。OCIBindDynamic()のコールは、提供されたデータまたはその一部を示すために、必要に応じてコールバック・ルーチンを設定します。OCI_DATA_AT_EXECモードを選択した場合でも、コールバックのかわりに標準のOCIのピース単位ポーリング・メソッドを使用する場合は、OCIBindDynamic()コールは必要ありません。

RETURN句の変数をバインドするとき、アプリケーションでは、OCI_DATA_AT_EXECモードを使用して、コールバックを提供する必要があります。

関連項目:
ピース単位操作の詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

REF CURSOR変数のバインド

REF CURSORは、バインド・データ型のSQLT_RSETを使用して、文ハンドルにバインドされます。

関連項目:
「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」

OCIでの定義の概要

問合せ文は、データベースのデータをアプリケーションに戻します。問合せを処理するときには、データを検索する選択リストの各項目について、出力変数または出力変数の配列を定義する必要があります。定義ステップでは、戻される結果の格納場所と格納形式を判断する関連付けを行います。

たとえば、プログラムで次の文を処理するには、通常は2つの出力変数を定義する必要があります。1つは、name列から戻される値を受け取るための変数、もう1つはssn列から戻される値を受け取るための変数です。

SELECT name, ssn FROM employees
WHERE empno = :empnum

name列の値のみを取り出す場合は、ssn列用の出力変数を定義する必要はありません。処理されるSELECT文が問合せに対して複数の行を戻す場合、出力変数はスカラー値のかわりに配列を定義できます。

定義ステップは、アプリケーションに応じて文の実行前または実行後に行います。コンパイル時に選択リスト項目のデータ型がわかっている場合には、文を実行する前に定義を行うことができます。実行時に入力する動的SQL文、あるいは明確に定義された選択リストがない文をアプリケーションで処理する場合、アプリケーションはその文を実行して、記述情報を取り出す必要があります。記述情報を取り出した後、各選択リスト項目の型情報を使用して、出力変数を定義できます。

OCIでは、クライアント側で定義コールをローカルに処理します。定義ステップでは、結果を格納するバッファの位置を指示し、さらに、データがアプリケーションに戻されるときに行う必要があるデータ変換の種類を決定します。

注意:
出力バッファには、2バイトの位置揃えを行う必要があります。

OCIDefineByPos()コールのdtyパラメータでは、出力変数のデータ型を指定します。OCIでは、データを出力変数にフェッチするときに広範囲のデータ変換を行うことができます。たとえば、Oracle DATE形式の内部データは、出力時に、自動的にStringデータ型に変換できます。

関連項目:

- データ型および変換の詳細は、第3章を参照してください。

- 「選択リスト項目の記述」

OCIの定義に使用するステップ

基本的な定義は、定位置コールのOCIDefineByPos()により行われます。このステップでは、選択リスト項目と出力変数との間の関連付けを行います。特定のデータ型またはフェッチ・モードには追加の定義コールが必要です。定義ステップが完了すると、OCIライブラリでは、データを入れる位置を決定します。SQL文を再準備または再実行することなく、定義コールを再度行って出力変数を再定義できます。

例5-14では、実行および記述操作の後にスカラー出力変数を定義しています。

例5-14 実行および記述操作後のスカラー出力変数の定義

SELECT department_name FROM departments WHERE department_id = :dept_input

/* The input placeholder was bound earlier, and the data comes from the
user input below */

printf("Enter employee dept: ");
scanf("%d", &deptno);

/* Execute the statement. If OCIStmtExecute() returns OCI_NO_DATA, meaning that
no data matches the query, then the department number is invalid. */

if ((status = OCIStmtExecute(svchp, stmthp, errhp, 0, 0, (OCISnapshot *) 0, (OCISnapshot *) 0,
OCI_DEFAULT))
&& (status != OCI_NO_DATA))
{
checkerr(errhp, status);
return OCI_ERROR;
}
if (status == OCI_NO_DATA) {
printf("The dept you entered does not exist.\n");
return 0;
}

/* The next two statements describe the select-list item, dname, and
return its length */
checkerr(errhp, OCIParamGet((void *)stmthp, (ub4) OCI_HTYPE_STMT, errhp, (void **)&parmdp, (ub4) 1));
checkerr(errhp, OCIAttrGet((void*) parmdp, (ub4) OCI_DTYPE_PARAM,
(void*) &deptlen, (ub4 *) &sizelen, (ub4) OCI_ATTR_DATA_SIZE,
(OCIError *) errhp  ));

/* Use the retrieved length of dname to allocate an output buffer, and
then define the output variable. If the define call returns an error,
exit the application */
dept = (text *) malloc((int) deptlen + 1);
if (status = OCIDefineByPos(stmthp, &defnp, errhp,
1, (void *) dept, (sb4) deptlen+1,
SQLT_STR, (void *) 0, (ub2 *) 0,
(ub2 *) 0, OCI_DEFAULT))
{
checkerr(errhp, status);
return OCI_ERROR;
}

関連項目:
記述ステップの詳細は、「選択リスト項目の記述」を参照してください。

OCIでの拡張定義操作

この項では、マルチステップ定義、名前付きデータ型およびREFなどの拡張定義操作について説明します。

定義ステップで、OCIDefineByPos()のコール以外の別のコールが必要になる場合があります。たとえば、配列フェッチOCIDefineArrayOfStruct()または名前付きデータ型フェッチOCIDefineObject()の属性を定義する場合です。たとえば、1列の名前付きデータ型を含む複数の行をフェッチするには、その列で3つのコールをすべて呼び出す必要があります。スカラー列のみを含む複数の行をフェッチするには、OCIDefineArrayOfStruct()およびOCIDefineByPos()が適しています。

また、Oracle Databaseには、オブジェクト型属性をマップする事前定義済のCデータ型が用意されています。

関連項目:

- 第12章「OCIのオブジェクト・リレーショナル・データ型」

- 「OCIでの拡張定義操作」

LOB出力変数の定義

LOBを定義するには、次の2つの方法があります。

- 実際のLOB値ではなく、LOBロケータを定義します。この場合、LOB値の書込みや読取りは、LOBロケータをOCI LOB関数に渡すことによって行われます。

- LOBロケータを使用せず、LOB値を直接定義します。

LOBロケータの定義

単一の定義コール内では、単一のロケータを定義することも、ロケータの配列を定義することもできます。いずれの場合も、アプリケーションは、ロケータ自体ではなく、LOBロケータのアドレスを渡す必要があります。たとえば、アプリケーションで次のSQL文が準備されたとします。

SELECT lob1 FROM some_table;

この文では、lob1はLOB列で、one_lobは次の宣言を伴ったLOB列に対応する定義変数です。

OCILobLocator * one_lob;

次のようなコールを使用して、プレースホルダをバインドし、文を実行します。

/* initialize single locator */
OCIDescriptorAlloc(...&one_lob, OCI_DTYPE_LOB...);
...
/* pass the address of the locator */
OCIBindByName(...,(void *) &one_lob,... SQLT_CLOB, ...);
OCIStmtExecute(...,1,...);                /* 1 is the iters parameter */

また、同一のSQL SELECT文を使用して、配列の挿入ができます。このケースでは、アプリケーション内に次のコードが組み込まれている必要があります。

OCILobLocator * lob_array[10];
...
for (i=0; i<10, i++)
OCIDescriptorAlloc(...&lob_array[i], OCI_DTYPE_LOB...);
/* initialize array of locators */
...
OCIBindByName(...,(void *) lob_array,...);
OCIStmtExecute(...,10,...);               /* 10 is the iters parameter */

記述子は、使用する前にOCIDescriptorAlloc()関数によって割り当てる必要があります。ロケータの配列では、OCIDescriptorAlloc()を使用して、各配列要素を初期化する必要があります。BLOB、CLOBおよびNCLOBを割り当てる場合は、OCI_DTYPE_LOBをtypeパラメータとして使用します。BFILEを割り当てる場合は、OCI_DTYPE_FILEを使用します。

LOBデータの定義

0 (ゼロ)以外のあらゆるサイズのLOBでSELECTの定義が可能です。OCIDefineByPos()およびPL/SQLの定義を使用すると、使用可能な最大サイズのデータをLOB列から選択できます。1行に複数のLOBを含めることができるため、同一のSELECT文中の各LOBに対して最大サイズのデータを選択できます。

例5-15と例5-16では、次のSQL文が基礎となっています。

CREATE TABLE lob_tab (C1 CLOB, C2 CLOB);

例5-15 実行前のLOBの定義

void select_define_before_execute()      /* A function in an OCI program */
{
/* The following is allowed */
ub1 buffer1[8000];
ub1 buffer2[8000];
text *select_sql = (text *)"SELECT c1, c2 FROM lob_tab";

OCIStmtPrepare(stmthp, errhp, select_sql, (ub4)strlen((char*)select_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIDefineByPos(stmthp, &defhp[0], errhp, 1, (void *)buffer1, 8000,
SQLT_LNG, (void *)0, (ub2 *)0, (ub2 *)0, (ub4) OCI_DEFAULT);
OCIDefineByPos(stmthp, &defhp[1], errhp, 2, (void *)buffer2, 8000,
SQLT_LNG, (void *)0, (ub2 *)0, (ub2 *)0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *)0,
(OCISnapshot *)0, OCI_DEFAULT);
}

例5-16 実行後のLOBの定義

void select_execute_before_define()
{
/* The following is allowed */
ub1 buffer1[8000];
ub1 buffer2[8000];
text *select_sql = (text *)"SELECT c1, c2 FROM lob_tab";

OCIStmtPrepare(stmthp, errhp, select_sql, (ub4)strlen((char*)select_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 0, 0, (OCISnapshot *)0,
(OCISnapshot *)0, OCI_DEFAULT);
OCIDefineByPos(stmthp, &defhp[0], errhp, 1, (void *)buffer1, 8000,
SQLT_LNG, (void *)0, (ub2 *)0, (ub2 *)0, (ub4) OCI_DEFAULT);
OCIDefineByPos(stmthp, &defhp[1], errhp, 2, (void *)buffer2, 8000,
SQLT_LNG, (void *)0, (ub2 *)0, (ub2 *)0, (ub4) OCI_DEFAULT);
OCIStmtFetch(stmthp, errhp, 1, OCI_FETCH_NEXT, OCI_DEFAULT);
}

PL/SQL出力変数の定義

PL/SQLブロック内のSQL SELECT文の選択リスト項目については、出力変数を定義するのに定義コールは使用しません。かわりに、OCIバインド・コールを使用してください。

関連項目:
PL/SQL出力変数の定義の詳細は、「名前付きデータ型、REF定義およびPL/SQL OUTバインドの情報」を参照してください。

ピース単位フェッチの定義

ピース単位フェッチでは、最初にOCIDefineByPos()をコールする必要があります。アプリケーションで、標準のポーリング・メカニズムではなくコールバックを使用する場合は、追加のOCIDefineDynamic()コールが必要です。

OCIでの構造体配列のバインドと定義

構造体配列の定義では、最初にOCIDefineByPos()をコールする必要があります。構造体配列操作に必要なskipパラメータなどの各追加パラメータを設定するには、追加のOCIDefineArrayOfStruct()コールが必要です。

構造体配列の使用により、複数行、複数列の操作の処理を簡素化できます。関連したスカラー・データ項目の構造体を作成し、データベースの値を構造体配列へフェッチしたり、これらの構造体配列の値をデータベースに挿入できます。

たとえば、あるアプリケーションでNAME、AGEおよびSALARYという列から、複数行のデータをフェッチする必要があるとします。アプリケーションでは、個別のフィールド(それぞれが、データベース表で1行に含まれているNAME、AGEおよびSALARYのデータを保持)を含む構造体の定義を組み込むことができます。アプリケーションでは、次に、これらの構造体配列へデータをフェッチします。

構造体配列を使用して、複数行、複数列の操作を実行するには、その操作に関連する各列を、構造体の中の1フィールドと関連付けておく必要があります。この関連付けは、OCIDefineArrayOfStruct()コールおよびOCIBindArrayOfStruct()コールの一部であり、データの格納場所を指定します。

スキップ・パラメータ

構造体配列間で列データを分割すると、それはデータベース内では連続した列データとして格納されなくなります。単一の構造体配列は、いくつかのスカラー配列で構成されているかのようにデータを格納します。このため、バインドまたは定義を行う各フィールドにスキップ・パラメータを指定する必要があります。スキップ・パラメータは、構造体配列の中にある同じフィールドまでスキップするために必要なバイト数です。通常は、1つの構造体のバイト数と等しい値です。

図5-2は、スキップ・パラメータの決定方法を示しています。このケースでは、スキップ・パラメータは、field1 (2バイト)、field2 (4バイト)およびfield3 (2バイト)のサイズの合計8バイトです。このサイズは、1つの構造体のサイズと同じです。

図5-2 スキップ・パラメータの決定

オペレーティング・システムによっては、スキップ・パラメータをsizeof(struct)ではなく、sizeof(one_array_element)に設定することが必要な場合もあります。これは、コンパイラによっては、構造体に余分なバイトを挿入する場合があるからです。

ub4とub1という2つのフィールドで構成されたC構造体配列のケースを考えてみます。

struct demo {
ub4 field1;
ub1 field2;
};
struct demo demo_array[MAXSIZE];

コンパイラによっては、この配列内の次の構造体を開始するub4の位置を正しくするために、ub1の後に3バイトの埋込みを挿入することがあります。このようなコンパイラでは、次の文を使用すると、誤った値が戻される可能性があります。

skip_parameter = sizeof(struct demo);

一部のオペレーティング・システムでは、これで8バイトの適切なスキップ・パラメータが戻されます。その他のシステムでは、この文でskip_parameterが5に設定されます。後者の場合、スキップ・パラメータの正しい値を得るには次の文を使用します。

skip_parameter = sizeof(demo_array[0]);

標準配列のスキップ・パラメータ

構造体配列は、単一変数の配列をバインドおよび定義する機能を拡張したものです。単一変数の配列操作を指定する場合、関連したスキップ・パラメータは、その配列のデータ型のサイズと等しくなります。たとえば、配列を次のように宣言したとします。

text emp_names[4][20];

バインドまたは定義操作のスキップ・パラメータは20になります。配列の各データ要素は、構造体の一部としてでなく、別個の単位として認識されます。

構造体配列で使用されるOCIコール

構造体配列に関係する操作を行う際には、次の2つのOCIコールを使用する必要があります。

- OCIBindArrayOfStruct()は、入力変数の構造体配列でフィールドをバインドする場合に使用します。

- OCIDefineArrayOfStruct()は、出力変数の構造体配列を定義する場合に使用します。

注意:
構造体の配列のバインドまたは定義には、複数のコールが必要です。OCIBindByName()またはOCIBindByPos()へのコールはOCIBindArrayOfStruct()へのコールに先行し、OCIDefineByPos()へのコールはOCIDefineArrayOfStruct()に先行する必要があります。

構造体配列と標識変数

構造体配列を実装することによって、標識変数とリターン・コードの使用も可能になります。フェッチ、挿入または更新された情報の配列に対応して、列レベルの標識変数とリターン・コードのパラレル配列を宣言できます。これらの配列には、独自のスキップ・パラメータを含めることができ、スキップ・パラメータは、OCIBindArrayOfStruct()またはOCIDefineArrayOfStruct()コール中に指定します。

プログラム値および標識変数の構造配列を設定する方法は多数あります。データベースの3列のデータを、3つのフィールドを含む構造配列にフェッチするアプリケーションについて考えてみます。この場合、3つのフィールドの標識変数の構造に対応する配列を設定でき、データベースからフェッチされるいずれかの列に対してそれぞれが列レベルの標識変数になります。インジケータ構造体内のフィールドと選択リスト項目数の間に1対1関係が存在する必要はありません。

関連項目:
「標識変数」

複数バッファのバインドと定義

単一のバインドまたは定義コールで使用する複数のバッファを指定できます。様々な不連続アドレスに格納されているデータが1つの連続アドレスにコピーされることがないため、ラウンドトリップ数が減少し、パフォーマンスが向上します。これにより、CPU使用時間とメモリー使用量も減少します。

OCIIOVデータ型の定義は、次のとおりです。

typedef struct OCIIOV
{
void *bfp;  /* The pointer to a buffer for the data    */
ub4  bfl;   /* The size of the buffer                  */
}OCIIOV;

複数のバッファをバインドする場合、OCIBindByPos()およびOCIBindByName()関数でmodeパラメータに値OCI_IOVを使用します。modeにこの値を指定する場合は、パラメータvaluepでOCIIOVのアドレスを渡す必要があります。データ型のサイズは、パラメータvalueszで渡す必要があります。たとえば、次のようにします。

OCIIOV vecarr[NumBuffers];
...
/* For bind at position 1 with data type int     */
OCIBindByPos(stmthp, bindp, errhp, 1, (void *)&vecarr[0],
sizeof(int), ... OCI_IOV);
...

複数バッファを定義する場合、OCIDefineByPos()関数でmodeパラメータに値OCI_IOVを使用します。modeにこの値を指定する場合は、パラメータvaluepでOCIIOVのアドレスを渡します。データ型のサイズは、パラメータvalueszで渡す必要があります。

関連項目:

- 「OCIBindByName()」

- 「OCIBindByPos()」

- 「OCIDefineByPos()」

例5-17は、構造体OCIIOVとそのmode値の使用例です。

例5-17 複数のバインドおよび定義バッファの使用

/* The following macros mention the maximum length of the data in the
* different buffers. */

#define    LENGTH_DATE      10
#define    LENGTH_EMP_NAME  100

/* These two macros represent the number of elements in each bind and define
array */
#define  NUM_BIND     30
#define  NUM_DEFINE   45

/* The bind buffers for inserting dates */
char  buf_1[NUM_BIND][LENGTH_DATE],
char  buf_2[NUM_BIND * 2][LENGTH_DATE],

/* The bind buffer for inserting emp name */
char  buf_3[NUM_BIND * 3][LENGTH_EMP_NAME],

/* The define buffers */
char  buf_4[NUM_DEFINE][LENGTH_EMP_NAME];
char  buf_5[NUM_DEFINE][LENGTH_EMP_NAME];

/* The size of data value for buffers corresponding to the same column must be
the same, and that value is passed in the OCIBind or Define calls.
buf_4 and buf_5 above have the same data values; that is, LENGTH_EMP_NAME
although the  number of elements are different in the two buffers.

*/
OCIBind     *bndhp1 = (OCIBind   *)0;
OCIBind     *bndhp2 = (OCIBind   *)0;
OCIDefine   *defhp  = (OCIDefine *)0;
OCIStmt     *stmthp = (OCIStmt   *)0;
OCIError    *errhp  = (OCIError  *)0;

OCIIOV  bvec[2], dvec[2];

/*
Example of how to use indicators and return codes with this feature,
showing the allocation when using with define. You allocate memory
for indicator, return code, and the length buffer as one chunk of
NUM_DEFINE * 2 elements.
*/
short *indname[NUM_DEFINE*2];            /* indicators */
ub4   *alenname[NUM_DEFINE*2];           /* return lengths */
ub2   *rcodename[NUM_DEFINE*2];          /* return codes */

static text *insertstr  =
"INSERT INTO EMP (EMP_NAME, JOIN_DATE) VALUES (:1, :2)";
static text *selectstr  = "SELECT EMP_NAME FROM EMP";

/* Allocate environment, error handles, and so on, and then initialize the
environment.  */
...
/* Prepare the statement with the insert query in order to show the
binds. */
OCIStmtPrepare  (stmthp, errhp, insertstr,
(ub4)strlen((char *)insertstr),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);

/* Populate buffers with values. The following represents the simplest
* way of populating the buffers. However, in an actual scenario
* these buffers may have been populated by data received from different
* sources. */

/* Store the date in the bind buffers for the date. */
strcpy(buf_1[0], "21-SEP-02");
...
strcpy(buf_1[NUM_BIND - 1], "21-OCT-02");
...
strcpy(buf_2[0], "22-OCT-02");
...
strcpy(buf_2[2*NUM_BIND - 1], "21-DEC-02");
...
memset(bvec[0], 0, sizeof(OCIIOV));
memset(bvec[1], 0, sizeof(OCIIOV));

/* Set up the addresses in the IO Vector structure */
bvec[0].bfp = buf_1[0];                       /* Buffer address of the data */
bvec[0].bfl = NUM_BIND*LENGTH_DATE;           /* Size of the buffer */

/* And so on for other structures as well. */
bvec[1].bfp = buf_2[0];                       /* Buffer address of the data */
bvec[1].bfl = NUM_BIND*2*LENGTH_DATE;         /* Size of the buffer  */

/* Do the bind for date, using OCIIOV */
OCIBindByPos (stmthp, &bindhp2, errhp, 2, (void *)&bvec[0],
sizeof(buf_1[0]), SQLT_STR,
(void *)inddate, (ub2 *)alendate, (ub2 *)rcodedate, 0,
(ub4 *)0,  OCI_IOV);

/* Store the employee names in the bind buffers, 3 for the names */
strcpy (buf_3[0], "JOHN ");
...
strcpy (buf_3[NUM_BIND *3 - 1], "HARRY");

/* Do the bind for employee name */
OCIBindByPos  (stmthp,  &bindhp1, errhp, 1, buf_3[0], sizeof(buf_3[0]),
SQLT_STR, (void *)indemp, (ub2 *)alenemp, (ub2 *)rcodeemp, 0,
(ub4 *)0, OCI_DEFAULT);

OCIStmtExecute (svchp, stmthp, errhp, NUM_BIND*3, 0,
(OCISnapshot *)0, (OCISnapshot *)0, OCI_DEFAULT);

...
/* Now the statement to depict defines */
/* Prepare the statement with the select query in order to show the
defines */
OCIStmtPrepare(stmthp, errhp, selectstr,(ub4)strlen((char *)selectstr),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);

memset(dvec[0], 0, sizeof(OCIIOV);
memset(dvec[1], 0, sizeof(OCIIOV));

/* Set up the define vector */
dvec[0].bfp = buf_4[0];
dvec[0].bfl = NUM_DEFINE*LENGTH_EMP_NAME;

dvec[1].bfp = buf_5[0];
dvec[1].bfl = NUM_DEFINE*LENGTH_EMP_NAME;

/*
Pass the buffers for the indicator, length of the data, and the
return code.  Note that the buffer where you receive
the data is split into two locations,
each having NUM_DEFINE number of elements. However, the indicator
buffer, the actual length buffer, and the return code buffer comprise a
single chunk of NUM_DEFINE * 2 elements.
*/
OCIDefineByPos (stmthp, &defhp, errhp, 1, (void *)&dvec[0],
sizeof(buf_4[0]), SQLT_STR, (void *)indname,
(ub2 *)alenname, (ub2 *)rcodename, OCI_IOV);

OCIStmtExecute (svchp, stmthp, errhp, NUM_DEFINE*2, 0,
(OCISnapshot*)0,
(OCISnapshot*)0, OCI_DEFAULT);
...

OCIでのRETURNING句を使用したDML

OCIでは、SQL INSERT文、UPDATE文およびDELETE文でのRETURNING句の使用をサポートします。この項では、RETURNING句を使用してDML文を正しく実装するためのルールについて、その概要を説明します。

関連項目:

- 完全な例は、Oracleインストールに含まれているデータベース・デモ・プログラムを参照してください。詳細は、付録Bを参照してください。

- INSERT文、UPDATE文またはDELETE文でのRETURNING句の使用の詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

2つのSQL文を結合するためのDMLでのRETURNING の使用

DML文でRETURNING句を使用することにより、2つのSQL文を1つに結合でき、サーバー・ラウンドトリップを削減できます。これは、追加の句を従来のUPDATE文、INSERT文およびDELETE文に追加することで実行できます。追加の句では、問合せをDML文に効果的に追加します。

OCIでは、OUTバインド変数として値がアプリケーションに戻されます。次の例では、バインド変数の前にコロン":"が付いています。これらの例では、col1、col2およびcol3という列を含む表table1を想定しています。

次の文では、新しい値をデータベースに挿入して、影響を受ける行の列値をデータベースから取り出します。これにより、挿入された行を操作できます。

INSERT INTO table1 VALUES (:1, :2, :3)
RETURNING col1, col2, col3
INTO :out1, :out2, :out3

次の例は、col1の値がある範囲内にあるすべての列の値を更新し、変更による影響を受けた行を戻します。

UPDATE table1 SET col1 = col1 + :1, col2 = :2, col3 = :3
WHERE col1 >= :low AND col1 <= :high
RETURNING col1, col2, col3
INTO :out1, :out2, :out3

DELETE文では、col1の値が特定の範囲内にある行を削除し、それらの行からデータを戻します。

DELETE FROM table1 WHERE col1 >= :low AND col2 <= :high
RETURNING col1, col2, col3
INTO :out1, :out2, :out3

RETURNING...INTO変数のバインド

UPDATE文およびDELETE文は表内の複数行に影響し、DML文は1回のOCIStmtExecute()コールで複数回実行できるため、どれだけのデータが戻ってくるのかを実行時に判断できない場合があります。そのため、RETURNING...INTOプレースホルダに対応する変数は、OCI_DATA_AT_EXECモードでバインドする必要があります。アプリケーションでは、ポーリング・メカニズムを使用するのではなく、アプリケーション自体の動的データ処理コールバックを定義する必要があります。

RETURNING句は、LOBを操作するときに特に役立ちます。通常、アプリケーションでは、空のLOBロケータをデータベースに挿入し、再度選択して操作を行います。RETURNING句を使用することで、アプリケーションではこれら2つのステップを1つの文に結合できます。

INSERT INTO some_table VALUES (:in_locator)
RETURNING lob_column
INTO :out_locator

OCIアプリケーションは、RETURNING句のプレースホルダを純OUTバインド変数として実装します。ただし、RETURNING句のすべてのバインドの初期値はINであるため、適切に初期化する必要があります。有効な値を設定するために、NULLインジケータを使用して、そのインジケータを-1に設定できます。

アプリケーションでは、RETURNING句のバインド変数を操作するとき、次のルールに従う必要があります。

- OCIBindByName()またはOCIBindByPos()を使用して、OCI_DATA_AT_EXECモードでRETURNING句のプレースホルダをバインドした後で、各プレースホルダに対してOCIBindDynamic()をコールします。

- RETURNING句のプレースホルダをバインドする場合は、OCIBindDynamic()コールのocbfpパラメータとして、有効なOUTバインド関数を指定します。この関数では、戻されたデータを保持するための記憶域が必要です。

- OCIBindDynamic()コールのicbfpパラメータによって、コール時にNULL値を戻すデフォルトの関数を提供する必要があります。

- OCIBindDynamic()のpiecepパラメータを、OCI_ONE_PIECEに設定します。

RETURNING句を使用したDML文では、重複バインドは使用できず、文のDMLセクションのバインド変数と、RETURNINGセクションのバインド変数の間では重複は認められません。

注意:
OCIでは、RETURNING句バインドのコールバック・メカニズムのみがサポートされています。ポーリング・メカニズムはサポートされていません。

OCIエラー処理

OCIBindDynamic()に提供されたOUTバインド関数には、エラー時に文の結果の一部を受け取る準備が必要です。10回実行されるDML文をアプリケーションで発行し、5回目の実行中にエラーが発生した場合、Oracle Databaseは、1回目から4回目までのデータを戻します。コールバック関数は、最初の4回のデータを受け取るためにさらにコールされます。

OCIでのRETURNING REF...INTO句を使用したDML

RETURNING句を使用して、データベースに挿入するオブジェクトやデータベース内で更新するオブジェクトにREFを戻すこともできます。

UPDATE extaddr e SET e.zip = '12345', e.state ='AZ'
WHERE e.state = 'CA' AND e.zip = '95117'
RETURNING REF(e), zip
INTO :addref, :zip

前述の文では、オブジェクト表内のオブジェクトの属性をいくつか更新し、RETURNING句でオブジェクトへのREF (およびスカラーZIPコード)を戻します。

出力変数のバインド

OCIアプリケーションでREF出力変数をバインドするには、次の3つのステップが必要です。

1. 初期バインド情報を、OCIBindByName()を使用して設定します。

2. REF (型の記述オブジェクト(TDO)を含む)に対する追加のバインド情報は、OCIBindObject()を使用して設定します。

3. OCIBindDynamic()に対するコールを作成します。

例5-18の次の擬似コードは、前の3ステップに必要なバインドを実行する関数を示します。

例5-18 OCIアプリケーションでのREF出力変数のバインド

sword bind_output(stmthp, bndhp, errhp)
OCIStmt *stmthp;
OCIBind *bndhp[];
OCIError *errhp;
{
ub4 i;
/* get TDO for BindObject call */
if (OCITypeByName(envhp, errhp, svchp, (CONST text *) 0,
(ub4) 0, (CONST text *) "ADDRESS_OBJECT",
(ub4) strlen((CONST char *) "ADDRESS_OBJECT"),
(CONST text *) 0, (ub4) 0,
OCI_DURATION_SESSION, OCI_TYPEGET_HEADER, &addrtdo))
{
return OCI_ERROR;
}

/* initial bind call for both variables */
if (OCIBindByName(stmthp, &bndhp[2], errhp,
(text *) ":addref", (sb4) strlen((char *) ":addref"),
(void *) 0, (sb4) sizeof(OCIRef *), SQLT_REF,
(void *) 0, (ub2 *)0, (ub2 *)0,
(ub4) 0, (ub4 *) 0, (ub4) OCI_DATA_AT_EXEC)
||  OCIBindByName(stmthp, &bndhp[3], errhp,
(text *) ":zip", (sb4) strlen((char *) ":zip"),
(void *) 0, (sb4) MAXZIPLEN, SQLT_CHR,
(void *) 0, (ub2 *)0, (ub2 *)0,
(ub4) 0, (ub4 *) 0, (ub4) OCI_DATA_AT_EXEC))
{
return OCI_ERROR;
}

/* object bind for REF variable */
if (OCIBindObject(bndhp[2], errhp, (OCIType *) addrtdo,
(void **) &addrref[0], (ub4 *) 0, (void **) 0, (ub4 *) 0))
{
return OCI_ERROR;
}

for (i = 0; i < MAXCOLS; i++)
pos[i] = i;
/* dynamic binds for both RETURNING variables */
if (OCIBindDynamic(bndhp[2], errhp, (void *) &pos[0], cbf_no_data,
(void *) &pos[0], cbf_get_data)
||  OCIBindDynamic(bndhp[3], errhp, (void *) &pos[1], cbf_no_data,
(void *) &pos[1], cbf_get_data))
{
return OCI_ERROR;
}

return OCI_SUCCESS;
}

OCIコールバックに関するその他の注意

コールバック関数がコールされるとき、バインド・ハンドルのOCI_ATTR_ROWS_RETURNED属性により、アプリケーションでは、ある特定の反復処理で戻される行数がわかります。最初のコールバックの反復処理中に、そのバインド変数に対して戻されるすべての行に領域を割り当てることができます。同一の反復処理内で後続のコールバックを実行しているときは、割り当てられた領域内の正確なメモリーまでバッファ・ポインタを増やします。

OCIでのDML RETURNING文に対する配列インタフェース

OCIでは、各反復処理で複数の行を戻す単一行DML操作および配列DML操作に追加の機能性を提供します。この機能を利用するには、バインド・コールのOUTバッファを、OCIStmtExecute()コールで指定した反復件数以上の値に指定する必要があります。これは、コールバックを介してバインド・バッファに提供される追加機能です。

いずれかの反復処理で複数の行が戻された場合は、アプリケーションにOCI_SUCCESS_WITH_INFOリターン・コードが戻されます。この場合、DML操作は正常に完了しています。このとき、アプリケーションでは、トランザクションをロールバックするか、警告を無視します。

OCIバインドおよび定義における文字変換

この項では、クライアントとサーバー間での文字変換に関する問題について説明します。

キャラクタ・セットの選択

文字データを含むデータベースの列がNCHARまたはNVARCHAR2列として定義されている場合、その列に関連するバインドまたは定義では、キャラクタ・セット仕様の処理について特別な配慮が必要です。

クライアントとサーバーのキャラクタ・セットの幅が異なる場合、および適切に文字変換を行うために、これらの考慮が必要です。異なるキャラクタ・セット間でデータを変換する間に、データ・サイズが、4倍に増加したり4分の1に縮小する場合があります。データを保存するためのバッファのサイズを十分に確保してください。

アプリケーションでは、NCHARまたはNVARCHAR2データをバイト数(通常の場合)ではなく文字数で処理する方が簡単な場合があります。

キャラクタ・セット・フォームとキャラクタ・セットID

各OCIバインドおよび定義ハンドルには、OCI_ATTR_CHARSET_FORM属性およびOCI_ATTR_CHARSET_ID属性が関連付けられています。アプリケーションでは、バインドまたは定義バッファのキャラクタ・フォームおよびキャラクタ・セットIDを指定するために、OCIAttrSet()コールを使用してこれらの属性を設定できます。

csform属性(OCI_ATTR_CHARSET_FORM)は、バインドの場合はクライアント・バッファのキャラクタ・セットを示し、定義の場合はフェッチされたデータを格納するキャラクタ・セットを示します。この属性の値は、次のうちいずれかになります。

- SQLCS_IMPLICIT: デフォルト値で、バインド・バッファまたは定義バッファ用のデータベース・キャラクタ・セットIDを示し、文字バッファ・データはサーバーのデータベース・キャラクタ・セットに変換されます。

- SQLCS_NCHAR: バインド・バッファまたは定義バッファ用の各国語キャラクタ・セットIDを示し、クライアントのバッファ・データはサーバーの各国語キャラクタ・セットに変換されます。

キャラクタ・セットID属性OCI_ATTR_CHARSET_IDが指定されていない場合は、csformの値に応じて、クライアントのデータベース・キャラクタ・セットIDまたは各国語キャラクタ・セットIDのデフォルト値が使用されます。これらはそれぞれ、環境変数NLS_LANGまたはNLS_NCHARで指定された値です。

注意:

- クライアント側のキャラクタ・セットIDに関係なく、データはサーバーのデータベース・キャラクタ・セットIDまたは各国語キャラクタ・セットIDに従って変換され、データベースに挿入されます。

- OCI_ATTR_CHARSET_IDに0 (ゼロ)を設定することはできません。

- 定義ハンドル属性OCI_ATTR_CHARSET_FORMおよびOCI_ATTR_CHARSET_IDは、LOBタイプには影響しません。サーバーからフェッチされたLOBロケータは、元のcsformを保持します。これらの属性に基づく定義変換の一部として、CLOB/NCLOB変換は行われません。

関連項目:
NCHARデータの詳細は、『Oracle Databaseリファレンス』を参照してください。

CHARとNCHARの間の暗黙的な変換

データベース・キャラクタ・セットと各国語キャラクタ・セット間での暗黙的な変換の結果、OCIでは、CHARとNCHARの間でのクロスバインドおよびクロス定義に対するサポートが可能となりました。OCI_ATTR_CHARSET_FORM属性がSQLCS_NCHARに設定されている場合でも、OCIでは、データがCHAR列に挿入されると、データをデータベース・キャラクタ・セットに変換できます。

OCIでのクライアント・キャラクタ・セットの設定

クライアント・キャラクタ・セットは、OCIEnvNlsCreate()関数のcharsetパラメータおよびncharsetパラメータを使用して設定できます。両方のパラメータともOCI_UTF16IDを設定できます。charsetパラメータでは、メタデータおよびCHARデータのコーディングが制御されます。ncharsetパラメータでは、NCHARデータのコーディングが制御されます。OCINlsEnvironmentVariableGet()関数は、NLS_LANGのキャラクタ・セットおよびNLS_NCHARの各国語キャラクタ・セットを戻します。

例5-19は、これらの関数の使用例です(OCIには、UTF-16データのバインドと定義を容易にするために、utextと呼ばれるtypedefが用意されています)。

例5-19 OCIでのクライアント・キャラクタ・セットのOCI_UTF16IDへの設定

OCIEnv *envhp;
ub2 ncsid = 2; /* we8dec */
ub2 hdlcsid, hdlncsid;
OraText thename[20];
utext *selstmt = L"SELECT ename FROM emp"; /* UTF16 statement */
OCIStmt *stmthp;
OCIDefine *defhp;
OCIError *errhp;
OCIEnvNlsCreate(OCIEnv **envhp, ..., OCI_UTF16ID, ncsid);
...
OCIStmtPrepare(stmthp, ..., selstmt, ...); /* prepare UTF16 statement */
OCIDefineByPos(stmthp, defnp, ..., 1, thename, sizeof(thename), SQLT_CHR,...);
OCINlsEnvironmentVariableGet(&hdlcsid, (size_t)0, OCI_NLS_CHARSET_ID, (ub2)0,
(size_t*)NULL);
OCIAttrSet(defnp, ..., &hdlcsid, 0, OCI_ATTR_CHARSET_ID, errhp);
/* change charset ID to NLS_LANG setting*/
...

関連項目:

- 「OCIEnvNlsCreate()」

- 「OCINlsEnvironmentVariableGet()」

OCIでの変数のバインド

更新操作または挿入操作は、変数のバインドによって行われます。変数をバインドするときは、バインド・ハンドルのOCI_ATTR_MAXCHAR_SIZE属性およびOCI_ATTR_MAXDATA_SIZE属性を指定して、Oracle Databaseにデータを挿入するときに使用するバイト制約と文字制約を指定します。

これらの属性は、次のように定義します。

- OCI_ATTR_MAXDATA_SIZE属性により、サーバー側のバッファで許容される最大バイト数を設定します(詳細は、「OCI_ATTR_MAXDATA_SIZE属性の使用」を参照)。

- OCI_ATTR_MAXCHAR_SIZE属性により、サーバー側のバッファで許容される最大文字数を設定します(詳細は、「OCI_ATTR_MAXCHAR_SIZE属性の使用」を参照)。

OCI_ATTR_MAXDATA_SIZE属性の使用

すべてのバインド・ハンドルにはOCI_ATTR_MAXDATA_SIZE属性があり、キャラクタ・セットの変換後、クライアント側バインド・データを格納するためにサーバーに割り当てるバイト数が指定されます。

通常、アプリケーションでは、使用方法に応じて、OCI_ATTR_MAXDATA_SIZEに、列の最大サイズまたはPL/SQL変数のサイズを設定します。OCI_ATTR_MAXDATA_SIZEが変換後のデータを格納するのに十分でない場合、エラーが発生します。

IN/INOUTバインドの場合、OCI_ATTR_MAXDATA_SIZE属性を設定するには、バインド・バッファは、キャラクタ・セットの各文字のバイト数を乗算した文字数を保持できる大きさである必要があります。

OCI_ATTR_MAXCHAR_SIZEが100などの0 (ゼロ)以外の値に設定されている場合で、キャラクタ・セットの各文字が2バイトである場合は、割当て可能な最小サイズは200バイトになります。

次のシナリオで、OCI_ATTR_MAXDATA_SIZE属性のいくつかの使用方法を説明します。

- シナリオ1: CHAR (ソース・データ)から非CHAR (宛先列)への変換
データに対して暗黙的バインド変換が行われます。ソース・バッファ・サイズに、クライアント側とOracle Database側のキャラクタ・セット間の最悪の膨張率を乗算した値を、OCI_ATTR_MAXDATA_SIZEの値として設定することをお薦めします。

- シナリオ2: CHAR (ソース・データ)からCHAR (宛先列)または非CHAR (ソース・データ)からCHAR (宛先列)への変換
列のサイズを、OCI_ATTR_MAXDATA_SIZEの値として設定することをお薦めします。

- シナリオ3: CHAR (ソース・データ)からPL/SQL変数への変換
このケースでは、PL/SQL変数のサイズを、OCI_ATTR_MAXDATA_SIZEの値として設定することをお薦めします。

OCI_ATTR_MAXCHAR_SIZE属性の使用

OCI_ATTR_MAXCHAR_SIZEを使用すると、バイト数ではなく文字数でデータを処理できます。

バインドについては、OCI_ATTR_MAXCHAR_SIZE属性を使用して、Oracle Databaseに確保する文字数を設定し、バインド・データを格納します。

たとえば、OCI_ATTR_MAXDATA_SIZEが100に設定され、OCI_ATTR_MAXCHAR_SIZEが0 (ゼロ)に設定されている場合、Oracle Databaseでのデータの変換後に可能な最大サイズは100バイトです。ただし、OCI_ATTR_MAXDATA_SIZEが300に設定され、OCI_ATTR_MAXCHAR_SIZEが100などの0 (ゼロ)以外の値に設定されている場合で、キャラクタ・セットに2バイトまたは2文字がある場合は、割当て可能な最大サイズは200バイトになります。

定義については、クライアント・アプリケーションのバッファに戻すことができる最大文字数をOCI_ATTR_MAXCHAR_SIZE属性で指定します。導出されたバイト長は、OCIDefineByPos()コールで指定されたmaxlengthパラメータを上書きします。

注意:
バインド・コールまたは定義コールで指定されたバッファ長は、OCI_ATTR_MAXCHAR_SIZE属性の値に関係なく、常にバイト数による長さです。また、送受信する実際の長さもバイト数になります。

OCIバインド時のバッファの拡張

OUTバインドまたはPL/SQLバインドの場合は、OCI_ATTR_MAXDATA_SIZEを設定しないでください。OCI_ATTR_MAXDATA_SIZEは、INSERT文またはUPDATE文の場合のみ設定してください。

いずれの属性も設定されていない場合、OCIでは最適な見積りを行ってバッファを拡張します。

INバインド

INバインドの場合、基礎となる列が文字長セマンティクスを使用して作成されている場合は、OCI_ATTR_MAXCHAR_SIZEを使用して制約を指定することをお薦めします。実際のバッファに含まれる文字数がOCI_ATTR_MAXCHAR_SIZEで指定した文字数より少なければ、OCIレベルでの制約違反は発生しません。

基礎となる列がバイト長セマンティクスを使用して作成されている場合は、バインド・ハンドルのOCI_ATTR_MAXDATA_SIZEを使用して、サーバーでのバイト制約を指定します。OCI_ATTR_MAXCHAR_SIZEの値も指定している場合は、この制約がサーバー側の受信バッファの割当て時に適用されます。

動的SQL

動的SQLの場合は、パラメータ・ハンドルのOCI_ATTR_DATA_SIZEおよびOCI_ATTR_CHAR_SIZEを取得するための明示的な記述を、バインド・ハンドルのOCI_ATTR_MAXDATA_SIZE属性およびOCI_ATTR_MAXCHAR_SIZE属性を設定するためのガイドとして使用できます。OCI_ATTR_MAXDATA_SIZEおよびOCI_ATTR_MAXCHAR_SIZEを、実際の列幅より少ない値(バイト数または文字数)に設定することをお薦めします。

挿入時のバッファの拡張

OCI_ATTR_MAXDATA_SIZEを使用して、挿入時のバッファ拡張による予期しない動作の発生を回避します。

データベース列に文字長セマンティクスがあり、その列にユーザーがOCIBindByPos()またはOCIBindByName()を使用してデータの挿入を試み、OCI_ATTR_MAXCHAR_SIZEのみを3000バイトに設定したとします。データベース・キャラクタ・セットはUTF8で、クライアント・キャラクタ・セットはASCIIです。この場合、クライアント側ではサイズが3000バイトのバッファに3000文字が入りますが、サーバー側ではバッファが拡張されて4000バイトを超えることになります。基礎となる列がLONG型またはLOB型でないかぎり、サーバーでエラーが発生します。この問題を回避するには、OCI_ATTR_MAXDATA_SIZEを4000に指定して、Oracle Databaseが4000バイトを決して超えないことを保証します。

定義時の制約チェック

OCIでは、列からクライアント・バッファへのデータ選択に事前定義の変数が使用されます。OCI_ATTR_MAXCHAR_SIZE値を設定して、その定義バッファに対して文字長の追加の制約を適用できます。バイト単位のバッファ・サイズはバイト長の制限として機能するため、定義ハンドルに対するOCI_ATTR_MAXDATA_SIZE属性はありません。OCIDefineByPos()コールで指定された定義バッファのサイズをバイト制約として使用できます。

動的SQLでの選択

動的SQLのバッファ・サイズを指定するときは、切捨てによるデータの損失を回避するために、常に暗黙的な記述でOCI_ATTR_DATA_SIZE値を使用します。データベース列が文字長セマンティクスを使用して作成されている場合(OCI_ATTR_CHAR_USED属性によって判明します)は、OCI_ATTR_MAXCHAR_SIZE値を使用して、定義バッファに追加の制約を設定できます。OCI_ATTR_MAXCHAR_SIZE値の最大文字数がバッファに配置されます。

戻される長さ

次の長さの値は、データベースの文字長セマンティクスに関係なく、常にバイト単位で戻されます。

- alenで戻される値、つまり、バインドと定義での実際の長さフィールド

- VARCHARやLONG VARCHARなど、特殊なデータ型の前に付けられる長さの値

- 切捨てが発生した場合のための標識変数の値

この規則の唯一の例外は、OCI_UTF16IDキャラクタ・セットIDの文字列バッファで、戻される長さはUTF-16単位になります。

注意:
バインド・コールと定義コールのバッファ・サイズ、OCIStmtGetPieceInfo()とOCIStmtSetPieceInfo()のピース・サイズおよびコールバックは常にバイト単位になります。

OCIでの文字長セマンティクスの互換性に関する一般的な問題

- リリース8.1以下のOracle Databaseと通信するリリース9.0以上のクライアントの場合は、OCI_ATTR_MAXCHAR_SIZEはOracle Databaseでは認識されないため、この値は無視されます。この値のみを指定した場合、OCIでは、クライアント側キャラクタ・セットの各文字の最大バイト数に基づいて、対応するOCI_ATTR_MAXDATA_SIZE値が導出されます。

- リリース9.0以上のOracle Databaseと通信するリリース8.1以下のクライアントの場合は、クライアントでOCI_ATTR_MAXCHAR_SIZE値を指定できないため、Oracle Databaseではクライアントが常にバイト長セマンティクスを使用しているものとみなします。これは、クライアントでOCI_ATTR_MAXDATA_SIZEのみを指定した場合に類似しています。

いずれの場合も、Oracle Databaseとクライアントは適切な方法で情報を交換できます。

OCI_ATTR_MAXCHAR_SIZEを使用した挿入と選択のコード例

列がN個の文字を指定して作成されると、データベースでの実際の割当てでは、例5-20のような最悪のケース・シナリオが検討されます。割り当てられる実際のバイト数は、Nの倍数、つまりNのM倍です。現在、UTF8では各文字に割り当てられる最大バイト数として、Mが3に設定されています。

たとえば、例5-20では、EMP表で、ENAME列が30文字として定義され、ADDRESS列が80文字として定義されています。これに対応するデータベースでのバイト長はそれぞれ、M×30または3×30 = 90、およびM×80または3×80 = 240になります。

例5-20 OCI_ATTR_MAXCHAR_SIZE属性を使用した挿入および選択操作

...
utext ename[31], address[81];
/* E' <= 30+ 1, D' <= 80+ 1, considering null-termination */
sb4 ename_max_chars = EC=20, address_max_chars = ED=60;
/* EC <= (E' - 1), ED <= (D' - 1) */
sb4 ename_max_bytes = EB=80, address_max_bytes = DB=200;
/* EB <= M * EC, DB <= M * DC */
text *insstmt = (text *)"INSERT INTO EMP(ENAME, ADDRESS) VALUES (:ENAME, \
:ADDRESS)";
text *selstmt = (text *)"SELECT ENAME, ADDRESS FROM EMP";
...
/* Inserting Column Data */
OCIStmtPrepare(stmthp1, errhp, insstmt, (ub4)strlen((char *)insstmt),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
OCIBindByName(stmthp1, &bnd1p, errhp, (text *)":ENAME",
(sb4)strlen((char *)":ENAME"),
(void *)ename, sizeof(ename), SQLT_STR, (void *)&insname_ind,
(ub2 *)alenp, (ub2 *)rcodep, (ub4)maxarr_len, (ub4 *)curelep, OCI_DEFAULT);
/* either */
OCIAttrSet((void *)bnd1p, (ub4)OCI_HTYPE_BIND, (void *)&ename_max_bytes,
(ub4)0, (ub4)OCI_ATTR_MAXDATA_SIZE, errhp);
/* or */
OCIAttrSet((void *)bnd1p, (ub4)OCI_HTYPE_BIND, (void *)&ename_max_chars,
(ub4)0, (ub4)OCI_ATTR_MAXCHAR_SIZE, errhp);
...
/* Retrieving Column Data */
OCIStmtPrepare(stmthp2, errhp, selstmt, strlen((char *)selstmt),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
OCIDefineByPos(stmthp2, &dfn1p, errhp, (ub4)1, (void *)ename,
(sb4)sizeof (ename),
SQLT_STR, (void *)&selname_ind, (ub2 *)alenp, (ub2 *)rcodep,
(ub4)OCI_DEFAULT);
/* if not called, byte semantics is by default */
OCIAttrSet((void *)dfn1p, (ub4)OCI_HTYPE_DEFINE, (void *)&ename_max_chars,
(ub4)0,
(ub4)OCI_ATTR_MAXCHAR_SIZE, errhp);
...

UTF-16のバインドと定義のコード例

CHARまたはVARCHAR2のバインドおよび定義、またはNCHARまたはNVARCHAR2改良型ハンドルにおけるキャラクタ・セットIDは、すべてのデータがUTF-16 (Unicode)エンコーディングで渡されるものとして設定できます。UTF-16を指定するには、OCI_ATTR_CHARSET_ID = OCI_UTF16IDを設定します。

関連項目:
「バインド・ハンドル属性」

OCIには、UTF-16データのバインドと定義を容易にするため、utextと呼ばれるtypedefが用意されています。utextの内部表現は、16ビットの符号なし整数(ub2)です。wchar_tデータ型のコード体系がUTF-16に準拠しているオペレーティング・システムでは、キャスト演算子を使用してutextをwchar_tデータ型に容易に変換できます。

UTF-16データの場合でも、バインド・コールと定義コールでのバッファ・サイズはバイト単位とみなされます。utextデータ型は、入出力データのバッファとして使用してください。

例5-21では、UTF-16データのバインドと定義を説明する擬似コードを示しています。

例5-21 UTF-16データのバインドと定義

...
OCIStmt  *stmthp1, *stmthp2;
OCIDefine *dfn1p, *dfn2p;
OCIBind *bnd1p, *bnd2p;
text *insstmt=
(text *) "INSERT INTO EMP(ENAME, ADDRESS) VALUES (:ename, :address)"; \
text *selname =
(text *) "SELECT ENAME, ADDRESS FROM EMP";
utext ename[21];   /* Name -    UTF-16 */
utext address[51]; /* Address - UTF-16 */
ub2 csid = OCI_UTF16ID;
sb4 ename_col_len = 20;
sb4 address_col_len = 50;
...
/* Inserting UTF-16 data */
OCIStmtPrepare (stmthp1, errhp, insstmt, (ub4)strlen ((char *)insstmt),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
OCIBindByName (stmthp1, &bnd1p, errhp, (text*)":ENAME",
(sb4)strlen((char *)":ENAME"),
(void *) ename, sizeof(ename), SQLT_STR,
(void *)&insname_ind, (ub2 *) 0, (ub2 *) 0, (ub4) 0,
(ub4 *)0, OCI_DEFAULT);
OCIAttrSet ((void *) bnd1p, (ub4) OCI_HTYPE_BIND, (void *) &csid,
(ub4) 0, (ub4)OCI_ATTR_CHARSET_ID, errhp);
OCIAttrSet((void *) bnd1p, (ub4) OCI_HTYPE_BIND, (void *) &ename_col_len,
(ub4) 0, (ub4)OCI_ATTR_MAXDATA_SIZE, errhp);
...
/* Retrieving UTF-16 data */
OCIStmtPrepare (stmthp2, errhp, selname, strlen((char *) selname),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
OCIDefineByPos (stmthp2, &dfn1p, errhp, (ub4)1, (void *)ename,
(sb4)sizeof(ename), SQLT_STR,
(void *)0, (ub2 *)0, (ub2 *)0, (ub4)OCI_DEFAULT);
OCIAttrSet ((void *) dfn1p, (ub4) OCI_HTYPE_DEFINE, (void *) &csid,
(ub4) 0, (ub4)OCI_ATTR_CHARSET_ID, errhp);
...

OCIでのPL/SQL REF CURSORおよびNESTED TABLE

OCIには、PL/SQL REF CURSORおよびNESTED TABLEを、バインドおよび定義する機能があります。アプリケーションでは、これらの型の変数をハンドルおよび定義するために、文ハンドルを使用できます。次の例で、このPL/SQLブロックを考えてみます。

static const text *plsql_block = (text *)
"begin \
OPEN :cursor1 FOR SELECT employee_id, last_name, job_id, manager_id, \
salary, department_id \
FROM employees WHERE job_id=:job ORDER BY employee_id; \
OPEN :cursor2 FOR SELECT * FROM departments ORDER BY department_id;
end;";

アプリケーションは、OCIHandleAlloc()をコールして、バインドのための文ハンドルを割り当て、次のコード例で:cursor1がstm2pにバインドされるように、プレースホルダ:cursor1を文ハンドルにバインドします。

例5-22 プレースホルダ:cursor1を文ハンドルstm2pにREF CURSORとしてバインド

status = OCIStmtPrepare (stm1p, errhp, (text *) plsql_block,
strlen((char *)plsql_block), OCI_NTV_SYNTAX, OCI_DEFAULT);
...
status = OCIBindByName (stm1p, (OCIBind **) &bnd1p, errhp,
(text *)":cursor1", (sb4)strlen((char *)":cursor1"),
(void *)&stm2p, (sb4) 0,  SQLT_RSET, (void *)0,
(ub2 *)0, (ub2 *)0, (ub4)0, (ub4 *)0,   (ub4)OCI_DEFAULT);

例5-22のこのコードでは、stm1pはPL/SQLブロックの文ハンドルで、stm2pは、後のデータ検索のためのREF CURSORとしてバインドされる文ハンドルです。SQLT_RSETの値は、dtyパラメータに渡されます。

別の例として、次のコードを考えてみます。

static const text *nst_tab = (text *)
"SELECT last_name, CURSOR(SELECT department_name, location_id \
FROM  departments)  FROM employees WHERE last_name = 'FORD'";

2番目の位置がネストした表で、例5-23に示すように、OCIアプリケーションで文ハンドルとして定義できます。

例5-23 ネストした表(2番目の位置)を文ハンドルとして定義

status = OCIStmtPrepare (stm1p, errhp, (text *) nst_tab,
strlen((char *)nst_tab), OCI_NTV_SYNTAX, OCI_DEFAULT);
...
status = OCIDefineByPos (stm1p, (OCIDefine **) &dfn2p, errhp, (ub4)2,
(void *)&stm2p, (sb4)0, SQLT_RSET, (void *)0, (ub2 *)0,
(ub2 *)0, (ub4)OCI_DEFAULT);

実行後、行をstm2pにフェッチすると、有効な文ハンドルになります。

注意:
複数のREF CURSORを取り出した場合は、stm2pへのフェッチをいつ行うか注意する必要があります。1つ目をフェッチすると、そのデータを取り出すためにフェッチを実行できます。ただし、2番目のREF CURSORをstm2pにフェッチすると、最初のREF CURSORからのデータにはアクセスできなくなります。
OCIでは、スクロール・モードで実行されたPL/SQL REF CURSORはサポートしていません。

OCIでは、REF CURSORによってすでにフェッチされている行にスクロールして戻ることはできないため、スクロール可能REF CURSORはサポートされていません。

OCIでのランタイム・データ割当てとピース単位操作

OCIを使用して、データのピース単位の挿入、更新およびフェッチを実行できます。また、OCIを使用すると、バインド値の静的配列を提供するかわりに、配列の挿入または更新の際に動的にデータを提供できます。非常に大きな列を小さいサイズの一連のチャンクとして挿入または取得することにより、クライアント側のメモリー要件を最小限にできます。

個々のピースのサイズは、実行時にアプリケーションにより判断され、統一することもできます。

OCIのピース単位機能は、文字列やバイナリ・データの膨大なブロックで操作(CLOB、BLOB、LONG、RAW、LONG RAWなどのデータを格納するデータベース列に関係する操作など)を行う際に特に有効です。

最後のOCIStmtFetch2()コールがOCI_SUCCESSの値を戻すと、ピース単位フェッチが完了します。

ピース単位のフェッチおよび挿入では、操作を正常に完了するために必要なコールの順序を理解することが重要です。ピース単位挿入では、コールバックが使用されない場合、挿入するピースの数よりも1回多くOCIStmtExecute()をコールする必要があります。これは、最初のOCIStmtExecute()コールが、挿入される最初のピースが必要であることを示す値を戻すからです。結果として、n個のピースを挿入する場合は、OCIStmtExecute()を合計n+1回コールする必要があります。

同様に、ピース単位フェッチを実行するときは、フェッチするピースの数より1回多くOCIStmtFetch2()をコールする必要があります。

ピース単位操作に有効なデータ型

一部のデータ型のみが、ピース単位で操作できます。次のデータ型は、OCIアプリケーションでピース単位のフェッチ、挿入または更新を実行できます。

- VARCHAR2

- STRING

- LONG

- LONG RAW

- RAW

- CLOB

- BLOB

すべてのデータ型に対してこの機能を使用する別な方法として、配列の挿入または更新のためにデータを動的に提供する方法があります。ピース単位操作をサポートしないデータ型に対しては、コールバックで、そのコールバックのpiecepパラメータのOCI_ONE_PIECEを常に指定する必要があります。

ピース単位操作の種類

ピース単位操作は、次の2通りの方法で実行できます。

- ポーリング・パラダイムに基づいてピース単位操作を実行するには、OCIライブラリで提供されているコールを使用します。

- 必要な情報およびデータ・ブロックを提供するには、ユーザー定義のコールバック関数を使用します。

OCIBindByPos()コールまたはOCIBindByName()コールのmodeパラメータをOCI_DATA_AT_EXECに設定すると、OCIアプリケーションでは実行時にINSERTまたはUPDATEのためのデータが動的に提供されます。

同様に、OCIDefineByPos()コールのmodeパラメータをOCI_DYNAMIC_FETCHに設定した場合は、アプリケーションが、フェッチ時にデータを受け取るための割当てスペースを動的に提供することを示します。

どちらの場合でも、コールバック関数またはピース単位操作のいずれかの方法によって、INSERT、UPDATEまたはFETCH操作のランタイム情報を提供できます。コールバックを使用するときはコールバックを登録するために、追加のバインド・コールまたは定義コールが必要です。

次項以降では、挿入、更新およびフェッチのためのデータ割当てとピース単位操作について具体的に説明します。

注意:
ピース単位操作は、SQLブロックおよびPL/SQLブロックでも有効です。

実行時のINSERTまたはUPDATEデータの提供

OCIBindByPos()コールまたはOCIBindByName()コールでOCI_DATA_AT_EXECモードを指定すると、value_szパラメータによって、実行時に提供できるデータの合計サイズが定義されます。アプリケーションでは、実行時INデータ・バッファを、要求に応じて操作完了に必要な回数だけOCIライブラリにいつでも提供できるようにしておく必要があります。割り当てたバッファは、不要になった際にクライアント側で解放する必要があります。

ランタイム・データは、次の2つの方法のいずれかで提供されます。

- OCIBindDynamic()関数を使用したコールバックを定義でき、実行時にこれをコールすると、データのピースまたはデータ全体を戻します。

- コールバックを1つも定義していない場合は、SQL文を処理するOCIStmtExecute()コールは、OCI_NEED_DATAエラー・コードを戻します。次に、クライアント・アプリケーションは、使用されるバインドおよびピースを指定するOCIStmtSetPieceInfo()コールを使用して、IN/OUTデータ・バッファまたはピースを提供します。

ピース単位の挿入または更新の実行

OCI環境が初期化され、データベース接続およびセッションが確立すると、SQL文またはPL/SQL文を準備するコールと入力値をバインドするコールが実行され、ピース単位挿入が開始されます。ユーザー定義のコールバックではなく、標準のOCIコールを使用するピース単位操作では、OCIBindDynamic()をコールする必要はありません。

注意:
ピース単位操作の一部でない追加のバインド変数は、データ型に応じて、追加のバインド・コールが必要な場合があります。

文の準備およびバインドの次に、アプリケーションでOCIStmtExecute()、OCIStmtGetPieceInfo()およびOCIStmtSetPieceInfo()を連続してコールし、ピース単位操作を完了します。それぞれのOCIStmtExecute()コールは、次に実行する処理を決定する値を戻します。一般的には、アプリケーションで次のピースの挿入を指示する値を取り出し、そのピースをバッファに移してから挿入を行います。最後のピースを挿入すると操作は完了します。

挿入バッファは任意のサイズにでき、実行時に提供されることに注意してください。また、挿入する各ピースは、同じサイズである必要はありません。挿入するピースのサイズは、それぞれOCIStmtSetPieceInfo()コールで設定します。

注意:
すべての挿入で同じサイズのピースが使用され、挿入されるデータのサイズがそのピースのサイズで均等に割り切れない場合は、挿入される最後のピースは小さくなります。このことを考慮して、最後のOCIStmtSetPieceInfo()コールで小さいサイズを指定する必要があります。

その手順は図5-3で示すとおりで、図の次に各ステップを説明しています。

図5-3 ピース単位挿入の実行

1. OCI環境を初期化して必要なハンドルを割り当て、サーバーに接続してユーザーを認証し、OCIStmtPrepare2()を使用して文の要求を準備します。

2. OCIBindByName()またはOCIBindByPos()を使用して、プレースホルダをバインドします。使用するピースの実際のサイズを指定する必要はありませんが、実行時に提供できるデータの全体のサイズを指定します。

3. 初めてOCIStmtExecute()をコールします。ここではデータは挿入されず、アプリケーションにOCI_NEED_DATAエラー・コードが戻されます。その他の値が戻された場合は、エラーが発生しています。

4. OCIStmtGetPieceInfo()をコールし、挿入する必要があるピースの情報を取り出します。OCIStmtGetPieceInfo()のパラメータには、必要なピースが最初のピース(OCI_FIRST_PIECE)なのか、後続のピース(OCI_NEXT_PIECE)なのかを示す値を戻すポインタが含まれています。

5. アプリケーションは、挿入するデータのピースをバッファに移し、次のパラメータを使用してOCIStmtSetPieceInfo()をコールします。

- ピースへのポインタ

- ピースの長さへのポインタ

- これが最初のピース(OCI_FIRST_PIECE)、中間のピース(OCI_NEXT_PIECE)または最後のピース(OCI_LAST_PIECE)のいずれであるかを示す値

6. 再度、OCIStmtExecute()をコールします。ステップ5でOCI_LAST_PIECEが示され、OCIStmtExecute()がOCI_SUCCESSを戻した場合は、すべてのピースが正常に挿入されています。OCIStmtExecute()でOCI_NEED_DATAが戻された場合は、ステップ3に戻り、次の挿入を行います。OCIStmtExecute()がこれ以外の値を戻した場合は、エラーが発生しています。

最後のピースが正常に挿入されると、ピース単位操作は完了します。これは、最後の OCIStmtExecute()コールによるOCI_SUCCESS戻り値によって示されます。

ピース単位更新も同様の方法で実行します。ピース単位更新操作では、更新対象のデータが挿入バッファに移され、OCIStmtExecute()がコールされて更新が実行されます。

関連項目:
「OCIでのポーリング・モード操作」

PL/SQLでのピース単位操作

OCIアプリケーションでは、前に概説した方法と似た方法で、IN、OUTおよびIN/OUTバインド変数について、PL/SQLでのピース単位操作を実行できます。PL/SQL文のすべてのプレースホルダは、定義ではなくバインドされることに注意してください。OCIBindDynamic()のコールでは、OUTパラメータまたはIN/OUTパラメータについて、適切なコールバックを指定します。

PL/SQL索引付き表のバインドのサポート

PL/SQL索引付き表は、OCIを使用してPL/SQL無名ブロックにIN/OUTバインドとして渡すことができます。PL/SQL索引付き表をバインドする手順は、SQL文に対して配列バインドを実行する手順に非常によく似ています。OCIプログラムでは、OCIBindByName()またはOCIBindByPos()のいずれかを使用して、次のとおりに配列の場所を配列の他のメタデータにバインドする必要があります。C配列をPL/SQL索引付き表バインド変数にバインドするプロセスでは、バインド・コール時に次の情報を指定する必要があります。

- void *valuep (IN/OUT): クライアント・メモリーで配列の始まりを指定する場所のポインタ

- ub2 dty (IN): クライアントで表されている配列の要素のデータ型

- sb4 value_sz (IN): クライアントで表されている配列の各要素の最大サイズ(バイト単位)

- ub4 maxarr_len (IN): 配列で存続期間中に保持されるデータ型の最大要素数
静的バインド実行のために前もって配列全体を割り当てる場合、配列をmaxarr_len数の要素(それぞれのサイズがvalue_sz)を含むのに十分なサイズに設定する必要があります。この情報は、PL/SQLで表示されるように索引付き表に制約をかけるためにも使用されます。PL/SQLでは、指定したこの制限を越えて索引付き表を(読取りまたは書込みのいずれかのために)参照することはできません。

- ub4 *curelep (IN/OUT): 現在有効な配列内の要素の数(配列の最初から)のポインタ。
これは、最大配列長以下にする必要があります。この情報は、PL/SQLで表示されるように索引付き表に制約をかけるためにも使用されることに注意してください。INバインドの場合、PL/SQLは指定したこの制限を越えて索引付き表から読み取ることはできません。OUTバインドの場合、PL/SQLはこの制限を越えて索引付き表に書き込むことはできますが、maxarr_len制限を越えることはできません。

IN索引付き表バインドの場合、OCIStmtExecute()を実行する前に、ユーザーはその実行のために現在の配列長(*curelep)を設定する必要があります。さらに、ユーザーは、配列の要素ごとに、実際の長さとインジケータを規定どおりに設定することも必要です。

OUTバインドの場合、OCIでは配列の要素ごとに、現在の配列長(*curelep)と実際の長さ、インジケータおよびリターン・コードを規定どおりに戻す必要があります。

最高のパフォーマンスを得るには、配列を最大配列長が割り当てられたままにして、実際にやり取りされている要素の数に基づいて、実行と実行の間に現在の配列長を変更します。この方法だと、実行ごとに割当ての解除と再割当てを繰り返す必要はなく、その結果アプリケーション全体のパフォーマンスが向上します。

また、PL/SQL索引付き表に対するOCIのピース単位のコールを使用して、バインドすることもできます。この方法では、配列全体を前もって割り当てる必要はありません。OCIStmtSetPieceInfo()コールとOCIStmtGetPieceInfo()コールを使用すれば、個々の要素をピース単位で渡すこともできます。

関連項目:

- 「OCIBindByName()」

- 「OCIBindByPos()」

制限

PL/SQL索引付き表のOCIバインド・インタフェースでは、次のバインドがサポートされません。

- ADTまたはREFの配列

- LOB記述子、ROWID記述子、日時または時間隔記述子などの記述子型の配列

- PLSQLレコード型の配列

実行時のフェッチ情報の提供

modeパラメータにOCI_DYNAMIC_FETCHを設定してOCIDefineByPos()をコールすると、アプリケーションでは、フェッチ時のデータ・バッファに関する情報を指定できます。また、OCIDefineDynamic()をコールして、データ・バッファに関する情報を取得するために呼び出すコールバック関数を設定する必要がある場合があります。

ランタイム・データは、次の2つの方法のいずれかで提供されます。

- OCIDefineDynamic()関数を使用したコールバックを定義できます。実行時に提供されるデータの最大サイズは、value_szパラメータによって定義されます。クライアント・ライブラリで、フェッチ済データを戻すためのバッファが必要な場合は、このコールバックが呼び出され、ピースまたは全体のデータを戻すための実行時バッファが提供されます。

- コールバックが1つも定義されていない場合は、OCI_NEED_DATAエラー・コードが戻り、クライアント・アプリケーションでOCIStmtSetPieceInfo()を使用して、OUTデータ・バッファまたはピースを提供します。OCIStmtGetPieceInfo()コールにより、どの定義およびピースが含まれるかについての情報が提供されます。

ピース単位フェッチの実行

フェッチ・バッファは、任意のサイズにすることができます。また、フェッチする各ピースは、同じサイズである必要はありません。ただし、最後にフェッチするサイズは、残っている最後のピースに一致する必要があります。フェッチする各ピースのサイズは、OCIStmtSetPieceInfo()コールでそれぞれ設定します。そのプロセスは図5-4で示すとおりで、図の次に各ステップを説明しています。

図5-4 ピース単位フェッチの実行

1. OCI環境を初期化して必要なハンドルを割り当て、データベースに接続してユーザーを認証し、文を準備してからOCIStmtExecute()を使用して文を実行します。

2. modeをOCI_DYNAMIC_FETCHに設定し、OCIDefineByPos()を使用して出力変数を定義します。この時点では、使用するピースの実際のサイズを指定する必要はありませんが、実行時にフェッチするデータの全体のサイズを指定します。

3. 初めてOCIStmtFetch2()をコールします。データは取得されず、アプリケーションにOCI_NEED_DATAエラー・コードが戻されます。その他の値が戻された場合は、エラーが発生しています。

4. OCIStmtGetPieceInfo()をコールし、フェッチするピースに関する情報を取得します。piecepパラメータは、そのピースが最初のピース(OCI_FIRST_PIECE)であるか、その後続のピース(OCI_NEXT_PIECE)であるか、または最後のピース(OCI_LAST_PIECE)であるかを示します。

5. OCIStmtSetPieceInfo()をコールして、フェッチ・バッファを指定します。

6. 再度、 OCIStmtFetch2()をコールし、実際のピースを取り出します。OCIStmtFetch2()でOCI_SUCCESSが戻された場合は、すべてのピースが正常にフェッチされています。OCIStmtFetch2()でOCI_NEED_DATAが戻された場合は、ステップ4に戻って次のピースを処理します。その他の値が戻された場合は、エラーが起きています。

関連項目:
「OCIでのポーリング・モード操作」

LOBのピース単位のバインドおよび定義

LOBのピース単位のバインドおよび定義を実行するには、次の2つの方法があります。

- データ・インタフェースの使用
次の関数の入力データ型として、SQLT_CHR (VARCHAR2)またはSQLT_LNG (LONG)を使用して、CLOB列の文字データをバインドまたは定義できます。次の関数の入力データ型として、SQLT_LBI (LONG RAW)およびSQLT_BIN (RAW)を使用して、BLOB列の行データをバインドまたは定義することもできます。

- OCIDefineByPos()

- OCIBindByName()

- OCIBindByPos()

関連項目:

- INSERT文およびUPDATE文の使用方法および使用例は、「LOBデータのバインド」を参照してください。

- SELECT文の使用方法および使用例は、「LOBデータの定義」を参照してください。

次に説明するピース単位操作はすべて、この場合、CLOB列およびBLOB列に対してサポートされています。

- LOBロケータの使用
次の関数の入力データ型として、SQLT_CLOB (CLOB)またはSQLT_BLOB (BLOB)を使用して、CLOB列およびBLOB列のLOBロケータをバインドまたは定義できます。

- OCIDefineByPos()

- OCIBindByName()

- OCIBindByPos()

次に、OCILob*関数をコールし、データを読み取って操作する必要があります。OCILobRead2()およびOCILobWrite2()は、ピース単位モードおよびコールバック・モードをサポートしています。

関連項目:

- 「OCILobRead2()」

- 「OCILobWrite2()」

- OCILobWrite2()およびOCILobRead2()でコールバックを使用したストリームの詳細は、「LOB読取りおよび書込みコールバック」を参照してください。

6 スキーマ・メタデータの記述

この章では、OCIDescribeAny()関数を使用して、スキーマ要素に関する情報を取得する方法を説明します。

この章は、次の項目で構成されています。

- OCIDescribeAny()の使用

- パラメータ属性

- 記述操作での文字長セマンティクスのサポート

- OCIDescribeAny()の使用例

OCIDescribeAny()の使用

OCIDescribeAny()関数を使用すると、次のスキーマ・オブジェクトおよびそのサブスキーマ・オブジェクトを明示的に記述できます。

- 表とビュー

- シノニム

- プロシージャ

- 関数

- パッケージ

- 順序

- コレクション

- 型

- スキーマ

- データベース

他のスキーマ要素(ファンクションの引数、列、型属性および型メソッド)の情報は、前述のスキーマ・オブジェクトのいずれかの記述、あるいはサブスキーマ・オブジェクトの明示的な記述によって取得できます。

アプリケーションで表を記述する場合は、その表の列の情報も取り出すことができます。さらに、OCIDescribeAny()では、表の列、関数のパッケージ、型のフィールドなどのサブスキーマ・オブジェクトの名前が指定されている場合、それらのサブスキーマ・オブジェクトを直接記述できます。

OCIDescribeAny()コールには、引数の1つとして記述ハンドルが必要です。記述ハンドルは、OCIHandleAlloc()へのコールを使用して、事前に割り当ててください。

図6-1のように、OCIDescribeAny()で戻された情報は、ツリーのように階層的に編成されています。

図6-1 OCIDescribeAny()の表記述

OCIDescribeAny()によって戻される記述ハンドルには、このような記述ツリーを指し示す属性OCI_ATTR_PARAMがあります。ツリーの各ノードには、そのノードに関連する属性、および再帰的な記述ハンドルのように詳細情報を含むサブツリーを指し示す属性があります。列リストなどのリスト要素のように、すべての属性が同じ構造である場合、それらの属性をパラメータと呼びます。ノードに関連付けられた属性はOCIAttrGet()によって、パラメータはOCIParamGet()によって戻されます。

表の記述ハンドルについてのOCIAttrGet()に対するコールは、列リストの情報のハンドルを戻します。アプリケーションでは、OCIParamGet()を使用して、列リスト内の特定の列の列記述へのハンドルを取り出します。列記述子へのハンドルをOCIAttrGet()へ受け渡すことによって、名前やデータ型などの列に関する詳細を得ることができます。

SQL文を実行した後、文ハンドルの属性として選択リストに関する情報を取得できます。明示的な記述コールは必要ありません。アプリケーションで文ハンドルから選択リストに関する情報を取り出すには、選択リストの各位置に対してOCIParamGet()を1回ずつコールし、その位置のパラメータ記述子を割り当てる必要があります。

注意:
後続のOCIAttrGet()コールまたはOCIParamGet()コールでは、すべての記述がOCIDescribeAny()によってクライアント側のキャッシュに保存されているので、追加のネットワーク・ラウンドトリップは発生しません。

OCIDescribeAny()に関する制限

OCIDescribeAny()コールは基本情報に戻される情報を制限し、それが別の記述操作になる場合、ノードの拡張を停止します。たとえば、表の列がオブジェクト型である場合、OCIでは型を記述しているサブツリーを戻しませんが、これはその情報が別の記述によって取得できるからです。

OCIDescribeAny()によって、またはOCIStmtExecute()を暗黙的に使用することでは、表名は戻されません。列が表に関連付けられていないこともあります。ほとんどの場合、この表はすでに認識されています。

関連項目:

- 「選択リスト項目の記述」

- 「OCIDescribeAny()」

型および属性の注意

記述操作を行う際には、次のことを注意する必要があります。

データ型コード

OCI_ATTR_TYPECODEは、CREATE TYPE文を使用して新しい型が作成されたときに、ユーザーが指定した型を表す型コードを戻します。これらの型コードは、数え上げ可能な型のOCITypeCodeで、OCI_TYPECODE定数で表されます。内部PL/SQL型(ブール)はサポートされません。

OCI_ATTR_DATA_TYPEは、データベースの列に格納されるデータ型を表す型コードを戻します。これらは、Oracle Databaseの以前のバージョンで戻される記述値に似ています。これらの値は、SQLT定数(ub2値)で表されます。ブール型はSQLT_BOLを戻します。

関連項目:

- SQLT_BOLの詳細は、「外部データ型」を参照してください。

- 型コード(OCI_ATTR_TYPECODE属性に戻されるOCI_TYPECODE値、OCI_ATTR_DATA_TYPE属性に戻されるSQLT型コードなど)の詳細は、「型コード」を参照してください。

型の記述

型オブジェクトを記述するには、例6-1のように、OCIプロセスをオブジェクト・モードで初期化する必要があります。

例6-1 オブジェクト・モードでのOCIプロセスの初期化

/* Initialize the OCI Process */
if (OCIEnvCreate((OCIEnv **) &envhp, (ub4) OCI_OBJECT, (voivoid *) 0,
(void * (*)(void *,size_t)) 0,
(void * (*)(void *, void *, size_t)) 0,
(void (*)(void *, void *)) 0, (size_t) 0, (void **) 0))
{
printf("FAILED: OCIEnvCreate()\n");
return OCI_ERROR;
}

関連項目:
「OCIEnvCreate()」

暗黙的および明示的記述操作

OCIStmtExecute()による暗黙的記述およびOCIDescribeAny()による明示的記述を使用して、列属性OCI_ATTR_PRECISIONを戻すことができます。暗黙的記述を使用する場合は、精度をsb2に設定します。明示的記述を使用する場合は、精度をプレースホルダに対してub1に設定します。この設定は、ディクショナリ内の精度のデータ型と一致させるために必要です。

OCI_ATTR_LIST_ARGUMENTS属性

型メソッドのOCI_ATTR_LIST_ARGUMENTS属性は、そのメソッドの2次レベルの引数を表します。

たとえば、次のように、レコードmy_typeと、型my_typeの引数が指定されたプロシージャmy_procを指定するとします。

my_type record(a number, b char)
my_proc (my_input my_type)

この例では、OCI_ATTR_LIST_ARGUMENTS属性は、my_typeレコードの引数aとbに適用されます。

パラメータ属性

パラメータは、OCIParamGet()によって戻されます。パラメータは、複数の型のオブジェクトまたは情報を記述して、そこに含まれる記述の型に応じた属性または型固有の属性を持つことができます。この項では、複数のパラメータに属している属性およびハンドルについて説明します。

OCIDescribeAny()では、3つ以上の名前コンポーネント(たとえば、schema.type.attr1.attr2.method1)はサポートされません。コンポーネントが複数である場合、最初のコンポーネントはスキーマ名として解釈されます(他のフラグが設定されていない場合)。フラグの中には、オブジェクトがPUBLIC下で参照されるように指定する、つまり「a」を記述するものがあります(ここで、「a」はカレント・スキーマ内のオブジェクトまたはパブリック・シノニムのいずれか)。

オブジェクト型が何であるかわからない場合は、OCI_PTYPE_UNKを指定してください。そうでない場合、実際のオブジェクト型が指定した型と一致しない場合にはエラーが戻されます。

次の表6-1は、すべてのパラメータの属性のリストです。

表6-1 すべてのパラメータの属性

属性

説明

属性のデータ型

OCI_ATTR_OBJ_ID

オブジェクトIDまたはスキーマID。

ub4

OCI_ATTR_OBJ_NAME

スキーマ内のデータベース名またはオブジェクト名。

OraText *

OCI_ATTR_OBJ_SCHEMA

そのオブジェクトが存在しているスキーマの名前。

OraText *

OCI_ATTR_PTYPE

パラメータによって記述される情報の種類。可能な値は次のとおりです。

OCI_PTYPE_TABLE－ 表

OCI_PTYPE_VIEW－ ビュー

OCI_PTYPE_PROC－ プロシージャ

OCI_PTYPE_FUNC－ ファンクション

OCI_PTYPE_PKG－ パッケージ

OCI_PTYPE_TYPE－ 型

OCI_PTYPE_TYPE_ATTR－ 型の属性

OCI_PTYPE_TYPE_COLL－ コレクション型情報

OCI_PTYPE_TYPE_METHOD － 型のメソッド

OCI_PTYPE_SYN－ シノニム

OCI_PTYPE_SEQ－ 順序

OCI_PTYPE_COL－ 表またはビューの列

OCI_PTYPE_ARG－ ファンクションまたはプロシージャの引数

OCI_PTYPE_TYPE_ARG－ 型メソッドの引数

OCI_PTYPE_TYPE_RESULT － メソッドの結果

OCI_PTYPE_LIST－ 表およびビューの列のリスト、ファンクションおよびプロシージャの引数リスト、またはパッケージのサブプログラム・リスト

OCI_PTYPE_SCHEMA－ スキーマ

OCI_PTYPE_DATABASE－ データベース

OCI_PTYPE_UNK－ 不明なスキーマ・オブジェクト

ub1

OCI_ATTR_TIMESTAMP

Oracle日付書式がその記述の基礎となるオブジェクトのタイムスタンプ。

ub1 *

次の項では、様々なパラメータの型に特有の属性およびハンドルのリストを示します。

表またはビューのパラメータ

表6-2では、表またはビュー(OCI_PTYPE_TABLE型またはOCI_PTYPE_VIEW型)のパラメータの型に特有の属性を示しています。

表6-2 表またはビューの属性

属性

説明

属性のデータ型

OCI_ATTR_OBJID

オブジェクトID

ub4

OCI_ATTR_NUM_COLS

列の数。

ub2

OCI_ATTR_LIST_COLUMNS

列リスト(OCI_PTYPE_LIST型)。

OCIParam *

OCI_ATTR_REF_TDO

エクステント表の基本型の型記述オブジェクト(TDO)に対するREF

OCIRef *

OCI_ATTR_IS_TEMPORARY

表が一時表であることを示します。

ub1

OCI_ATTR_IS_TYPED

表に型が指定されていることを示します。

ub1

OCI_ATTR_DURATION

一時表の継続時間。可能な値は次のとおりです。

OCI_DURATION_SESSION－ セッション

OCI_DURATION_TRANS－ トランザクション

OCI_DURATION_NULL－ 非一時表

OCIDuration

表6-3では、表に属する追加属性を示しています。

表6-3 表に特有の属性

属性

説明

属性のデータ型

OCI_ATTR_RDBA

セグメント・ヘッダーのデータ・ブロック・アドレス。

ub4

OCI_ATTR_TABLESPACE

表が存在する表領域

word

OCI_ATTR_CLUSTERED

表がクラスタ化表であることを示します。

ub1

OCI_ATTR_PARTITIONED

表がパーティション表であることを示します。

ub1

OCI_ATTR_INDEX_ONLY

表が索引のみの表であることを示します。

ub1

プロシージャ、ファンクション、サブプログラム属性

表6-4では、プロシージャまたはファンクションのパラメータ(OCI_PTYPE_PROC型またはOCI_PTYPE_FUNC型)の場合の型に特有の属性を示しています。

表6-4 プロシージャまたはファンクションの属性

属性

説明

属性のデータ型

OCI_ATTR_LIST_ARGUMENTS

引数リスト。「リスト属性」を参照してください。

void *

OCI_ATTR_IS_INVOKER_RIGHTS

プロシージャまたはファンクションに実行者権限があることを示します。

ub1

表6-5では、パッケージ・サブプログラム用にのみ定義されている属性を示しています。

表6-5 パッケージ・サブプログラムに特有の属性

属性

説明

属性のデータ型

OCI_ATTR_NAME

プロシージャまたはファンクションの名前。

OraText *

OCI_ATTR_OVERLOAD_ID

ID番号のオーバーロード(プロシージャまたはファンクションがパッケージの一部で、オーバーロードされる場合)。戻される値が、PL/SQLファンクションまたはプロシージャの直接問合せとは異なる場合があります。

ub2

パッケージ属性

表6-6では、パッケージのパラメータ(OCI_PTYPE_PKG型)の場合の属性を示しています。

表6-6 パッケージの属性

属性

説明

属性のデータ型

OCI_ATTR_LIST_SUBPROGRAMS

サブプログラム・リスト。「リスト属性」を参照してください。

void *

OCI_ATTR_IS_INVOKER_RIGHTS

パッケージに実行者権限があることを示します。

ub1

型属性

表6-7では、型のパラメータ(OCI_PTYPE_TYPE型)の場合の属性を示しています。これらの属性は、OCIEnvCreate()のコールの際に、アプリケーションによってOCI_OBJECTモードでOCIプロセスが初期化された場合にのみ有効です。

表6-7 型の属性

属性

説明

属性のデータ型

OCI_ATTR_REF_TDO

列の型がオブジェクト型の場合は、その型の型記述子オブジェクト(TDO)のインメモリーREFを戻します。OCIRef用の領域が確保されていない場合は、領域がキャッシュ内に暗黙的に割り当てられます。次に、コール元はOCIObjectPin()を使用してTDOを確保できます。

OCIRef *

OCI_ATTR_TYPECODE

型コード。「データ型コード」を参照してください。現在は、OCI_TYPECODE_OBJECTまたはOCI_TYPECODE_NAMEDCOLLECTIONのみが使用できます。

OCITypeCode

OCI_ATTR_COLLECTION_TYPECODE

型がコレクションの場合はコレクションの型コードで、それ以外の場合は無効です。「データ型コード」を参照してください。現在は、OCI_TYPECODE_VARRAYまたはOCI_TYPECODE_TABLEのみが使用できます。この属性がコレクションでない型に対して問い合せられれば、エラーが発生します。

OCITypeCode

OCI_ATTR_IS_INCOMPLETE_TYPE

不完全な型であることを示します。

ub1

OCI_ATTR_IS_SYSTEM_TYPE

システム型であることを示します。

ub1

OCI_ATTR_IS_PREDEFINED_TYPE

事前定義済の型であることを示します。

ub1

OCI_ATTR_IS_TRANSIENT_TYPE

一時的な型であることを示します。

ub1

OCI_ATTR_IS_SYSTEM_GENERATED_TYPE

システム生成型であることを示します。

ub1

OCI_ATTR_HAS_NESTED_TABLE

ネストした表属性を含む型です。

ub1

OCI_ATTR_HAS_LOB

LOB属性を含む型です。

ub1

OCI_ATTR_HAS_FILE

BFILE属性を含む型です。

ub1

OCI_ATTR_COLLECTION_ELEMENT

コレクション要素へのハンドル。「コレクション属性」を参照してください。

void *

OCI_ATTR_NUM_TYPE_ATTRS

型属性の数。

ub2

OCI_ATTR_LIST_TYPE_ATTRS

型属性のリスト。「リスト属性」を参照してください。

void *

OCI_ATTR_NUM_TYPE_METHODS

型メソッドの数。

ub2

OCI_ATTR_LIST_TYPE_METHODS

型メソッドのリスト。「リスト属性」を参照してください。

void *

OCI_ATTR_MAP_METHOD

型のマップ・メソッド。「型メソッド属性」を参照してください。

void *

OCI_ATTR_ORDER_METHOD

型のオーダー・メソッド。「型メソッド属性」を参照してください。

void *

OCI_ATTR_IS_INVOKER_RIGHTS

型に実行者権限があることを示します。

ub1

OCI_ATTR_NAME

型属性名である文字列へのポインタ。

OraText *

OCI_ATTR_SCHEMA_NAME

型作成時のスキーマ名が付いた文字列。

OraText *

OCI_ATTR_IS_FINAL_TYPE

最後の型であることを示します。

ub1

OCI_ATTR_IS_INSTANTIABLE_TYPE

インスタンス化可能な型であることを示します。

ub1

OCI_ATTR_IS_SUBTYPE

サブタイプであることを示します。

ub1

OCI_ATTR_SUPERTYPE_SCHEMA_NAME

スーパータイプを含むスキーマの名前。

OraText *

OCI_ATTR_SUPERTYPE_NAME

スーパータイプの名前。

OraText *

型属性の属性

表6-8では、型の属性のパラメータ(OCI_PTYPE_TYPE_ATTR型)の場合の属性を示しています。

表6-8 型属性の属性

属性

説明

属性のデータ型

OCI_ATTR_DATA_SIZE

型属性の最大サイズ。この長さは、文字列と行について、文字ではなくバイト単位で戻されます。NUMBERについては22を戻します。

ub2

OCI_ATTR_TYPECODE

型コード。「データ型コード」を参照してください。

OCITypeCode

OCI_ATTR_DATA_TYPE

型属性のデータ型。「データ型コード」を参照してください。

ub2

OCI_ATTR_NAME

型属性名である文字列へのポインタ。

OraText *

OCI_ATTR_PRECISION

数値型属性の精度。精度が0 (ゼロ)以外でスケールが-127の場合はFLOATで、それ以外の場合はNUMBER(precision, scale)です。精度が0 (ゼロ)の場合は、NUMBER(precision, scale)を単にNUMBERと表すことができます。

ub1 for explicit describe
sb2 for implicit describe

OCI_ATTR_SCALE

数値型属性のスケール。精度が0 (ゼロ)以外でスケールが-127の場合はFLOATで、それ以外の場合はNUMBER(precision, scale)です。精度が0 (ゼロ)の場合は、NUMBER(precision, scale)を単にNUMBERと表すことができます。

sb1

OCI_ATTR_TYPE_NAME

型名である文字列。データ型がSQLT_NTYまたはSQLT_REFの場合は、戻される値に型名が含まれます。データ型がSQLT_NTYの場合は、名前付きデータ型の型名が戻されます。データ型がSQLT_REFの場合は、REFによって示されている名前付きデータ型の型名が戻されます。

OraText *

OCI_ATTR_SCHEMA_NAME

型作成時のスキーマ名が付いた文字列。

OraText *

OCI_ATTR_REF_TDO

列の型がオブジェクト型の場合は、その型のTDOのインメモリーREFを戻します。OCIRef用の領域が確保されていない場合は、領域がキャッシュ内に暗黙的に割り当てられます。次に、コール元はOCIObjectPin()を使用してTDOを確保できます。

OCIRef *

OCI_ATTR_CHARSET_ID

型属性が文字列また文字型の場合は、キャラクタ・セットID。

ub2

OCI_ATTR_CHARSET_FORM

型属性が文字列または文字型の場合は、キャラクタ・セット・フォーム。

ub1

OCI_ATTR_FSPRECISION

日時または時間隔の小数秒の精度。

ub1

OCI_ATTR_LFPRECISION

時間隔の先行フィールドの精度。

ub1

型メソッド属性

表6-9では、型のメソッドのパラメータ(OCI_PTYPE_TYPE_METHOD型)の場合の属性を示しています。

表6-9 型メソッドの属性

属性

説明

属性のデータ型

OCI_ATTR_NAME

メソッド名(プロシージャまたはファンクション)。

OraText *

OCI_ATTR_ENCAPSULATION

メソッドのカプセル化レベル(OCI_TYPEENCAP_PRIVATEまたはOCI_TYPEENCAP_PUBLICのいずれか)。

OCITypeEncap

OCI_ATTR_LIST_ARGUMENTS

引数リスト。「OCI_ATTR_LIST_ARGUMENTS属性」および「リスト属性」を参照してください。

void *

OCI_ATTR_IS_CONSTRUCTOR

メソッドがコンストラクタであることを示します。

ub1

OCI_ATTR_IS_DESTRUCTOR

メソッドがデストラクタであることを示します。

ub1

OCI_ATTR_IS_OPERATOR

メソッドが演算子であることを示します。

ub1

OCI_ATTR_IS_SELFISH

メソッドが自己参照的であることを示します。

ub1

OCI_ATTR_IS_MAP

メソッドがマップ・メソッドであることを示します。

ub1

OCI_ATTR_IS_ORDER

メソッドがオーダー・メソッドであることを示します。

ub1

OCI_ATTR_IS_RNDS

「Read No Data State」がメソッドに設定されていることを示します。

ub1

OCI_ATTR_IS_RNPS

「Read No Process State」がメソッドに設定されていることを示します。

ub1

OCI_ATTR_IS_WNDS

「Write No Data State」がメソッドに設定されていることを示します。

ub1

OCI_ATTR_IS_WNPS

「Write No Process State」がメソッドに設定されていることを示します。

ub1

OCI_ATTR_IS_FINAL_METHOD

最後のメソッドであることを示します。

ub1

OCI_ATTR_IS_INSTANTIABLE_METHOD

インスタンス化可能なメソッドであることを示します。

ub1

OCI_ATTR_IS_OVERRIDING_METHOD

オーバーライドするメソッドであることを示します。

ub1

コレクション属性

表6-10では、コレクション型のパラメータ(OCI_PTYPE_COLL型)の場合の属性を示しています。

表6-10 コレクション型の属性

属性

説明

属性のデータ型

OCI_ATTR_DATA_SIZE

型属性の最大サイズ。この長さは、文字列と行について、文字ではなくバイト単位で戻されます。NUMBERについては22を戻します。

ub2

OCI_ATTR_TYPECODE

型コード。「データ型コード」を参照してください。

OCITypeCode

OCI_ATTR_DATA_TYPE

型属性のデータ型。「データ型コード」を参照してください。

ub2

OCI_ATTR_NUM_ELEMS

配列の要素の数。コレクションが配列である場合にのみ有効です。

ub4

OCI_ATTR_NAME

型属性名である文字列へのポインタ。

OraText *

OCI_ATTR_PRECISION

数値型属性の精度。精度が0 (ゼロ)以外でスケールが-127の場合はFLOATで、それ以外の場合はNUMBER(precision, scale)です。精度が0 (ゼロ)の場合は、NUMBER(precision, scale)を単にNUMBERと表すことができます。

ub1 for explicit describe
sb2 for implicit describe

OCI_ATTR_SCALE

数値型属性のスケール。精度が0 (ゼロ)以外でスケールが-127の場合はFLOATで、それ以外の場合はNUMBER(precision, scale)です。精度が0 (ゼロ)の場合は、NUMBER(precision, scale)を単にNUMBERと表すことができます。

sb1

OCI_ATTR_TYPE_NAME

型名である文字列。データ型がSQLT_NTYまたはSQLT_REFの場合は、戻される値に型名が含まれます。データ型がSQLT_NTYの場合は、名前付きデータ型の型名が戻されます。データ型がSQLT_REFの場合は、REFによって示されている名前付きデータ型の型名が戻されます。

OraText *

OCI_ATTR_SCHEMA_NAME

型作成時のスキーマ名が付いた文字列。

OraText *

OCI_ATTR_REF_TDO

列の型がオブジェクト型の場合は、その型の型記述子オブジェクト(TDO)のインメモリーREFを戻します。OCIRef用の領域が確保されていない場合は、領域がキャッシュ内に暗黙的に割り当てられます。次に、コール元はOCIObjectPin()を使用してTDOを確保できます。

OCIRef *

OCI_ATTR_CHARSET_ID

型属性が文字列また文字型の場合は、キャラクタ・セットID。

ub2

OCI_ATTR_CHARSET_FORM

型属性が文字列または文字型の場合は、キャラクタ・セット・フォーム。

ub1

シノニム属性

表6-11では、シノニムのパラメータ(OCI_PTYPE_SYN型)の場合の属性を示しています。

表6-11 シノニムの属性

属性

説明

属性のデータ型

OCI_ATTR_OBJID

オブジェクトID

ub4

OCI_ATTR_SCHEMA_NAME

シノニム翻訳のスキーマ名を含む文字列。

OraText *

OCI_ATTR_NAME

シノニム翻訳のオブジェクト名を含む、NULLで終了する文字列。

OraText *

OCI_ATTR_LINK

シノニム翻訳のデータベース・リンク名を含む、NULLで終了する文字列。

OraText *

順序属性

表6-12では、順序のパラメータ(OCI_PTYPE_SEQ型)の場合の属性を示しています。

表6-12 順序の属性

属性

説明

属性のデータ型

OCI_ATTR_OBJID

オブジェクトID

ub4

OCI_ATTR_MIN

最小値(Oracle NUMBER書式)。

ub1 *

OCI_ATTR_MAX

最大値(Oracle NUMBER書式)。

ub1 *

OCI_ATTR_INCR

増分(Oracle NUMBER書式)。

ub1 *

OCI_ATTR_CACHE

キャッシュされた順序番号の数。順序がキャッシュされた順序でない場合は、0 (ゼロ)です(Oracle NUMBER書式)。

ub1 *

OCI_ATTR_ORDER

順序が順序指定されているかどうか。

ub1

OCI_ATTR_HW_MARK

最高水位標(NUMBER書式)。

ub1 *

関連項目:
「OCINumberの例」

列属性

注意:
BINARY_FLOATおよびBINARY_DOUBLEの場合:
OCIDescribeAny()を使用して、表のBINARY_FLOAT列またはBINARY_DOUBLE列の列データ型(OCI_ATTR_DATA_TYPE)を取り出す場合は、内部データ型コードが戻されます。

BINARY_FLOATおよびBINARY_DOUBLEの内部データ型コードに対応するSQLTコードは、SQLT_IBFLOATおよびSQLT_IBDOUBLEです。

表6-13では、表またはビューの列のパラメータ(OCI_PTYPE_COL型)の場合の属性を示しています。

表6-13 表またはビューの列の属性

属性

説明

属性のデータ型

OCI_ATTR_CHAR_USED

列の長さセマンティクスの型を戻します。0 (ゼロ)はバイト長セマンティクスを示し、1は文字長セマンティクスを示します。「記述操作での文字長セマンティクスのサポート」を参照してください。

ub1

OCI_ATTR_CHAR_SIZE

列の文字長、つまり列内で使用可能な文字数を戻します。これはOCI_ATTR_DATA_SIZEに相当するもので、バイト長で使用します。「記述操作での文字長セマンティクスのサポート」を参照してください。

ub2

OCI_ATTR_DATA_SIZE

列の最大サイズ。この長さは、文字列と行について、文字ではなくバイト単位で戻されます。NUMBERについては22を戻します。

ub2

OCI_ATTR_DATA_TYPE

列のデータ型。「データ型コード」を参照してください。

ub2

OCI_ATTR_NAME

列名である文字列へのポインタ。

OraText *

OCI_ATTR_PRECISION

数値列の精度。精度が0 (ゼロ)以外でスケールが-127の場合はFLOATで、それ以外の場合はNUMBER(precision, scale)です。精度が0 (ゼロ)の場合は、NUMBER(precision, scale)を単にNUMBERと表すことができます。

ub1 for explicit describe
sb2 for implicit describe

OCI_ATTR_SCALE

数値列のスケール。精度が0 (ゼロ)以外でスケールが-127の場合はFLOATで、それ以外の場合はNUMBER(precision, scale)です。精度が0 (ゼロ)の場合は、NUMBER(precision, scale)を単にNUMBERと表すことができます。

sb1

OCI_ATTR_IS_NULL

列にNULL値が許可されていない場合に、0 (ゼロ)を戻します。CUBEまたはROLLUP操作に対する正しい値を戻しません。

ub1

OCI_ATTR_TYPE_NAME

型名である文字列を戻します。データ型がSQLT_NTYまたはSQLT_REFの場合は、戻される値に型名が含まれます。データ型がSQLT_NTYの場合は、名前付きデータ型の型名が戻されます。データ型がSQLT_REFの場合は、REFによって示されている名前付きデータ型の型名が戻されます。

OraText *

OCI_ATTR_SCHEMA_NAME

型の作成時に使用したスキーマ名を持つ文字列を戻します。

OraText *

OCI_ATTR_REF_TDO

列の型がオブジェクト型の場合は、その型のTDOのREF。

OCIRef *

OCI_ATTR_CHARSET_ID

列が文字列または文字型の場合は、キャラクタ・セットID。

ub2

OCI_ATTR_CHARSET_FORM

列が文字列または文字型の場合は、キャラクタ・セット・フォーム。

ub1

引数および結果の属性

表6-14では、プロシージャやファンクションの引数のパラメータ(OCI_PTYPE_ARG型)、型メソッド引数のパラメータ(OCI_PTYPE_TYPE_ARG型)またはメソッド結果のパラメータ(OCI_PTYPE_TYPE_RESULT型)の場合の属性を示しています。

表6-14 引数および結果の属性

属性

説明

属性のデータ型

OCI_ATTR_NAME

引数名である文字列へのポインタを戻します。

OraText *

OCI_ATTR_POSITION

引数リストの引数の位置。常に0 (ゼロ)を戻します。

ub2

OCI_ATTR_TYPECODE

型コード。「データ型コード」を参照してください。

OCITypeCode

OCI_ATTR_DATA_TYPE

引数のデータ型。「データ型コード」を参照してください。

ub2

OCI_ATTR_DATA_SIZE

引数のデータ型のサイズ。この長さは、文字列と行について、文字ではなくバイト単位で戻されます。NUMBERについては22を戻します。

ub2

OCI_ATTR_PRECISION

数値引数の精度。精度が0 (ゼロ)以外でスケールが-127の場合はFLOATで、それ以外の場合はNUMBER(precision, scale)です。精度が0 (ゼロ)の場合は、NUMBER(precision, scale)を単にNUMBERと表すことができます。

明示的記述の場合はb1

暗黙的記述の場合はsb2

OCI_ATTR_SCALE

数値引数のスケール。精度が0 (ゼロ)以外でスケールが-127の場合はFLOATで、それ以外の場合はNUMBER(precision, scale)です。精度が0 (ゼロ)の場合は、NUMBER(precision, scale)を単にNUMBERと表すことができます。

sb1

OCI_ATTR_LEVEL

データ型のレベル。この属性は常に0 (ゼロ)を戻します。

ub2

OCI_ATTR_HAS_DEFAULT

引数にデフォルト値があるかどうかを示します。

ub1

OCI_ATTR_LIST_ARGUMENTS

次のレベルの引数のリスト(引数がレコード型または表型のとき)。

void *

OCI_ATTR_IOMODE

次の引数モードを示します。

0はIN (OCI_TYPEPARAM_IN)

1はOUT (OCI_TYPEPARAM_OUT)

2はIN/OUT (OCI_TYPEPARAM_INOUT)

OCITypeParamMode

OCI_ATTR_RADIX

基数を戻します(数値型の場合)。

ub1

OCI_ATTR_IS_NULL

列にNULL値が許可されていない場合に、0 (ゼロ)を戻します。

ub1

OCI_ATTR_TYPE_NAME

パッケージのローカル型の場合は、型名またはパッケージ名の文字列を戻します。データ型がSQLT_NTYまたはSQLT_REFの場合は、戻される値に型名が含まれます。データ型がSQLT_NTYの場合は、名前付きデータ型の型名が戻されます。データ型がSQLT_REFの場合は、REFによって示されている名前付きデータ型の型名が戻されます。

OraText *

OCI_ATTR_SCHEMA_NAME

SQLT_NTYまたはSQLT_REFについては、型の作成時、またはパッケージ・ローカル型用のパッケージの作成時に使用したスキーマ名を持つ文字列を戻します。

OraText *

OCI_ATTR_SUB_NAME

SQLT_NTYまたはSQLT_REFの場合、パッケージ・ローカル型にはタイプ名を持つ文字列を戻します。

OraText *

OCI_ATTR_LINK

SQLT_NTYまたはSQLT_REFについては、型が存在しているデータベースのデータベース・リンク名を持つ文字列を戻します。これは、パッケージがリモートで、そのパッケージがローカル型の場合にのみ発生します。

OraText *

OCI_ATTR_REF_TDO

引数型がオブジェクトの場合は、その型の型記述子オブジェクト(TDO)のREFを戻します。

OCIRef *

OCI_ATTR_CHARSET_ID

引数が文字列または文字型の場合は、キャラクタ・セットIDを戻します。

ub2

OCI_ATTR_CHARSET_FORM

引数が文字列または文字型の場合は、キャラクタ・セット・フォームを戻します。

ub1

リスト属性

列、引数またはサブプログラムのリストのパラメータ(OCI_PTYPE_LIST型)の場合、 表6-15に示すような型に特有の属性およびハンドル(パラメータ)があります。

リストには、リスト型を指定するOCI_ATTR_LTYPE属性があります。表6-15では、リストの横断時に予想される値とその下限を示しています。

表6-15 リスト属性

リスト属性

説明

下限

OCI_LTYPE_COLUMN

列リスト。

1

OCI_LTYPE_ARG_PROC

プロシージャ引数リスト。

1

OCI_LTYPE_ARG_FUNC

ファンクション引数リスト。

0

OCI_LTYPE_SUBPRG

サブプログラム・リスト。

0

OCI_LTYPE_TYPE_ATTR

型属性リスト。

1

OCI_LTYPE_TYPE_METHOD

型メソッド・リスト。

1

OCI_LTYPE_TYPE_ARG_PROC

結果引数なしの型メソッド・リスト。

0

OCI_LTYPE_TYPE_ARG_FUNC

結果引数なしの型メソッド・リスト。

1

OCI_LTYPE_SCH_OBJ

スキーマ内のオブジェクト・リスト。

0

OCI_LTYPE_DB_SCH

データベース内のスキーマ・リスト。

0

リストには、リスト内の要素数を調べるOCI_ATTR_NUM_PARAMS属性があります。

各リストには、LowerBound ... OCI_ATTR_NUM_PARAMSパラメータがあります。LowerBoundは、表6-15の「下限」列の値です。ファンクション引数リストの場合、位置0には、戻り値(OCI_PTYPE_ARG型)のパラメータがあります。

スキーマ属性

表6-16では、スキーマ型のパラメータ(OCI_PTYPE_SCHEMA型)の場合の属性を示しています。

表6-16 スキーマ固有の属性

属性

説明

属性のデータ型

OCI_ATTR_LIST_OBJECTS

スキーマ内のオブジェクトのリスト。

OCIParam *

データベース属性

表6-17では、データ型のパラメータ(OCI_PTYPE_DATABASE型)の場合の属性を示しています。

表6-17 データベース固有の属性

属性

説明

属性のデータ型

OCI_ATTR_VERSION

データベースのバージョン。

OraText *

OCI_ATTR_CHARSET_ID

サーバー・ハンドルからのデータベース・キャラクタ・セットID。

ub2

OCI_ATTR_NCHARSET_ID

サーバー・ハンドルからのデータベース各国語キャラクタ・セットID。

ub2

OCI_ATTR_LIST_SCHEMAS

データベース内のスキーマのリスト(OCI_PTYPE_SCHEMA型)。

ub1

OCI_ATTR_MAX_PROC_LEN

プロシージャ名の最大長。

ub4

OCI_ATTR_MAX_COLUMN_LEN

列名の最大長。

ub4

OCI_ATTR_CURSOR_COMMIT_BEHAVIOR

COMMIT操作によりデータベース内のカーソルおよびプリペアド文が受ける影響。値は次のとおりです。

OCI_CURSOR_OPEN: カーソルの状態をCOMMIT操作の前の状態に保持します。

OCI_CURSOR_CLOSED: カーソルは、COMMITでにクローズされますが、アプリケーションでは、文を再度プリコンパイルせずに再実行できます。

ub1

OCI_ATTR_MAX_CATALOG_NAMELEN

カタログ(データベース)名の最大長。

ub1

OCI_ATTR_CATALOG_LOCATION

修飾表内のカタログの位置。値はOCI_CL_STARTおよびOCI_CL_ENDです。

ub1

OCI_ATTR_SAVEPOINT_SUPPORT

データベースがセーブポイントをサポートするかどうか。値はOCI_SP_SUPPORTEDおよびOCI_SP_UNSUPPORTEDです。

ub1

OCI_ATTR_NOWAIT_SUPPORT

データベースがNOWAIT句をサポートするかどうか。値はOCI_NW_SUPPORTEDおよびOCI_NW_UNSUPPORTEDです。

ub1

OCI_ATTR_AUTOCOMMIT_DDL

DDL文で自動コミット・モードが必要かどうか。値はOCI_AC_DDLおよびOCI_NO_AC_DDLです。

ub1

OCI_ATTR_LOCKING_MODE

データベースのロック・モード。値はOCI_LOCK_IMMEDIATEおよびOCI_LOCK_DELAYEDです。

ub1

ルール属性

表6-18では、ルールのパラメータ(OCI_PTYPE_RULE型)の場合の属性を示しています。

表6-18 ルールに特有の属性

属性

説明

属性のデータ型

OCI_ATTR_CONDITION

ルール条件。

OraText *

OCI_ATTR_EVAL_CONTEXT_OWNER

ルールに関連する評価コンテキストの所有者名(ある場合)。

OraText *

OCI_ATTR_EVAL_CONTEXT_NAME

ルールに関連する評価コンテキストのオブジェクト名(ある場合)。

OraText *

OCI_ATTR_COMMENT

ルールに関連するコメント(ある場合)。

OraText *

OCI_ATTR_LIST_ACTION_CONTEXT

処理コンテキストの名前/値ペアのリスト(OCI_PTYPE_LIST型)。

void *

ルール・セット属性

表6-19では、ルール・セットのパラメータ(OCI_PTYPE_RULE_SET型)の場合の属性を示しています。

表6-19 ルール・セットに特有の属性

属性

説明

属性のデータ型

OCI_ATTR_EVAL_CONTEXT_OWNER

ルール・セットに関連する評価コンテキストの所有者名(ある場合)。

OraText *

OCI_ATTR_EVAL_CONTEXT_NAME

ルール・セットに関連する評価コンテキストのオブジェクト名(ある場合)。

OraText *

OCI_ATTR_COMMENT

ルール・セットに関連するコメント(ある場合)。

OraText *

OCI_ATTR_LIST_RULES

ルール・セットのルールのリスト(OCI_PTYPE_LIST型)。

void *

評価コンテキスト属性

表6-20では、評価コンテキストのパラメータ(OCI_PTYPE_EVALUATION_CONTEXT型)の場合の属性を示しています。

表6-20 評価コンテキストに特有の属性

属性

説明

属性のデータ型

OCI_ATTR_EVALUATION_FUNCTION

評価コンテキストに関連する評価ファンクション(ある場合)。

OraText *

OCI_ATTR_COMMENT

評価コンテキストに関連するコメント(ある場合)。

OraText *

OCI_ATTR_LIST_TABLE_ALIASES

評価コンテキストの表別名のリスト(OCI_PTYPE_LIST型)。

void *

OCI_ATTR_LIST_VARIABLE_TYPES

評価コンテキストの変数型のリスト(OCI_PTYPE_LIST型)。

void *

表別名の属性

表6-21では、表別名のパラメータ(OCI_PTYPE_TABLE_ALIAS型)の場合の属性を示しています。

表6-21 表別名に特有の属性

属性

説明

属性のデータ型

OCI_ATTR_NAME

表別名。

OraText *

OCI_ATTR_TABLE_NAME

別名に関連する表名。

OraText *

変数型の属性

表6-22では、変数のパラメータ(OCI_PTYPE_VARIABLE_TYPE型)の場合の属性を示しています。

表6-22 変数型に特有の属性

属性

説明

属性のデータ型

OCI_ATTR_NAME

変数名。

OraText *

OCI_ATTR_TYPE

変数型。

OraText *

OCI_ATTR_VAR_VALUE_FUNCTION

変数に関連する変数値ファンクション(ある場合)。

OraText *

OCI_ATTR_VAR_METHOD_FUNCTION

変数に関連する変数メソッド・ファンクション(ある場合)。

OraText *

名前/値の属性

表6-23では、名前/値ペアのパラメータ(OCI_PTYPE_NAME_VALUE型)の場合の属性を示しています。

表6-23 名前/値ペアに特有の属性

属性

説明

属性のデータ型

OCI_ATTR_NAME

名前。

OraText *

OCI_ATTR_VALUE

値

OCIAnyData*

記述操作での文字長セマンティクスのサポート

Oracle9i以上での問合せ情報と列情報は、文字長セマンティクスでサポートされます。

記述ハンドルの次の属性は、文字長セマンティクスをサポートします。

- OCI_ATTR_CHAR_SIZEは、列の文字長、つまり、列内で使用可能な文字数を示します。これはOCI_ATTR_DATA_SIZEに相当するもので、バイト長で使用します。

- ストアド・プロシージャ・パラメータがバインドされていないため、属性OCI_ATTR_CHAR_SIZEまたはOCI_ATTR_DATA_SIZEを使用してOCIAttrGet()をコールすると、ストアド・プロシージャ・パラメータのデータは戻されません。

- OCI_ATTR_CHAR_USEDでは、列の長さセマンティクスの型を取得します。0 (ゼロ)はバイト長セマンティクスを示し、1は文字長セマンティクスを示します。

アプリケーションでは、OCIStmtExecute()を使用して選択リスト問合せを暗黙的にも明示的にも記述できます。その他のスキーマ要素は、OCIDescribeAny()を使用して明示的に記述する必要があります。

暗黙的記述

データベース列が文字長セマンティクスを使用して作成されている場合、暗黙的な記述情報には、文字長、バイト長、およびデータベース列の作成方法を示すフラグが含まれます。OCI_ATTR_CHAR_SIZEは、列または式の文字長です。この場合、OCI_ATTR_CHAR_USEDフラグは、列または式が文字長セマンティクスを使用して作成されたことを示す1になります。

OCI_ATTR_DATA_SIZEは常に、すべてのデータ、すなわちOCI_ATTR_CHAR_SIZEの文字数と同じだけのデータを保持するのに十分な大きさの値になります。OCI_ATTR_DATA_SIZEは通常、(OCI_ATTR_CHAR_SIZE)×(クライアントの各文字の最大バイト数)に設定されます。

データベース列がバイト長セマンティクスを使用して作成されている場合、暗黙的な記述では(その動作はリリース9.0より前と同じ)、戻されるOCI_ATTR_DATA_SIZEは、(列のバイト長)×(クライアントとサーバーのキャラクタ・セット間での最大変換率)の値になります。つまり、(列のバイト長)÷(サーバーの各文字の最大バイト数)×(クライアントの各文字の最大バイト数)になります。OCI_ATTR_CHAR_USED値は0で、OCI_ATTR_CHAR_SIZE値はOCI_ATTR_DATA_SIZEと同じ値に設定されます。

明示的記述

表の明示的記述には、次の属性が含まれます。

- OCI_ATTR_DATA_SIZEは、サーバーで表示される列のサイズをバイト数で取得します。

- OCI_ATTR_CHAR_SIZEは、列の長さを文字数で示します。

- OCI_ATTR_CHAR_USEDは、列の長さセマンティクスの型に関して前に述べたように、列の作成方法を示すフラグです。

OCI_ATTR_CHAR_USEDのフラグが設定されている場合は、挿入時に、バインド・バンドルのOCI_ATTR_MAXCHAR_SIZEを、パラメータ・ハンドルのOCI_ATTR_CHAR_SIZEによって戻される値に設定できます。これにより、列のサイズ制限に違反することを防ぎます。

関連項目:
「INバインド」

記述に関するクライアントとサーバー間の互換性の問題

Oracle9i 以上のクライアントがOracle8i 以下のサーバーと通信を行うと、そのクライアントは、データベースがバイト長セマンティクスのみを使用しているかのように動作します。

Oracle8i 以下のクライアントがOracle9i 以上のサーバーと通信を行うと、クライアント側でOCI_ATTR_CHAR_SIZE属性とOCI_ATTR_CHAR_USED属性を使用することはできません。

いずれの場合も、サーバーまたはクライアントがOracle8i 以下のソフトウェア・リリースである場合、文字長セマンティクスは記述できません。

OCIDescribeAny()の使用例

次の例では、異なる種類のスキーマ・オブジェクトを記述するためのOCIDescribeAny()の使用方法を示します。より詳細なコード例は、Oracle Databaseのインストールに含まれているデモ・プログラムcdemodsa.cを参照してください。

関連項目:
デモ・プログラムの詳細は、 付録Bを参照してください。

表用の列データ型の取出し

例6-2では、表の列データ型を取り出す明示的な記述の使用方法を示しています。

例6-2 表の列データ型を取り出す明示的な記述の使用方法

...
int i=0;
text objptr[] = "EMPLOYEES"; /* the name of a table to be described */
ub2          numcols, col_width;
ub1          char_semantics;
ub2  coltyp;
ub4 objp_len = (ub4) strlen((char *)objptr);
OCIParam *parmh = (OCIParam *) 0;         /* parameter handle */
OCIParam *collsthd = (OCIParam *) 0;      /* handle to list of columns */
OCIParam *colhd = (OCIParam *) 0;         /* column handle */
OCIDescribe *dschp = (OCIDescribe *)0;      /* describe handle */

OCIHandleAlloc((void *)envhp, (void **)&dschp,
(ub4)OCI_HTYPE_DESCRIBE, (size_t)0, (void **)0);

/* get the describe handle for the table */
if (OCIDescribeAny(svch, errh, (void *)objptr, objp_len, OCI_OTYPE_NAME, 0,
OCI_PTYPE_TABLE, dschp))
return OCI_ERROR;

/* get the parameter handle */
if (OCIAttrGet((void *)dschp, OCI_HTYPE_DESCRIBE, (void *)&parmh, (ub4 *)0,
OCI_ATTR_PARAM, errh))
return OCI_ERROR;

/* The type information of the object, in this case, OCI_PTYPE_TABLE,
is obtained from the parameter descriptor returned by the OCIAttrGet(). */
/* get the number of columns in the table */
numcols = 0;
if (OCIAttrGet((void *)parmh, OCI_DTYPE_PARAM, (void *)&numcols, (ub4 *)0,
OCI_ATTR_NUM_COLS, errh))
return OCI_ERROR;

/* get the handle to the column list of the table */
if (OCIAttrGet((void *)parmh, OCI_DTYPE_PARAM, (void *)&collsthd, (ub4 *)0,
OCI_ATTR_LIST_COLUMNS, errh)==OCI_NO_DATA)
return OCI_ERROR;

/* go through the column list and retrieve the data type of each column,
and then recursively describe column types. */

for (i = 1; i <= numcols; i++)
{
/* get parameter for column i */
if (OCIParamGet((void *)collsthd, OCI_DTYPE_PARAM, errh, (void **)&colhd, (ub4)i))
return OCI_ERROR;

/* for example, get data type for ith column */
coltyp = 0;
if (OCIAttrGet((void *)colhd, OCI_DTYPE_PARAM, (void *)&coltyp, (ub4 *)0,
OCI_ATTR_DATA_TYPE, errh))
return OCI_ERROR;

/* Retrieve the length semantics for the column */
char_semantics = 0;
OCIAttrGet((void*) colhd, (ub4) OCI_DTYPE_PARAM,
(void*) &char_semantics,(ub4 *) 0, (ub4) OCI_ATTR_CHAR_USED,
(OCIError *) errh);

col_width = 0;
if (char_semantics)
/* Retrieve the column width in characters */
OCIAttrGet((void*) colhd, (ub4) OCI_DTYPE_PARAM,
(void*) &col_width, (ub4 *) 0, (ub4) OCI_ATTR_CHAR_SIZE,
(OCIError *) errh);
else
/* Retrieve the column width in bytes */
OCIAttrGet((void*) colhd, (ub4) OCI_DTYPE_PARAM,
(void*) &col_width,(ub4 *) 0, (ub4) OCI_ATTR_DATA_SIZE,
(OCIError *) errh);
}

if (dschp)
OCIHandleFree((void *) dschp, OCI_HTYPE_DESCRIBE);
...

ストアド・プロシージャの記述

プロシージャとファンクションの違いは、ファンクションには引数リストに位置0 (ゼロ)の戻り型がありますが、プロシージャには、引数リストの位置0 (ゼロ)に対応する引数がないことです。型メソッドの記述に必要なステップ(ファンクションとプロシージャへの分割も行います)は、通常のPL/SQLファンクションおよびプロシージャのステップとまったく同じです。プロシージャおよびファンクションは、オブジェクトのデフォルト型を引数として使用できることに注意してください。次のプロシージャで考えてみます。

P1 (arg1 emp.sal%type, arg2 emp%rowtype)

例6-3では、emp表の各行には、name(VARCHAR2(20))およびsal(NUMBER)の2列があると想定します。P1の引数リストには、arg1とarg2の2つの引数がそれぞれレベル0 (ゼロ)の位置1と位置2にあり、引数のnameとsalがそれぞれレベル1の位置1と位置2にあります。P1の記述では、引数の数を2として戻し、レベル0 (ゼロ)を超える(> 0)引数を、レベル0 (ゼロ)の引数の属性として戻します。

例6-3 ストアド・プロシージャの記述

...
int i = 0, j = 0;
text objptr[] = "add_job_history"; /* the name of a procedure to be described */
ub4 objp_len = (ub4)strlen((char *)objptr);
ub2 numargs = 0, numargs1, pos, level;
text *name, *name1;
ub4 namelen, namelen1;
OCIParam *parmh = (OCIParam *) 0;         /* parameter handle */
OCIParam *arglst = (OCIParam *) 0;          /* list of args */
OCIParam *arg = (OCIParam *) 0;             /* argument handle */
OCIParam *arglst1 = (OCIParam *) 0;          /* list of args */
OCIParam *arg1 = (OCIParam *) 0;             /* argument handle */
OCIDescribe *dschp = (OCIDescribe *)0;      /* describe handle */

OCIHandleAlloc((void *)envhp, (void **)&dschp,
(ub4)OCI_HTYPE_DESCRIBE, (size_t)0, (void **)0);

/* get the describe handle for the procedure */
if (OCIDescribeAny(svch, errh, (void *)objptr, objp_len, OCI_OTYPE_NAME, 0,
OCI_PTYPE_PROC, dschp))
return OCI_ERROR;

/* get the parameter handle */
if (OCIAttrGet((void *)dschp, OCI_HTYPE_DESCRIBE, (void *)&parmh, (ub4 *)0,
OCI_ATTR_PARAM, errh))
return OCI_ERROR;

/* Get the number of arguments and the arg list */
if (OCIAttrGet((void *)parmh, OCI_DTYPE_PARAM, (void *)&arglst,
(ub4 *)0, OCI_ATTR_LIST_ARGUMENTS, errh))
return OCI_ERROR;

if (OCIAttrGet((void *)arglst, OCI_DTYPE_PARAM, (void *)&numargs, (ub4 *)0,
OCI_ATTR_NUM_PARAMS, errh))
return OCI_ERROR;

/* For a procedure, you begin with i = 1; for a
function, you begin with i = 0. */

for (i = 1; i <= numargs; i++) {
OCIParamGet ((void *)arglst, OCI_DTYPE_PARAM, errh, (void **)&arg, (ub4)i);
namelen = 0;
OCIAttrGet((void *)arg, OCI_DTYPE_PARAM, (void *)&name, (ub4 *)&namelen,
OCI_ATTR_NAME, errh);

/* to print the attributes of the argument of type record
(arguments at the next level), traverse the argument list */

OCIAttrGet((void *)arg, OCI_DTYPE_PARAM, (void *)&arglst1, (ub4 *)0,
OCI_ATTR_LIST_ARGUMENTS, errh);

/* check if the current argument is a record. For arg1 in the procedure
arglst1 is NULL. */

if (arglst1) {
numargs1 = 0;
OCIAttrGet((void *)arglst1, OCI_DTYPE_PARAM, (void *)&numargs1, (ub4 *)0,
OCI_ATTR_NUM_PARAMS, errh);

/* Note that for both functions and procedures,the next higher level
arguments start from index 1. For arg2 in the procedure, the number of
arguments at the level 1 would be 2 */

for (j = 1; j <= numargs1; j++) {
OCIParamGet((void *)arglst1, OCI_DTYPE_PARAM, errh, (void **)&arg1,
(ub4)j);
namelen1 = 0;
OCIAttrGet((void *)arg1, OCI_DTYPE_PARAM, (void *)&name1, (ub4 *)&namelen1,
OCI_ATTR_NAME, errh);
}
}
}

if (dschp)
OCIHandleFree((void *) dschp, OCI_HTYPE_DESCRIBE);
...

オブジェクト型の属性の取出し

例6-4では、名前付きオブジェクト型についての明示的な記述の使用方法を示しています。オブジェクトを名前またはオブジェクト参照(OCIRef)によって記述する方法を説明します。次のコード・フラグメントによって、オブジェクト型の属性について各データ型値の取出しが試みられます。

例6-4 名前付きオブジェクト型についての明示的な記述の使用方法

...
int i = 0;
text type_name[] = "inventory_typ";
ub4 type_name_len = (ub4)strlen((char *)type_name);
OCIRef *type_ref = (OCIRef *) 0;
ub2 numattrs = 0, describe_by_name = 1;
ub2 datatype = 0;
OCITypeCode typecode = 0;
OCIDescribe *dschp = (OCIDescribe *) 0;      /* describe handle */
OCIParam *parmh = (OCIParam *) 0;         /* parameter handle */
OCIParam *attrlsthd = (OCIParam *) 0;     /* handle to list of attrs */
OCIParam *attrhd = (OCIParam *) 0;        /* attribute handle */

/* allocate describe handle */
if (OCIHandleAlloc((void *)envh, (void **)&dschp,
(ub4)OCI_HTYPE_DESCRIBE, (size_t)0, (void **)0))
return OCI_ERROR;

/* get the describe handle for the type */
if (describe_by_name) {
if (OCIDescribeAny(svch, errh, (void *)type_name, type_name_len,
OCI_OTYPE_NAME, 0, OCI_PTYPE_TYPE, dschp))
return OCI_ERROR;
}
else {
/* get ref to type using OCIAttrGet */

/* get the describe handle for the type */
if (OCIDescribeAny(svch, errh, (void*)type_ref, 0, OCI_OTYPE_REF,
0, OCI_PTYPE_TYPE, dschp))
return OCI_ERROR;
}

/* get the parameter handle */
if (OCIAttrGet((void *)dschp, OCI_HTYPE_DESCRIBE, (void *)&parmh, (ub4 *)0,
OCI_ATTR_PARAM, errh))
return OCI_ERROR;

/* The type information of the object, in this case, OCI_PTYPE_TYPE, is
obtained from the parameter descriptor returned by OCIAttrGet */

/* get the number of attributes in the type */
if (OCIAttrGet((void *)parmh, OCI_DTYPE_PARAM, (void *)&numattrs, (ub4 *)0,
OCI_ATTR_NUM_TYPE_ATTRS, errh))
return OCI_ERROR;

/* get the handle to the attribute list of the type */
if (OCIAttrGet((void *)parmh, OCI_DTYPE_PARAM, (void *)&attrlsthd, (ub4 *)0,
OCI_ATTR_LIST_TYPE_ATTRS, errh))
return OCI_ERROR;

/* go through the attribute list and retrieve the data type of each attribute,
and then recursively describe attribute types. */

for (i = 1; i <= numattrs; i++)
{
/* get parameter for attribute i */
if (OCIParamGet((void *)attrlsthd, OCI_DTYPE_PARAM, errh, (void **)&attrhd, i))
return OCI_ERROR;

/* for example, get data type and typecode for attribute; note that
OCI_ATTR_DATA_TYPE returns the SQLT code, whereas OCI_ATTR_TYPECODE returns the
Oracle Type System typecode. */

datatype = 0;
if (OCIAttrGet((void *)attrhd, OCI_DTYPE_PARAM, (void *)&datatype, (ub4 *)0,
OCI_ATTR_DATA_TYPE,errh))
return OCI_ERROR;

typecode = 0;
if (OCIAttrGet((void *)attrhd, OCI_DTYPE_PARAM,(void *)&typecode, (ub4 *)0,
OCI_ATTR_TYPECODE, errh))
return OCI_ERROR;

/* if attribute is an object type, recursively describe it */
if (typecode == OCI_TYPECODE_OBJECT)
{
OCIRef *attr_type_ref;
OCIDescribe *nested_dschp;

/* allocate describe handle */
if (OCIHandleAlloc((void *)envh,(void**)&nested_dschp,
(ub4)OCI_HTYPE_DESCRIBE,(size_t)0, (void **)0))
return OCI_ERROR;

if (OCIAttrGet((void *)attrhd, OCI_DTYPE_PARAM,
(void *)&attr_type_ref, (ub4 *)0, OCI_ATTR_REF_TDO,errh))
return OCI_ERROR;

OCIDescribeAny(svch, errh,(void*)attr_type_ref, 0,
OCI_OTYPE_REF, 0, OCI_PTYPE_TYPE, nested_dschp);
/* go on describing the attribute type... */
}
}

if (dschp)
OCIHandleFree((void *) dschp, OCI_HTYPE_DESCRIBE);
...

名前付きコレクション型のコレクション要素のデータ型の取出し

例6-5では、名前付きコレクション型についての明示的な記述の使用方法を示しています。

例6-5 名前付きコレクション型についての明示的な記述の使用

text type_name[] = "phone_list_typ";
ub4 type_name_len = (ub4) strlen((char *)type_name);
OCIRef *type_ref = (OCIRef *) 0;
ub2 describe_by_name = 1;
ub4 num_elements = 0;
OCITypeCode typecode = 0, collection_typecode = 0, element_typecode = 0;
void *collection_element_parmh = (void *) 0;
OCIDescribe *dschp = (OCIDescribe *) 0;      /* describe handle */
OCIParam *parmh = (OCIParam *) 0;         /* parameter handle */

/* allocate describe handle */
if (OCIHandleAlloc((void *)envh, (void **)&dschp,
(ub4)OCI_HTYPE_DESCRIBE, (size_t)0, (void **)0))
return OCI_ERROR;

/* get the describe handle for the type */
if (describe_by_name) {
if (OCIDescribeAny(svch, errh, (void *)type_name, type_name_len,
OCI_OTYPE_NAME, 0, OCI_PTYPE_TYPE, dschp))
return OCI_ERROR;
}
else {
/* get ref to type using OCIAttrGet */

/* get the describe handle for the type */
if (OCIDescribeAny(svch, errh, (void*)type_ref, 0, OCI_OTYPE_REF,
0, OCI_PTYPE_TYPE, dschp))
return OCI_ERROR;
}

/* get the parameter handle */
if (OCIAttrGet((void *)dschp, OCI_HTYPE_DESCRIBE, (void *)&parmh, (ub4 *)0,
OCI_ATTR_PARAM, errh))
return OCI_ERROR;

/* get the Oracle Type System type code of the type to determine that this is a
collection type */
typecode = 0;
if (OCIAttrGet((void *)parmh, OCI_DTYPE_PARAM,(void *)&typecode, (ub4 *)0,
OCI_ATTR_TYPECODE, errh))
return OCI_ERROR;

/* if typecode is OCI_TYPECODE_NAMEDCOLLECTION,
proceed to describe collection element */
if (typecode == OCI_TYPECODE_NAMEDCOLLECTION)
{
/* get the collection's type: OCI_TYPECODE_VARRAY or OCI_TYPECODE_TABLE */
collection_typecode = 0;
if (OCIAttrGet((void *)parmh, OCI_DTYPE_PARAM, (void *)&collection_typecode,
(ub4 *)0,
OCI_ATTR_COLLECTION_TYPECODE, errh))
return OCI_ERROR;

/* get the collection element; you MUST use this to further retrieve information
about the collection's element */
if (OCIAttrGet((void *)parmh, OCI_DTYPE_PARAM, &collection_element_parmh,
(ub4 *)0,
OCI_ATTR_COLLECTION_ELEMENT, errh))
return OCI_ERROR;
/* get the number of elements if collection is a VARRAY; not valid for nested
tables */
if (collection_typecode == OCI_TYPECODE_VARRAY) {
if (OCIAttrGet((void *)collection_element_parmh, OCI_DTYPE_PARAM,
(void *)&num_elements, (ub4 *)0, OCI_ATTR_NUM_ELEMS, errh))
return OCI_ERROR;
}
/* now use the collection_element parameter handle to retrieve information about
the collection element */
element_typecode = 0;
if (OCIAttrGet((void *)collection_element_parmh, OCI_DTYPE_PARAM,
(void *)&element_typecode, (ub4 *)0, OCI_ATTR_TYPECODE, errh))
return OCI_ERROR;

/* do the same to describe additional collection element information; this is
very similar to describing type attributes */
}

if (dschp)
OCIHandleFree((void *) dschp, OCI_HTYPE_DESCRIBE);
...

文字長セマンティクスを使用した記述

例6-6では、問合せの実行後に、問合せに対応する列名およびデータ型を取り出すループを示しています。この問合せは、事前にOCIStmtPrepare()のコールによって文ハンドルと関連付けられています。

例6-6 データ型、列名および文字長セマンティクスを取り出すためのパラメータ記述子の使用

...
OCIParam     *mypard = (OCIParam *) 0;
ub2          dtype;
text         *col_name;
ub4          counter, col_name_len, char_semantics;
ub2          col_width;
sb4          parm_status;

text *sqlstmt = (text *)"SELECT * FROM employees WHERE employee_id = 100";

checkerr(errhp, OCIStmtPrepare(stmthp, errhp, (OraText *)sqlstmt,
(ub4)strlen((char *)sqlstmt),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, 0, 0, (OCISnapshot *)0, (OCISnapshot *)0, OCI_DEFAULT));

/* Request a parameter descriptor for position 1 in the select list */
counter = 1;
parm_status = OCIParamGet((void *)stmthp, OCI_HTYPE_STMT, errhp,
(void **)&mypard, (ub4) counter);
/* Loop only if a descriptor was successfully retrieved for
current position, starting at 1 */
while (parm_status == OCI_SUCCESS) {
/* Retrieve the data type attribute */
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void*) &dtype,(ub4 *) 0, (ub4) OCI_ATTR_DATA_TYPE,
(OCIError *) errhp  ));
/* Retrieve the column name attribute */
col_name_len = 0;
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void**) &col_name, (ub4 *) &col_name_len, (ub4) OCI_ATTR_NAME,
(OCIError *) errhp ));
/* Retrieve the length semantics for the column */
char_semantics = 0;
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void*) &char_semantics,(ub4 *) 0, (ub4) OCI_ATTR_CHAR_USED,
(OCIError *) errhp  ));
col_width = 0;
if (char_semantics)
/* Retrieve the column width in characters */
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void*) &col_width, (ub4 *) 0, (ub4) OCI_ATTR_CHAR_SIZE,
(OCIError *) errhp  ));
else
/* Retrieve the column width in bytes */
checkerr(errhp, OCIAttrGet((void*) mypard, (ub4) OCI_DTYPE_PARAM,
(void*) &col_width,(ub4 *) 0, (ub4) OCI_ATTR_DATA_SIZE,
(OCIError *) errhp  ));
/* increment counter and get next descriptor, if there is one */
counter++;
parm_status = OCIParamGet((void *)stmthp, OCI_HTYPE_STMT, errhp,
(void **)&mypard, (ub4) counter);
} /* while */
...

7 LOBおよびBFILEの操作

この章は、次の項目で構成されています。

- LOBでのOCI関数の使用

- 永続LOBの作成と変更

- 表内のBFILEとオペレーティング・システム・ファイルの関連付け

- オブジェクトのLOB属性

- LOBの配列インタフェース

- 4GBより大きいサイズのLOBの使用

- OCIのLOB関数およびBFILE関数

- 一時LOBのサポート

- LOBデータ、長さおよびチャンク・サイズのプリフェッチ

- SecureFiles LOBのオプション

LOBでのOCI関数の使用

OCIには、データベース内のラージ・オブジェクト(Large Object: LOB)で操作を実行するための一連の関数があります。永続LOB (BLOB、CLOB、NCLOB)はデータベースの表領域に格納されており、領域の最適化とアクセスの効率化を実現します。これらのLOBは、Oracle Databaseのトランザクションを完全にサポートしています。BFILEとは、データベース表領域外のサーバーのオペレーティング・システム・ファイルに格納された大型のデータ・オブジェクトのことです。

また、OCIは一時LOBもサポートしており、これは、LOBデータ上で操作するローカル変数のように使用することができます。

BFILEは読取り専用です。バイナリのBFILEのみをサポートしています。

関連項目:

- LOBの使用方法を示したコード例は、付録Bを参照してください。

- 特定のLOBコードのサンプルは、$ORACLE_HOME/rdbms/demo/lobs/oci/を参照してください。

- DBMS_LOBパッケージは、『Oracle Database PL/SQLパッケージおよびタイプ・リファレンス』を参照してください。

- 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』

永続LOBの作成と変更

LOBインスタンスは永続的(データベースに格納)または一時的(アプリケーションの有効範囲内のみに存在)のいずれかである可能性があります。永続LOBと永続オブジェクトの概念を混同しないでください。

永続LOBの作成および変更には、次の2つの方法があります。

- データ・インタフェースの使用
文字データをCLOB列に挿入、またはRAWデータをBLOB列に直接挿入すると、LOBを作成できます。SQLのUPDATE文を使用するか、文字データをCLOB列にバインドするか、またはRAWデータをBLOB列にバインドすると、LOBを変更することもできます。

リモート・サーバーとローカル・サーバーがいずれもOracle Database 10gリリース2以上であるので、リモートLOBの(dblinkを介した)挿入、更新および選択がサポートされます。データ・インタフェースでは、最大2GB -1、つまりsb4データ型の最大サイズまでのデータ・サイズのみサポートされます。

関連項目:
詳細と例は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の永続LOBのデータ・インタフェースに関する章を参照してください。

- LOBロケータの使用
内部LOBを新規作成するには、OCIDescriptorAlloc()を使用して新規のLOBロケータを初期化してから、OCIAttrSet()をコールして(OCI_ATTR_LOBEMPTY属性を使用して)空に設定し、次に、そのロケータをINSERT文でプレースホルダにバインドします。この処理により、LOB列または属性がある表に空のロケータを挿入します。次に、SELECT...FOR UPDATE操作をこの行で実行してロケータを取得し、OCI LOB関数の1つを使用してロケータに書き込みます。

注意:
LOB列または属性を変更(書込み、コピー、切捨てなど)するには、そのLOBが含まれている行をロックする必要があります。そのためには、操作を実行する前にSELECT...FOR UPDATE文を使用してロケータを選択します。

関連項目:
INSERTおよびUPDATEの使用方法および使用例は、「LOBデータのバインド」を参照してください。

LOB書込みコマンドを正常終了するには、トランザクションをオープンしておく必要があります。データの書込み前にトランザクションをコミットする場合は、コミットによってトランザクションがクローズされるため、(SELECT...FOR UPDATE文の再発行などにより)行を再ロックする必要があります。

表内のBFILEとオペレーティング・システム・ファイルの関連付け

INSERT文でBFILENAME関数を使用すると、外部サーバー側(オペレーティング・システム)ファイルと表内のBFILE列または属性を関連付けることができます。UPDATE文でBFILENAMEを使用して、BFILEの列または属性を別のオペレーティング・システム・ファイルに関連付けます。OCILobFileSetName()を使用して、表内のBFILEをオペレーティング・システム・ファイルに関連付けることもできます。通常、BFILENAMEはINSERTまたはUPDATE文内でバインド変数なしで使用され、OCILobFileSetName()がバインド変数に使用されます。

関連項目:

- 「OCILobFileSetName()」

- BFILENAME関数の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

オブジェクトのLOB属性

OCIアプリケーションでは、OCIObjectNew()関数を使用して、LOB属性を持つ永続オブジェクトまたは一時オブジェクトを作成することができます。

オブジェクトのLOB属性への書込み

OCIを使用して、LOB属性を持つ新規の永続オブジェクトを作成したり、そのLOB属性への書込みができます。LOBロケータを使用するときは、アプリケーションでは次のステップに従います。

1. OCIObjectNew()をコールして、LOB属性を持つ永続オブジェクトを作成します。

2. オブジェクトを「使用済」(変更済)とマークします。

3. 表に行を挿入して、オブジェクトをフラッシュします。

4. オブジェクトをデータベースから取り出し、LOBに有効なロケータを取得して、オブジェクトの最新バージョンを再確保します(またはオブジェクトをリフレッシュします)。

5. オブジェクト内のLOBロケータを使用してOCILobWrite2()をコールし、データを書き込みます。

関連項目:
オブジェクトの詳細は、第11章とその後の各章を参照してください。

LOB属性に書き込むには、もう1つ方法があります。データ・インタフェースを使用すると、CLOB属性の文字データ、またはBLOB属性のRAWデータのバインドまたは定義ができます。

関連項目:

- INSERT文およびUPDATE文の使用方法および使用例は、「LOBデータのバインド」を参照してください。

- SELECT文の使用方法および使用例は、「LOBデータの定義」を参照してください。

LOB属性を持つ一時オブジェクト

アプリケーションでは、OCIObjectNew()をコールして、内部LOB(BLOB、CLOB、NCLOB)属性を持つ一時オブジェクトを作成できます。ただし、LOB属性を持つ一時オブジェクトは現在サポートされていないため、読取りや書込みなどの、LOB属性での操作は実行できません。一時内部LOB型を作成するためのOCIObjectNew()コールは失敗しませんが、アプリケーションでは、この一時LOBでLOB操作を使用することはできません。

ただし、アプリケーションでは、BFILE属性を持つ一時オブジェクトを作成し、BFILE属性を使用して、サーバーのファイル・システムに格納されているファイルからデータを読み取ることができます。アプリケーションでは、OCIObjectNew()をコールして、一時BFILEを作成できます。

LOBの配列インタフェース

OCI配列インタフェースは、他のデータ型と同様に、LOBに対しても使用できます。配列インタフェースを使用するには、次の2つの方法があります。

- データ・インタフェースの使用
文字データの配列をCLOB列に対して、またはRAWデータの配列をBLOB列に対してバインドまたは定義できます。配列のバインドおよび定義インタフェースを使用すると、LOBを含む複数の行をサーバーへの1回のラウンドトリップで挿入および選択できます。

関連項目:

- INSERT文およびUPDATE文の使用方法および使用例は、「LOBデータのバインド」を参照してください。

- SELECT文の使用方法および使用例は、「LOBデータの定義」を参照してください。

- LOBロケータの使用
LOBロケータを使用するときは、例7-1に示すように、記述子を割り当てる必要があります。

例7-1 LOBロケータの使用と記述子の割当て

/* First create an array of OCILobLocator pointers: */
OCILobLocator *lobp[10];

for (i=0; i < 10; i++)
{ OCIDescriptorAlloc (...,&lobp[i],...);

/* Then bind the descriptor as follows */
OCIBindByPos(... &lobp[i], ...);

4GBより大きいサイズのLOBの使用

OCIのOracle Database 10gリリース1からは、4GBより大きいサイズのLOBをサポートする関数が導入されました。この新機能は、4GBより小さいLOBの新規アプリケーションでも使用できます。

Oracle Databaseを使用すると、データベースのブロック・サイズとは異なるブロック・サイズを持つ表領域を作成できます。LOBの最大サイズは、表領域のブロック・サイズに応じて異なります。LOBが格納される表領域のブロック・サイズにより、LOB記憶域のパラメータであるCHUNKの値が制御されます。LOB列を作成する場合、CHUNKの値を指定できます。これは、LOBの操作用に割り当てるバイト数です。この値は、表領域ブロック・サイズの倍数である必要があります。そうでない場合、Oracle Databaseによって次の倍数に切り上げられます。(表領域のブロック・サイズがデータベースのブロック・サイズと同じ場合、CHUNKは、データベースのブロック・サイズの倍数でもあります。)CHUNKのデフォルト・サイズは、1つの表領域ブロックのサイズであり、最大値は32KBです。

このマニュアルでは、4GBは4GB–1、または4,294,967,295バイトと定義します。LOB(永続または一時)の最大サイズは、(4GB–1)×(CHUNK)です。LOBの最大サイズは、8TBから128TBの範囲です。

たとえば、データベースのブロック・サイズが32KBで、標準外の8KBのブロック・サイズで表領域を作成するとします。さらに、LOB列を持つ表を作成し、CHUNKサイズを16KB (表領域のブロック・サイズである8KBの倍数)に指定するとします。この場合、この列のLOBの最大サイズは(4GB-1)×16KBです。

BFILEの最大サイズは、ご使用のオペレーティング・システムで許容される最大ファイル・サイズとUB8MAXVALのどちらか小さい方となります。

以前のLOB関数ではub4を一部のパラメータのデータ型として使用し、ub4データ型では最大4GBしか保持できません。新しい関数では、8バイト長のパラメータ、oraub8を使用し、これはoratypes.hで定義されるデータ型です。コンパイラとオペレーティング・システムに応じて、データ型oraub8およびorasb8は該当する64ビット固有のデータ型にマップされます。厳密なANSIオプションを使用して32ビット・モードでコンパイルする場合、マクロを使用してoraub8およびorasb8を定義することはできません。

OCILobGetChunkSize()は、利用可能なチャンク・サイズをBLOB、CLOBおよびNCLOBに対してバイト数で戻します。チャンクに格納されるバイト数は、内部記憶域のオーバヘッドにより、実際にはCHUNKパラメータのサイズより小さくなります。関数OCILobGetStorageLimit()により、現行インストールにおける内部LOBの最大サイズがバイト数で戻されます。

注意:
Oracle Databaseでは、どのようなプログラム環境においても、4GBを超えるBFILEはサポートされません。ご使用のオペレーティング・システムのその他のファイル・サイズ制限もBFILEに適用されます。

増加したLOBサイズに対して使用する関数

名前が「2」で終わり、データ型ub4のかわりにデータ型oraub8を使用する8つの関数が、Oracle Database 10gリリース1で導入されました。その他、いくつかの問題を解決するために、読取りおよび書込みの関数(OCILobRead2()、 OCILobWrite2()およびOCILobWriteAppend2())で変更が行われました。

問題点: Oracle Database 10g リリース1より前では、パラメータamtpにより、LOBがバイト長または文字長のどちらであるかが、ロケータ・タイプおよびキャラクタ・セットに基づいて判断されていました。これは複雑で、ユーザーは要件に応じてバイト長または文字長を柔軟に使用することができませんでした。

解決策: 読取り/書込みコールでは、amtpパラメータのかわりに、byte_amtpおよびchar_amtpの両方のパラメータが必要です。char_amtpパラメータはCLOBとNCLOBでは基本設定となり、byte_amtpパラメータは、char_amtpが0 (ゼロ)の場合のみ、入力とみなされます。CLOBおよびNCLOBの出力時には、byte_amtpとchar_amtpの両方のパラメータに値が入ります。BLOBおよびBFILEの場合、入力時も出力時もchar_amptパラメータは無視されます。

問題点: OCILobRead2()には、ポーリング・モードを示すためのフラグがありません。このため、ユーザーは「100バイトのバッファがあります。できるかぎり使用してください。」と指示するのが困難になります。以前は、総量に対して指定する文字数を見積もる必要がありました。あまり多く見積もりすぎると、意図せずポーリング・モードに移行されていました。このように、ユーザー・コードによりポーリング・モードでトラップされる場合があり、以降のOCIコールがすべてブロックされてしまいます。

解決策: このコールでは、pieceを入力パラメータとして取り、OCI_ONE_PIECEが渡された場合は、byte_amtpパラメータまたはchar_amtpパラメータで指定した値がバッファ長より大きくても、バッファを可能なかぎり埋めて出る必要があります。buflの値を使用して、読み取るバイトの最大量を指定します。

問題点: ポーリング・モードでLOB書込みをコールした後は、ポーリングの終了までに実際にフェッチされる文字数またはバイト数をユーザーは認識できません。

解決策: ポーリング・モードでの各コール後に、byte_amtpおよびchar_amtpの両パラメータを更新してください。

問題点: コールバックを使用した、ストリーム・モードでの読取り時または書込み時には、ユーザーはデータの各ピースに対して同じバッファを使用する必要があります。

解決策: コールバック関数には、バッファおよびバッファ長を指定する2つの新規パラメータを含めてください。コールバック関数で、バッファ・パラメータをNULLに設定すると、以前の動作に従います(すべてのピースに対する最初のコールで渡されるデフォルト・バッファを使用)。

関連項目:

- 「LOB関数」

- 「OCILobRead2()」

- 「OCILobWrite2()」

- 「OCILobWriteAppend2()」

互換性および移行

既存のOCIプログラムを拡張して、4GBより大きい大容量のLOBデータを処理できます。表7-1に、互換性の問題点をまとめます(「旧」とは、Oracle Database 10gリリース1より前のリリースを指します)。

表7-1 LOB関数の互換性および移行

LOB関数

旧クライアント/新規または旧サーバー脚注 1

新規クライアント/旧サーバー

新規クライアント/新規サーバー

OCILobArrayRead()

NA脚注 2

ピース・サイズおよびオフセットが4GB未満であればOK。

OK

OCILobArrayWrite()

NA

ピース・サイズおよびオフセットが4GB未満であればOK。

OK

OCILobCopy2()

NA

LOBサイズ、ピース・サイズ(量)およびオフセットが4GB未満であればOK。

OK

OCILobCopy()

OK (制限は4GB)。

OK

OK (制限は4GB)。

OCILobErase2()

NA

ピース・サイズおよびオフセットが4GB未満であればOK。

OK

OCILobErase()

OK (制限は4GB)。

OK

OK (制限は4GB)。

OCILobGetLength2()

NA

OK

OK

OCILobGetLength()

OK (制限は4GB)。

OK

OK (LOBサイズが > 4GBの場合はOCI_ERRORとなります)。

OCILobLoadFromFile2()

NA

LOBサイズ、ピース・サイズ(量)およびオフセットが4GB未満であればOK。

OK

OCILobLoadFromFile()

OK (制限は4GB)。

OK

OK (制限は4GB)。

OCILobRead2()

NA

LOBサイズ、ピース・サイズ(量)およびオフセットが4GB未満であればOK。

OK

OCILobRead()

OK (制限は4GB)。

新規サーバーを使用した場合: 4GB以上の量を4GB未満のオフセットから読み取ろうとすると、OCI_ERRORが戻されます。これは、ユーザーが4GB以上の量を読み取ると、*amtpの戻り値がオーバーフローするためで、エラーとしてフラグが立てられます。

注意:

- オフセットから4GB – 1までを読み取る場合は、エラーとしてフラグは立てられません。

- ポーリング・モードとともにストリーム・モードを使用すると、4GBを超えるピース・サイズを使用しない場合(この場合、4GBを超えるデータの読取りが可能)、エラーは戻されません。

OK

OK。

4GB以上の量を4GB未満のオフセットから読み取ろうとすると、OCI_ERRORが戻されます。これは、ユーザーが4GB以上の量を読み取ると、*amtpの戻り値がオーバーフローするためで、エラーとしてフラグが立てられます。

注意:

- オフセットから4GB – 1までを読み取る場合は、エラーとしてフラグは立てられません。

- ポーリング・モードとともにストリーム・モードを使用すると、4GBを超えるピース・サイズを使用しない場合はエラーは戻されません。

OCILobTrim2()

NA

OK

OK

OCILobTrim()

OK (制限は4GB)。

OK

OK (制限は4GB)。

OCILobWrite2()

NA

LOBサイズ、ピース・サイズ(量)およびオフセットが4GB未満であればOK。

OK

OCILobWrite()

OK (制限は4GB)。

新規サーバーを使用した場合:

4GB以上の量を(4GB未満のオフセットから)書き込むと、*amtpの戻り値がオーバーフローするため、OCI_ERRORが戻されます。

注意: 4GB –1までの量のデータにより、10GBのLOBを4GB –1までのオフセットから更新しても、エラーとしてフラグは立てられません。

OK

OK。

4GB以上の量を(4GB未満のオフセットから)書き込むと、*amtpの戻り値がオーバーフローするため、OCI_ERRORが戻されます。

注意: 4GB –1までの量のデータにより、10GBのLOBを4GB –1までのオフセットから更新しても、エラーとしてフラグは立てられません。

OCILobWriteAppend2()

NA

LOBサイズおよびピース・サイズが4GB未満であればOK。

OK

OCILobWriteAppend()

OK (制限は4GB)。

新規サーバーを使用した場合: 4GB以上のデータを追加すると、*amtpの戻り値がオーバーフローするため、OCI_ERRORが戻されます。

OK

OK (制限は4GB)。

4GB以上のデータを追加すると、*amtpの戻り値がオーバーフローするため、OCI_ERRORが戻されます。

OCILobGetStorageLimit()

NA

エラー

OK

脚注 1 「旧」とは、Oracle Database 10gリリース1より前のリリースを指します。

脚注 2 NAは、該当なしを意味します。

現行サーバーと現行クライアントを使用する場合は、「2」で終わる関数を使用してください。非推奨の関数を「2」で終わる関数と併用すると、OCILobWrite2()を使用して書き込まれたデータが4GBより大きいときに、アプリケーションでOCILobRead()を使用してそれが読み取られると、データの一部しか取得されない(コールバック関数が使用されていない場合)など、予期せぬ状況になる可能性があります。サイズが4GBを超えていて、非推奨の関数が使用されると、ほとんどの場合、アプリケーションでエラー・メッセージを受け取ります。ただし、サイズが4GBより小さいLOBに対して非推奨の関数を使用する場合、問題は発生しません。

OCIのLOB関数およびBFILE関数

データへのオフセットを伴うすべてのLOB操作では、オフセットは1から始まります。OCILobCopy2()、OCILobErase2()、OCILobLoadFromFile2()およびOCILobTrim2()などのLOB操作の場合、amountパラメータは、クライアント側のキャラクタ・セットにかかわらず、CLOBとNCLOBの文字数です。

これらのLOB操作は、サーバー上のLOBデータの量を参照します。クライアント側のキャラクタ・セットが可変幅の場合は、次の一般的な規則がLOBコールのamountパラメータとoffsetパラメータに適用されます。

- amount－amountパラメータがサーバー側のLOBを参照する場合、amountは文字数です。amountパラメータがクライアント側のバッファを参照する場合、amountはバイト数です。

- offset - クライアント側のキャラクタ・セットが可変幅かどうかにかかわらず、offsetパラメータは常にCLOBまたはNCLOBの場合は文字数、BLOBまたはBFILEの場合はバイト数です。

これらの一般的な規則の例外は、特定のLOBコールの説明で示してあります。

関連項目:

- 「LOB関数」

- 「OCIバインド時のバッファの拡張」

LOBの読取り/書込みパフォーマンスの向上

次に、パフォーマンスを向上させるためのヒントをいくつか示します。

LOBに対するデータ・インタフェースの使用

CLOB列の文字データまたはBLOB列のRAWデータをバインドまたは定義できます。ここでは、複数回のラウンドトリップを必要とする従来のLOBインタフェースとは対照的に、LOBを挿入または選択する際に必要なラウンドトリップは1回のみです。

関連項目:

- INSERT文およびUPDATE文の使用方法および使用例は、「LOBデータのバインド」を参照してください。

- SELECT文の使用方法および使用例は、「LOBデータの定義」を参照してください。

OCILobGetChunkSize()の使用方法

OCILobGetChunkSize()は、利用可能なチャンク・サイズをBLOB、CLOBおよびNCLOBに対してバイト数で戻します。OCILobGetChunkSize()コールを使用すれば、BasicFile LOBに関するLOBの読取りおよび書込み操作のパフォーマンスを改善できます。サイズが利用可能なチャンク・サイズの倍数で、操作がチャンクの境界から始まるBasicFile LOBデータで読取りまたは書込みが行われると、パフォーマンスが向上します。OCILobGetChunkSize()の位置合せを使用して、SecureFile LOBを読取りまたは書込みする必要はありません。

関連項目:
"「SecureFiles LOBのオプション」

OCILobGetChunkSize()のコールにより、LOBの利用可能なチャンク・サイズが戻されるため、アプリケーションは、同じチャンクに対する複数のLOB書込みコールを発行するかわりに、チャンク全体に対する一連の書込み操作をバッチ処理できます。

OCILobWriteAppend2()の使用方法

OCIでは、LOBの末尾へのデータの書込みをより効率的にするためのショートカットが提供されています。OCILobWriteAppend2()コールにより、最初にOCILobGetLength2()をコールしてOCILobWrite2()操作の開始点を決定しなくても、データをLOBの末尾に追加できます。OCILobWriteAppend2()では、両方のステップが行われます。

OCILobArrayRead()およびOCILobArrayWrite()の使用方法

OCILobArrayRead()を使用して、複数のLOBロケータに対してLOBデータを読み取り、OCILobArrayWrite()を使用して、複数のLOBロケータに対してLOBデータを書き込むことにより、パフォーマンスを改善できます。これら関数は、Oracle Database 10gリリース2で導入され、これらの操作のラウンドトリップ数を減らします。

関連項目:
これらの関数をコールバック関数とともにピース単位モードで使用する方法の詳細とコード例は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の「LOB配列読取り」および「LOB配列書込み」の項を参照してください。

LOBバッファリング関数

OCIには、内部LOB値の小さな読取りと書込みのために、LOBのバッファリングを制御する次のコールがあります。

- OCILobEnableBuffering()

- OCILobDisableBuffering()

- OCILobFlushBuffer()

これらの関数により、内部LOB (BLOB、CLOB、NCLOB)を使用するアプリケーションでは、クライアント側のバッファで小さな読取りと書込みをバッファできます。これにより、ネットワーク・ラウンドトリップの回数とLOBのバージョンを削減でき、LOBのパフォーマンスが大幅に向上します。

関連項目:

- 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』。LOBバッファの詳細は、LOB APIの使用に関する章を参照してください。

- 各関数に必要なサーバー・ラウンドトリップ回数のリストは、「LOB関数のラウンドトリップ」を参照してください。

LOBのオープンおよびクローズのための関数

OCIでは、LOBを明示的にオープンするための関数(OCILobOpen())およびLOBをクローズするための関数(OCILobClose())と、LOBがオープンされているかどうかをテストするための関数(OCILobIsOpen())が提供されています。これらの関数により、一連のLOB操作の開始および終了がマークされるため、LOBのクローズ時に索引の更新など特定の処理が実行できます。

内部LOBでは、オープンされているかどうかの概念は、ロケータではなくLOBに関連しています。ロケータには、LOBの状態に関する情報は格納されません。オープンされている同じLOBを、複数のロケータが指し示すことが可能です。ただし、BFILEについては、オープンは特定のロケータに関連付けられます。したがって、別のロケータを使用して、同じBFILEに対して複数のオープン・コールが実行されることがあります。

アプリケーションで、LOB操作をOCILobOpen()コールとOCILobClose()コールのセットで囲んでいない場合は、LOBが変更されるたびにLOBが暗黙的にオープンおよびクローズされ、それによってLOBの変更に関連付けられているトリガーが起動します。

LOB操作がオープン・コールとクローズ・コールで囲まれていない場合は、LOBの変更時に、LOBの拡張可能な索引がすべて更新されるため、索引は常に有効で、いつでも使用できます。OCILobOpen()コールとOCILobClose()コールで囲まれているLOBが変更された場合、個々のLOBの変更に対してトリガーは起動されません。トリガーはOCILobClose()コールの後にのみ起動されるため、索引が更新されるのはクローズ・コールの後であり、索引はオープン・コールからクローズ・コールまでの間は無効です。OCILobIsOpen()は、内部LOBおよびBFILEsとともに使用できます。

トランザクションでオープンしたすべてのLOBをクローズする前に、そのトランザクションをコミットしようとすると、エラーが発生します。エラーが戻された場合、それ以降LOBはオープンとしてマークは付けられませんが、トランザクションのコミットは正常に行われます。このため、トランザクション内でLOBおよび非LOBデータに対して行われた変更はすべてコミットされますが、ドメイン索引およびファンクション索引は更新されません。これが起こった場合は、LOB列のファンクション索引とドメイン索引を再作成します。

トランザクションがない場合にオープンしているLOBは、セッションの終了前にクローズする必要があります。セッションの終了時にオープンしているLOBがある場合、そのLOBはオープンとしてマークされなくなり、ドメイン索引とファンクション索引は更新されません。これが起こった場合は、LOB列のファンクション索引とドメイン索引を再作成します。

LOBのオープンおよびクローズに関する制限事項

LOBのオープンとクローズに関するメカニズムには、次の制限があります。

- アプリケーションでは、トランザクションをコミットする前に、以前にオープンしたLOBをすべてクローズする必要があります。これを行わないと、エラーが発生します。トランザクションをロールバックする場合、すべてのオープンLOBは、行われた変更とともに廃棄されます。LOBがクローズされないために、関連付けられたトリガーは起動されません。

- 内部LOBのオープン数に制限はありませんが、ファイルのオープン数には制限があります。『Oracle Databaseリファレンス』のSESSION_MAX_OPEN_FILESパラメータを参照してください。すでにオープンしているロケータを別のロケータに割り当てても、新規LOBのオープンとしてはカウントされません。

- 同じトランザクション内で、別のロケータまたは同じロケータを使用して同じ内部LOBを2度オープンまたはクローズすると、エラーになります。

- オープンしていないLOBをクローズするとエラーになります。

注意:
オープンLOB値をクローズする必要があるトランザクションの定義は、次のいずれかとなります。

- SET TRANSACTIONとCOMMITの間

- DATA MODIFYING DMLまたはSELECT... FOR UPDATEとCOMMITとの間。

- 自律型トランザクション・ブロック内

関連項目:

- オンライン・デモ・プログラムのOCILobOpen()コールおよびOCILobClose()コールの使用例は、付録Bを参照してください。

- 表C-2「OCILobコール用のサーバー・ラウンドトリップ」

LOB読取りおよび書込みコールバック

OCIでは、読取りおよび書込み用コールバック関数をサポートします。次の項では、コールバックの使用方法を詳しく説明します。

ストリーム転送のコールバック・インタフェース

データの挿入または取出しに使用するユーザー定義の読取りおよび書込み用コールバック関数により、LOBをストリーム転送するためのポーリング・メソッドにかわる方法が提供されます。これらの関数はプログラマが実装し、OCILobRead2()コール、OCILobWriteAppend2()コールおよびOCILobWrite2()コールを通じてOCIに登録します。これらのコールバック関数は、必要に応じてOCIでコールします。

コールバックを使用したLOBの読取り

ユーザー定義の読取りコールバック関数は、OCILobRead2()関数を通じて登録されます。コールバック関数には次のプロトタイプが必要です。

CallbackFunctionName ( void *ctxp, CONST void *bufp, oraub8 len, ub1 piece,
void **changed_bufpp, oraub8 *changed_lenp);

最初のパラメータのctxpはコールバックのコンテキストで、OCILobRead2()関数コールでOCIに渡されます。コールバック関数がコールされると、ctxpで提供した情報が戻されます(OCIがINの途中でこの情報を使用することはありません)。OCILobRead2()内のbufpパラメータは、LOBデータが戻される格納場所へのポインタで、buflはこのバッファの長さを表します。これにより、指定したバッファに読み取られたデータの量がわかります。

元のOCILobRead2()コールで提供したバッファの長さが、サーバーから戻されるデータをすべて格納するのに十分でない場合は、ユーザー定義コールバックがコールされます。この場合、pieceパラメータにより、バッファに戻された情報が最初のピース、次のピースまたは最後のピースのどれであるかが示されます。

changed_bufppパラメータとchanged_lenpパラメータは、コールバック関数内で使用すると、バッファを動的に変更できます。changed_bufppパラメータは変更されたバッファのアドレスを指し、changed_lenpパラメータは変更されたバッファの長さを指します。changed_bufppパラメータとchanged_lenpパラメータは、アプリケーションでバッファが動的に変更されない場合、コールバック関数内で使用する必要はありません。

例7-2では、OCILobRead2()関数を使用して、読取りコールバック関数を実装するコード・フラグメントを示しています。loblは前もって選択してある有効なロケータ、svchpは有効なサービス・ハンドル、errhpは有効なエラー・ハンドルであると想定します。この例では、すべてのLOBデータが読み取られるまで、ユーザー定義関数cbk_read_lob()が繰り返しコールされます。

例7-2 OCILobRead2()を使用した読取りコールバック関数の実装

...
oraub8   offset = 1;
oraub8   loblen = 0;
oraub8   byte_amt = 0;
oraub8   char_amt = 0
ub1      bufp[MAXBUFLEN];

sword retval;
byte_amtp = 4294967297;     /* 4 gigabytes plus 1 */

if (retval = OCILobRead2(svchp, errhp, lobl, &byte_amt, &char_amt, offset,
(void *) bufp, (oraub8) MAXBUFLEN, (void *) 0, OCI_FIRST_PIECE,
cbk_read_lob, (ub2) 0, (ub1) SQLCS_IMPLICIT))
{
(void) printf("ERROR: OCILobRead2() LOB.\n");
report_error();
}
...
sb4 cbk_read_lob(ctxp, bufxp, len, piece, changed_bufpp, changed_lenp)
void       *ctxp;
CONST void *bufxp;
oraub8      len;
ub1         piece;
void       **changed_bufpp;
oraub8      *changed_lenp;
{
static ub4 piece_count = 0;
piece_count++;

switch (piece)
{
case OCI_LAST_PIECE:     /*--- buffer processing code goes here ---*/
(void) printf("callback read the %d th piece\n\n", piece_count);
piece_count = 0;
break;
case OCI_FIRST_PIECE:   /*--- buffer processing code goes here ---*/
(void) printf("callback read the %d th piece\n", piece_count);
/* --Optional code to set changed_bufpp and changed_lenp if the
buffer must be changed dynamically --*/
break;
case OCI_NEXT_PIECE:   /*--- buffer processing code goes here ---*/
(void) printf("callback read the %d th piece\n", piece_count);
/* --Optional code to set changed_bufpp and changed_lenp if the
buffer must be changed dynamically --*/
break;
default:
(void) printf("callback read error: unknown piece = %d.\n", piece);
return OCI_ERROR;
}
return OCI_CONTINUE;
}

コールバックを使用したLOBの書込み

読取りコールバックと同様に、ユーザー定義の書込みコールバック関数が、OCILobWrite2()関数を通じて登録されます。コールバック関数には次のプロトタイプが必要です。

CallbackFunctionName ( void *ctxp, void *bufp, oraub8 *lenp, ub1 *piecep,
void **changed_bufpp, oraub8 *changed_lenp);

最初のパラメータのctxpはコールバックのコンテキストで、OCILobWrite2()関数コールでOCIに渡されます。OCIでコールバック関数がコールされると、ctxpで提供した情報が戻されます(OCIがINの途中でこの情報を使用することはありません)。bufpパラメータは記憶領域へのポインタで、OCILobWrite2()へのコールで指定されます。

コールで指定するデータをOCILobWrite2()に挿入した後も、残りのデータがユーザー定義コールバックによって挿入されます。コールバックでは、bufpによって示される記憶域に挿入するデータを指定し、またその長さをlenpに指定します。さらに、piecepパラメータを使用して、次のピース(OCI_NEXT_PIECE)か最後のピース(OCI_LAST_PIECE)か示します。アプリケーションで提供される記憶域ポインタにより、記憶域の割当てサイズより大きいデータが書き込まれないことを確認する必要があります。

changed_bufppパラメータとchanged_lenpパラメータは、コールバック関数内で使用すると、バッファを動的に変更できます。changed_bufppパラメータは変更されたバッファのアドレスを指し、changed_lenpパラメータは変更されたバッファの長さを指します。changed_bufppパラメータとchanged_lenpパラメータは、アプリケーションでバッファが動的に変更されない場合、コールバック関数内で使用する必要はありません。

例7-3では、OCILobWrite2()関数を使用して、書込みコールバック関数を実装するコード・フラグメントを示しています。loblは更新用にロックされている有効なロケータ、svchpは有効なサービス・ハンドル、errhpは有効なエラー・ハンドルであると想定しています。ユーザー定義関数cbk_write_lob()は、アプリケーションが最後のピースを提供していることをpiecepパラメータが示すまで繰り返しコールされます。

例7-3 OCILobWrite2()を使用した書込みコールバック関数の実装

...

ub1      bufp[MAXBUFLEN];
oraub8   byte_amt = MAXBUFLEN * 20;
oraub8   char_amt = 0;
oraub8   offset = 1;
oraub8   nbytes = MAXBUFLEN;

/*-- code to fill bufp with data goes here. nbytes should reflect the size and
should be less than or equal to MAXBUFLEN --*/
if (retval = OCILobWrite2(svchp, errhp, lobl, &byte_amt, &char_amt, offset,
(void*)bufp, (ub4)nbytes, OCI_FIRST_PIECE, (void *)0, cbk_write_lob,
(ub2) 0, (ub1) SQLCS_IMPLICIT))
{
(void) printf("ERROR: OCILobWrite2().\n");
report_error();
return;
}
...
sb4 cbk_write_lob(ctxp, bufxp, lenp,  piecep, changed_bufpp, changed_lenp)
void    *ctxp;
void    *bufxp;
oraub8  *lenp;
ub1       *piecep;
void  **changed_bufpp;
oraub8  *changed_lenp;
{
/*-- code to fill bufxp with data goes here. *lenp should reflect the
size and should be less than or equal to MAXBUFLEN -- */
/* --Optional code to set changed_bufpp and changed_lenp if the
buffer must be changed dynamically --*/
if (this is the last data buffer)
*piecep = OCI_LAST_PIECE;
else
*piecep = OCI_NEXT_PIECE;
return OCI_CONTINUE;
}

一時LOBのサポート

OCIでは、一時LOBの作成および解放のための関数OCILobCreateTemporary()およびOCILobFreeTemporary()と、LOBが一時LOBであるかどうかを判断する関数OCILobIsTemporary()が提供されています。

一時LOBは、データベース内に永続的に格納されることはありませんが、LOBデータを操作するために、ローカル変数のように動作します。標準(永続) LOB上で動作するOCI関数は、一時LOB上でも使用できます。

永続LOBと同様に、すべての関数は一時LOBのロケータ上で動作し、実際のLOBデータにはロケータを介してアクセスされます。

一時LOBロケータは、次の型のSQL文への引数として使用できます。

- UPDATE: 一時LOBロケータは、NULLかどうかのテスト時にWHERE句内の値として使用するか、あるいは関数へのパラメータとして使用できます。ロケータは、SET句内で使用することもできます。

- DELETE: 一時LOBロケータは、NULLかどうかのテスト時にWHERE句内で使用するか、あるいは関数へのパラメータとして使用できます。

- SELECT: 一時LOBロケータは、NULLかどうかのテスト時にWHERE句内で使用するか、あるいは関数へのパラメータとして使用できます。また、一時LOBは、関数の戻り値を選択する場合、SELECT...INTO文で戻される変数として使用することもできます。

注意:
永続ロケータを一時ロケータに選択した場合、一時ロケータは永続ロケータによって上書きされます。この場合、一時LOBは暗黙的には解放されません。ユーザーはSELECT...INTO操作の前に一時LOBを明示的に解放する必要があります。明示的に解放しなければ、一時LOBは指定したdurationの終了時まで解放されません。同じLOBを指し示している別の一時ロケータがなければ、元のロケータはSELECT...INTOによって上書きされるため、その一時LOBを指し示すロケータはなくなります。

一時LOBの作成および解放

OCILobCreateTemporary()関数を使用して一時LOBを作成します。この関数に渡されるパラメータには、LOBの継続時間を示す値が含まれています。デフォルトの継続時間は、カレント・セッションの長さです。継続時間の終了時に、すべての一時LOBが削除されます。ユーザーは、OCILobFreeTemporary()関数で一時LOBを明示的に解放することによって、一時LOBの領域を再生できます。一時LOBは、作成されたときは空の状態です。

一時LOBを作成するとき、その一時LOBがサーバーのバッファ・キャッシュに読み取られるかどうかも指定できます。

一時LOBを永続的にするには、OCILobCopy2()を使用して、データを一時LOBから永続LOBにコピーします。また、一時LOBをINSERT文のVALUES句で使用したり、UPDATE文内の割当てのソースとして使用したり、あるいは一時LOBを通常の永続LOB属性に割り当てて、オブジェクトをフラッシュできます。一時LOBは、標準LOBに使用する関数と同じ関数を使用して変更できます。

注意:
空のLOBを挿入する最も効率的な方法は、値が割り当てられていない一時LOBのバインドです。これは、次のメソッドより使用するリソースが少なくてすみます。

INSERT INTO tab1 VALUES(EMPTY_CLOB())

一時LOBの継続時間

OCIでは、いくつかの一時LOB用の事前定義済継続時間、およびアプリケーションでアプリケーション固有の継続時間を定義するために使用できる関数のセットが用意されています。事前定義済の継続時間とその関連属性は、次のとおりです。

- コール(OCI_DURATION_CALL)、サーバー側のみ

- セッション(OCI_DURATION_SESSION)

セッション継続時間は、セッションまたは接続が終了した時点で期限切れになります。コール継続時間は、現行のOCIコールが終了した時点で期限切れになります。

オブジェクト・モードで実行している場合は、アプリケーション固有の継続時間も定義できます。アプリケーション固有の継続時間はユーザー期間とも呼ばれ、OCIDurationBegin()を使用して継続開始時間を指定し、OCIDurationEnd()を使用して継続終了時間を指定することによって定義されます。

注意:
ユーザー定義の継続時間は、アプリケーションがオブジェクト・モードで初期化されている場合にのみ利用できます。

アプリケーション固有の継続時間にはそれぞれ、OCIDurationBegin()で戻される継続時間識別子があり、OCIDurationEnd()がコールされるまで一意であることが保証されます。アプリケーション固有の継続時間は、セッションの継続時間と同じに設定できます。

継続時間の終了時には、その継続時間に関連付けられたすべての一時LOBが解放されます。一時LOBに関連付けられた記述子は、OCIDescriptorFree()コールを使用して明示的に解放する必要があります。

ユーザー継続時間はネストできるため、1つの継続時間を別のユーザー継続時間の子継続時間として定義できます。親の継続時間が子の継続時間を持ち、その子が自分の子の継続時間を持つことも可能です。

注意:
継続時間がOCIDurationBegin()で開始されると、パラメータの1つは親の継続時間の識別子となります。親の継続時間が終了すると、子の継続時間もすべて終了します。

一時LOBの解放

OCIプログラムがSQLまたはPL/SQLからLOBロケータを取得するたびに、OCILobIsTemporary()関数を使用して、一時ロケータかどうかをチェックします。そうである場合は、ロケータによってアプリケーションが終了される際、OCILobFreeTemporary()コールを使用してロケータを解放します。ロケータは、SELECTまたはOUT BIND中にDEFINEから取得できます。一時LOBの継続期間は、クライアント側に受け渡されるときに、常にセッション継続期間にアップグレードされます。アプリケーションでは、ロケータが次行のロケータで上書きされる前に次の関数を実行する必要があります。

OCILobIsTemporary(env, err, locator, is_temporary);
if(is_temporary)
OCILobFreeTemporary(svc, err, locator);

関連項目:

- 「OCILobIsTemporary()」

- 「OCILobFreeTemporary()」

ポインタを割り当てる際の注意事項

OCILobLocatorポインタを割り当てるときは、特に注意が必要です。ポインタ割当てにより、LOBの簡単なコピーが作成されます。ポインタの割当て後は、ソースLOBおよびターゲットLOBはデータの同じコピーを指します。これは、割当てを実行するOCILobAssign()またはOCILobLocatorAssign()などのLOB APIを使用するのとは異なります。APIを使用すると、ロケータは割当て後にデータの個別のコピーを論理的に指します。

一時LOBの場合、ポインタ割当て前に、ターゲットとなるLOBロケータの一時LOBが、OCILobFreeTemporary()によって解放されることを確認する必要があります。OCILobLocatorAssign()を使用すると、割当てが発生する前に、ターゲットLOBロケータ変数の元の一時LOB(ある場合)が解放されます。

SQL文の実行において、OUTバインド変数を再利用する前に、OCILobFreeTemporary()コールを使用して、既存のOUTバインドLOBロケータ・バッファ内の一時LOBを解放する必要があります。

関連項目:

- 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の一時LOBのパフォーマンスのガイドラインに関する項

- 一時LOBの最適なパフォーマンスの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

一時LOBの例

例7-4は、一時LOBをどのように使用できるかを示しています。

例7-4 一時LOBの使用方法

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <oci.h>

/* Function Prototype */
static void checkerr (/*_ OCIError *errhp, sword status _*/);
sb4 select_and_createtemp (OCILobLocator *lob_loc,
OCIError      *errhp,
OCISvcCtx     *svchp,
OCIStmt       *stmthp,
OCIEnv        *envhp);
/* This function reads in a single video frame from the print_media table.
Then it creates a temporary LOB. The temporary LOB that is created is read
through the CACHE, and is automatically cleaned up at the end of the user's
session, if it is not explicitly freed sooner. This function returns OCI_SUCCESS
if it completes successfully or OCI_ERROR if it fails. */

sb4 select_and_createtemp (OCILobLocator *lob_loc,
OCIError      *errhp,
OCISvcCtx     *svchp,
OCIStmt       *stmthp,
OCIEnv        *envhp)
{
OCIDefine     *defnp1;
OCIBind       *bndhp;
text          *sqlstmt;
int rowind =1;
ub4 loblen = 0;
OCILobLocator *tblob;
printf ("in select_and_createtemp \n");
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;
}
/* arbitrarily select where Clip_ID =1 */
sqlstmt=(text *)"SELECT Frame FROM print_media WHERE product_ID = 1 FOR UPDATE";
if (OCIStmtPrepare(stmthp, errhp, sqlstmt, (ub4) strlen((char *)sqlstmt),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT))
{
(void) printf("FAILED: OCIStmtPrepare() sqlstmt\n");
return OCI_ERROR;
}
/* Define for BLOB */
if (OCIDefineByPos(stmthp, &defnp1, errhp, (ub4)1, (void *) &lob_loc, (sb4)0,
(ub2) SQLT_BLOB, (void *)0, (ub2 *)0, (ub2 *)0, (ub4) OCI_DEFAULT))
{
(void) printf("FAILED: Select locator: OCIDefineByPos()\n");
return OCI_ERROR;
}
/* Execute the select and fetch one row */
if (OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4) 0,
(CONST OCISnapshot*) 0, (OCISnapshot*) 0, (ub4) OCI_DEFAULT))
{
(void) printf("FAILED: OCIStmtExecute() sqlstmt\n");
return OCI_ERROR;
}
if(OCILobCreateTemporary(svchp, errhp, tblob, (ub2)0, SQLCS_IMPLICIT,
OCI_TEMP_BLOB, OCI_ATTR_NOCACHE, OCI_DURATION_SESSION))
{
(void) printf("FAILED: CreateTemporary() \n");
return OCI_ERROR;
}
if (OCILobGetLength(svchp, errhp, lob_loc, &loblen) != OCI_SUCCESS)
{
printf("OCILobGetLength FAILED\n");
return OCI_ERROR;
}
if (OCILobCopy(svchp, errhp, tblob,lob_loc,(ub4)loblen, (ub4) 1, (ub4) 1))
{
printf( "OCILobCopy FAILED \n");
}
if(OCILobFreeTemporary(svchp,errhp,tblob))
{
printf ("FAILED: OCILobFreeTemporary call \n");
return OCI_ERROR;
}
return OCI_SUCCESS;
}
int main(char *argv, int argc)
{
/* OCI Handles */
OCIEnv        *envhp;
OCIServer     *srvhp;
OCISvcCtx     *svchp;
OCIError      *errhp;
OCISession    *authp;
OCIStmt       *stmthp;
OCILobLocator *clob, *blob;
OCILobLocator *lob_loc;
int type =1;
/* Initialize and Log on */
OCIEnvCreate(&envhp, OCI_DEFAULT, (void *)0, 0, 0, 0,
(size_t)0, (void *)0);
(void) OCIHandleAlloc( (void *) envhp, (void **) &errhp, OCI_HTYPE_ERROR,
(size_t) 0, (void **) 0);
/* server contexts */
(void) OCIHandleAlloc( (void *) envhp, (void **) &srvhp, OCI_HTYPE_SERVER,
(size_t) 0, (void **) 0);
/* service context */
(void) OCIHandleAlloc( (void *) envhp, (void **) &svchp, OCI_HTYPE_SVCCTX,
(size_t) 0, (void **) 0);
/* attach to Oracle Database */
(void) OCIServerAttach( srvhp, errhp, (text *)"", strlen(""), 0);
/* set attribute server context in the service context */
(void) OCIAttrSet ((void *) svchp, OCI_HTYPE_SVCCTX,
(void *)srvhp, (ub4) 0,
OCI_ATTR_SERVER, (OCIError *) errhp);
(void) OCIHandleAlloc((void *) envhp,
(void **)&authp, (ub4) OCI_HTYPE_SESSION,
(size_t) 0, (void **) 0);
(void) OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_SESSION,
(void *) "scott", (ub4)5,
(ub4) OCI_ATTR_USERNAME, errhp);
(void) OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_SESSION,
(void *) "password", (ub4) 5,
(ub4) OCI_ATTR_PASSWORD, errhp);
/* Begin a User Session */
checkerr(errhp, OCISessionBegin ( svchp,  errhp, authp, OCI_CRED_RDBMS,
(ub4) OCI_DEFAULT));
(void) OCIAttrSet((void *) svchp, (ub4) OCI_HTYPE_SVCCTX,
(void *) authp, (ub4) 0,
(ub4) OCI_ATTR_SESSION, errhp);
/* ------- Done logging in ----------------------------------*/
/* allocate a statement handle */
checkerr(errhp, OCIHandleAlloc( (void *) envhp, (void **) &stmthp,
OCI_HTYPE_STMT, (size_t) 0, (void **) 0));
checkerr(errhp, OCIDescriptorAlloc((void *)envhp, (void **)&lob_loc,
(ub4) OCI_DTYPE_LOB, (size_t) 0, (void **) 0));
/* Subroutine calls begin here */
printf("calling select_and_createtemp\n");
select_and_createtemp (lob_loc, errhp, svchp,stmthp,envhp);
return 0;
}
void checkerr(errhp, status)
OCIError *errhp;
sword status;
{
text errbuf[512];
sb4 errcode = 0;
switch (status)
{
case OCI_SUCCESS:
break;
case OCI_SUCCESS_WITH_INFO:
(void) printf("Error - OCI_SUCCESS_WITH_INFO\n");
break;
case OCI_NEED_DATA:
(void) printf("Error - OCI_NEED_DATA\n");
break;
case OCI_NO_DATA:
(void) printf("Error - OCI_NODATA\n");
break;
case OCI_ERROR:
(void) OCIErrorGet((void *)errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), OCI_HTYPE_ERROR);
(void) printf("Error - %.*s\n", 512, errbuf);
break;
case OCI_INVALID_HANDLE:
(void) printf("Error - OCI_INVALID_HANDLE\n");
break;
case OCI_STILL_EXECUTING:
(void) printf("Error - OCI_STILL_EXECUTE\n");
break;
case OCI_CONTINUE:
(void) printf("Error - OCI_CONTINUE\n");
break;
default:
break;
}
}

LOBデータ、長さおよびチャンク・サイズのプリフェッチ

小さいLOBのOCIアクセスを改善するために、LOBデータをプリフェッチしてキャッシュする間にロケータもフェッチできます。これは内部LOB、一時LOBおよびBFILEに適用されます。アプリケーションを準備するには、次のステップに従います。

1. セッション・ハンドルのOCI_ATTR_DEFAULT_LOBPREFETCH_SIZE属性を設定します。この属性の値は、LOBロケータのデフォルトのプリフェッチ・データ・サイズを示します。この属性値により、セッション中にフェッチされる全LOBロケータのプリフェッチが可能になります。この属性のデフォルト値は0 (LOBデータのプリフェッチなし)です。このオプションにより、アプリケーション開発者は定義ハンドルごとにプリフェッチLOBサイズを設定する必要がなくなります。この属性を設定するか、または(ステップ3で)OCI_ATTR_LOBPREFETCH_SIZEを設定することができます。

2. 実行する文の準備ステップと定義ステップを実行します。

3. 必要な場合は、定義ハンドルのOCI_ATTR_LOBPREFETCH_SIZE属性を設定して、フェッチするLOBロケータのデフォルト・プリフェッチ・サイズをオーバーライドできます。このオプション属性では、特定の列からフェッチされるロケータのプリフェッチ・サイズを制御できます。

4. OCI_ATTR_LOBPREFETCH_LENGTH属性を、プリフェッチするLOBの長さおよびチャンク・サイズに設定します。

5. 文を実行します。

6. 個別のLOBロケータを指定してOCILobRead2()またはOCILobArrayRead()をコールします。OCIによりプリフェッチ・バッファからデータが取得され、必要な文字変換が実行され、データがLOB読取りバッファにコピーされます(LOBセマンティクスは変更されません)。要求されたデータがプリフェッチ・バッファより大きい場合は、追加のラウンドトリップが必要になります。

7. OCILobGetLength2()およびOCILobGetChunkSize()をコールして、サーバーへのラウンドトリップなしで長さとチャンク・サイズを取得します。

プリフェッチ・サイズは、BLOBおよびBFILEの場合はバイト数、CLOBの場合は文字数であることに注意してください。

例7-5では、これらのステップを説明するコード・フラグメントを示しています。

例7-5 LOBデータ、長さおよびチャンク・サイズのプリフェッチ

...
ub4 default_lobprefetch_size = 2000;                  /* Set default size to 2K */
...
/* set LOB prefetch attribute to session */
OCIAttrSet (sesshp, (ub4) OCI_HTYPE_SESSION,
(void *)&default_lobprefetch_size,               /* attribute value */
0,                      /* attribute size; not required to specify; */
(ub4) OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE,
errhp);
...
/* select statement */
char *stmt = "SELECT lob1 FROM lob_table";
...
/* declare and allocate LOB locator */
OCILobLocator * lob_locator;
lob_locator = OCIDescriptorAlloc(..., OCI_DTYPE_LOB, ...);

OCIDefineByPos(..., 1, (void *) &lob_locator, ..., SQLT_CLOB, ...);
...
/* Override the default prefetch size to 4KB */
ub4 prefetch_size = 4000;
OCIAttrSet (defhp,  OCI_HTYPE_DEFINE,
(void *) &prefetch_size                             /* attr value */,
0                  /* restricting prefetch size to be ub4 max val */,
OCI_ATTR_LOBPREFETCH_SIZE                            /* attr type */,
errhp);
...
/* Set prefetch length attribute */
boolean prefetch_length = TRUE;
OCIAttrSet( defhp,  OCI_HTYPE_DEFINE,
(dvoid *) &prefetch_length  /* attr value */,
0,
OCI_ATTR_LOBPREFETCH_LENGTH  /* attr type */,
errhp );
...
/* execute the statement. 4KB of data for the LOB is read and
* cached in descriptor cache buffer.
*/
OCIStmtExecute (svchp, stmthp, errhp,
1,               /* iters */
0,               /* row offset */
NULL,            /* snapshot IN */
NULL,            /* snapshot out */
OCI_DEFAULT);    /* mode */
...
oraub8 char_amtp = 4000;
oraub8 lob_len;
ub4 chunk_size;

/* LOB chunk size, length, and data are read from cache. No round-trip. */

OCILobGetChunkSize (svchp, errhp, lob_locator, &chunk_size);

OCILobGetLength2(svchp, errhp, lob_locator, &lob_len );

OCILobRead2(svchp, errhp, lob_locator, NULL, &char_amtp, ...);
...

プリフェッチ・キャッシュ割当て: 記述子用のプリフェッチ・キャッシュ・バッファは、LOBロケータをフェッチするときに割り当てられます。割り当てられるバッファ・サイズは、定義ハンドルのOCI_ATTR_LOBPREFETCH_SIZE属性によって決定され、この属性のデフォルト値は、セッション・ハンドルのOCI_ATTR_DEFAULT_LOBPREFETCH_SIZE属性値によって示されます。キャッシュ・バッファがすでに割り当てられている場合は、必要に応じてサイズ変更します。

次の2つのLOB APIの場合、ソース・ロケータにキャッシュされたデータがあると、宛先ロケータのキャッシュが割り当てられるかサイズ変更され、キャッシュ・データがソースから宛先にコピーされます。

- OCILobAssign()

- OCILobLocatorAssign()

記述子用に割り当てられたキャッシュ・バッファ・メモリーは、記述子自体が解放されるときに解放されます。

プリフェッチ・キャッシュの無効化: 記述子用のキャッシュは、ロケータを使用してLOBデータが更新されるときに無効化されます。これは、そのキャッシュがデータの読取りに使用されなくなり、ロケータでの次のOCILobRead2()コールでラウンドトリップが発生することを意味します。

次のLOB APIにより、使用された記述子用のプリフェッチ・キャッシュが無効化されます。

- OCILobErase() (非推奨)

- OCILobErase2()

- OCILobTrim() (非推奨)

- OCILobTrim2()

- OCILobWrite() (非推奨)

- OCILobWrite2()

- OCILobWriteAppend() (非推奨)

- OCILobWriteAppend2()

- OCILobArrayWrite()

次のLOB APIにより、宛先LOBロケータ用のキャッシュが無効化されます。

- OCILobAppend()

- OCILobCopy() (非推奨)

- OCILobCopy2()

- OCILobLoadFromFile() (非推奨)

- OCILobLoadFromFile2()

パフォーマンス・チューニング: プリフェッチ・バッファのサイズは、平均LOBサイズとクライアント側のメモリーに基づいて決定する必要があります。大量のデータがプリフェッチされる場合は、メモリーの可用性を確認する必要があります。データ・フェッチに伴うコストの方がサーバーへのラウンドトリップに伴うコストよりも大きいため、大きいLOBをプリフェッチする場合には、大幅なパフォーマンス向上は期待できない可能性があります。

このLOBプリフェッチ機能を活用できるように、LOBデータ・サイズを適正に考慮する必要があります。パラメータはアプリケーション設計の一部であるため、パラメータ値の変更が必要になれば、アプリケーションを再作成する必要があります。

関連項目:

- 「OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE」

- 「OCI_ATTR_LOBPREFETCH_LENGTH」

- 「OCI_ATTR_LOBPREFETCH_SIZE」

アップグレード: リリース11.1より前のサーバー、リリース11.1以降のサーバーに対するリリース11.1より前のクライアントには、LOBプリフェッチを使用できません。リリース11.1より前のサーバーをリリース11.1以降のクライアントに対して使用している場合、OCIAttrSet()からエラー、または、この機能がサーバーでサポートされていないという旨のエラー・メッセージが戻されます。

SecureFiles LOBのオプション

SecureFiles (Oracle Database 11gリリース1で導入されたSTORE AS SECUREFILEオプションを使用するLOB)の場合、CREATE TABLEおよびALTER TABLE文にSQLパラメータDEDUPLICATEを指定できます。このパラメータにより、LOB列の複数行で同一のLOBデータが同じデータ・ブロックを共有するように指定して、ディスク領域を節約できます。この機能をオフにするには、KEEP_DUPLICATESを使用します。次の各オプションも、SECUREFILEとともに使用されます。

パラメータCOMPRESSでは、LOB圧縮をオンにします。NOCOMPRESSでは、LOB圧縮をオフにします。

パラメータENCRYPTでは、LOB暗号化をオンにして、オプションで暗号化アルゴリズムを選択します。NOENCRYPTでは、LOB暗号化をオフにします。各LOB列には、他のLOB列または非LOB列の暗号化に関係なく、独自の暗号化仕様を設定できます。有効なアルゴリズムは、3DES168、AES128、AES192およびAES256です。

リリース11.1より前に使用されていたLOBパラタイムがデフォルトです。このデフォルトのLOBパラダイムは、オプションSTORE AS BASICFILEでも明示的に設定されます。

次のOCI関数が、SECUREFILE機能で使用されます。

- OCILobGetOptions()

- OCILobSetOptions()

- OCILobGetContentType()

- OCILobSetContentType()

関連項目:
関連SQL関数とPL/SQLパッケージの相互参照の詳細と、SecureFilesへの移行については、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

8 スケーラブルなプラットフォームの管理

この章は、次の項目で構成されています。

- OCIでのトランザクションのサポート

- トランザクションの複雑度のレベル

- パスワードおよびセッションの管理

- OCIでの中間層アプリケーション

- 外部でOCIから初期化されたコンテキスト

- クライアント・アプリケーション・コンテキスト

- Editionベースの再定義

- OCIセキュリティ拡張機能

- OCIマルチスレッド開発の概要

- OCIThreadパッケージ

OCIでのトランザクションのサポート

OCIには、ローカル・トランザクションとグローバル・トランザクションの両方での操作に対応した一連のAPIコールが用意されています。これらのコールにはオブジェクトのサポートが含まれているため、OCIアプリケーションがオブジェクト・モードで実行されている場合は、コミット・コールおよびロールバック・コールでオブジェクト・キャッシュとトランザクションの状態が同期します。

トランザクション操作を実行する関数は、次のとおりです。それぞれのコールは、適切なサーバー・コンテキストおよびユーザー・セッション・ハンドルで初期化する必要がある、サービス・コンテキスト・ハンドルを取ります。トランザクション・ハンドルは、サービス・コンテキストの3番目の要素で、トランザクションに関する特定の情報を格納します。SQL文が準備されると、トランザクション・ハンドルは、特定のサービス・コンテキストと関連付けられます。その文が実行されると、その結果(問合せ、フェッチ、挿入)は、サービス・コンテキストと現在関連しているトランザクションの一部になります。

- OCITransStart()は、トランザクションの開始をマークします。

- OCITransDetach()は、トランザクションを連結解除します。

- OCITransCommit()は、トランザクションをコミットします。

- OCITransRollback()は、トランザクションをロールバックします。

- OCITransPrepare()は、分散処理環境でトランザクションをコミットする準備をします。

- OCITransMultiPrepare()は、1回のコールで、複数のブランチのあるトランザクションを準備します。

- OCITransForget()は、発見的に完了したグローバル・トランザクションの記憶をサーバーから消します。

これらのコールをすべて使用するか、そのうちのいくつかのみを使用するかは、アプリケーションでのトランザクションの複雑度のレベルによって異なります。次の項で、詳細に説明します。

関連項目:
「トランザクション関数」

トランザクションの複雑度のレベル

OCIでは、次のトランザクションの複雑度レベルをサポートします。

- 単純なローカル・トランザクション

- シリアライズ可能または読取り専用のローカル・トランザクション

- グローバル・トランザクション

単純なローカル・トランザクション

ほとんどのアプリケーションで扱うのは、単純なローカル・トランザクションのみです。これらのアプリケーションでは、そのアプリケーションの中でデータベースを変更すると、暗黙的トランザクションが作成されます。アプリケーションなどで必要とされるトランザクション特有のコールには、次のようなコールがあります。

- OCITransCommit(): トランザクションをコミットします。

- OCITransRollback(): トランザクションをロールバックします。

1つのトランザクションがコミットまたはロールバックするとすぐに、次のデータベース変更によって、そのアプリケーションに対する新規の暗黙的トランザクションが作成されます。

1つのサービス・コンテキストでは、常に1つの暗黙的トランザクションのみをアクティブにできます。暗黙的なトランザクションの属性は、ユーザーには不透明です。

アプリケーションで複数のセッションを作成すると、それぞれの権限に対し、関連する暗黙的トランザクションを1つずつ保持することができます。

関連項目:
単純なローカル・トランザクションの使用方法を示すコード例は、「OCITransCommit()」を参照してください。

シリアライズ可能または読取り専用のローカル・トランザクション

アプリケーションでシリアライズ可能または読取り専用トランザクションが必要な場合は、トランザクションを開始する追加のOCIのOCITransStart()コールが必要です。

OCITransStart()コールでは、flagsパラメータに対して、OCI_TRANS_SERIALIZABLEまたはOCI_TRANS_READONLYの適切な値を指定する必要があります。フラグが指定されない場合、デフォルト値は、標準の読取り/書込みトランザクションのOCI_TRANS_READWRITEです。

OCITransStart()コールで読取り専用オプションを指定すると、SET TRANSACTION READ ONLY文を実行するためのサーバー・ラウンドトリップは必要ありません。

グローバル・トランザクション

グローバル・トランザクションは、より高度なトランザクションを処理するアプリケーションでのみ必要です。

トランザクション識別子

トランザクション処理(TP)モニターなどの3層アプリケーションでは、グローバル・トランザクションの作成および管理を行います。これらは、グローバル・トランザクション識別子(XID)を提供し、これによって、サーバーにローカル・トランザクションが関連付けられます。

1つのグローバル・トランザクションには、1つ以上のブランチがあります。それぞれのブランチは、XIDによって識別されます。XIDは、グローバル・トランザクション識別子(gtrid)およびブランチ修飾子(bqual)から構成されます。この構造は、標準のXA仕様に基づくものです。

表8-1では、1つの考えられる1234というXIDの構造を示しています。

表8-1 グローバル・トランザクション識別子

コンポーネント

値

gtrid

12

bqual

34

gtrid+bqual=XID

1234

OCIトランザクション・コールで使用されるトランザクション識別子は、OCIAttrSet()を使用して、トランザクション・ハンドルのOCI_ATTR_XID属性で設定します。かわりに、OCI_ATTR_TRANS_NAME属性で設定した名前でトランザクションを識別することもできます。

OCI_ATTR_TRANS_NAME属性

この属性をトランザクション・ハンドルで設定するときは、名前の長さは最大64バイトです。XIDのformatidは0 (ゼロ)で、ブランチ修飾子も0 (ゼロ)です。

この属性をトランザクション・ハンドルから取り出すときは、戻されたトランザクション名はグローバル・トランザクション識別子となります。サイズはグローバル・トランザクション識別子の長さとなります。

トランザクション・ブランチ

単一のグローバル・トランザクションで、一対のブランチが密結合している場合と疎結合している場合の両方をサポートしています。

- 密結合ブランチは同じローカル・トランザクションを共有します。この場合、gtridは、一意のローカル・トランザクションを参照し、複数のブランチが同じトランザクションを指し示します。トランザクションの所有者は、最初に作成されたブランチです。

- 疎結合ブランチは異なるローカル・トランザクションを使用します。gtridとbqualがともに一意のローカル・トランザクションにマッピングされます。各ブランチは、異なるトランザクションを指し示します。

OCITransStart()のflagsパラメータによって、アプリケーションからOCI_TRANS_TIGHT値またはOCI_TRANS_LOOSE値を渡して、結合のタイプを指定できます。

セッションはOCISessionBegin()で作成され、ユーザー・セッションに対応します。

図8-1では、あるアプリケーションの密結合ブランチを説明します。2つのブランチ(B1とB2)のXIDは、同じトランザクション(T)で操作されているので、同じgtridを共有しますが、これらは別々のブランチなので、異なるbqualを持ちます。

図8-1 複数の密結合ブランチ

図8-2では、異なるブランチでの単一セッションの操作を説明します。XIDのgtridコンポーネンは、別々のグローバル・トランザクション表すために異なります。

図8-2 複数のブランチで動作するセッション

同じトランザクションを共有する複数のブランチを単一セッションで操作することも可能ですが、これはあまり実用的ではありません。

関連項目:
この場合のコード例は、「OCITransStart()」を参照してください。

ブランチの状態

トランザクションのブランチには、アクティブ・ブランチと非アクティブ・ブランチの2通りの状態があります。

サーバー・プロセスがブランチに対する要求を実行しているとき、ブランチはアクティブ状態です。サーバー・プロセスがブランチ内の要求を実行していないとき、ブランチは非アクティブ状態です。この場合は、ブランチの親セッションは1つもなく、ブランチはサーバーのPMONプロセスに所有されます。

ブランチの連結解除と再開

OCIアプリケーションがOCITransDetach()コールを使用してブランチを連結解除すると、ブランチは非アクティブ状態になります。flagsパラメータにOCI_TRANS_RESUMEを設定したOCITransStart()のコールを使用してブランチを再開すると、ブランチを再びアクティブにできます。

アプリケーションでOCITransDetach()をコールし、ブランチを連結解除する場合は、そのブランチを作成したOCITransStart()コールのtimeoutパラメータで指定した値を利用します。timeoutパラメータで指定した秒数が経過すると、PMONの子として休止しているトランザクションは削除されます。

アプリケーションでブランチを再開するには、OCITransStart()をコールし、このときトランザクション・ハンドルの属性としてブランチのXIDを、flagsパラメータにOCI_TRANS_RESUMEを、またtimeoutパラメータには異なる値を指定します。このコールのtimeoutの値は、ブランチが他のプロセスで使用中の場合、セッションでそのブランチが使用可能になるまで待つ時間の長さを指定します。ブランチにアクセスしているプロセスがない場合は、すぐに再開されます。トランザクションは、そのトランザクションを連結解除したプロセス以外のプロセスからでも再開できますが、そのプロセスに、トランザクションを連結解除したプロセスと同じ権限がある場合に限られます。

クライアント・データベース名の設定

サーバー・ハンドルには、OCI_ATTR_EXTERNAL_NAME属性およびOCI_ATTR_INTERNAL_NAME属性があります。これらの属性により、グローバル・トランザクションを実行するときに記録されるクライアント・データベース名を設定します。障害のために準備状態で保留になっている可能性があるトランザクションを追跡するために、データベース管理者がこの名前を使用できます。

注意:
OCIアプリケーションでは、グローバル・トランザクションにログオンして使用する前に、OCIAttrSet()を使用して、これらの属性を設定します。

1フェーズ・コミットと2フェーズ・コミット

グローバル・トランザクションは、1フェーズまたは2フェーズでコミットされます。最も単純な状態は、単一のトランザクションが単一のデータベースに対して操作されている場合です。この場合は、アプリケーションではOCITransCommit()をコールすることによって、このコールのデフォルト値であるトランザクションの1フェーズ・コミットを実行できます。

アプリケーションで、複数のOracle Databaseに対してトランザクションが処理されている場合は、状況はさらに複雑になります。この場合は、2フェーズ・コミットが必要です。2フェーズ・コミット操作は、次のステップからなります。

1. 準備: アプリケーションから各トランザクションに対し、OCITransPrepare()コールを発行します。各トランザクションでは、現行の作業をコミットできるか(OCI_SUCCESS)、できないか(OCI_ERROR)を示す値を戻します。

2. コミット: 各OCITransPrepare()コールがOCI_SUCCESSの値を戻した場合は、アプリケーションから各トランザクションにOCITransCommit()コールを発行できます。このコミット・コールのデフォルトが1フェーズ・コミットであるため、適切な処理を行うためには、このコールのflagsパラメータにOCI_TRANS_TWOPHASEを明示的に設定する必要があります。

注意:
トランザクションが読取り専用であることを示す必要がある場合、OCITransPrepare()コールはOCI_SUCCESS_WITH_INFOも戻します。したがって、コミットは不適切かつ不必要です。

追加のコールOCITransForget()により、完了したトランザクションの情報がデータベースから消えることになります。このコールは、問題が起きて2フェーズ・コミットを終了させる必要がある場合に使用します。Oracle DatabaseでOCITransForget()コールを受け取ると、トランザクションに関する情報はすべて消去されます。

単一のメッセージによる複数のブランチの準備

同じOracle Databaseに対し、複数のアプリケーションでグローバル・トランザクションの異なるブランチが使用される場合があります。そのようなトランザクションをコミットする前に、すべてのブランチを準備する必要があります。

大抵の場合、ブランチを使用しているアプリケーションにはそれぞれ固有のブランチを準備する役割があります。しかし、アーキテクチャによってはこの役割を外部のトランザクション・サービスに求めるものがあります。その場合、外部のトランザクション・サービスで、グローバル・トランザクションの各ブランチを準備してください。従来のOCITransPrepare()コールは、各ブランチを別々に準備する必要があるため、このタスクには非効率的です。OCITransMultiPrepare()コールでは、同じグローバル・トランザクションに含まれる複数のブランチを1ラウンドトリップで準備します。このコールの方が効率がよく、クライアントからサーバーに送られるメッセージ数を大幅に削減できます。

トランザクションの例

表8-1から表8-5までは、トランザクションOCIコールの使用方法を説明しています。

これらは、一連のOCIコールおよびその他の処理を、その処理結果とともに示しています。簡単にするために、これらのコールのパラメータをすべて示すのではなく、コールの流れを解説しています。

OCIの処理列は、OCIアプリケーションの活動やコールの内容を示します。XID列には、必要に応じて、トランザクション識別子がリストされます。フラグ列は、flagsパラメータに渡された値を示します。結果列は、コールの結果を説明します。

初期化パラメータ

グローバル・トランザクション・ブランチおよび移行可能オープン接続の使用に関連する初期化パラメータには、次の2つがあります。

- TRANSACTIONS－ このパラメータでは、システム全体のグローバル・トランザクション・ブランチの最大数を指定します。一方、1つのグローバル・トランザクションの最大ブランチ数は8です。

- OPEN_LINKS_PER_INSTANCE－ このパラメータでは、移行可能オープン接続の最大数を指定します。移行可能オープン接続は、トランザクションをコミットした後に接続をキャッシュできるように、グローバル・トランザクションで使用します。これと対照的に、OPEN_LINKSパラメータは、1セッションからの接続数を制御しますが、グローバル・トランザクションを使用するアプリケーションには適用できません。

更新成功、1フェーズ・コミット

表8-2では、1フェーズ・コミット操作のステップを示しています。

表8-2 1フェーズ・コミット

ステップ

OCIの処理

XID

フラグ

結果

1

OCITransStart()

1234

OCI_TRANS_NEW

新規の読取り/書込みトランザクションを開始する

2

SQL UPDATE

-

-

列を更新する。

3

OCITransCommit()

-

-

コミットが成功する。

トランザクションの開始、連結解除、再開、準備、2フェーズ・コミット

表8-3では、2フェーズ・コミット操作のステップを示しています。

表8-3 2フェーズ・コミット

ステップ

OCIの処理

XID

フラグ

結果

1

OCITransStart()

1234

OCI_TRANS_NEW

新規の読取り専用トランザクションを開始する。

2

SQL UPDATE

-

-

行を更新する。

3

OCITransDetach()

-

-

トランザクションを連結解除する。

4

OCITransStart()

1234

OCI_TRANS_RESUME

トランザクションを再開する。

5

SQL UPDATE

-

-

-

6

OCITransPrepare()

-

-

トランザクションで2フェーズ・コミットを準備する。

7

OCITransCommit()

-

OCI_TRANS_TWOPHASE

トランザクションをコミットする。

ステップ4では、同じ権限を持つ別のプロセスからトランザクションを再開することもできます。

読取り専用トランザクションの更新失敗

表8-4では、読取り専用更新操作の失敗でのステップを示しています。

表8-4 読取り専用トランザクションの更新失敗

ステップ

OCIの処理

XID

フラグ

結果

1

OCITransStart()

1234

OCI_TRANS_NEW |

OCI_TRANS_READONLY

新規の読取り専用トランザクションを開始する。

2

SQL UPDATE

-

-

トランザクションが読取り専用なので、更新は失敗する。

3

OCITransCommit()

-

-

コミットによる影響はありません。

読取り専用トランザクションの開始、選択およびコミット

表8-5では、読取り専用トランザクションのステップを示しています。

表8-5 読取り専用トランザクション

ステップ

OCIの処理

XID

フラグ

結果

1

OCITransStart()

1234

OCI_TRANS_NEW |

OCI_TRANS_READONLY

新規の読取り専用トランザクションを開始する。

2

SQL SELECT

-

-

データベースに問い合せる。

3

OCITransCommit()

-

-

影響なし — トランザクションは読取り専用なので、何も変更なし

パスワードおよびセッションの管理

OCIでは、複数のユーザーを認証および管理できます。

OCIの認証管理

OCISessionBegin()コールは、サービス・コンテキスト・ハンドルに設定されたサーバーに対してユーザーを認証します。指定したサーバー・ハンドルに対して最初にコールする必要があります。OCISessionBegin()は、コールのサーバー・ハンドルおよびサービス・コンテキストで指定したOracle Databaseにアクセスするユーザーを認証します。OCIServerAttach()がサーバー・ハンドルを初期化した後に、OCISessionBegin()をコールしてそのサーバーのユーザーを認証する必要があります。

サーバー・ハンドルに対して、最初にOCISessionBegin()をコールしたとき、ユーザー・セッションは、移行可能モード(OCI_MIGRATE)では作成されません。サーバー・ハンドルに対してOCISessionBegin()をコールした後、アプリケーションではOCISessionBegin()を再度コールし、別のユーザー・セッション・ハンドルを、別の(または同じ)資格証明と別の(または同じ)操作モードを使用して初期化できます。アプリケーションでユーザーをOCI_MIGRATEモードで認証する場合、サービス・ハンドルは、移行不可能なユーザー・ハンドルにすでに関連付けられている必要があります。このユーザー・ハンドルのuseridは、移行可能なユーザー・セッションの所有者IDになります。移行可能なすべてのセッションは、移行不可能な親セッションを持つ必要があります。

- OCI_MIGRATEモードを指定しない場合、ユーザー・セッション・コンテキストは、OCISessionBegin()で指定したサーバー・ハンドルでのみ使用できます。

- OCI_MIGRATEモードを指定した場合、ユーザー認証は、その他のサーバー・ハンドルで設定できます。ただし、ユーザー・セッション・コンテキストは、同じデータベース・インスタンスに解決するサーバー・ハンドルでのみ使用できます。セキュリティ・チェックは、セッションの切替え中に行われます。

移行可能セッションを別のサーバー・ハンドルに切り替えることができるのは、セッションの所有者IDが、現在その同じサーバーに接続されている移行不可能なセッションのuseridと一致する場合のみです。

OCI_SYSDBA、OCI_SYSOPERおよびOCI_PRELIM_AUTH設定は、主ユーザー・セッション・コンテキストでのみ使用できます。

移行可能セッションは、環境ハンドルによって表される環境内のサーバー・ハンドルに切替えまたは移行できます。また、移行可能セッションは、同じプロセスまたは別のモードの別プロセス内にある、別の環境のサーバー・ハンドルに移行またはクローニングすることもできます。この移行またはクローニングを実行するには、次の手順を実行する必要があります。

1. OCI_ATTR_MIGSESSIONを使用して、セッション・ハンドルからセッションIDを抽出します。これは、コール元が変更する必要がないバイトの配列です。

関連項目:
「ユーザー・セッション・ハンドル属性」

2. このセッションIDを別のプロセスに移送します。

3. 新しい環境内でセッション・ハンドルを作成し、OCI_ATTR_MIGSESSIONを使用してセッションIDを設定します。

4. OCISessionBegin()を実行します。結果のセッション・ハンドルは、完全に認証されています。

OCISessionBegin()へのコールに資格証明を与えるために、ユーザー・セッション・ハンドル・パラメータにおけるデータベース認証に対して、有効なユーザー名およびパスワードのペアを提供する必要があります。この方法では、OCIAttrSet()を使用して、ユーザー・セッション・ハンドルに対してOCI_ATTR_USERNAME性およびOCI_ATTR_PASSWORD属性を設定します。これにより、OCI_CRED_RDBMSを指定してOCISessionBegin()がコールされます。

ユーザー・セッション・ハンドルがOCISessionEnd()によって終了した場合、ユーザー名とパスワードの属性は変更されるため、OCISessionBegin()への次回以降のコールでは再利用できません。次回のOCISessionBegin()コールの前に新しい値を再設定する必要があります。

または、外部資格証明を与えることもできます。この方法では、OCISessionBegin()をコールする前に、ユーザー・セッション・ハンドルについて属性を設定する必要はありません。資格証明のタイプはOCI_CRED_EXTです。すでにOCI_ATTR_USERNAMEおよびOCI_ATTR_PASSWORDに値を設定してある場合、OCI_CRED_EXTを使用すると、これらは無視されます。

OCIでのパスワード管理

OCIPasswordChange()コールにより、アプリケーションを使用して、必要に応じてユーザーのデータベース・パスワードを変更できます。これは、OCISessionBegin()へのコールで、ユーザーのパスワードが期限切れであることを示すエラー・メッセージまたは警告が戻された場合に特に有効です。

アプリケーションでは、OCIPasswordChange()を使用して、ユーザー認証コンテキストを設定し、パスワードを変更することもできます。OCIPasswordChange()が未初期化サービス・コンテキストとともにコールされる場合は、サービス・コンテキストが確立され、旧パスワードを使用してユーザーのアカウントを認証し、次に新しいパスワードに変更されます。OCI_AUTHフラグを設定している場合、ユーザー・セッションは初期化された状態のままになります。そうでない場合、ユーザー・セッションは消去されます。

OCIPasswordChange()に渡したサービス・コンテキストがすでに初期化されている場合、OCIPasswordChange()では、指定のアカウントが旧パスワードを使用して認証され、旧パスワードが新パスワードに変更されます。この場合、どのフラグを設定していても、ユーザー・セッションは初期化された状態のままになります。

セキュアな外部パスワード・ストア

データベースへの接続にアプリケーションでパスワード資格証明を使用するような大規模なデプロイメントの場合、このような資格証明をクライアント側のOracleウォレットに格納できます。Oracleウォレットは、認証や署名の資格証明を格納するために使用する、セキュアなソフトウェア・コンテナです。

クライアント側のOracleウォレットにデータベースのパスワード資格証明を格納すると、アプリケーション・コードやバッチ・ジョブ、スクリプトにユーザー名とパスワードを埋め込む必要がなくなります。このため、スクリプトやアプリケーション・コード内にクリアテキスト・パスワードを公開する危険性が減少し、ユーザー名やパスワードを変更するたびにコードを変更する必要がなくなるため、管理が単純化されます。さらに、アプリケーション・コードを変更する必要がないため、これらのユーザー・アカウントに対するパスワード管理ポリシーの実施は今までより簡単になります。

外部パスワード・ストアを使用するようにクライアントを構成すると、アプリケーションではパスワード認証を使用するデータベースの接続に次の構文を使用できます。

CONNECT /@database_alias

このCONNECT文では、データベース・ログイン資格証明を指定する必要はありません。かわりに、クライアントのウォレットでデータベース・ログイン資格証明が検索されます。

関連項目:
クライアントをセキュアな外部パスワード・ストアを使用するように構成する方法の詳細は、『Oracle Database管理者ガイド』を参照してください。

OCIでのセッション管理

ユーザー・セッションをいくつかのサーバー接続に渡って多重化することによりユーザーのロードをアクティブに均衡化するトランザクション・サーバーでは、これらの接続をサーバー・グループにグループ化する必要があります。サーバー・グループを使用してこれらの接続を識別し、セッションを効率的で安全に管理できます。

OCIAttrSet()コールを使用してサーバー・グループ名を指定するには、例8-1に示すようにOCI_ATTR_SERVER_GROUP属性を定義する必要があります。

例8-1 サーバー・グループ名を渡すためのOCI_ATTR_SERVER_GROUP属性の定義

OCIAttrSet ((void *) srvhp, (ub4) OCI_HTYPE_SERVER, (void *) group_name,
(ub4) strlen ((CONST char *) group_name),
(ub4) OCI_ATTR_SERVER_GROUP, errhp);

サーバー・グループ名は、最大30文字までの英数字文字列です。この属性は、OCIServerAttach()のコール後にのみ設定できます。OCI_ATTR_SERVER_GROUP属性は、そのコンテキストを使用して移行不可能なセッションを作成する前に、サーバー・コンテキストで設定する必要があります。セッションの作成が成功し、サーバーへの接続が確立した後は、サーバー・グループ名は変更できません。

関連項目:
「サーバー・ハンドル属性」

あるサーバー・グループ内のサーバー上で作成されたすべての移行可能セッションは、同じサーバー・グループ内の他のサーバーにのみ移行が可能です。終了したサーバーは、サーバー・グループから削除されます。既存のサーバー・グループ内には、いつでも新しいサーバーを作成できます。

サーバー・グループの使用はオプションです。サーバー・グループが指定されない場合、サーバーはDEFAULTというサーバー・グループ内に作成されます。

デフォルト以外のサーバー・グループ内で作成された最初の移行不可能なセッションの所有者は、そのサーバー・グループの所有権となります。このサーバー・グループにおけるサーバーの後続の移行不可能なセッションはすべて、そのサーバー・グループの所有者によって作成される必要があります。

サーバー・グループ機能は、専用サーバーを使用する場合に便利です。これは、共有サーバーには効果がありません。すべての共有サーバーはサーバー・グループDEFAULTに効率的に所属しています。

OCIでの中間層アプリケーション

中間層アプリケーションは、ブラウザ・クライアントから要求を受け取ります。アプリケーションでは、データベース・アクセスと、HTMLページを生成するかどうかを決定します。アプリケーションは、1つのデータベース・セッション内に複数の軽量ユーザー・セッションを含めることができます。これらの軽量セッションを使用すると、別のデータベース接続によるオーバーヘッドなしに各ユーザーが認証され、実ユーザーとしての識別情報が中間層を通して保たれます。

クライアントの認証が中間層で行われ、また、中間層の認証がデータベースで行われ、中間層がクライアントのかわりに稼働する権限を管理者から与えられているかぎり、クライアントのセキュリティに影響することなく、クライアントの識別情報をデータベース内で幅広くメンテナンスできます。

セキュアな3層アーキテクチャは、3つのトラスト・ゾーンを囲むように設計されています。

第1は、クライアント・トラスト・ゾーンです。Webアプリケーション・サーバーに接続しているクライアントは、パスワード、暗号トークンなどを使用して中間層で認証されます。この方法は、他のトラスト・ゾーンの確立に使用する方法とはまったく異なります。

第2のトラスト・ゾーンは、アプリケーション・サーバーです。データ・サーバーではアプリケーション・サーバーの識別情報を検証し、信頼できる場合、正しいクライアントの識別情報を渡します。

第3のトラスト・ゾーンでは、データ・サーバーが認可サーバーと対話し、クライアントとアプリケーション・サーバーに割り当てられているロールを取得します。

アプリケーション・サーバーがサーバーに接続すると、1次セッションが確立されます。アプリケーション・サーバーにより通常の方法でデータベースに対して認証が行われ、アプリケーション・サーバー・トラスト・ゾーンが作成されます。これで、アプリケーション・サーバーの識別情報はデータ・サーバーよって予約済になり、信頼されたことになります。

アプリケーションで、アプリケーション・サーバーに接続しているクライアントの識別情報を検証した場合は、第1のトラスト・ゾーンが作成されます。アプリケーション・サーバーでは、クライアントの要求に応じることができるように、クライアントに対するセッション・ハンドルが必要です。中間層プロセスではセッション・ハンドルを割り当て、OCIAttrSet()を使用して次のようなクライアント属性を設定します。

- クライアントのデータベース・ユーザー名を設定するOCI_ATTR_USERNAME。

- プロキシ要求を行う認証済アプリケーションを示すOCI_ATTR_PROXY_CREDENTIALS。

アプリケーション・サーバーがクライアントとして接続した後にアクティブ化するロールのリストを指定するには、OCISessionBegin()コールの前に、OCIAttrSet()を属性OCI_ATTR_INITIAL_CLIENT_ROLESおよびロールのリストを含む文字列の配列を指定してコールします。1回のラウンドトリップで、ロールが確立され、プロキシ機能が検証されます。アプリケーション・サーバーがクライアントの代理として機能することが許可されていない場合、あるいは指定されたロールをアクティブ化することが許可されていない場合は、OCISessionBegin()コールが失敗します。

中間層アプリケーションのOCI属性

次の属性を使用すると、クライアントの外部名と初期権限を指定できます。アプリケーションでは、クライアントを識別または認証する代替方法として、これらの資格証明が使用されます。

OCI_CRED_PROXY

クライアントにかわってアプリケーション・サーバーでセッションを開始した場合、OCI_CRED_RDBMS (データベースのユーザー名とパスワードが必要です)やOCI_CRED_EXT (外部に資格証明が与えられます)ではなく、OCI_CRED_PROXYをOCISessionBegin()のcredtパラメータに渡される値として使用します。

OCI_ATTR_PROXY_CREDENTIALS

OCI_ATTR_PROXY_CREDENTIALS属性を使用して、クライアントの認証に使用するアプリケーション・サーバーの資格証明を指定します。例8-2のように、次の宣言とOCIAttrSet()コールをコード化できます。

例8-2 クライアント認証用のアプリケーション・サーバーの資格証明を指定するためのOCI_ATTR_PROXY_CREDENTIALS属性の定義

OCISession *session_handle;
OCISvcCtx  *application_server_session_handle;
OCIError   *error_handle;
...
OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION,
(void *)application_server_session_handle, (ub4) 0,
OCI_ATTR_PROXY_CREDENTIALS, error_handle);

OCI_ATTR_DISTINGUISHED_NAME

アプリケーションでは、データベースのユーザー名ではなく、X.509証明書に含まれる識別名をクライアントのログイン名として使用できます。

クライアントの識別名を渡すには、例8-3のように、中間層サーバーでOCIAttrSet()をコールし、OCI_ATTR_DISTINGUISHED_NAMEを渡します。

例8-3 クライアントの識別名を渡すためのOCI_ATTR_DISTINGUISHED_NAME属性の定義

/* Declarations */
...
OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION,
(void *)distinguished_name, (ub4) 0,
OCI_ATTR_DISTINGUISHED_NAME, error_handle);

OCI_ATTR_CERTIFICATE

OCI_ATTR_CERTIFICATEを使用した証明書ベースのプロキシ認証は、Oracle Databaseの今後のリリースではサポートされません。かわりに、OCI_ATTR_DISTINGUISHED_NAME属性またはOCI_ATTR_USERNAME属性を使用してください。この認証方法は、識別名の使用に似ています。X.509証明書全体が、中間層サーバーによってデータベースに渡されます。

証明書全体を渡すには、例8-4のように、中間層サーバーでOCIAttrSet()をコールし、OCI_ATTR_CERTIFICATEを渡します。

例8-4 X.509証明書全体を渡すためのOCI_ATTR_CERTIFICATE属性の定義

OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION,
(void *)certificate, ub4 certificate_length,
OCI_ATTR_CERTIFICATE, error_handle);

OCI_ATTR_INITIAL_CLIENT_ROLES

アプリケーション・サーバーがOracle Databaseに接続する場合は、OCI_ATTR_INITIAL_CLIENT_ROLES属性を使用して、クライアントが所有するロールを指定します。一連のロールを使用可能にするために、例8-5のように、属性、NULLで終了する文字列の配列および配列内の文字列の数を指定してOCIAttrSet()関数をコールします。

例8-5 クライアント・ロールを渡すためのOCI_ATTR_INITIAL_CLIENT_ROLES属性の定義

OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION,
(void *)role_array, (ub4) number_of_strings,
OCI_ATTR_INITIAL_CLIENT_ROLES, error_handle);

OCI_ATTR_CLIENT_IDENTIFIER

多数の中間層アプリケーションがデータベースにアプリケーションとして接続し、中間層を使用してエンド・ユーザーの識別情報を追跡します。様々なデータベース・コンポーネントでこれらのユーザーの識別情報の追跡を統合するため、データベース・クライアントはいつでもセッション・ハンドルにCLIENT_IDENTIFIER (アプリケーション・コンテキスト・ネームスペースUSERENVの事前定義済属性)を設定できます。OCIAttrSet()へのコールで、例8-6のように、OCIのOCI_ATTR_CLIENT_IDENTIFIER属性を使用します。サーバーへの次の要求で情報が伝播され、サーバー・セッションに格納されます。

OCI_ATTR_CLIENT_IDENTIFIERは、グローバル・アプリケーション・コンテキストとも使用でき、これらのユーザーの選択された識別情報に対してコンテキストの可用性を制限します。

例8-6 エンドユーザー識別情報を渡すためのOCI_ATTR_CLIENT_IDENTIFIER属性の定義

OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION,
(void *)"janedoe", (ub4)strlen("janedoe"),
OCI_ATTR_CLIENT_IDENTIFIER, error_handle);

クライアントに複数のセッションがあるときは、同じクライアント識別子を使用して、各セッションに対してOCIAttrSet()を実行します。OCIAttrSet()は、透過的アプリケーション・フェイルオーバー(TAF)により再確立されるセッションに対して、手動で実行する必要があります。

クライアント識別子は、CLIENT_IDENTIFIER列としてV$SESSIONにあるか、または次のSQL文とともにシステム・コンテキスト内にあります。

SELECT SYS_CONTEXT('userenv', 'client_identifier') FROM DUAL;

関連項目:

- 『Oracle Databaseセキュリティ・ガイド』の複数層環境におけるユーザー識別情報の保護に関する項

- 「OCIでの透過的アプリケーション・フェイルオーバー」

OCI_ATTR_PASSWORD

中間層では、データベース・サーバーに対して、認証自体を行うかわりにクライアントのパスワードを検証することでクライアントを認証するように要求できます。クライアント/サーバー接続と同じように見えますが、クライアントでは、データベース操作を実行するために、クライアントのシステムにOracle Databaseソフトウェアがインストールされている必要はありません。アプリケーション・サーバーでは、クライアントのパスワードを使用するため、例8-7のように、既存のOCI_ATTR_PASSWORD属性を使用して、OCIAttrSet()に認証データを提供します。

例8-7 検証のパスワードを渡すためのOCI_ATTR_PASSWORD属性の定義

OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION, (void *)password,
(ub4)0, OCI_ATTR_PASSWORD, error_handle);

関連項目:
「ユーザー・セッション・ハンドル属性」

例8-8では、クライアントの外部名と初期権限を指定できるOCI属性を示しています。OCIアプリケーションでは、クライアントを識別または認証する代替方法として、これらの資格照明が使用されます。

例8-8 クライアントの外部名と初期権限を指定できるOCI属性

...
*OCIEnv *environment_handle;
OCIServer *data_server_handle;
OCIError *error_handle;
OCISvcCtx *application_server_service_handle;
OraText *client_roles[2];
OCISession *first_client_session_handle, second_client_session_handle;
...
/*
** General initialization and allocation of contexts.
*/

(void) OCIInitialize((ub4) OCI_DEFAULT, (void *)0,
(void * (*)(void *, size_t)) 0,
(void * (*)(void *, void *, size_t))0,
(void (*)(void *, void *)) 0 );
(void) OCIEnvInit( (OCIEnv **) &environment_handle, OCI_DEFAULT, (size_t) 0,
(void **) 0 );
(void) OCIHandleAlloc( (void *) environment_handle, (void **) &error_handle,
OCI_HTYPE_ERROR, (size_t) 0, (void **) 0);
/*
** Allocate and initialize the server and service contexts used by the
** application server.
*/

(void) OCIHandleAlloc( (void *) environment_handle,
(void **)&data_server_handle, OCI_HTYPE_SERVER, (size_t) 0, (void **) 0);
(void) OCIHandleAlloc( (void *) environment_handle, (void **)
&application_server_service_handle, OCI_HTYPE_SVCCTX, (size_t) 0,
(void **) 0);
(void) OCIAttrSet((void *) application_server_service_handle,
OCI_HTYPE_SVCCTX, (void *) data_server_handle, (ub4) 0, OCI_ATTR_SERVER,
error_handle);
/*
** Authenticate the application server. In this case, external authentication is
** being used.
*/

(void) OCIHandleAlloc((void *) environment_handle,
(void **)&application_server_session_handle, (ub4) OCI_HTYPE_SESSION,
(size_t) 0, (void **) 0);
checkerr(error_handle, OCISessionBegin(application_server_service_handle,
error_handle, application_server_session_handle, OCI_CRED_EXT,
OCI_DEFAULT));
/*
** Authenticate the first client.
** Note that no password is specified by the
** application server for the client as it is trusted.
*/

(void) OCIHandleAlloc((void *) environment_handle,
(void **)&first_client_session_handle, (ub4) OCI_HTYPE_SESSION,
(size_t) 0,(void **) 0);
(void) OCIAttrSet((void *) first_client_session_handle,
(ub4) OCI_HTYPE_SESSION, (void *) "jeff", (ub4) strlen("jeff"),
OCI_ATTR_USERNAME, error_handle);
/*
** In place of specifying a password, pass the session handle of the application
** server instead.
*/

(void) OCIAttrSet((void *) first_client_session_handle,
(ub4) OCI_HTYPE_SESSION, (void *) application_server_session_handle,
(ub4) 0, OCI_ATTR_PROXY_CREDENTIALS, error_handle);
(void) OCIAttrSet((void *) first_client_session_handle,
(ub4) OCI_HTYPE_SESSION, (void *) "jeff@VeryBigBank.com",
(ub4) strlen("jeff@VeryBigBank.com"), OCI_ATTR_EXTERNAL_NAME,
error_handle);
/*
** Establish the roles that the application server can use as the client.
*/

client_roles[0] = (OraText *) "TELLER";
client_roles[1] = (OraText *) "SUPERVISOR";
(void) OCIAttrSet((void *) first_client_session_handle,
OCI_ATTR_INITIAL_CLIENT_ROLES, error_handle);
checkerr(error_handle, OCISessionBegin(application_server_service_handle,
error_handle, first_client_session_handle, OCI_CRED_PROXY, OCI_DEFAULT));
/*
** To start a session as another client, the application server does the
** following.
** This code is unchanged from the current way of doing session switching.
*/

(void) OCIHandleAlloc((void *) environment_handle,
(void **)&second_client_session_handle, (ub4) OCI_HTYPE_SESSION,
(size_t) 0, (void **) 0);
(void) OCIAttrSet((void *) second_client_session_handle,
(ub4) OCI_HTYPE_SESSION, (void *) "mutt", (ub4) strlen("mutt"),
OCI_ATTR_USERNAME, error_handle);
(void) OCIAttrSet((void *) second_client_session_handle,
(ub4) OCI_HTYPE_SESSION, (void *) application_server_session_handle,
(ub4) 0, OCI_ATTR_PROXY_CREDENTIALS, error_handle);
(void) OCIAttrSet((void *) second_client_session_handle,
(ub4) OCI_HTYPE_SESSION, (void *) "mutt@VeryBigBank.com",
(ub4) strlen("mutt@VeryBigBank.com"), OCI_ATTR_EXTERNAL_NAME,
error_handle);
/*
** Note that the application server has not specified any initial roles to have
** as the second client.
*/

checkerr(error_handle, OCISessionBegin(application_server_service_handle,
error_handle, second_client_session_handle, OCI_CRED_PROXY, OCI_DEFAULT));
/*
** To switch to the first user, the application server applies the session
** handle obtained by the first
** OCISessionBegin() call. This is the same as is currently done.
*/

(void) OCIAttrSet((void *)application_server_service_handle,
(ub4) OCI_HTYPE_SVCCTX, (void *)first_client_session_handle,
(ub4)0, (ub4)OCI_ATTR_SESSION, error_handle);
/*
** After doing some operations, the application server can switch to
** the second client. That
** is be done by the following call:
*/

(void) OCIAttrSet((void *)application_server_service_handle,
(ub4) OCI_HTYPE_SVCCTX,
(void *)second_client_session_handle, (ub4)0, (ub4)OCI_ATTR_SESSION,
error_handle);
/*
** and then do operations as that client
*/
...

外部でOCIから初期化されたコンテキスト

外部で初期化されたコンテキストとは、属性をOCIから初期化できるアプリケーション・コンテキストです。SQL文のCREATE CONTEXTでINITIALIZED EXTERNALLYオプションを使用して、サーバーにコンテキスト・ネームスペースを作成します。

これで、OCIAttrSet()とOCISessionBegin()を使用してセッションを確立するときに、OCIインタフェースを初期化できます。CREATE CONTEXT文で指定されたPL/SQLパッケージのみを使用して、ネームスペース内に属性を書き込む後続のコマンドを発行します。

デフォルト値と他のセッション属性は、OCISessionBegin()コールを使用して設定できるため、サーバー・ラウンドトリップ回数が削減されます。

関連項目:

- 『Oracle Databaseセキュリティ・ガイド』のアプリケーション開発者向けのセキュリティ管理に関する章

- 『Oracle Database SQL言語リファレンス』のCREATE CONTEXT文およびSYS_CONTEXT関数

外部でOCIから初期化されたコンテキスト属性

クライアント・アプリケーションを開発する場合、認証を行う前に、OCI関数に次の属性を使用して、明示的にアプリケーション・コンテキストをセッション・ハンドルに設定できます。

OCI_ATTR_APPCTX_SIZE

OCI_ATTR_APPCTX_SIZE属性を、例8-9のように、OCIAttrSet()コールで使用して、コンテキストの配列サイズを任意の数のコンテキスト属性で初期化します。

例8-9 コンテキストの配列サイズを任意の数のコンテキスト属性で初期化するためのOCI_ATTR_APPCTX_SIZE属性の定義

OCIAttrSet(session, (ub4) OCI_HTYPE_SESSION,
(void *)&size, (ub4)0, OCI_ATTR_APPCTX_SIZE, error_handle);

OCI_ATTR_APPCTX_LIST

OCI_ATTR_APPCTX_LIST属性を、例8-10のように、OCIAttrGet()コールで使用して、セッションに対するアプリケーション・コンテキスト・リスト記述子のハンドルを取得します。(ctxl_descパラメータのデータ型は、OCIParam *であることが必要です。)

例8-10 セッションに対するアプリケーション・コンテキスト・リスト記述子のハンドルを取得するためのOCI_ATTR_APPCTX_LIST属性の使用

OCIAttrGet(session, (ub4) OCI_HTYPE_SESSION,
(void *)&ctxl_desc, (ub4)0, OCI_ATTR_APPCTX_LIST, error_handle);

例8-11では、OCIParamGet()のコールでアプリケーション・コンテキスト・リスト記述子を使用し、i番目のアプリケーション・コンテキストの個々の記述子を取得する方法を示しています。

例8-11 アプリケーション・コンテキスト・リスト記述子を使用して、i番目のアプリケーション・コンテキストの個々の記述子を取得するためのOCIParamGet()のコール

OCIParamGet(ctxl_desc, OCI_DTYPE_PARAM, error_handle,(void **)&ctx_desc, i);

外部で初期化されたコンテキストの設定に使用するセッション・ハンドル属性

次の属性を使用して、アプリケーション・コンテキストの適切な値を設定します。

- OCI_ATTR_APPCTX_NAMEを使用して、コンテキスト・ネームスペース(有効なSQL識別子であることが必要)を設定します。

- OCI_ATTR_APPCTX_ATTRを使用して、指定されたコンテキストに、最大30バイトの大/小文字区別がない文字列で属性名を設定します。

- OCI_ATTR_APPCTX_VALUEを使用して、指定されたコンテキストに属性の値を設定します。

各ネームスペースに複数の属性を保持でき、各属性には1つの値を設定します。例8-12では、これらを設定するために使用できるコールを示しています。

例8-12 外部で初期化されたコンテキストを設定するためのセッション・ハンドル属性の定義

OCIAttrSet(ctx_desc, OCI_DTYPE_PARAM,
(void *)ctx_name, sizeof(ctx_name), OCI_ATTR_APPCTX_NAME, error_handle);

OCIAttrSet(ctx_desc, OCI_DTYPE_PARAM,
(void *)attr_name, sizeof(attr_name), OCI_ATTR_APPCTX_ATTR, error_handle);

OCIAttrSet(ctx_desc, OCI_DTYPE_PARAM,
(void *)value, sizeof(value), OCI_ATTR_APPCTX_VALUE, error_handle);

アプリケーション・コンテキスト操作はVARCHAR2データ型に基づいているため、文字型のみサポートされていることに注意してください。

関連項目:
「ユーザー・セッション・ハンドル属性」

エンドツーエンド・アプリケーションのトレース

次の属性を使用して、サーバー・ラウンドトリップを含まない、サーバーのコール・タイムを測定します。また、これらの属性は、サーバーに対してラウンドトリップを1回発生させる、PL/SQLパッケージDBMS_APPLICATION_INFOを使用して設定できます。OCIを使用して属性を設定すると、ラウンドトリップは発生しません。

OCI_ATTR_COLLECT_CALL_TIME

boolean変数をTRUEまたはFALSEに設定します。OCIAttrSet()をコールしてOCI_ATTR_COLLECT_CALL_TIME属性を設定した後で、サーバーにより各コール・タイムが測定されます。変数をTRUEに設定した時間とFALSEに設定した時間の間のすべてのサーバー・タイムが測定されます。

OCI_ATTR_CALL_TIME

最後のサーバー・コールの経過時間(マイクロ秒)は、OCI_ATTR_CALL_TIME属性を使用してOCIAttrGet()をコールすると、ub8変数で戻されます。例8-13では、コード・フラグメントでこの方法を示しています。

例8-13 最後のサーバー・コールの経過時間を取得するためのOCI_ATTR_CALL_TIME属性の使用

boolean enable_call_time;
ub8 call_time;
...
enable_call_time = TRUE;
OCIAttrSet(session, OCI_HTYPE_SESSION, (void *)&enable_call_time,
(ub4)0, OCI_ATTR_COLLECT_CALL_TIME,
(OCIError *)error_handle);
OCIStmtExecute(...);
OCIAttrGet(session, OCI_HTYPE_SESSION, (void *)&call_time,
(ub4)0, OCI_ATTR_CALL_TIME,
(OCIError *)error_handle);
...

エンドツーエンド・アプリケーションのトレースの属性

これらの属性を設定して、次のアプリケーションをトレースおよびデバッグします。

- OCI_ATTR_MODULE: クライアント・アプリケーションの現行モジュールの名前。

- OCI_ATTR_ACTION: 現行モジュールの現行処理の名前。処理を指定しない場合はNULLに設定します。

- OCI_ATTR_CLIENT_INFO: クライアント・アプリケーションの追加情報。

関連項目:
「ユーザー・セッション・ハンドル属性」

外部で初期化されたコンテキストによるOCISessionBegin()の使用

OCISessionBegin()をコールすると、セッション・ハンドルに設定されたコンテキストがサーバーにプッシュされます。このサーバー・セッションに追加コンテキストは伝播されません。例8-14では、これらのコールおよび属性の使用方法を示しています。

例8-14 外部で初期化されたコンテキストによるOCISessionBegin()の使用

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <oci.h>

static OraText *username = (OraText *) "HR";
static OraText *password = (OraText *) "HR";

static OCIEnv *envhp;
static OCIError *errhp;

int main(/*_ int argc, char *argv[] _*/);

static sword status;

int main(argc, argv)
int argc;
char *argv[];
{

OCISession *authp = (OCISession *) 0;
OCIServer *srvhp;
OCISvcCtx *svchp;
OCIDefine *defnp = (OCIDefine *) 0;
void     *parmdp;
ub4        ctxsize;
OCIParam  *ctxldesc;
OCIParam  *ctxedesc;

OCIEnvCreate(&envhp, OCI_DEFAULT, (void *)0, 0, 0, 0,
(size_t)0, (void *)0);

(void) OCIHandleAlloc( (void *) envhp, (void **) &errhp, OCI_HTYPE_ERROR,
(size_t) 0, (void **) 0);

/* server contexts */
(void) OCIHandleAlloc( (void *) envhp, (void **) &srvhp, OCI_HTYPE_SERVER,
(size_t) 0, (void **) 0);

(void) OCIHandleAlloc( (void *) envhp, (void **) &svchp, OCI_HTYPE_SVCCTX,
(size_t) 0, (void **) 0);

(void) OCIServerAttach( srvhp, errhp, (OraText *)"", strlen(""), 0);

/* set attribute server context in the service context */
(void) OCIAttrSet( (void *) svchp, OCI_HTYPE_SVCCTX, (void *)srvhp,
(ub4) 0, OCI_ATTR_SERVER, (OCIError *) errhp);

(void) OCIHandleAlloc((void *) envhp, (void **)&authp,
(ub4) OCI_HTYPE_SESSION, (size_t) 0, (void **) 0);
/****************************************/
/* set app ctx size to 2 because you want to set up 2 application contexts */
ctxsize = 2;

/* set up app ctx buffer */
(void) OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_SESSION,
(void *) &ctxsize, (ub4) 0,
(ub4) OCI_ATTR_APPCTX_SIZE, errhp);

/* retrieve the list descriptor */
(void) OCIAttrGet((void *)authp, (ub4) OCI_HTYPE_SESSION,
(void *)&ctxldesc, 0, OCI_ATTR_APPCTX_LIST, errhp );

/* retrieve the 1st ctx element descriptor */
(void) OCIParamGet(ctxldesc, OCI_DTYPE_PARAM, errhp, (void**)&ctxedesc, 1);

(void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
(void *) "HR", (ub4) strlen((char *)"HR"),
(ub4) OCI_ATTR_APPCTX_NAME, errhp);

(void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
(void *) "ATTR1", (ub4) strlen((char *)"ATTR1"),
(ub4) OCI_ATTR_APPCTX_ATTR, errhp);

(void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
(void *) "VALUE1", (ub4) strlen((char *)"VALUE1"),
(ub4) OCI_ATTR_APPCTX_VALUE, errhp);

/* set second context */
(void) OCIParamGet(ctxldesc, OCI_DTYPE_PARAM, errhp, (void**)&ctxedesc, 2);

(void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
(void *) "HR", (ub4) strlen((char *)"HR"),
(ub4) OCI_ATTR_APPCTX_NAME, errhp);

(void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
(void *) "ATTR2", (ub4) strlen((char *)"ATTR2"),
(ub4) OCI_ATTR_APPCTX_ATTR, errhp);

(void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
(void *) "VALUE2", (ub4) strlen((char *)"VALUE2"),
(ub4) OCI_ATTR_APPCTX_VALUE, errhp);
/****************************************/
(void) OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_SESSION,
(void *) username, (ub4) strlen((char *)username),
(ub4) OCI_ATTR_USERNAME, errhp);

(void) OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_SESSION,
(void *) password, (ub4) strlen((char *)password),
(ub4) OCI_ATTR_PASSWORD, errhp);

OCISessionBegin ( svchp,  errhp, authp, OCI_CRED_EXT, (ub4) OCI_DEFAULT);

}

クライアント・アプリケーション・コンテキスト

データベース・クライアント(中間層アプリケーションなど)は、アプリケーション・コンテキストを使用して、1回のラウンドトリップだけで実行されたそれぞれの文により、任意のセッション・データをサーバーに設定および送信できます。サーバーでは、文の実行前にこのデータがセッション・コンテキストに格納され、このデータを使用して問合せまたはDML操作を制限できます。ビュー、トリガー、仮想プライベート・データベース(VPD)ポリシー、PL/SQLストアド・プロシージャなどのすべてのデータベース機能は、セッション・データを使用してこれらの操作を制限します。

パブリックで書込み可能なネームスペースnmが作成されます。

CREATE CONTEXT nm USING hr.package1;

ネームスペースでグループ化されたデータを変更するには、指定されたPL/SQLパッケージ(hr.package1)を実行する必要があります。ただし、ユーザー・セッションではこの情報の問合せに権限は必要ありません。

ユーザー・セッションに格納された可変長のアプリケーション・コンテキスト・データの形式は、コンテキスト・ネームスペースの下でグループ化された属性と値のペアです。

たとえば、人事管理アプリケーションでユーザー・セッションにエンドユーザーの職責情報を格納する必要がある場合、nmネームスペースと、"responsibility"という、"manager"や"accountant"といった値を割り当てるための属性を作成できます。このマニュアルでは、これを設定操作と呼びます。

アプリケーションでは、nmネームスペース内の"responsibility"属性の値を消去する場合、この属性をNULLまたは空の文字列に設定します。このマニュアルでは、これを消去操作と呼びます。

アプリケーションでは、nmネームスペース内のすべての情報を消去する場合、全消去の操作の一部としてネームスペース情報をサーバーに送信します。このマニュアルでは、これをネームスペース内の全消去操作と呼びます。

ネームスペースに対してパッケージのセキュリティが定義されていない場合は、このネームスペースはクライアントのネームスペースとみなされ、すべてのOCIクライアントがこのネームスペースのデータをサーバーに転送できます。権限やパッケージのセキュリティ・チェックは行われません。

アプリケーション・コンテキスト・データのネットワーク・トランスポートは、サーバーへの1回のラウンドトリップで行われますます。

複数のSET操作

OCIAppCtxSet()関数を使用して、CLIENTCONTEXTネームスペース内の"responsibility"属性に対して一連の設定操作を行います。この情報がサーバーに転送されると、この最新値がネームスペース内の特定の属性よりも優先されます。CLIENTCONTEXTネームスペース内の"responsibility"属性の値を"manager"から"vp"に変更するには、クライアント側で、例8-15に示したコード・フラグメントを使用します。この情報がサーバーに転送されると、サーバーでは、CLIENTCONTEXTネームスペース内の"responsibility"属性に最新の値"vp"が表示されます。

例8-15 CLIENTCONTEXTネームスペース内の"responsibility"属性値の変更

err = OCIAppCtxSet((void *) sesshndl,(void *)"CLIENTCONTEXT",(ub4) 13,
(void *)"responsibility", 14
(void *)"manager", 7, errhp, OCI_DEFAULT);
err = OCIAppCtxSet((void *) sesshndl, (void*)"CLIENTCONTEXT", 13,
(void *)"responsibility", 14,(void *)"vp",2, errhp,
OCI_DEFAULT);

クライアントのネームスペース内の特定の属性情報を消去できます。例8-16のように、 OCIAppCtxSet()関数を使用して、属性の値をNULLまたは空の文字列に設定して消去します。

例8-16 クライアント・ネームスペース内の特定の属性情報を消去するための2つの方法

(void) OCIAppCtxSet((void *) sesshndl, (void *)"CLIENTCONTEXT", 13,
(void *)"responsibility", 14, (void *)0, 0,errhp,
OCI_DEFAULT);

(void) OCIAppCtxSet((void *) sesshndl, (void *)"CLIENTCONTEXT", 13
(void *)"responsibility", 14, (void *)"", 0,errhp,
OCI_DEFAULT);

SET操作間のCLEAR-ALL操作

特定のクライアント・ネームスペース内のすべてのコンテキスト情報は、OCIAppCtxClearAll()関数を使用して消去でき、次のネットワーク・トランスポート時に、サーバー側ユーザー・セッションでも消去されます。

クライアント・アプリケーションでは、いくつかの設定操作の後にネームスペース内で全消去操作を行うと、ネームスペース内でこの全消去操作の前に設定されたすべての属性の値は、クライアント側とサーバー側でクリーン・アップされます。全消去操作の後に行われた設定操作のみが、サーバー側で反映されます。クライアント側では、例8-17のようなコードが表示されます。

例8-17 特定のクライアント・ネームスペースでのすてべのコンテキスト情報の消去

err = OCIAppCtxSet((void *) sesshndl,(void *)"CLIENTCONTEXT", 13,
(void *)"responsibility", 14,
(void *)"manager", 7,errhp, OCI_DEFAULT);
err = OCIAppCtxClearAll((void *) sesshndl, (void *)"CLIENTCONTEXT", 13, errhp,
OCI_DEFAULT);
err = OCIAppCtxSet((void *) sesshndl, (void*)"CLIENTCONTEXT",13
(void *)"office",6, (void *)"2op123", 5, errhp, OCI_DEFAULT);

全消去操作は、ネームスペースCLIENTCONTEXT内のそれより前に行われた操作で設定されたすべての情報を消去します("responsibility"の属性値"manager"は削除されます)。その後に設定された情報は、サーバー側で反映されません。

クライアント・ネームスペースでのネットワーク・トランスポートおよびPL/SQL

アプリケーションでは、OCIStmtExecute()コールのアプリケーション・コンテキスト情報をサーバーに送信でき、DBMS_SESSIONパッケージを実行することによって、このコール時に同じコンテキスト情報の変更も試行できます。

通常、サーバー側では、転送された情報が最初に処理され、メイン・コールは後で処理されます。この動作は、アプリケーション・コンテキストのネットワーク・トランスポートにも当てはまります。

この両方が同じクライアント・ネームスペースおよび属性セットへの書込みである場合、メイン・コールの情報により、最初のネットワークのトランスポート・メカニズムによって設定された情報が上書きされます。ネットワーク・トランスポート・コールでエラーが発生すると、メイン・コールは実行されません。

ただし、メイン・コールで発生したエラーは、ネットワーク・トランスポートのコール処理には影響しません。ネットワーク・トランスポート・コールは、いったん処理されると元に戻すことはできません。このエラーは、(OCI関数によって)コール元にレポートされるときに、汎用ORAエラーとしてレポートされます。現時点では、ネットワーク・トランスポートで発生したエラーとメイン・コールで発生したエラーとを識別する簡単な方法はありません。クライアントでは、メイン・コールで発生したエラーによりラウンドトリップ・ネットワーク処理を元に戻すことは考えずに、適切な例外処理メカニズムを実装して、非一貫性が発生しないようにしてください。

関連項目:

- 「OCIAppCtxClearAll()」

- 「OCIAppCtxSet()」

エディションベースの再定義

エディションは、既存のアプリケーションが使用可能であっても、アプリケーション・パッチによって変更されたエディション化可能なオブジェクトをインストールし実行できるステージング領域を提供します。セッション開始時にOCI_ATTR_EDITION属性を設定することで、データベース・デフォルト以外のエディションを指定できます。アプリケーションでは、例8-18のように、この属性名およびエディションを値として指定したOCIAttrSet()をコールできます。

例8-18 OCI_ATTR_EDITION属性を設定するためのOCIAttrSet()のコール

static void workerFunction()
{
OCISvcCtx *svchp = (OCISvcCtx *) 0;
OCIAuthInfo *authp = (OCIAuthInfo *)0;
sword err;
err =  OCIHandleAlloc((void *) envhp, (void **)&authp,
(ub4) OCI_HTYPE_AUTHINFO,
(size_t) 0, (void **) 0);
if (err)
checkerr(errhp, err);

checkerr(errhp, OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_AUTHINFO,
(void *) username, (ub4) strlen((char *)username),
(ub4) OCI_ATTR_USERNAME, errhp));

checkerr(errhp,OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_AUTHINFO,
(void *) password, (ub4) strlen((char *)password),
(ub4) OCI_ATTR_PASSWORD, errhp));

(void) OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_SESSION,
(void *) "Patch_Bug_12345",
(ub4) strlen((char *)"Patch_Bug_12345"),
(ub4) OCI_ATTR_EDITION, errhp);

printf(("Create a new session that connects to the specified edition\n");
if (err = OCISessionGet(envhp, errhp, &svchp, authp,
(OraText *)connstr, (ub4)strlen((char *)connstr), NULL,
0, NULL, NULL, NULL, OCI_DEFAULT))
{
checkerr(errhp, err);
exit(1);
}

checkerr(errhp, OCISessionRelease(svchp, errhp, NULL, (ub4)0, OCI_DEFAULT));

OCIHandleFree((void *)authp, OCI_HTYPE_AUTHINFO);
}

OCIAttrSet()がコールされない場合、エディション名の値はオペレーティング・システム環境変数ORA_EDITIONから取得されます。その変数が設定されていない場合、OCI_ATTR_EDITIONの値は空の文字列となります。空でない値が指定された場合、サーバーがセッションの指定エディションを設定するか、セッションでデータベースのデフォルト・エディションが使用されます。次に、サーバーはユーザーがそのEditionに対するUSE権限を持っているかどうかをチェックします。権限がない場合、接続に失敗します。存在しないエディション名が指定された場合は、エラーが戻されます。

関連項目:

- 「OCI_ATTR_EDITION」

- エディションベースの再定義の詳細は、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』を参照してください。

- 「OCIセッション・プール用にサポートされる属性に対する制限」

OCIセキュリティ拡張機能

次のセキュリティ拡張機能では、init.oraファイルまたはsqlnet.oraファイル内の構成済パラメータが使用され(後者のファイルは、該当する機能について具体的に示されています)、その詳細は『Oracle Databaseセキュリティ・ガイド』を参照してください。これらの初期化パラメータは、データベースの全インスタンスに適用されます。

関連項目:
『Oracle Databaseセキュリティ・ガイド』の中間層アプリケーションへのコールの埋込みによるクライアント・セッションIDの取得、設定および消去に関する項

表示されるデータベース・バージョン・バナーの制御

認証前に(OCIServerAttach()をコールした後に接続済サーバー・ハンドルで)OCIServerVersion()関数を発行して、データベースのバージョンを取得できます。認証前にデータベース・バージョン文字列が開示されないようにするには、初期化パラメータSEC_RETURN_SERVER_RELEASE_BANNERをNOに設定します。たとえば、次のようにします。

SEC_RETURN_SERVER_RELEASE_BANNER = NO

これにより、Oracle Databaseリリース11.1以降の全リリースおよびパッチ・セットの場合は、次の文字列が表示されます。

Oracle Database 11g Release 11.1.0.0.0 - Production

SEC_RETURN_SERVER_RELEASE_BANNERをYESに設定すると、現行のバナーが表示されます。Oracle Databaseリリース11.2.0.2をインストール済の場合は、次のバナーが表示されます。

Oracle Database 11g Enterprise Edition Release 11.2.0.2 - Production

この機能は、Oracle Databaseリリース11.1以降のサーバーとすべてのバージョンのクライアントで動作します。

不正なアクセスおよびユーザー・アクション監査用のバナー

次のシステム全体のパラメータはsqlnet.oraにあり、不正なアクセスとユーザー・アクションに可能な監査に関する警告をユーザーに対して表示します。これらの機能は、Oracle Databaseリリース11.1以降のサーバーおよびクライアントで使用可能です。バナーのコンテンツは、データベース管理者が作成するテキスト・ファイルにあります。バナーのコンテンツの表示には、512バイトのバッファ制限があります。このバッファ制限を超えると、バナーのコンテンツは途中で切り取られたようになります。アクセス・バナーの構文は、次のとおりです。

SEC_USER_UNAUTHORIZED_ACCESS_BANNER = file_path1

この構文では、file_path1はテキスト・ファイルのパスです。このバナーを取得するには、OCIServerAttach()またはOCISessionGet()のコール後に、サーバー・ハンドルからOCI_ATTR_ACCESS_BANNER属性の値を取得します。

関連項目:
「OCI_ATTR_ACCESS_BANNER」

監査バナーの構文は、次のとおりです。

SEC_USER_AUDIT_ACTION_BANNER = file_path2

この構文では、file_path2はテキスト・ファイルのパスです。このバナーを取得するには、OCISessionBegin()、OCISessionGet()、OCILogon()またはOCILogon2()のコールの後に、セッション・ハンドルからOCI_ATTR_AUDIT_BANNER属性の値を取得します。

関連項目:
「OCI_ATTR_AUDIT_BANNER」

非遅延リンケージ

アプリケーションの非遅延リンケージはサポート外となり、Makefileはこのリンケージを削除するように変更されています。このリンク方法は、OCIリリース7まで使用されていました。

OCIマルチスレッド開発の概要

スレッドは大きなプロセス内に存在する軽量のプロセスです。複数のスレッドで同一コードおよび同一データ・セグメントを共有しますが、プログラム・カウンタ、システム・レジスタおよびスタックはスレッドごとにあります。グローバル変数および静的変数は、すべてのスレッドに共通で、1つのアプリケーション内で、複数のスレッドからのこれらの変数へのアクセスを管理する相互排他メカニズムが必要です。

スレッドは、一度作成されると他のスレッドとは非同期的に動作します。このため、順序を気にせずに共通のデータ要素にアクセスし、OCIコールを実行できます。このようにしてデータ要素に共有アクセスを行うため、アクセスされるデータの完全性を維持する同期化メカニズムが必要です。

データ・アクセスを管理するメカニズムでは、mutexes (相互排他ロック)のフォームを使用します。このメカニズムは、ユーザーには不透明な共有内部データにアクセスする複数のスレッド間で競合が発生しないように実装されています。OCIでは、mutexはそれぞれの環境ハンドルに付与されます。

Oracle DatabaseおよびOCIライブラリのスレッド・セーフティ機能により、開発者はOCIをマルチスレッド環境で使用できます。スレッド・セーフティ機能を使用すると、副作用なしに、OCIのコードを、OCIコールを実行する複数のスレッドから再入可能にできます。

注意:
スレッド・セーフティは、どのオペレーティング・システムでも利用できるとはかぎりません。詳細は、使用しているOracle Databaseシステム固有のドキュメントで確認してください。
マルチスレッドのLinuxまたはUNIX環境では、OCIBreak()を除くOCIコールはユーザー・シグナル・ハンドラでは使用できません。

ハンドルを使用および解放する正しい方法とは、アプリケーションの終了時、すべてのスレッドが破棄された後にのみ、ハンドルを作成して使用してから解放することです。

OCIスレッド・セーフティの利点

OCIにスレッド・セーフティを実装すると、次の利点があります。

- 複数のスレッドでOCIコールを実行した場合も、単一のスレッドで連続するコールを実行した場合と同じ結果になります。

- 複数のスレッドでOCIコールを実行した場合は、スレッド間で副作用がありません。

- マルチスレッド・プログラムを作成しない場合でも、スレッド・セーフのOCIコールを使用してもパフォーマンスが低下しません。

- 複数のスレッドを使用すると、プログラムのパフォーマンスが向上します。パフォーマンスが向上するのは、別々のプロセッサでスレッドを同時実行するマルチプロセッサ・システム、および低速操作と高速操作の間でオーバーラップが発生するシングル・プロセッサ・システムの場合です。

OCIスレッド・セーフティと3層アーキテクチャ

クライアント/サーバー・アプリケーションでは、クライアントをマルチスレッド・プログラムにでき、マルチスレッド・アプリケーションの典型的な使用は、3層(クライアント/エージェント/サーバー)アーキテクチャにおける使用です。このアーキテクチャでは、クライアントが関係するのは表示サービスのみです。エージェント(アプリケーション・サーバー)は、クライアント・アプリケーションのアプリケーション・ロジックを処理します。一般的には、この関係は多対1の関係で、複数のクライアントが同一のアプリケーション・サーバーを共有します。

この場合のサーバー層は、データベースです。このアプリケーション・サーバー(エージェント)は、それぞれのスレッドが1つのクライアント・アプリケーションに対してサービスを提供することから、マルチスレッド・アプリケーション・サーバーに最適です。Oracle Database環境では、このアプリケーション・サーバーはOCIプログラムまたはプリコンパイラ・プログラムです。

スレッド・セーフティの実装

スレッド・セーフティを利用するには、アプリケーションをスレッド・セーフなオペレーティング・システム上で実行する必要があります。アプリケーションでは、modeパラメータの値としてOCI_THREADEDを使用して、OCIEnvNlsCreate()をコールすることで、マルチスレッド環境で実行するように指定します。

OCIEnvNlsCreate()の後続のコールすべてにも、OCI_THREADEDを指定する必要があります。

注意:
スレッド・セーフでないオペレーティング・システムで実行するアプリケーションの場合は、OCIEnvCreate()にもOCIEnvNlsCreate()にもOCI_THREADEDの値を渡さないでください。

シングル・スレッド・アプリケーションでは、オペレーティング・システムがスレッド・セーフであるかどうかにかかわらず、 OCIEnvCreate()またはOCIEnvNlsCreate()にOCI_DEFAULTの値を渡す必要があります。シングル・スレッド・アプリケーションをOCI_THREADEDモードで実行すると、パフォーマンスが低下する可能性があります。

マルチスレッド・アプリケーションがスレッド・セーフなオペレーティング・システム上で動作している場合は、OCIライブラリで、環境ハンドルごとにアプリケーションのmutexが管理されます。OCIEnvCreate()コールまたはOCIEnvNlsCreate()コールのいずれかのmodeパラメータでOCI_ENV_NO_MUTEXの値を指定することで、アプリケーションではこの機能をオーバーライドし、独自のmutexスキームを維持できます。

想定されるのは、次のシナリオです。このシナリオは、各環境ハンドルに存在する接続の数、および各接続で作成されるスレッドの数によって変わります。

- アプリケーションに複数の環境ハンドルがあっても、それぞれの環境ハンドルにスレッドが1つの場合は、mutexは必要ありません。

- OCI_THREADEDモードで実行しているアプリケーションに1つ以上の環境ハンドルがあり、それぞれの環境ハンドルに複数の接続がある場合は、次の方法の中から選択できます。

- OCIEnvNlsCreate()のmodeに対してOCI_ENV_NO_MUTEXの値を渡します。アプリケーションでは、同一環境ハンドルで実行するOCIコールに、相互排他ロック(mutex)を設定する必要があります。この方法には、アプリケーションの設計に対してmutexスキームを最適化できるという利点があります。プログラマは、いつでも1つの環境ハンドル接続で必ず1つのOCIコールのみを処理するようにすることも必要です。

- OCIEnvNlsCreate()のmodeに対してOCI_DEFAULTの値を渡します。OCIライブラリが、同一環境ハンドルの各OCIコールに対して自動的にmutexを取得します。

注意:
OCIコールの処理の大部分はサーバー上で行われ、そのため、OCIコールを使用している2つのスレッドの接続先が同じである場合は、サーバーで一方のスレッドの処理が終了するまでもう一方はブロックできます。
OCIエラーはその他のスレッドで上書きできるため、アプリケーションのスレッドごとに1つのエラー・ハンドルを使用します。

ポーリング・モード操作とスレッド・セーフティ

OCIでは、ポーリング・モード操作をサポートします。OCIがスレッド・モードで動作中の場合、完了についてのOCIのポーリング・コールでは、OCIコールが活発に実行されているときにmutexが取得されます。ただし、OCIからアプリケーションに制御が戻されると、OCIでは取得したmutexをすべて解放します。コール元は、進行中のポーリング・モードOCI操作が完了するまで、その接続でその他のOCIコールが行われないようにする必要があります。

関連項目:
「OCIでのポーリング・モード操作」

リリース7.xとそれより後のリリースのOCIコールの混在

アプリケーションでリリース7.xとそれより後のリリースのOCIコールが混在し、後のリリースの適切なコールを使用してアプリケーションがスレッド・セーフとして初期化されている場合、スレッド・セーフティを達成するためにopinit()をコールする必要はありません。アプリケーションでは、後続のリリース7.x関数コールでリリース7.xの動作を実現できます。

OCIThreadパッケージ

OCIThreadパッケージには、通常よく使用されるスレッドの基本形がいくつか含まれています。また、様々なオペレーティング・システムにネイティブなスレッド機能へのポータブル・インタフェースを備えていますが、ネイティブなスレッド機能を持たないオペレーティング・システムにはスレッドを実装しません。

OCIThreadではポータブル実装は提供されませんが、ネイティブなマルチスレッド機能用の一連のポータブル・カバーとして動作します。このため、マルチスレッドをネイティブにサポートしていないオペレーティング・システムは、OCIThreadパッケージのごく一部の実装しかサポートできません。その結果、すべてのOCIThread機能に依存している製品は、すべてのオペレーティング・システムには移植できません。製品をすべてのオペレーティング・システムに移植するには、OCIThread機能のサブセットのみを使用する必要があります。

OCIThread APIは、主に3つの部分で構成されます。ここでは、各部分について簡単に説明します。それぞれの部分の詳細は、これ以降の項で説明します。

- 初期化および終了。これらのコールでは、OCIThreadコンテキストの初期化と終了を行います。このコンテキストは、他のOCIThreadコールで必須です。
OCIThreadでは、OCIThreadがマルチスレッド・アプリケーション内で使用されているときにのみ、プロセス初期化関数であるOCIThreadProcessInit()のコールが必要です。シングル・スレッド・アプリケーションでOCIThreadProcessInit()をコールできなくても、エラーになりません。

OCIThreadInit()をコールするたびに、常に同じOCIThreadコンテキストが戻されます。各OCIThreadInit()コールは、結果的にOCIThreadTerm()コールに合致する必要があります。

- 非アクティブなスレッドの基本形。非アクティブなスレッドの基本形は、相互排他ロック(mutex)、スレッドIDおよびスレッド固有のデータ・キーを扱うのに使用されます。これらの基本形が非アクティブと呼ばれる理由は、仕様上は複数のスレッドの存在が可能ですが、複数のスレッドを必要としないためです。これらの基本形は、シングル・スレッド環境とマルチスレッド環境の両方の仕様に応じて実装できます。このため、これらの基本形のみを使用するOCIThreadクライアントでは、複数のスレッド環境を使用しなくても正常に機能します。コードを分岐せずにシングル・スレッド環境を稼働することができます。

- アクティブなスレッドの基本形。アクティブなスレッドの基本形では、スレッドの作成、終了および操作を行います。これらの基本形がアクティブと呼ばれる理由は、真のマルチスレッド環境でのみ使用できるためです。これらの基本形の仕様では、複数のスレッドが明示的に要求されます。マルチスレッド環境であるかどうかを実行時に判断する必要がある場合は、OCIThreadのアクティブ基本形を使用する前に、OCIThreadIsMulti()をコールします。
同じアプリケーションでシングル・スレッド・オペレーティング・システムで実行するバージョンを作成するには、ソース・ファイルのアプリケーションを分岐するか、あるいはOCIThreadIsMulti()コールを使用して実行時に分岐するかのいずれであれ、コードを分岐する必要があります。

関連項目:

- 「スレッド管理関数」

- マルチスレッド・アプリケーションの例は、demoディレクトリのcdemothr.cを参照してください。

初期化および終了

この項で説明する型および関数は、OCIThreadパッケージの初期化および終了に関係しています。OCIThreadの機能を使用する場合は、あらかじめ初期化する必要があります。

初期化関数と終了関数の外見上の動作は、OCIThreadをシングル・スレッド環境で使用した場合もマルチスレッド環境で使用した場合も同じになります。表8-6には、スレッド初期化関数および終了関数がリストされています。

表8-6 初期化マルチスレッド関数および終了マルチスレッド関数

関数

用途

OCIThreadProcessInit()

OCIThreadプロセスの初期化を行います。

OCIThreadInit()

OCIThreadコンテキストを初期化します。

OCIThreadTerm()

OCIThreadレイヤーを終了してコンテキストのメモリーを解放します。

OCIThreadIsMulti()

アプリケーションがマルチスレッド環境とシングル・スレッド環境のどちらで動作しているかを、コール元に通知します。

関連項目:
「スレッド管理関数」

OCIThreadコンテキスト

OCIThread関数をコールするときは、多くの場合、OCI環境またはユーザー・セッション・ハンドルをパラメータとして使用します。OCIThreadコンテキストは、OCI環境またはユーザー・セッション・ハンドルの一部なので、OCIThreadInit()をコールして初期化する必要があります。OCIThreadコンテキストの終了は、OCIThreadTerm()をコールして行います。

注意:
OCIThreadコンテキストは、不透明なデータ構造になっています。コンテキストの内容を検査する必要はありません。

非アクティブなスレッドの基本形

非アクティブなスレッドの基本形は、mutex、スレッドID、およびスレッド固有のデータを扱います。これらの基本形の仕様では、複数のスレッドが存在する必要がないため、マルチスレッドとシングル・スレッドの両方のオペレーティング・システムで使用できます。表8-7には、非アクティブなスレッドの実装に使用する関数がリストされています。

表8-7 非アクティブなスレッドの基本形

関数

用途

OCIThreadMutexInit()

mutexの割当ておよび初期化を行います。

OCIThreadMutexDestroy()

mutexの破棄および割当て解除を行います。

OCIThreadMutexAcquire()

コールが行われたスレッドに対してmutexを取得します。

OCIThreadMutexRelease()

mutexを解放します。

OCIThreadKeyInit()

新規の鍵の割当てと生成を行います。

OCIThreadKeyDestroy()

キーの破棄および割当て解除を行います。

OCIThreadKeyGet()

コール側スレッドのキーの現在の値を取得します。

OCIThreadKeySet()

コール側スレッドのキー値を設定します。

OCIThreadIdInit()

スレッドIDの割当ておよび初期化を行います。

OCIThreadIdDestroy()

スレッドIDの破棄および割当て解除を行います。

OCIThreadIdSet()

スレッドIDの設定を変更します。

OCIThreadIdSetNull()

スレッドIDをNULLにします。

OCIThreadIdGet()

コール側スレッドのスレッドIDを取り出します。

OCIThreadIdSame()

2つのスレッドIDが同じスレッドを表すかどうかを調べます。

OCIThreadIdNull()

スレッドIDがNULLかどうかを調べます。

OCIThreadMutex

OCIThreadMutexデータ型はmutexの表現に使用されます。このmutexを使用すると、次のことを確認できます。

- 特定のデータ・セットに同時にアクセスできるのは1つのスレッドのみです。

- コードの特定の重要セクションを同時に実行できるのは1つのスレッドのみです。

mutexポインタは、クライアント構造またはスタンドアロン変数の一部として宣言できます。これらは、使用する前にOCIThreadMutexInit()により初期化する必要があります。不要になった場合は、OCIThreadMutexDestroy()を使用して破棄する必要があります。

OCIThreadMutexAcquire()を使用して、スレッドからmutexを取得できます。この場合、同時に複数のスレッドによって特定のmutexが保持されることはありません。mutexを保持しているスレッドは、OCIThreadMutexRelease()をコールすると解放できます。

OCIThreadKey

データ型OCIThreadKeyは、スレッド固有の値を持つプロセス全体の変数とみなすことができます。この場合、プロセス内のすべてのスレッドは指定したキーを使用できますが、各スレッドは他のスレッドとは独立してそのキーを調べたり変更したりできます。スレッドがキーを調べる際の値は、常にそのキーに対して最後に設定された値と同じです。他のスレッドがそのキーに対して設定した値は表示されません。キーに保持されている値のデータ型はvoid *汎用ポインタです。

キーは、OCIThreadKeyInit()を使用して作成できます。キー値はすべてのスレッドに対して、NULLに初期化されます。

スレッドからは、OCIThreadKeySet()を使用してキーの値を設定できます。また、OCIThreadKeyGet()を使用してキーの値を取得できます。

OCIThreadキー関数によって、スレッド固有のデータの保存および取出しを行うことができます。クライアントでスレッド・プールを管理し、スレッドごとに異なるタスクを割り当てる場合、OCIThreadキー関数を使用してタスクに関連付けられたデータを保存するのが適切でないことがあります。

ここでは、処理が失敗する状況を示すシナリオを示します。あるスレッドが、タスクの初期化を実行するように割り当てられているとします。初期化時、タスクによりOCIThreadキー関数を使用してスレッド内にデータが格納されます。初期化後、スレッドはスレッド・プールに戻されます。後に、スレッド・プール・マネージャは、タスクでいくつかの操作を実行するように別のスレッドを割り当てますが、タスクでは初期化時に格納されたデータを取り出す必要が生じます。タスクは別のスレッドで実行されているため、同じデータを取り出すことはできません。アプリケーション開発者がスレッド・プールを使用する場合は、この点に注意する必要があります。

OCIThreadKeyDestFunc

OCIThreadKeyDestFuncは、キーのデストラクタ・ルーチンへのポインタの型です。OCIThreadKeyInit()を使用してキーを作成すると、そのキーをデストラクタ・ルーチンに関連付けることができます。キーのデストラクタ・ルーチンは、キーに対してNULL以外の値でスレッドが終了するときには常にコールされます。デストラクタ・ルーチンは何も戻さず、1つのパラメータのみを受け入れますが、その値はスレッドの終了時にキーに対して設定された値です。

デストラクタ・ルーチンは、スレッドの終了時およびプロセス終了前に、キー内のスレッドの値に応じてコールされることが保証されています。デストラクタ・ルーチンをコールするタイミングに関してこれ以上正確な保証はありません。プロセス内のコードは、デストラクタ・ルーチンの事後条件を想定できません。特に、デストラクタは、終了したスレッドでの結合コールが戻される前に実行することは保証されていません。

OCIThreadId

OCIThreadIdデータ型は、スレッドを識別するのに使用します。指定した時間に、2つのスレッドが同じOCIThreadIdを持つことはできませんが、OCIThreadId値はリサイクルできます。スレッドの終了後、同じOCIThreadId値を持つ新規スレッドが作成されることがあります。特に、スレッドIDはプロセス内のスレッドTを一意的に識別する必要があり、プロセスのすべてのスレッドU内で一貫性があり有効である必要があります。この場合、TがUと同時に実行されることが保証されます。スレッドTのスレッドIDは、スレッドT内で取出し可能にしておく必要があります。これは、OCIThreadIdGet()を使用して実行します。

OCIThreadId型は、NULLスレッドIDの概念をサポートしています。NULLスレッドIDは、実際のスレッドのIDと同じになることはありません。

アクティブなスレッドの基本形

アクティブなスレッドの基本形では、実際のスレッドの操作を行います。これら大部分の基本形の仕様には複数のスレッドが必要なため、有効なOCIThreadでのみ正しく機能します。有効になっていないOCIThreadでは、常にエラーが戻されます。ただし、OCIThreadHandleGet()は例外で、シングル・スレッド環境でコールできますが、この場合は効果がありません。

アクティブ基本形は、マルチスレッド環境で実行されているコードからのみコールできます。OCIThreadIsMulti()をコールして、環境がマルチスレッドかシングル・スレッドかどうかを調べることができます。表8-8に、アクティブなスレッドの実装に使用する関数がリストされています。

表8-8 アクティブなスレッドの基本形

関数

用途

OCIThreadHndInit()

スレッド・ハンドルの割当ておよび初期化を行います。

OCIThreadHndDestroy()

スレッド・ハンドルの破棄および割当て解除を行います。

OCIThreadCreate()

新しいスレッドを作成します。

OCIThreadJoin()

コール側スレッドを別のスレッドと結合します。

OCIThreadClose()

スレッド・ハンドルをクローズします。

OCIThreadHandleGet()

スレッド・ハンドルを取り出します。

OCIThreadHandle

アクティブな基本形のOCIThreadJoin()およびOCIThreadClose()のスレッドを操作するには、OCIThreadHandleデータ型を使用します。OCIThreadCreate()によってオープンされたスレッド・ハンドルは、対応するOCIThreadClose()コールでクローズする必要があります。OCIThreadClose()のコール後は、スレッド・ハンドルは無効になります。

9 OCIプログラミングの高度なトピック

この章は、次の項目で構成されています。

- OCIでの接続プーリング

- OCIでのセッション・プーリング

- データベース常駐接続プーリング

- 接続プーリングまたはセッション・プーリングの使用/不使用の判断

- OCIでの文キャッシュ

- OCIでのユーザー定義コールバック関数

- OCIでの透過的アプリケーション・フェイルオーバー

- HAイベント通知

- OCIおよびStreamsアドバンスト・キューイング

- OCIでのパブリッシュ・サブスクライブの通知

OCIでの接続プーリング

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

- OCI接続プーリングの概念

- 接続プーリングのOCIコール

- OCI接続プーリングの例

接続プーリングとは、ロードを均衡化するために、再使用可能な物理接続のグループ(プール)を複数のセッションで使用することです。プールは、アプリケーションではなく、OCIにより管理されます。Webアプリケーション・サーバーおよび電子メール・サーバーの中間層アプリケーションでも接続プーリングを使用できます。

この機能は、バックエンドのOracle Databaseに接続しているWebアプリケーション・サーバーで使用する方法があります。Webアプリケーション・サーバーで、データベース・サーバーから同時に複数のデータ要求を受けたとします。アプリケーションでは、アプリケーションの初期化を行うとき、各環境にプール(またはプール・セット)を作成できます。

OCI接続プーリングの概念

Oracle Databaseは、データベース・セッションと接続のファイングレイン管理など、いくつかのトランザクション・モニター機能を備えています。データベース・セッションのファイングレイン管理は、接続(サーバー・ハンドル)からデータベース・セッション(ユーザー・ハンドル)の概念を切り離すことで実行されます。セッション切替えやセッション移行でOCIコールを使用すると、アプリケーション・サーバーまたはトランザクション・モニターでは、少数の物理接続で複数のセッションを多重化でき、したがって、接続およびバックエンドのOracleサーバー・プロセスをプールすることで、高度な拡張性が実現します。

接続プール自体は通常、物理接続の共有プールで構成され、同じ数の専用サーバー・プロセスを含むバックエンド・サーバー・プールに変換されます。

物理接続の数は、アプリケーションで使用するデータベース・セッションの数より少なくなります。物理接続とバックエンド・サーバー・プロセスの数も、接続プーリングを使用することで少なくなります。これによって、多重化できるデータベース・セッションの数が多くなります。

共有サーバーとの類似点と相違点

中間層での接続プーリングは、共有サーバーがバックエンドで提供する機能に似ています。セッション多重化ロジックを中間層で管理することで、接続プーリングは、専用サーバー・インスタンスを共有サーバー・インスタンスと同じように動作させます。

中間層の接続プールによって、専用サーバー・プロセスへの着信接続を含む専用サーバー・プロセスのプーリングが制御されます。接続プーリングと共有サーバーの主な相違点は、共有サーバーの場合、クライアントからの接続は、通常データベース・インスタンスのディスパッチャへの接続である点です。ディスパッチャには、クライアント要求を適切な共有サーバーに送信します。ただし、接続プールからの物理接続は、中間層からバックエンドのサーバー・プールにある専用サーバー・プロセスに直接接続されます。

接続プーリングは、中間層自体がマルチスレッドである場合にのみ有効です。各スレッドでは、データベースに対するセッションをメンテナンスできます。データベースへの実際の接続は接続プールでメンテナンスされ、その接続(専用データベース・サーバー・プロセスのプールを含む)は中間層のすべてのスレッドの間で共有されます。

ステートレス・セッションとステートフル・セッション

ステートレス・セッションは、中間層スレッド間で逐次再利用可能です。ある3層ユーザーのためにスレッドでデータベース要求を処理した後で、異なる3層ユーザーの異なる要求のために同じデータベース・セッションを再利用できます。

ただし、データベースに対するステートフル・セッションは、特定の3層ユーザーに関連する特定の状態になっている場合があるため、中間層スレッド間で逐次再利用はできません。このような状態の例としては、オープン・トランザクション、文からのフェッチ状態、PL/SQLパッケージ状態などがあります。その状態が存在するかぎり、そのセッションは異なる要求には再利用できせん。

注意:
ステートレス・セッションも、オープン・トランザクション、オープン文のフェッチ状態などになる可能性があります。ただし、このような状態が継続するのは比較的短期間(中間層スレッドによって特定の3層要求を処理する期間のみ)であるため、(これらの状態がクリーン・アップされると)そのセッションを異なる三層ユーザーのために逐次再利用できます。
ステートレス・セッションは通常、文キャッシュとともに使用されます。

接続プーリングによって、ステートレス接続とステートフル・セッションが提供されます。ステートレス・セッションを操作する必要がある場合は、「OCIでのセッション・プーリング」を参照してください。

複数の接続プール

複数の接続プールの拡張概念を、様々なデータベース接続に使用できます。複数の接続プールは、異なる優先度がユーザーに割り当てられている場合にも使用できます。接続プーリングを使用すると、異なるレベルのサービス保証を実装できます。

図9-1は、OCI接続プーリングを示しています。

図9-1 OCI接続プーリング

透過的アプリケーション・フェイルオーバー

接続プーリングでは、透過的アプリケーション・フェイルオーバー(TAF)が使用可能になっています。BACKUPおよびPRECONNECT句が接続文字列では使用できず接続プーリングとTAFでは機能しない点を除いて、TAFの概念は、接続プール内の各接続に等しく適用されます。

接続プールの接続がフェイルオーバーする場合、主接続文字列自体を使用して接続します。セッションは、そのインスタンスに障害が発生した後に、プールを使用してデータベースとのラウンドトリップを行うときにフェイルオーバーします。リスナーは、サービスベースの接続文字列でよく行われるように、存在する正常なインスタンスに接続をルーティングするよう構成されます。

関連項目:
『Oracle Database Net Services管理者ガイド』の透過的アプリケーション・フェイルオーバーの構成に関する章

接続プーリングのOCIコール

アプリケーションで接続プーリングを使用するには、次のことが必要です。

1. プール・ハンドルの割当て

2. 接続プールの作成

3. データベースへのログイン

4. 接続プーリングでのSGA制限の処理

5. データベースからのログオフ

6. 接続プールの破棄

7. プール・ハンドルの解放

プール・ハンドルの割当て

接続プーリングでは、OCIHandleAlloc()によってプール・ハンドルOCI_HTYPE_CPOOLを割り当てる必要があります。指定された環境ハンドルに対して複数のプールを作成できます。

単一の接続プーリングの割当て例を次に示します。

OCICPool *poolhp;
OCIHandleAlloc((void *) envhp, (void **) &poolhp, OCI_HTYPE_CPOOL,
(size_t) 0, (void **) 0));

接続プールの作成

OCIConnectionPoolCreate()関数は、接続プール・ハンドルを初期化します。次のINパラメータがあります。

- connMin－ プールの作成時にオープンする最小接続数です。

- connIncr－ すべての接続がビジーのときにコールで接続が必要な場合に、オープンする接続の増分数です。この増分は、オープンしている接続の合計数がそのプールでオープン可能な最大接続数より少ない場合にのみ使用します。

- connMax－ プールでオープンできる最大接続数です。プールで最大数の接続がオープンするとすべての接続がビジーになるため、コールに接続が必要な場合は、取得するまで待機することになります。ただし、プールにOCI_ATTR_CONN_NOWAIT属性が設定されている場合は、エラーが戻されます。

- poolUsernameおよびpoolPassword－ ユーザー・セッションがプールの接続間で透過的に移行できます。

- さらに、OCI_ATTR_CONN_TIMEOUT属性によって、プールの接続のタイムアウトを設定できます。この時間を超えてアイドル状態の接続は定期的に終了し、オープン接続が最適な数に維持されます。この属性が設定されていない場合は、接続がタイムアウトになることはありません。

注意:
プールの縮小は、ネットワーク・ラウンドトリップがある場合にのみ発生します。操作がない場合、接続は継続されます。

前述の属性はすべて動的に構成できるため、アプリケーションでは現在のロード(オープン接続数とビジー接続数)を読み取り、これらの属性を適切に調整できます。

プール属性(connMax、connMin、connIncr)を動的に変更する場合は、modeパラメータにOCI_CPOOL_REINITIALIZEを設定したOCIConnectionPoolCreate()をコールする必要があります。

OUTパラメータpoolNameとpoolNameLenには、データベース名とその長さの引数のかわりに、後続のOCIServerAttach()とOCILogon2()コールで使用する値が格納されます。

アプリケーションで作成できるプールの数に制限はありません。中間層アプリケーションでは、複数のプールを作成して同一サーバーまたは異なるサーバーに接続し、アプリケーション固有のニーズに基づいてロードを均衡化できます。

このコールのコード例を次に示します。

OCIConnectionPoolCreate((OCIEnv *)envhp,
(OCIError *)errhp, (OCICPool *)poolhp,
&poolName, &poolNameLen,
(text *)database,strlen(database),
(ub4) connMin, (ub4) connMax, (ub4) connIncr,
(text *)poolUsername,strlen(poolUserLen),
(text *)poolPassword,strlen(poolPassLen),
OCI_DEFAULT));

データベースへのログイン

アプリケーションでは、次のいずれかのインタフェースを使用して、スレッドごとにデータベースにログインする必要があります。

- OCILogon2()
最も単純なインタフェースです。このインタフェースは、単純な接続プール接続が必要で、セッション・ハンドルの属性を変更する必要がない場合に使用します。このインタフェースは、データベースへのプロキシ接続を行う場合にも使用できます。

次に、OCILogon2()の使用例を示します。

for (i = 0; i < MAXTHREADS; ++i)
{
OCILogon2(envhp, errhp, &svchp[i], "hr", 2, "hr", 2, poolName,
poolNameLen, OCI_LOGON2_CPOOL));

}

このインタフェースを使用してプロキシ接続を行うには、パスワード・パラメータをNULLに設定してください。

- OCISessionGet()
このインタフェースの使用をお薦めします。このインタフェースを使用すると、ユーザーは、証明書、識別名などの外部認証方式も使用できます。OCISessionGet()は、セッションを取得する場合の推奨する統一関数コールです。

次に、OCISessionGet()の使用例を示します。

for (i = 0; i < MAXTHREADS; ++i)
{
OCISessionGet(envhp, errhp, &svchp, authp,
(OraText *) poolName,
strlen(poolName), NULL, 0, NULL, NULL, NULL,
OCI_SESSGET_CPOOL)
}

- OCIServerAttach()およびOCISessionBegin()
アプリケーションで、ユーザー・セッション・ハンドルおよびサーバー・ハンドルに特別な属性を設定する必要がある場合は、別のインタフェースを使用できます。このような要件に対して、アプリケーションでは、すべてのハンドル(接続プール・ハンドル、サーバー・ハンドル、セッション・ハンドルおよびサービス・コンテキスト・ハンドル)を割り当てる必要があります。次の順序に従います。

1. 接続プールを作成します。
接続プーリングでは、物理接続で仮想サーバー・ハンドルが透過的に多重化されるため、ユーザーがこの作業を行う必要はありません。ユーザーには、セッション用に専用(仮想)接続が確立されているように感じられます。多重化はユーザーに対して透過的に行われるため、仮想サーバー・ハンドル自体に対してセッションを多重化しないでください。ユーザー・レベルで明示的な多重化を必要とするセッション移行およびセッション切替えの概念は、接続プーリングに関しては廃止されたため、使用しないでください。

2. モードをOCI_CPOOLに設定してOCIServerAttach()をコールします。
OCIプログラムでは、ユーザーは、接続プールを使用して作成されるセッションごとに一意の仮想サーバー・ハンドルを作成(モードをOCI_CPOOLに設定してOCIServerAttach()をコール)する必要があります。仮想サーバー・ハンドルとセッションは、1対1対応である必要があります。

3. モードをOCI_DEFAULTに設定してOCISessionBegin()をコールします。
資格証明は、OCISessionBegin()を使用してOCI_CRED_RDBMS、OCI_CRED_EXTまたはOCI_CRED_PROXYに設定できます。資格証明をOCI_CRED_EXTに設定すると、セッション・ハンドルの設定ではユーザー名もパスワードも必要ありません。資格証明をOCI_CRED_PROXYに設定すると、セッション・ハンドルの設定ではユーザー名のみ必要です (1次セッションを明示的に作成したり、OCI_ATTR_MIGSESSIONを設定する必要はありません)。

仮想サーバー・ハンドルに接続プールを指定する(modeをOCI_CPOOLに設定してOCIServerAttach()をコールする)場合は、OCISessionBegin()へのコールでOCI_MIGRATEフラグを設定しないでください。互換性上の理由でのみ、このOCI_MIGRATEフラグを渡すことをお薦めします。接続プールを使用するときに、ユーザーには、セッションに独自の専用(仮想)接続が確立されているように感じられますが、この接続は実際の接続に対して透過的に多重化されているだけのため、OCI_MIGRATEフラグは使用しないでください。

接続プーリングでのSGA制限の処理

OCI_CPOOLモード(接続プーリング)では、バックエンド・データベースのセッション・メモリー(UGA)はSGAから取得されます。SGAで格納できるセッション・メモリー以上のメモリー量をアプリケーションで使用する場合は、バックエンド・データベースでSGAをチューニングしてSGAを拡張する必要性が生じる場合があります。バックエンド・データベースに対するメモリー・チューニングの要件は、インスタンスが専用モードである点を除けば、共有サーバーがバックエンドの場合にLARGE POOLを構成する動作に似ています。

関連項目:
『Oracle Databaseパフォーマンス・チューニング・ガイド』の共有サーバーの構成に関する項

さらにSGA制限が発生する場合は、次の点を考慮してください。

- セッションごとにオープンする文を少なくして、セッション・メモリーの使用量を減らします。

- 中間層にセッションをプールすることで、バックエンドのセッション数を減らします。

- それ以外の場合は、接続プーリングをオフにします。

アプリケーションでは、バックエンドで専用データベース・リンクを接続プーリングとともに使用しないでください。

バックエンドが専用サーバーの場合、専用データベース・リンクを使用するセッションは物理接続に連結され、同じ接続が他のセッションでは使用できなくなるため、効率的な接続プーリングは実現しません。アプリケーションで専用データベース・リンクを使用し、セッション間でバックエンド処理を効率的に共有できない場合は、共有データベース・リンクの使用を検討してください。

関連項目:
分散データベースの詳細は、『Oracle Database管理者ガイド』の共有データベース・リンクに関する項を参照してください。

データベースからのログオフ

次のコールから、ログイン・コールに対応するものを選択し、それを使用して接続プーリング・モードでデータベースからログオフします。

- OCILogoff()
OCILogon2()を使用して接続を行った場合は、OCILogoff()を使用してログオフする必要があります。

- OCISessionRelease()
OCISessionGet()をコールして接続を行った場合は、OCISessionRelease()をコールしてログオフする必要があります。

- OCISessionEnd()およびOCIServerDetach()
OCIServerAttach()およびOCISessionBegin()をコールして接続を行いセッションを開始した場合は、OCISessionEnd()をコールしてセッションを終了し、OCIServerDetach()をコールして接続を解放する必要があります。

接続プールの破棄

OCIConnectionPoolDestroy()を使用して、接続プールを破棄します。

プール・ハンドルの解放

プール・ハンドルは、OCIHandleFree()を使用して解放します。

次のコード・フラグメントは、前述した3つの処理を示しています。

for (i = 0; i < MAXTHREADS; ++i)
{
checkerr(errhp, OCILogoff((void *) svchp[i], errhp));
}
checkerr(errhp, OCIConnectionPoolDestroy(poolhp, errhp, OCI_DEFAULT));
checkerr(errhp, OCIHandleFree((void *)poolhp, OCI_HTYPE_CPOOL));

関連項目:

- 「接続プール・ハンドル属性」

- 「OCIConnectionPoolCreate()」、「OCILogon2()」および「OCIConnectionPoolDestroy()」

OCI接続プーリングの例

テストされた全プログラムでの接続プーリングの例は、ディレクトリdemoのcdemocp.cおよびcdemocpproxy.cにあります。

OCIでのセッション・プーリング

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

- OCIセッション・プーリングの機能

- 同種セッション・プールおよび異種セッション・プール

- セッション・プーリングでのタグの使用

- セッション・プーリング用のOCIハンドル

- OCIセッション・プーリングの使用

- セッション・プーリングのOCIコール

- OCIセッション・プーリングの例

- 実行時接続ロード・バランシング

セッション・プーリングとは、アプリケーションがデータベースに対するステートレス・セッションのグループを作成してメンテナンスすることを意味します。これらのセッションは、要求に応じてThinクライアントに提供されます。使用可能なセッションがない場合は、新しいセッションが作成されます。セッションでのクライアントの処理が完了すると、クライアントはプールに対してセッションを解放します。したがって、プール内のセッション数は動的に増加する場合があります。

プール内の一部のセッションに、特定のプロパティを使用してタグを付けることができます。たとえば、ユーザーは、デフォルト・セッションを要求して特定の属性を設定し、そのセッションにラベルまたはタグを付けて、プールに戻すことができます。そのユーザーまたは他のユーザーは、同じ属性を持つセッションを要求できるため、同じタグが付いたセッションを要求できます。プール内に、同じタグが付いた複数のセッションが存在する場合があります。セッションのタグは、変更またはリセットできます。

関連項目:
「セッション・プーリングでのタグの使用」

OCIでのセッション・プーリングを使用して、プロキシ・セッションを作成してメンテナンスすることもできます。

使用可能なセッションがなく、プールの最大サイズに達した場合のアプリケーションの動作は、指定した属性によって決まります。新しいセッションが作成されるか、エラーが戻されるか、またはスレッドがブロックしてセッションが使用可能になるまで待機する場合があります。

セッション・プーリングの主な利点は、パフォーマンスです。データベースへの接続(特にデータベースがリモートの場合)は、時間がかかるアクティビティです。したがって、クライアントでは、時間をかけてサーバーに接続し、資格証明を認証して有効なセッションを受け取るかわりに、プールからセッションを取り出すことができます。

OCIセッション・プーリングの機能

セッション・プーリングにより次のタスクを実行できます。

- ステートレス・セッションのプールを透過的に作成、メンテナンスおよび管理します。

- アプリケーションでプールを作成し、プール内のセッションの最小数、増分数および最大数を指定するインタフェースを提供します。

- ユーザーがデフォルト・セッションまたはタグ付けされたセッションをプールとの間で取得および解放するためのインタフェースを提供します。タグ付けされたセッションとは、クライアント定義の特定のプロパティが指定されたセッションです。

- アプリケーションで、セッションの最小数と最大数を動的に変更できます。

- 長時間アイドル状態のセッションをクローズし、必要なときにセッションを作成することによって、常に最適な数のセッションがオープンしているようにメンテナンスするメカニズムを提供します。

- セッション・プーリングで認証を行うことができます。

同種セッション・プールおよび異種セッション・プール

セッション・プールは、同種または異種のいずれかになります。同種セッション・プーリングとは、プール内のセッションの認証情報が同じ(同じユーザー名、パスワードおよび権限)であることを意味します。異種セッション・プーリングとは、セキュリティ属性と権限がセッションごとに異なる場合があるため、認証情報を指定する必要があることを意味します。

セッション・プーリングでのタグの使用

ユーザーは、タグを使用して、プール内のセッションをカスタマイズできます。クライアントは、デフォルト・セッションまたはタグが付いていないセッションをプールから取得して、特定の属性(NLS設定など)をセッションに設定し、OCISessionRelease()コールでセッションに適切なタグを付けて、プールに戻すことができます。

そのユーザーまたは他のユーザーは、同じ属性を持つセッションを使用するために、同じタグが付いたセッションを要求でき、これはOCISessionGet()コールで同じタグを指定することでできます。

関連項目:
セッションのタグ付けの詳細は、「OCISessionGet()」を参照してください。

セッション・プーリング用のOCIハンドル

セッション・プーリング用のハンドル ・タイプは次のとおりです。

OCISPool

セッション・プール・ハンドルです。これは、OCIHandleAlloc()を使用して割り当てます。OCISessionPoolCreate()およびOCISessionPoolDestroy()に渡す必要があります。属性の型はOCI_HTYPE_SPOOLです。

OCIHandleAlloc()コールの例を次に示します。

OCISPool *spoolhp;
OCIHandleAlloc((void *) envhp, (void **) &spoolhp, OCI_HTYPE_SPOOL,
(size_t) 0, (void **) 0));

環境ハンドルに対して、複数のセッション・プールを作成できます。

OCIAuthInfo

認証情報ハンドルです。これは、OCIHandleAlloc()を使用して割り当てます。これは、OCISessionGet()に渡されます。このハンドルでは、ユーザー・セッション・ハンドルでサポートされるすべての属性をサポートします。詳細は、「ユーザー・セッション・ハンドル属性」を参照してください。認証情報ハンドルの属性の型はOCI_HTYPE_AUTHINFOです(表2-1を参照)。

OCIHandleAlloc()コールの例を次に示します。

OCIAuthInfo *authp;
OCIHandleAlloc((void *) envhp, (void **) &authp, OCI_HTYPE_AUTHINFO,
(size_t) 0, (void **) 0));

関連項目:

- 認証情報ハンドルに属する属性は、「ユーザー・セッション・ハンドル属性」を参照してください。

- 接続プーリング属性の詳細は、「セッション・プール・ハンドル属性」を参照してください。

- セッション・プーリングで使用する関数の詳細は、「接続関数、認証関数および初期化関数」を参照してください。

- このコールで使用できるセッション・ハンドル属性の詳細は、「OCISessionGet()」を参照してください。

OCIセッション・プーリングの使用

ユーザー名とパスワードを使用する単純なセッション・プーリング・アプリケーションの作成手順は、次のとおりです。

1. OCISPoolハンドルに対してOCIHandleAlloc()を使用して、セッション・プール・ハンドルを割り当てます。環境ハンドルに対して複数のセッション・プールを作成できます。

2. modeをOCI_DEFAULT (新規セッション・プールの場合)に設定したOCISessionPoolCreate()を使用して、セッション・プールを作成します。その他のモードについては、関数の説明を参照してください。

3. スレッドごとにループを行います。次の処理を実行する関数を使用してスレッドを作成します。

1. OCIHandleAlloc()を使用して、OCIAuthInfo型の認証情報ハンドルを割り当てます。

2. OCIAttrSet()を使用して、認証情報ハンドルにユーザー名とパスワードを設定します。

3. modeをOCI_SESSGET_SPOOLに設定したOCISessionGet()を使用して、プールされたセッションを取得します。

4. トランザクションを実行します。

5. ハンドルを割り当てます。

6. 文を準備します。

注意:
OCIセッション・プールから取得したサービス・コンテキストを使用する場合、OCISessionGet() (またはOCILogon2())によって戻されたサービス・コンテキストを使用する必要があり、これらのコールの外で他のサービス・コンテキストを作成する必要はありません。
サービス・コンテキストを指定したOCIStmtPrepare2()を使用して取得した文ハンドルは、後で同じサービス・コンテキストとの組合せでのみ使用でき、異なるサービス・コンテキストとは使用できません。

7. 文を実行します。

8. トランザクションをコミットまたはロールバックします。

9. OCISessionRelease()を使用して、セッションを解放(ログオフ)します。

10. OCIHandleFree()を使用して、認証情報ハンドルを解放します。

11. 各スレッドのループを終了します。

4. OCISessionPoolDestroy()を使用して、セッション・プールを破棄します。

セッション・プーリングのOCIコール

ここでは、セッション・プーリングのOCIコールの使用方法について説明します。OCIには、次のタスクを実行するためにセッション・プーリングのコールが用意されています。

- プール・ハンドルの割当て

- 接続プールの作成

- データベースへのログイン

- データベースからのログオフ

- 接続プールの破棄

- プール・ハンドルの解放

プール・ハンドルの割当て

セッション・プーリングでは、OCIHandleAlloc()をコールしてプール・ハンドルOCI_HTYPE_SPOOLを割り当てる必要があります。

指定された環境ハンドルに対して複数のプールを作成できます。単一のセッション・プーリングの割当て例を次に示します。

OCISPool *poolhp;
OCIHandleAlloc((void *) envhp, (void **) &poolhp, OCI_HTYPE_SPOOL, (size_t) 0,
(void **) 0));

プール・セッションの作成

OCISessionPoolCreate()関数を使用して、セッション・プールを作成できます。このコールの使用例を次に示します。

OCISessionPoolCreate(envhp, errhp, poolhp, (OraText **)&poolName,
(ub4 *)&poolNameLen, database,
(ub4)strlen((const signed char *)database),
sessMin, sessMax, sessIncr,
(OraText *)appusername,
(ub4)strlen((const signed char *)appusername),
(OraText *)apppassword,
(ub4)strlen((const signed char *)apppassword),
OCI_DEFAULT);

データベースへのログイン

次のコールを使用して、セッション・プーリング・モードでデータベースにログインできます。

- OCILogon2()
最も単純なコールです。ただし、ユーザーは、セッションのタグ付けを行うことができません。セッション・プーリング・モードでOCILogon2()を使用してデータベースにログインするコード例を、次に示します。

for (i = 0; i < MAXTHREADS; ++i)
{
OCILogon2(envhp, errhp, &svchp[i], "hr", 2, "hr", 2, poolName,
poolNameLen, OCI_LOGON2_SPOOL));
}

- OCISessionGet()
これは、使用するのが推奨されるコールです。これにより、ユーザーは、プール内のセッションにラベル付け(タグ付け)ができるため、特定のセッションを容易に取得できます。次に、OCISessionGet()の使用例を示します。これは、demoディレクトリのcdemosp.cから取り出しました。

OCISessionGet(envhp, errhp, &svchp, authInfop,
(OraText *)database,strlen(database), tag,
strlen(tag), &retTag, &retTagLen, &found,
OCI_SESSGET_SPOOL);

OCIセッション・プールから取得したサービス・コンテキストを使用する場合、OCISessionGet() (またはOCILogon2())によって戻されたサービス・コンテキストを使用する必要があり、これらのコールの外で他のサービス・コンテキストを作成する必要はありません。

サービス・コンテキストを指定したOCIStmtPrepare2()を使用して取得した文ハンドルは、後で同じサービス・コンテキストとの組合せでのみ使用でき、異なるサービス・コンテキストとは使用できません。

データベースからのログオフ

次のコールから、ログイン・コールに対応するものを選択し、それを使用してセッション・プーリング・モードでデータベースからログオフします。

- OCILogoff()
OCILogon2()を使用して接続を行った場合は、OCILogoff()をコールしてログオフする必要があります。

- OCISessionRelease()
OCISessionGet()を使用して接続を行った場合は、OCISessionRelease()をコールしてログオフする必要があります。保留状態のトランザクションは自動的にコミットされます。

セッション・プールの破棄

セッション・プールを破棄するには、次の例に示すように、OCISessionPoolDestroy()をコールします。

OCISessionPoolDestroy(poolhp, errhp, OCI_DEFAULT);

プール・ハンドルの解放

セッション・プールを解放するには、次の例に示すように、OCIHandleFree()をコールします。

OCIHandleFree((void *)poolhp, OCI_HTYPE_SPOOL);

注意:
開発者: 接続をプールに解放する前に、オープン・トランザクションをコミットまたはロールバックしてください。そうしない場合、接続が解放されるときに、Oracle Databaseでは自動的にオープン・トランザクションがコミットされます。
セッション・プールの使用中にインスタンス障害が検出されると、OCIではそのインスタンスへのセッションのクリーン・アップを試みます。

OCIセッション・プーリングの例

テスト済の完成プログラムでのセッション・プーリングの例は、demoディレクトリのcdemosp.cを参照してください。

実行時接続ロード・バランシング

Oracle Real Application Clusters (Oracle RAC)は、単一データベースを複数ノードにある複数インスタンスで管理するデータベース・オプションです。Oracle RAC共有ディスクのデータベース・クラスタリングの方法により、拡張性が向上します。ノードは、現在の必要を満たすために、簡単に追加または解放でき、1つのノードに障害が発生した場合でも、他のノードでそのワークロードが引き継がれるため、可用性が向上します。Oracle RACにより、すべてのインスタンスがデータベース全体にアクセスできるため、データベースに高可用性機能とフェイルオーバー機能が加わります。

作業リクエストのバランシングは、接続時に1回と実行時に1回発生します。これらを、接続時ロード・バランシング(Oracle Net Servicesで提供)および実行時接続ロード・バランシングと呼びます。Oracle RAC環境の場合、セッション・プールでは、高速アプリケーション通知(FAN)イベントによりOracle RACロード・バランシング・アドバイザから受け取ったサービス・メトリックを使用して、アプリケーション・セッション要求を均衡化します。セッション・プールに入る作業リクエストは、現行のサービス・パフォーマンスを使用して、サービスを提供するOracle RACのインスタンス間で分散できます。

関連項目:

- demoディレクトリのcdemosp.c

- 「データベース常駐接続プーリング」

接続時ロード・バランシングは、アプリケーションによりセッションが最初に作成される時点で発生します。プールの一部であるセッションも、その最初の作成時にOracle RACインスタンス間で適切に分散される必要があります。これにより、各インスタンスでのセッションが作業を実行するチャンスを取得することになります。

ランタイム接続ロード・バランシングは、セッション・プール内で作業の処理に最も適切なセッションに作業リクエストをルーティングします。これは既存のセッション・プールからセッションを選択する際に発生するため、頻度の高いアクティビティです。単一インスタンスでのみサービスをサポートするセッション・プールの場合は、プール内で使用可能な最初のセッションで十分です。プールが複数インスタンスにまたがるサービスをサポートしている場合は、適切なサービスを提供できる、または容量の大きいインスタンスが多数のリクエストを取得するように、作業リクエストをインスタンス間で分散する必要があります。

実行時接続ロード・バランシングは、Oracle Databaseリリース10.2以上のサーバーと通信するOracle Databaseリリース11.1以上のクライアントでは、デフォルトで有効です。OCISessionPoolCreate()のコール時にmodeパラメータをOCI_SPC_NO_RLBに設定すると、実行時接続ロード・バランシングが無効になります。

ロード・バランシング・アドバイザFANイベントの受信

サービス時間に基づいてサービス・メトリックを受信するための要件は、次のとおりです。

- Oracleクラスタウェアを伴うOracle RAC環境が設定され、有効化されていること。

- アプリケーションがスレッド・ライブラリとリンクされていること。

- OCI環境がOCI_EVENTSおよびOCI_THREADEDモードで作成されていること。

- サービスが変更され、サービスの目的および接続ロード・バランシングの目的が次のように設定されていること。

EXEC DBMS_SERVICE.MODIFY_SERVICE("myService",
DBMS_SERVICE.GOAL_SERVICE_TIME,
clb_goal => dbms_service.clb_goal_short);

関連項目:

- 「OCISessionPoolCreate()」

- 『Oracle Real Application Clusters管理およびデプロイメント・ガイド』のFANイベントを受信するためのOCIクライアント有効化に関する項

- 『Oracle Database PL/SQLパッケージおよびタイプ・リファレンス』の「DBMS_SERVICE」

データベース常駐接続プーリング

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

- データベース常駐接続プーリングの構成

- DRCPでのOCIセッション・プールAPIの使用

- セッション純正値および接続クラス

- データベース常駐接続プールの開始

- データベース常駐接続プーリングの有効化

- OCIアプリケーションにおけるDRCPの拡張性による利点

- DRCPの使用に関するベスト・プラクティス

- 互換性および移行

- データベース常駐接続プーリングの使用に対する制限

- カスタム・プールでのDRCPの使用

- ステートフルまたはステートレスとしてのセッションの明示的作成

- DRCPとReal Application Clusters

- DRCPとData Guard

データベース常駐接続プーリング(DRCP)は、アプリケーションがデータベース接続を取得し、この接続で比較的短い時間動作してから接続を解放する一般的なWebアプリケーションの使用シナリオに対し、データベース・サーバーの接続プールを提供します。DRCPプール・サーバーのプロセスは、それぞれが専用サーバー・プロセスとデータベース・セッションを組み合せたものと同等であり、これをプール・サーバーと呼びます。プール・サーバーは、同じホストまたは複数のホストで実行されている複数のアプリケーション間で共有が可能です。接続ブローカ・プロセスは、プール・サーバーをデータベース・インスタンスのレベルで管理します。DRCPはプログラム実行時に選択される構成可能な機能であり、従来型とDRCPベースの接続アーキテクチャを同時に使用できるようになります。

DRCPは、中間層接続プーリングを実行できないマルチプロセス・シングル・スレッド・アプリケーション・サーバー(PHPやApacheなど)を含むアーキテクチャに特に関係しています。DRCPは、数百から数千単位のWebサーバーまたは中間層がデータベース・アクセスとクライアント側プールを必要とする大規模なWebデプロイメントでもきわめて効果的です(Javaのようなマルチスレッド・システムと言語でも)。データベースは、DRCPを使用して何万という同時接続に合せて拡張できます。多数の接続に伴ってデータベースWebアプリケーションのスケーリングが必要な場合、接続プーリング・ソリューションとしてDRCPが適しています。

DRCPは、中間層プロセスのスレッド間で接続を共有する中間層接続プールを補充します。また、DRCPを使用すると、同じ中間層ホスト上の中間層プロセス間でも、複数の中間層ホスト間でも、あるいは複数の中間層(Webサーバー、コンテナ)間でもデータベース接続を共有でき、異なる言語で書かれたアプリケーションにも対応できます。これにより、多数のクライアント接続をサポートするために必要となる主要なデータベース・リソースが大幅に削減されるため、データベース層のメモリー・フットプリントが削減され、中間層およびデータベース層の両方の拡張性が向上します。すぐに使用可能なサーバーのプールがあれば、クライアント接続の作成および分割にかかるコストを削減できるというメリットもあります。

クライアントはデータベース常駐接続プールから接続を取得し、接続ブローカと呼ばれるOracle Databaseバックグラウンド・プロセスに接続します。接続ブローカはプール機能を実装し、クライアントからの永続インバウンド接続間でプール・サーバーを多重化します

クライアントでデータベース・アクセスが必要な場合、接続プローカーではプールからサーバー・プロセスを取得して、クライアントに渡します。この結果、クライアントは要求が処理されるまで、そのサーバー・プロセスに直接接続されます。サーバーが終了すると、サーバー・プロセスは解放されてプールに戻され、クライアントからの接続は、接続ブローカに対してクライアント・プロセスからの永続インバウンド接続としてリストアされます。DRCPでは、リソースの解放によりセッションはそのままの状態で残りますが、接続(サーバー・プロセス)との関連付けはなくなります。このセッションは、システム・グローバル領域(SGA)ではなくプログラム・グローバル領域(PGA)にユーザー・グローバル領域(UGA)を格納するため、クライアントはアクティビティの検出時に透過的に接続を再確立できます。

DRCPは通常、接続数の多いアプリケーションで多用されます。共有サーバーは接続数が中程度の場合に効果的であり、専用セッションは接続数が少ない場合に適しています。しきい値サイズは、データベース・ホストで使用できるメモリー量と相対しています。

DRCPには、次の利点があります。

- 複数のクライアント・アプリケーション間と、中間層アプリケーション・サーバー間でリソース共有が可能になります。

- データベース・ホストでリソース使用量が減少するため、データベースとアプリケーションのスケーラビリティが向上します。

共有サーバーと比較した場合、DRCPには次のような利点もあります。

- DRCPは、クライアント側接続プーリングによって用意されるデータベース・サーバーに直接結び付けられます(つまり、クライアント側接続プーリングのような仲介を必要とせず、共有サーバーとも異なる)

- DRCPは、データベース・サーバーをプールできます(クライアント側接続プーリングおよび共有サーバーと同様)

- DRCPは、セッションをプールできます(クライアント側接続プーリングと同様で、共有サーバーとは異なる)

- DRCPは、中間層の境界間で接続を共有できます(クライアント側接続プーリングとは異なる)

DRCPは、データベース・リソースの使用率を最小限に抑えたまま、多数の接続が必要となる環境でのスケーラビリティ要件に対応できる、独自の接続プーリング・ソリューションです。

関連項目:

- DRCPアーキテクチャの詳細は、『Oracle Database概要』を参照してください

データベース常駐接続プーリングの構成

プールは、DBMS_CONNECTION_POOLパッケージを使用してDBAによって管理されます。プールはデフォルトでインストールされていますが、停止の状態です。DBAがプールを起動して、DRCP構成オプションを指定する必要があります。オプションには、プールで許可されるプール・サーバーの最小数と最大数、作成する接続ブローカの数、各接続ブローカが処理する接続の最大数などがあります。詳細は、リファレンスを参照してください。

OCIセッション・プールAPIは、データベース常駐接続プールと相互運用するために拡張されています。詳細は、リファレンスを参照してください。

関連項目:

- DBMS_CONNECTION_POOLパッケージの詳細は、『Oracle Database PL/SQLパッケージおよびタイプ・リファレンス』を参照してください。

- DRCP用のデータベース構成の詳細は、『Oracle Database管理者ガイド』を参照してください。

DRCPでのOCIセッション・プールAPIの使用

この後の各項では、データベース常駐接続プールと相互運用するために拡張されたOCIセッション・プールAPIについて説明します。OCIアプリケーションでは通常、DRCP用のOCIセッション・プールの環境を、データベース接続文字列(connStr)、ユーザー名(userid)とパスワード(password)が各セッションに関連付けられているかどうか、プール内のすべてのセッションが渡されたユーザー名およびパスワードで認証されるように、modeパラメータがOCI_SPC_HOMOGENEOUSとして指定されている場合に、開始される最小セッション数(sessMin)と次の増分セッション数(sessIncr)、セッション・プールで許可される最大セッション数(sessMax)などを指定することで、OCISessionPoolCreate()を使用して、DRCP用のOCIセッション・プールの環境を初期化します。

セッションはDRCPから取得され、modeパラメータでOCI_SESSGET_SPOOL属性を指定したOCISessionGet()によりOCIセッション・プールから取得され、OCISessionRelease()を使用してOCIセッション・プールに解放されたセッションは、DRCPに戻されます。OCIセッション・プールは、キャッシュされた接続ブローカに対する接続を透過的に維持することもでき、パフォーマンスが向上します。OCIアプリケーションでは、OCISessionGet() (authInfop)を使用して、OCI_ATTR_CONNECTION_CLASS属性を設定し、接続クラス名を指定するか、OCISessionGet()のコール前にOCIAuthInfoハンドルを使用することで、アプリケーションが同様の状態のセッションを残しているセッションを再利用できます。OCISessionGet() (mode)を使用すれば、OCIアプリケーションでは、セッションの純正値、つまり、プールされたセッションを再利用する(OCI_SESSGET_PURITY_SELF属性を設定)か、新規のセッションを使用する(OCI_SESSGET_PURITY_NEW属性を設定)かも指定できます。

また、タグ付け、文キャッシュおよび透過的アプリケーション・フェイルオーバー(TAF)など、従来のクライアント側OCIセッション・プールにより提供される機能は、DRCPでもサポートされています。

セッション純正値および接続クラス

Oracle Databaseリリース11.1では、OCIでOCISessionGet()を使用してセッションを取得する際に指定できる2つの設定が導入されました。

- セッション純正値

- 接続クラス

- セッション純正値および接続クラスのデフォルト

セッション純正値

セッション純正値は、アプリケーション・ロジックをプール・セッションを再利用するように設定するか、または新規セッションを使用するように設定するかを指定します。OCISessionGet()は、OCI_SESSGET_PURITY_NEWまたはOCI_SESSGET_PURITY_SELFの純正値設定を取り入れるよう拡張されています。または、OCISessionGet()をコールする前に、OCIAuthInfoハンドルでOCI_ATTR_PURITY_NEWまたはOCI_ATTR_PURITY_SELFを設定できます。どひらのメソッドも同じです。

注意:
プールからセッションを再利用する場合、サーバーのNLS属性がクライアントのNLS属性よりも優先されます。
たとえば、クライアントでNLS_LANGがfrench_france.us7asciiに設定されており、プールからドイツ語のセッションが割り当てられている場合、クライアント・セッションはドイツ語となります。

接続クラスを使用すれば、共有を制限し、この問題を回避できます。

例9-1では、接続プーリング・アプリケーションでのNEWセッションの設定方法を示しています。

例9-1 セッション純正値の設定

/* OCIAttrSet method */

ub4 purity = OCI_ATTR_PURITY_NEW;
OCIAttrSet (authInfop, OCI_HTYPE_AUTHINFO,  &purity, sizeof (purity),
OCI_ATTR_PURITY, errhp);
OCISessionGet (envhp, errhp, &svchp, authInfop, poolName, poolNameLen, NULL, 0,
NULL, NULL, NULL, OCI_SESSGET_SPOOL);
/* poolName is the name returned by OCISessionPoolCreate() */

/*  OCISessionGet mode method */
OCISessionGet (envhp, errhp, &svchp, authInfop, poolName, poolNameLen, NULL, 0,
NULL, NULL, NULL, OCI_SESSGET_SPOOL | OCI_SESSGET_PURITY_NEW);
/* poolName is the name returned by OCISessionPoolCreate() */

接続クラス

接続クラスには、アプリケーションで必要な接続のタイプの論理名を定義します。OCIセッション・プールのセッションは、複数のユーザーで共有することはできません(ユーザーHRに対して最初に作成されたセッションは、ユーザーHRによる後続の要求にのみ割り当てられます)。接続クラスの設定により、所定のユーザーのセッションをさらに分離できます。接続クラスの設定では、同一のデータベース・ユーザーとして接続している複数のアプリケーションにおいて、アプリケーションに対応する論理名を使用してセッションを識別できます。その結果OCIでは、特定の接続クラスに属するセッションが接続クラス外で共有されなくなります。

OCIAuthInfoハンドルでOCI_ATTR_CONNECTION_CLASS属性を使用すれば、接続クラスを設定できます。接続クラスは文字列属性です。OCIでサポートされる接続クラスの最大長は1024バイトです。アスタリスク(*)は特殊文字であり、接続クラス名には使用できません。

例9-2は、HRMSアプリケーションでは接続クラスHRMSで識別されるセッションが必要であることを示しています。

例9-2 接続クラスをHRMSとして設定

OCISessionPoolCreate (envhp, errhp, spoolhp, &poolName, &poolNameLen, "HRDB",
strlen("HRDB"), 0, 10, 1, "HR", strlen("HR"), "HR", strlen("HR"),
OCI_SPC_HOMOGENEOUS);

OCIAttrSet (authInfop, OCI_HTYPE_AUTHINFO, "HRMS", strlen ("HRMS"),
OCI_ATTR_CONNECTION_CLASS, errhp);
OCISessionGet (envhp, errhp, &svchp, authInfop, poolName, poolNameLen, NULL, 0,
NULL, NULL, NULL, OCI_SESSGET_SPOOL);

例9-3は、採用アプリケーションでは接続クラスRECMSで識別されるセッションが必要であることを示しています。

例9-3 接続クラスをRECMSとして設定

OCISessionPoolCreate (envhp, errhp, spoolhp, &poolName, &poolNameLen, "HRDB",
strlen("HRDB"), 0, 10, 1, "HR", strlen("HR"), "HR", strlen("HR"),
OCI_SPC_HOMOGENEOUS);

OCIAttrSet (authInfop, OCI_HTYPE_AUTHINFO,  "RECMS", strlen("RECMS"),
OCI_ATTR_CONNECTION_CLASS, errhp);
OCISessionGet (envhp, errhp, &svchp, authInfop, poolName, poolNameLen, NULL, 0,
NULL, NULL, NULL, OCI_SESSGET_SPOOL);

セッション純正値および接続クラスのデフォルト

表9-1では、様々なクライアント・シナリオで使用されるデフォルト値を示しています。

表9-1 各種クライアント・シナリオで使用されるデフォルト

属性または設定

アプリケーションがセッション・プールからOCISessionGet()を使用

OCIセッション・プールからのその他接続の取得なし

OCI_ATTR_PURITY

OCI_ATTR_PURITY_SELF

OCI_ATTR_PURITY_NEW

OCI_ATTR_CONNECTION_CLASS

OCIセッション・プールのすべての接続についてデフォルトの接続クラスとして使用されるクライアント側の各セッション・プールに対する、OCIで生成されたグローバル一意名。

SHARED

セッションの共有

OCIセッション・プールにセッションを要求するスレッド間でのセッションの共有。

デフォルトのSHARED接続クラスを使用した特定のデータベースの全接続間における共有

データベース常駐接続プールの開始

データベース管理者(DBA)はSYSDBAとしてログインし、DBMS_CONNECTION_POOL.START_POOLをデフォルト設定で使用して、デフォルト・プールSYS_DEFAULT_CONNECTION_POOLを開始する必要があります。

プールの構成の詳細は、『Oracle Database管理者ガイド』を参照してください。

データベース常駐接続プーリングの有効化

簡易接続文字列で:POOLEDを指定する(例9-4を参照)か、TNS接続文字列で(SERVER=POOLED)を指定する(例9-5を参照)することで、どのアプリケーションでもデータベース常駐接続プールの恩恵を受けられます。

例9-4 DRCP有効化のために簡易接続文字列で:POOLEDを指定

oraclehost.company.com:1521/books.company.com:POOLED

例9-5 DRCP有効化のためにTNS接続文字列でSERVER=POOLEDを指定

BOOKSDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=oraclehost.company.com)
(PORT=1521))(CONNECT_DATA = (SERVICE_NAME=books.company.com)(SERVER=POOLED)))

OCIアプリケーションにおけるDRCPの拡張性による利点

次の3種類のアプリケーション・シナリオについて検討し、それぞれでDRCPからどのような利点があるかについて説明します。

- OCIセッション・プーリングを使用せず、接続クラスや純正値設定も指定しない(または純正値にNEWを設定)アプリケーションは、DRCPから新しいセッションを取得します。同様に、アプリケーションが接続を解放してプールに戻した場合、デフォルトによりこのセッションは同じアプリケーションの他のインスタンスと共有されません。SQL*Plusは、OCIセッション・プーリングを使用しないクライアントの一例です。これは接続がアイドルのときでも、接続を保持し続けます。そのため、クライアント・セッションが存在する場合やクライアント・セッションがログオフしていない場合には、プール・サーバーが割り当てられたままになります。ただし、アプリケーションは既存のプール・サーバー・プロセスを再利用できるというメリットが得られます。

- OCIセッション・プール外でOCISessionGet()コールを使用するアプリケーション、または接続クラスを指定し、purity=SELFを設定するためのアプリケーションは、DRCPプール・サーバー・プロセスおよびセッションの両方を再利用できます。ただし、OCISessionRelease()コールの後、OCIは接続ブローカへの接続を終了します。次のOCISessionGet()コールで、アプリケーションはブローカに再接続します。再接続すると、DRCPは指定された接続クラスに属するプール・サーバー(およびセッション)を割り当てます。ただし、再接続では接続の確立および再認証のコストが発生します。こうしたアプリケーションはDRCPリソース(プロセスおよびセッション)をより効率的に共有できますが、接続ブローカへの接続をキャッシュするというメリットは得られません。

- OCIセッション・プールAPIを使用し、接続クラスを指定し、purity=SELFを設定するアプリケーションは、プール・サーバー・プロセスと関連付けられたセッションの両方を再利用することにより、DRCPの機能をフルに活用します。これらは、接続ブローカにキャッシュされた接続の恩恵を受けます。キャッシュされた接続では、OCISessionGet()コールで再認証のコストが発生しません。

DRCPの使用に関するベスト・プラクティス

DRCPがもたらすメリットを享受できるアプリケーションを設計する手順は、OCIセッション・プーリングの使用およびセッション・プーリングのためのOCIコールに関する項に示す、OCIセッション・プールを使用するアプリケーションに必要な手順とよく似ています。

唯一の追加ステップとして、DRCPとともに動作するようデプロイされた場合、最大限のパフォーマンスを得るために、アプリケーションで明示的な接続クラス設定を指定する必要があります。

最大限のパフォーマンスを得て、さらにDRCPリソースの共有機能を強化するため、同じアプリケーションの複数のインスタンスは、同じ接続クラス設定を指定する必要があります。アプリケーションの複数のインスタンスでデータベース・セッションを共有できることを確認してください。

例9-6では、データベース常駐接続プーリングDRCPアプリケーションを示しています。

例9-6 データベース常駐接続プーリング・アプリケーション

/* Assume that all necessary handles are allocated. */

/*   This middletier uses a single database user. Create a homogeneous
client-side session pool */
OCISessionPoolCreate (envhp, errhp, spoolhp, &poolName, &poolNameLen, "BOOKSDB",
strlen("BOOKSDB"), 0, 10, 1, "SCOTT", strlen("SCOTT"), "password",
strlen("password"), OCI_SPC_HOMOGENEOUS);

while (1)
{
/* Process a client request */
WaitForClientRequest();
/* Application function */

/* Set the Connection Class on the OCIAuthInfo handle that is passed as
argument to OCISessionGet*/

OCIAttrSet (authInfop, OCI_HTYPE_AUTHINFO,  "BOOKSTORE", strlen("BOOKSTORE"),
OCI_ATTR_CONNECTION_CLASS, errhp);

/* Purity need not be set, as default is OCI_ATTR_PURITY_SELF for OCISessionPool
connections */

/* You can get a SCOTT session released by Mid-tier 2 */
OCISessionGet(envhp, errhp, &svchp, authInfop, poolName, poolNameLen, NULL, 0,
NULL, NULL, NULL, OCI_SESSGET_SPOOL);

/* Database calls using the svchp obtained above  */
OCIStmtExecute(...)

/* This releases the pooled server on the database for reuse */
OCISessionRelease (svchp, errhp, NULL, 0, OCI_DEFAULT);
}

/* Mid-tier is done - exiting */
OCISessionPoolDestroy (spoolhp, errhp, OCI_DEFAULT);

例9-7および例9-8では、例9-6のコードに基づく2つのデプロイメントの例を示しており、コードがBOOKSTOREアプリケーションにサービスを提供する10の中間層ホストにデプロイされます。

最初のデプロイメント例では、使用されるデータベースが、専用サーバー・モードでDRCPが有効になっていないOracle Database 11g以下であると想定しています。クライアント側には11gライブラリがあります。例9-7では、このデプロイメントに使用する接続文字列を示しています。この場合、アプリケーションはデータベースから専用サーバー接続を取得します。

例9-7 DRCPが無効である専用サーバー・モードのデプロイメントで使用する接続文字列

BOOKSDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=oraclehost.company.com)
(PORT=1521))(CONNECT_DATA = (SERVICE_NAME=books.company.com)))

2番目のデプロイメント例では、Oracle Database 11gデータベースでDRCPが有効になっているものと想定します。これで、すべての中間層プロセスがDRCPで提供されるプーリング機能の恩恵を受けられます。DRCPのデータベース・リソース要件は、専用サーバー・モードでの要件より大幅に少なくなります。例9-8では、このタイプのデプロイメントで接続文字列を変更する方法を示しています。

例9-8 DRCPが有効であるデプロイメントに使用する接続文字列

BOOKSDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=oraclehost.company.com)
(PORT=1521))(CONNECT_DATA = (SERVICE_NAME=books.company.com)(SERVER=POOLED)))

互換性および移行

Oracle Database 11gクライアント・ライブラリにリンクされたOCIアプリケーションは、次のそれぞれに対して変更なしで動作します。

- DRCPが無効のOracle Database 11gデータベース

- Oracle Database 11gより前のリリースのデータベース・サーバー

- DRCP接続文字列でのデプロイ時に、DRCPが有効であるOracle Database 11gデータベース・サーバー

前述のとおり、OCIセッション・プールAPIを接続クラスおよび純正値設定とともに使用するようクライアントが適切に変更されていれば、そのクライアントはDRCPにより提供される高度な拡張性を利用できます。

データベース常駐接続プーリングの使用に対する制限

プール・サーバーでは、次のアクションを実行または使用できません。

- データベースの停止

- データベース常駐接続プールの停止

- 接続されたユーザーのパスワードの変更

- 共有データベース・リンクを使用した、異なるインスタンスにあるデータベース常駐接続プールへの接続

- TCPSによるアドバンスト・セキュリティ・オプション(ASO)の使用

- OCI_MIGRATEオプションを使用して直接、またはOCISessionPoolCreate()コールを使用して間接的に、サーバー側の移行可能なセッションを使用

- 初期クライアント・ロールの使用

- OCI_ATTR_APPCTX_NAMEおよびOCI_ATTR_APPCTX_VALUEなどのアプリケーション・コンテキスト属性の使用

プール内のDDL前のセッションはまだDDL後のクライアントに渡される可能性があるため、プール内のデータベース・ユーザーに関係するDDL文の実行には注意が必要です。たとえば、ユーザーを削除する場合、そのユーザーのセッションがプール内に存在せず、そのユーザーとして認証されたブローカへの接続がないことを確認します。

明示的なロールが使用可能であり、プールに解放されるセッションは、後でデフォルトのログイン・ロールを必要とする(同じユーザーの)接続に渡される可能性があります。明示的なロールのあるセッションは解放せずに、かわりにセッションを終了してください。

注意:
暗号化やDRCPを使用した厳密認証などのOracle Advanced Security機能を使用できます。

カスタム・プールでのDRCPの使用

DRCPは、「データベース常駐接続プーリング」で説明されているように、OCIセッション・プーリングとうまく統合されます。すでにDRCP、FANおよびRLBと統合されているので、OCIセッション・プールを使用することを強くお薦めします。

ただし、アプリケーションが独自のカスタム接続プールを使用して作成されている場合(またはアプリケーションでプーリングがまったく使用されていないが、セッションが使用されない期間があり、アプリケーションが正確さのために特定のセッションを取り戻すことに依存しない場合)でも、DRCPと統合できます。これは、「ステートフルまたはステートレスとしてのセッションの明示的作成」で説明されているように、OCI_ATTR_SESSION_STATE属性を有効にすることでできます。

アプリケーションでセッションにOCI_SESSION_STATELESSであるというフラグが立てられると、OCIではセッションを透過的にDRCPプールに戻す(DRCPが有効な場合)ときに、このセッションの注釈を利用します。同様に、アプリケーションでセッションをOCI_SESSION_STATEFULであると示すと、OCIでは該当するセッションを透過的にDRCPプールからチェックアウトするときに、この変更されたセッション状態の注釈を利用します。

アプリケーションでは、セッション状態をできるだけ速やかにマークして、基本のデータベース・リソースの効率的な利用を可能にする必要があります。

注意:
前に詳細に述べたように、その他のDRCP属性(接続クラスや純正など)をさらに指定する必要があります。

ステートフルまたはステートレスとしてのセッションの明示的作成

アプリケーションには通常、1単位の作業の継続期間中、特定のデータベース・セッションが必要です。この期間中、セッションはSTATEFULであるといわれます。この作業単位の最後に、後続の作業単位のためにその特定のセッションを維持することにアプリケーションが依存しない場合、そのセッションはSTATELESSであるといわれます。

アプリケーションでは、セッションのSTATEFULからSTATELESSへまたはその逆への遷移を検出すると、これらの遷移についてOCI_ATTR_SESSION_STATEを使用してOCIに明示的に通知できます。

アプリケーションまたはコール元によるこの指示により、OCIとOracle Databaseでは、この情報を利用して、特定のスケーラビリティの最適化を透過的に実行できます。たとえば、アプリケーションがそのセッションで動作していない場合、そのセッションを必要とする他の誰かに与えることができます。または、アプリケーションで再び必要となった場合は、別のセッションによって置き換えることもできます。

関連項目:
「カスタム・プールでのDRCPの使用」

セッションの状態をマークする例を、次のコード・フラグメントで示します。

wait_for_transaction_request();
do {

ub1 state;

/* mark  database session as STATEFUL  */
state = OCI_SESSION_STATEFUL;
checkerr(errhp, OCIAttrSet(usrhp, OCI_HTYPE_SESSION,
&state, 0, OCI_ATTR_SESSION_STATE, errhp));
/* do database work consisting of one or more related calls to the database */

...

/* done with database work, mark session as stateless */
state = OCI_SESSION_STATELESS;
checkerr(errhp, OCIAttrSet(usrhp, OCI_HTYPE_SESSION,
&state, 0,OCI_ATTR_SESSION_STATE, errhp));

wait_for_transaction_request();

} while(not _done);

セッションがOCIセッション・プールの外から取得された場合、セッションはOCI_SESSION_STATEFULとして開始され、アプリケーションにより明示的にOCI_SESSION_STATELESSへ変更されないかぎり、そのセッションの存続期間中OCI_SESSION_STATEFULのままです。

セッションがOCIセッション・プールから取得された場合、プールからの取得後にそのセッションで最初のコールが開始されたときに、セッションはデフォルトでOCI_SESSION_STATEFULとしてマークされます。セッションは、やはりデフォルトで、プールに対して解放されるときにOCI_SESSION_STATELESSとしてマークされます。したがって、OCIセッション・プールでこの属性を明示的に設定する必要はありません。OCIセッション・プーリングでは、これを透過的に行います。この属性を使用するのは、OCIセッション・プーリングを使用していない場合にかぎります。

関連項目:
「OCI_ATTR_SESSION_STATE」

DRCPとReal Application Clusters

Real Application Clusters環境のデータベースでデータベース常駐接続プールが構成されているとき、プールの構成は各データベース・インスタンスに適用されます。1つのインスタンスでプールを起動または停止すると、すべてのインスタンスのプールが起動または停止されます。

DRCPとData Guard

データベース常駐接続プールがData Guard環境で作動するためには特定の条件があります。

- プールの起動: プールが物理スタンバイ・データベース上で起動できるのは、プールがプライマリ・データベースですでに起動されている場合のみです。プールがプライマリで停止している場合は、スタンバイ・データベースで起動できません。

- プールの停止: プールがプライマリ・データベース上で稼働中の場合、物理スタンバイ・データベース上で停止することはできません。プールを停止できるのは、プライマリ・データベースでプールが実行していない場合のみです。

- 物理スタンバイ・データベース上では、プール・パラメータの構成、デフォルトへの復元または変更を行うことはできません。

- 役割の交換が発生する、つまりプライマリが停止して、セカンダリ・データベースがプライマリ・データベースの役割を担当すると、物理スタンバイ・データベースについてこれまでに説明した制限事項はなくなります。スタンバイ・データベースがプライマリになったため、すべてのプール操作を実行できます。

- ロジカル・スタンバイ・データベースでは、すべてのプール操作を行うことができます。

接続プーリングまたはセッション・プーリングの使用/不使用の判断

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

- セッション作成用の関数

- 様々なタイプのOCIセッションの選択

データベース・セッションを中間層スレッドで再利用できず(つまり、ステートフルのとき)、バックエンドのサーバー・プロセスの数によってはデータベースでスケール上の問題が発生する可能性がある場合は、OCI接続プーリングを使用します。

データベース・セッションを中間層スレッドで再利用でき(つまり、ステートレスのとき)、バックエンドのサーバー・プロセスの数によってはデータベースでスケール上の問題が発生する可能性がある場合は、OCIセッション・プーリングを使用します。

データベース・セッションを中間層スレッドで再利用できず(つまり、ステートフルのとき)、バックエンドのサーバー・プロセスの数がデータベースでスケール上の問題が発生するほど大きくない場合は、プーリングのメカニズムを使用する必要はありません。

注意:
プールされていないセッションまたは接続があると、すべての中間層ユーザー要求に対してデータベース・セッション/接続を分割し、再作成することになります。これにより、データベース側でスケール上の重大な問題が発生し、要求を履行するまでの待機時間が非常に長くなる可能性があります。そのため、データベース・セッションがステートフルであるかステートレスであるかに基づいて、プーリング手法の1つを中間層アプリケーションに採用することを強くお薦めします。

接続プーリングではプール要素は接続であり、セッション・プーリングではプール要素はセッションとなります。

プールと同様に、スレッドがデータベースでの作業を終了し、リソースが解放されるまでは、プーリングされたリソースはある一定期間、アプリケーション・スレッドによってロックされます。使用期間中は、リソースは他のスレッドでは使用できません。したがって、アプリケーション開発者は、どんな種類のプーリングでも、比較的短期のタスクを効率的に処理されるということを認識する必要があります。ただし、アプリケーションが長時間実行されるトランザクションを実行中の場合、プーリングされたリソースを他のアプリケーションと共有することを長期間拒絶するため、リソースが枯渇する可能性があります。したがって、プーリングは短期のタスクで使用し、プールのサイズは必要なトランザクションの並列性を維持できる大きさに保つ必要があります。

接続プーリングおよびセッション・プーリングに関する次の追加情報に注意してください。

- OCI接続プーリング
データベースへの接続はプーリングされます。ユーザーによって、セッションは作成および破棄されます。データベースに対する各コールにより、プールから使用できる適切な接続が取り出されます。

アプリケーションは、データベースに対する少数の物理的接続で複数のセッションを多重化します。ユーザーは、プール構成をチューニングして必要な並列性を達成できます。

アプリケーション・セッションの有効期間は、キャッシュされたプール接続の有効期間とは関係がありません。

- OCIセッション・プーリング
セッションおよび接続はOCIによってプーリングされます。このアプリケーションはプールからセッションを取得し、セッションをプールに戻して解放します。

セッション作成用の関数

OCIでは、セッション作成用の次の関数を提供しています。

- OCILogon()
OCILogon()は、OCIセッションを取得する最も簡単な方法です。この方法の利点は、OCIサービス・コンテキストを簡単に取得できる点です。欠点は、セッション移行、プロキシ認証、接続プールまたはセッション・プールの使用などの、拡張OCI操作を実行できない点です。

関連項目:

- 「OCILogon()」

- 「アプリケーションの初期化、接続およびセッション作成」

- OCILogon2()
OCILogon2()には、セッションを取得するOCILogon()の機能が含まれます。このセッションは、基礎となる新規の接続があるセッション、既存の接続プールから仮想接続によって開始されたセッション、または既存のセッション・プールからのセッションである場合があります。この関数がコールされるときのmodeパラメータ値によって、動作が決まります。

ユーザーは、OCIによって戻されるサービス・コンテキストの属性(OCI_ATTR_STMTCACHESIZEを除く)を変更できません。

関連項目:
「OCILogon2()」

- OCISessionBegin()
OCISessionBegin()は、プロキシ認証、接続プールまたはセッション・プールからのセッションの取得、外部資格照明および移行可能セッションなどの、OCIセッションの様々なオプションをすべてサポートします。これは、最低レベルのコールで、すべてのハンドルを明示的に割り当て、すべての属性を設定する必要があります。OCIServerAttach()は、このコールの前にコールする必要があります。

関連項目:
「OCISessionBegin()」

- OCISessionGet()
OCISessionGet()は、セッションを取得する方法としてお薦めします。このセッションは、基礎となる新規の接続があるセッション、既存の接続プールから仮想接続によって開始されたセッション、または既存のセッション・プールからのセッションである場合があります。この関数がコールされるときのmodeパラメータ値によって、動作が決まります。この動作はOCILogon2()に似ていますが、これを使用して、プールから特定のセッションを取得するタグを指定することもできます。

関連項目:
「OCISessionGet()」

様々なタイプのOCIセッションの選択

OCIには、次の種類のセッションがあります。

- 基本的なOCIセッション
基本的なOCIセッションは、専用OCIサーバー・ハンドル上でユーザー名およびパスワードを使用することで機能します。これは、プール・メカニズムではありません。使用するタイミングの詳細は、「接続プーリングまたはセッション・プーリングの使用/不使用の判断」を参照してください。

外部資格証明を使用して認証された場合、ユーザー名またはパスワードは必要ありません。

- セッション・プール・セッション
セッション・プール・セッションは、セッション・プール・キャッシュから取得します。一部のセッションはタグ付けされる場合があります。これは、ステートレス・セッションです。OCISessionGet()コールおよびOCISessionRelease()コールはそれぞれ、セッション・キャッシュからセッションを取得および解放します。これにより、セッションの作成および破棄からサーバーが保護されます。

接続プール・セッション、セッション・プーリング・セッション、非プーリング・セッションの比較については、「接続プーリングまたはセッション・プーリングの使用/不使用の判断」を参照してください。

- 接続プール・セッション
接続プール・セッションは、OCI接続プールからのOCISessionGet()コールおよびOCISessionBegin()コールを使用して作成されます。これはステートフル・セッションであるため、セッション・キャッシュはありません。各コールによって新規セッションが作成され、ユーザーの責任でこれらのセッションを終了します。

セッションは、接続プールのサーバー・ハンドル間で自動的に移行できます。各セッションにユーザー名およびパスワードを含めたり、各セッションをプロキシ・セッションにすることができます。接続プール・セッション、セッション・プーリング・セッション、非プーリング・セッションの比較については、「接続プーリングまたはセッション・プーリングの使用/不使用の判断」を参照してください。

- サーバー・ハンドルを共有するセッション
少数の物理接続で複数のOCIセッションを多重化できます。これらの複数のセッションに同じサーバー・ハンドルを持たせると、アプリケーションにより、手動で多重化できます。OCI接続プールのAPIを使用して、セッション多重化の詳細はOCIで行うことをお薦めします。

- プロキシ・セッション
プロキシ・セッションは、クライアントのパスワードを中間層から保護する必要がある場合に役立ちます。プロキシ・セッションはまた、OCI接続プールまたはOCIセッション・プールの一部に含めることができます。

関連項目:
「OCIでの中間層アプリケーション」

- 移行可能なセッション

移行可能なトランザクション・ハンドルを使用している場合、アプリケーションで移行可能なセッションを使用する必要はなく、かわりにOCI接続プーリングを使用します。

関連項目:
「OCIでのセッション管理」

OCIでの文キャッシュ

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

- OCIでの、セッション・プーリングを使用しない文キャッシュ

- OCIでの、セッション・プーリングを使用した文キャッシュ

- OCIでの文キャッシュの規則

- 文キャッシュでのバインドおよび定義の最適化

- OCIでの文キャッシュのコード例

文キャッシュは、セッションごとの文のキャッシュを提供および管理する機能です。文キャッシュによって、サーバーではカーソルが使用できる状態になり、文を再解析する必要はありません。文キャッシュは、接続プーリングおよびセッション・プーリングとともに使用でき、パフォーマンスおよび拡張性が向上します。また、セッション・プーリングを使用しなくても使用できます。文キャッシュを実装するOCIコールは次のとおりです。

- OCIStmtPrepare2()

- OCIStmtRelease()

OCIでの、セッション・プーリングを使用しない文キャッシュ

セッション・プーリングを使用せずに文のキャッシングを実行する場合、ユーザーは通常のOCI手順を実行してログオンします。セッションを取得するコールには、セッションにおいて文のキャッシングが有効であるかどうかを指定するモードがあります。最初、文キャッシュは空です。開発者は、文テキストを使用してキャッシュ内で文を見つけようとします。文が存在する場合、APIは以前に準備した文ハンドルを戻しますが、存在しない場合は、新しく準備した文ハンドルを戻します。

アプリケーション開発者は、文がキャッシュに戻される前に、文のバインドと定義を実行し、その後簡単に文の実行とフェッチを実行できます。キャッシュで文ハンドルが見つからない場合、開発者は、他のステップに加えて、ハンドルに異なる属性を設定する必要があります。

OCIStmtPrepare2()には、キャッシュ内に文が見つからない場合に、開発者がプリペアド文を使用するのか、またはNULLの文ハンドルを使用するのかを指定するモードがあります。

擬似コードは次のようになります。

OCISessionBegin( userhp, ... OCI_STMT_CACHE)  ;
OCIAttrset(svchp, userhp, ...);  /* Set the user handle in the service context */
OCIStmtPrepare2(svchp, &stmthp, stmttext, key, ...);
OCIBindByPos(stmthp, ...);
OCIDefineByPos(stmthp, ...);
OCIStmtExecute(svchp, stmthp, ...);
OCIStmtFetch2(svchp, ...);
OCIStmtRelease(stmthp, ...);
...

OCIでの、セッション・プーリングを使用した文キャッシュ

セッション・プーリングでの文キャッシュの場合、概念は同じですが、文キャッシュはセッション・レイヤーではなくセッション・プール・レイヤーで使用可能になります。

属性OCI_ATTR_SPOOL_STMTCACHESIZEにより、セッション・プール内のセッションごとにデフォルトの文キャッシュ・サイズが設定されます。これは、OCI_HTYPE_SPOOLハンドルで設定されます。プールの特定のセッションの文キャッシュ・サイズは、そのセッションでOCI_ATTR_STMTCACHESIZEを使用することでいつでも上書きできます。OCI_ATTR_SPOOL_STMTCACHESIZEの値は、いつでも変更できます。この属性を使用して、プール・レベルで文のキャッシングを有効または無効にできます。作成後、それと同時に、サービス・コンテキストで属性OCI_ATTR_STMTCACHESIZEを使用して、セッション・レベルで文のキャッシングを有効または無効にできます。この変更内容は、プール内の個別のセッションがユーザーに提供された際に反映されます。タグ付きセッションでは、この動作は当てはまりません。これについては、項の後半で説明します。

注意:
属性は、セッションの取得後に変更できます。ただし、いったん属性を変更すると、基本の物理セッションで設定されたままになります。この値は、セッションが解放されてセッション・プールに戻される間、暗黙的に元の値にリセットされることはありません。したがって、OCIStmtRelease()を使用してセッションを解放するまで、セッションの状態を維持するのは開発者の責任です。

文キャッシュの有効化または無効化は、プーリングされていないセッションと同様に、各プーリング・セッションで許可されます。

OCI_SESSGET_STMTCACHEまたはOCI_LOGON2_STMTCACHEをそれぞれモード引数に指定すると、OCISessionGet()コールまたはOCILogon2()コールで文キャッシュ以外のプールから取り出されたセッションでも、ユーザーは文キャッシュを使用可能にできます。

セッション・プールのセッションを要求する場合は、そのセッションの文キャッシュ・サイズのデフォルトはプールの文キャッシュ・サイズとなります。つまり、そのセッション内で文キャッシュを使用可能または使用不可にすることができます。たとえば、プーリング・セッション(セッションA)に使用可能な文キャッシュがあり、文キャッシュがプールでオフにされ、ユーザーがセッションを要求してセッションAが戻された場合、文キャッシュはセッションAではオフになります。別の例としては、プールのセッションAに使用可能な文キャッシュがなく、プール・レベルの文キャッシュがオンになっている場合、セッションAがユーザーに戻される前に、プールのセッションとサイズが等しいセッションAの文キャッシュがオンになります。

タグ付けされたセッションが要求され、取り出された場合は、異なる結果となります。この場合は、文キャッシュのサイズは変更されません。したがって、文キャッシュはオンまたはオフになりません。さらに、OCISessionGet()コールでユーザーがモードOCI_SESSGET_STMTCACHEを指定する場合、このセッションがタグ付けされていると、これは無視されます。前述の例では、セッションAがタグ付けされていた場合、ユーザーに対するセッションとして戻されます。

OCIでの文キャッシュの規則

OCIでの文キャッシュには、守るべきいくつかの規則があります。

- OCIStmtPrepare()ではなく、OCIStmtPrepare2()関数を使用します。OCIStmtPrepare()を使用する場合は、複数のサービス・コンテキスト間で1つの文ハンドルを使用しないことをお薦めします。使用した場合、OCIStmtPrepare2()を使用して文を取得するとエラーが発生します。文ハンドルを新規のサービス・コンテキストに移行するとき、実際には古いセッションに関連するカーソルがクローズされるため、文ハンドルの共有は取得されません。OCIでは、文ハンドルが移行されると、古いセッションに関連するすべてのバッファが解放されるため、クライアント側での共有も取得されません。

- セッションごとに1つのサービス・コンテキストを保持する必要があります。サービス・コンテキストを指定したOCIStmtPrepare2()を使用して取得した文ハンドルは、後で同じサービス・コンテキストとの組合せでのみ使用でき、異なるサービス・コンテキストとは使用できません。

- OCIStmtPrepare2()のコールは、セッションに文キャッシュがなくても、文ハンドルを割り当てます。そのため、OCIStmtPrepare2()のみを使用するアプリケーションでは、文ハンドルのためにOCIHandleAlloc()をコールできません。

- OCIStmtPrepare2()のコール後、ユーザーが文ハンドルでの処理を完了した後にOCIStmtRelease()をコールする必要があります。文キャッシュを使用する場合、これによって文はキャッシュに対して解放されます。文キャッシュを使用しない場合、文は割当て解除されます。OCIHandleFree()をコールしてメモリーを解放しないでください。

- OCI_PREP2_CACHE_SEARCHONLYモードを指定してOCIStmtPrepare2()をコールし、NULLの文が戻された(文が見つからなかった)場合、後続のOCIStmtRelease()コールは必要ないため、実行しないでください。

- OCIStmtPrepare()を使用してプリコンパイルされた文に対して、OCIStmtRelease()をコールしないでください。

- 文キャッシュには最大サイズ(文の数)があり、サービス・コンテキストのOCI_ATTR_STMTCACHESIZE属性で変更できます。デフォルト値は20です。また、この属性を使用して、プールされている、またはプールされていないセッションの文キャッシュを使用可能または使用不可にできます。モードを OCI_STMT_CACHEに設定しないでOCISessionBegin()をコールする場合、サービス・コンテキストのOCI_ATTR_STMTCACHESIZEを0 (ゼロ)以外の属性に設定し、文キャッシュをオンにできます。セッション・プール・レベルで文キャッシュをオンにしない場合、OCISessionGet()により、文キャッシュに対応していないセッションが戻されます。OCI_ATTR_STMTCACHESIZEを使用すれば、キャッシュをオンにできます。同様に、同じ属性を使用してキャッシュ・サイズを0 (ゼロ)に設定することにより、文キャッシュをオフにできます。

- 文の解放時に文にタグを付けることができ、これによって、次回に同じタグの文を要求できます。タグは、キャッシュを検索するために使用します。タグなしの文(タグがNULL)は、タグ付きの文の特殊なケースです。2つの文がタグのみ異なる場合、または、一方がタグ付きでもう一方がタグなしの場合、これらの文は異なる文とみなされます。

関連項目:

- 「文関数」

- 「サービス・コンテキスト・ハンドル属性」

- 「セッション・プール・ハンドル属性」

文キャッシュでのバインドおよび定義の最適化

アプリケーションがキャッシュ内の文でバインドおよび定義操作を繰り返すのを回避するために、アプリケーションは、文キャッシュから取得した文で不透明なコンテキストを登録し、サービス・コンテキストでコールバック関数を登録できます。バインドおよび定義バッファなどのアプリケーション・データは、不透明なコンテキストに包含することができます。このコンテキストは、最初にキャッシュから取得された文で登録されます。文が2回目以降キャッシュから取得された際には、アプリケーションはバインドおよび定義バッファを再利用でき、コンテキストはその文で登録されます。アプリケーションにはまだ、バインドおよび定義を管理する責任があります。さらに、バインドと定義両方のデータとバッファを再利用するか、データのみを変更してバッファを再利用するか、または現在のサイズが十分でない場合は、バッファを解放して再割当てできます。最後のケースでは、再バインドと再定義を行う必要があります。これらのバインドおよび定義バッファに対してアプリケーションが割り当てたメモリーをクリーンアップするには、セッションを閉じる一環として文をエージ・アウトするかまたは全キャッシュを消去する際に、コールバック関数をコールします。消去するすべての文に対してコールバック関数をコールします。コールバック関数の内部で、アプリケーションはメモリーを解放して、必要なその他のクリーンアップを実行します。例9-9に擬似コードを示します。

例9-9 キャッシュ内の文に対するバインドおよび定義操作の最適化

Get the statement using OCIStmtPrepare2(...)

Get the opaque context from the statement if it exists

If opaque context does not exist

{

Allocate fetch buffers, do the OCIBindByPos, OCIDefineByPos, and so forth

Enclose the buffer addresses inside a context and set the context and
callback function on the statement

}
Execute/Fetch using the statement, and process the data in the fetch buffers.

OCIStmtRelease() that statement

Next OCIStmtPrepare2()

OCIAttrGet() opaque application context from statement handle

Execute/Fetch using the statement and process the data in the fetch buffers.

OCIStmtRelease()

. . .

void callback_fn (context, statement, mode)

{

/* mode= OCI_CBK_STMTCACHE_STMTPURGE means this was called when statement was
aging out of the statement cache or if the session is ended */

<free the buffers in the context.>

}

関連項目:

- 「OCI_ATTR_STMTCACHE_CBKCTX"」

- 「OCI_ATTR_STMTCACHE_CBK」

OCIでの文キャッシュのコード例

文キャッシュの作業例は、demoディレクトリのcdemostc.cを参照してください。

OCIでのユーザー定義コールバック関数

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

- OCIでのユーザー・コールバックの登録

- 外部プロシージャからのOCIコールバック

Oracle Call Interfaceでは、OCIコールの他に、ユーザー固有のコードを実行できます。この機能は次のことに使用できます。

- ユーザーがアプリケーションをチューニングできるように、トレースやパフォーマンス測定のためのコードを追加します。

- 特定のOCIコールに対するコードの事前処理または事後処理を実行します。

- Oracle Database固有のOCIインタフェースを使用して、OCI付きの他のデータ・ソースにアクセスし、OCIコールがOracle以外のデータ・ソースへのユーザー・コールバックを使用するようにします。

OCIコールバック機能は、OCIコールの実行前後におけるユーザー・コードのコールをサポートしています。また、OCIコードを実行するかわりに、ユーザー定義コードを実行できる機能も用意されています。

アプリケーションのソース・コードを修正することなく、ユーザー・コールバック・コードを動的に登録できます。動的な登録は、OCIEnvCreate()コール時に環境ハンドルを初期化した後、ユーザーが作成した5つ以下の動的リンク・ライブラリをロードすることによって実装されます。ユーザーが作成したライブラリ(Windowsの動的リンク・ライブラリ(DLL)またはSolaris上の共有ライブラリなど)では、選択したOCIコールに対するユーザー・コールバックをアプリケーションに透過的に登録します。

サンプル・アプリケーション

OCIユーザー・コールバック機能を説明するすべてのデモ・プログラムのリストについては、付録Bを参照してください。

OCIでのユーザー・コールバックの登録

アプリケーションから、OCIUserCallbackRegister()関数を使用してユーザー・コールバック・ライブラリを登録できます。コールバックは、環境ハンドルのコンテキスト内に登録されます。アプリケーションでは、OCIUserCallbackGet()関数を使用してハンドルに登録されたコールバックについての情報を取り出すことができます。

関連項目:
「OCIUserCallbackGet()」および「OCIUserCallbackRegister()」

ユーザー定義コールバックは、OCIコールおよび環境ハンドルに対して登録されたサブルーチンです。ユーザー定義コールバックには、最初のコールバック、置換コールバックまたは最後のコールバックを指定できます。

- 最初のコールバックの場合は、プログラムからOCI関数をコールするときにコールされます。

- 置換コールバックは、最初のコールバック実行の後に実行されます。置換コールバックからOCI_CONTINUEの値が戻されると、後続の置換コールバックまたは通常のOCIコードが実行されます。置換コールバックからOCI_CONTINUE以外の値が戻される場合は、後続の置換コールバックおよびOCIコードは実行されません。

- 置換コールバックからOCI_CONTINUE以外の値が戻されるか、またはOCI関数が正常に実行されると、プログラムの制御は最後のコールバックに移ります(最後のコールバックが登録されている場合)。

置換コールバックまたは最後のコールバックからOCI_CONTINUE以外が戻された場合は、コールバックからのリターン・コードは、対応付けられたOCIコールから戻されます。

ユーザー・コールバックでは、無効なハンドルまたは無効なコンテキストが渡された場合に、OCI_INVALID_HANDLEを戻すことがあります。

注意:
任意のコールバックからOCI_CONTINUE以外の値が戻された場合は、リターン・コードが後続のコールバックに渡されます。置換コールバックまたは最後のコールバックからOCI_CONTINUE以外のリターン・コードが戻された場合は、最後の(OCI_CONTINUEではない)リターン・コードがOCIコールから戻されます。

OCIUserCallbackRegister

ユーザー・コールバックの登録には、OCIUserCallbackRegister()コールを使用します。

関連項目:
「OCIUserCallbackRegister()」

現段階では、OCIUserCallbackRegister()は環境ハンドルでしか登録できません。typedef OCIUserCallbackのユーザー・コールバック関数は、OCI関数コードfcodeによって識別されるOCIコールのコンテキストとともに登録します。コールバックの型は、最初のコールバック、置換または最後のコールバックのいずれの場合もwhenパラメータによって指定します。

たとえば、最初のコールバック関数stmtprep_entry_dyncbk_fnとそのコンテキストdynamic_contextは、次のパラメータを使用してOCIUserCallbackRegister()関数をコールすることにより、OCIStmtPrepare()コールの環境ハンドルhndlpに対して登録されます。

OCIUserCallbackRegister( hndlp,
OCI_HTYPE_ENV,
errh,
stmtprep_entry_dyncbk_fn,
dynamic_context,
OCI_FNCODE_STMTPREPARE,
OCI_UCBTYPE_ENTRY
(OCIUcb*) NULL);

ユーザー・コールバック関数

ユーザー・コールバック関数は、次の構文を使用する必要があります。

typedef sword (*OCIUserCallback)
(void *ctxp,      /* context for the user callback*/
void *hndlp,     /* handle for the callback, env handle for now */
ub4 type,         /* type of handlp, OCI_HTYPE_ENV for this release */
ub4 fcode,        /* function code of the OCI call */
ub1 when,         /* type of the callback, entry or exit */
sword returnCode, /* OCI return code */
ub4 *errnop,      /* Oracle error number */
va_list arglist); /* parameters of the oci call */

コールバックは、OCIUserCallbackRegister()コールで説明したパラメータの他に、リターン・コードerrnop、およびプロトタイプ定義で宣言された元のOCIのすべてのパラメータを使用してコールします。

最初のコールバックでは、リターン・コードは常にOCI_SUCCESSとして渡され、*errnopは常に0として渡されます。errnopはIN/OUTパラメータであるため、*errnopはerrnopの内容を指します。

コールバックがOCIリターン・コードを変更しない場合は、OCI_CONTINUEを戻す必要があり、*errnopに戻される値は無視されます。ただし、コールバックからOCI_CONTINUE以外のリターン・コードが戻された場合は、最後に戻されたリターン・コードがそのコールのリターン・コードになります。この時点で、*errnopに戻された値は、エラー・ハンドルに設定されるか、または環境ハンドルにエラー情報が戻された場合は環境ハンドルに設定されます。これは、OCIHandleAlloc()などの特定のOCIコールではエラー・ハンドルが存在しないためです。

置換コールバックの場合は、returnCodeは前のコールバックまたはOCIコールから戻されるOCI_CONTINUE以外のリターン・コードであり、*errnopはエラー・ハンドル内に戻されるエラー番号の値です。これによって、後続のコールバックでは、必要に応じてリターン・コードやエラー情報を変更できます。

置換コールバックからOCI_CONTINUE以外のリターン・コードが戻されると、後続の置換コールバックおよびOCIコードは無視され、最後のコールバックの処理に移るという点で、置換コールバックの処理は異なります。

置換コールバックからOCI_CONTINUEが戻されてOCIコードの処理が可能になった場合は、最初のコールバックからのリターン・コードが無視されることに注意してください。

OCIコールの元のパラメータはすべて、変数パラメータとしてコールバックに渡され、コールバックでは、それらをva_argを使用して取り出す必要があります。コールバックのデモ・プログラムには例が提供されています。

関連項目:
付録B「OCIデモ・プログラム」

コールバックの登録を解除するために、NULL値を登録することができます。つまり、OCIUserCallbackRegister()コールのコールバック(OCIUserCallback())の値がNULLの場合は、ユーザー・コールバックの登録は解除されます。

スレッドセーフ・モードを使用している場合、OCIプログラムでは、ユーザー・コールバックをコールする前にすべてのmutexを取得します。

ユーザー・コールバックの制御フロー

例9-10では、典型的なOCIコールの全体的な処理を説明する擬似コードを示しています。

例9-10 典型的なOCIコールの全体的な処理を説明する擬似コード

OCIXyzCall()
{
Acquire mutexes on handles;
retCode = OCI_SUCCESS;
errno = 0;
for all ENTRY callbacks do
{

EntryretCode = (*entryCallback)(..., retcode, &errno, ...);
if (retCode != OCI_CONTINUE)
{
set errno in error handle or environment handle;
retCode = EntryretCode;
}
}
for all REPLACEMENT callbacks do
{
retCode = (*replacementCallback) (..., retcode, &errno, ...);
if (retCode != OCI_CONTINUE)
{
set errno in error handle or environment handle
goto executeEXITCallback;
}
}

retCode = return code for XyzCall; /* normal processing of OCI call */

errno = error number from error handle or env handle;

executeExitCallback:
for all EXIT callbacks do
{
exitRetCode = (*exitCallback)(..., retCode, &errno,...);
if (exitRetCode != OCI_CONTINUE)
{
set errno in error handle or environment handle;
retCode = exitRetCode;
}
}
release mutexes;
return retCode
}

OCIErrorGet()のユーザー・コールバック

OCIコード全体がコールバックに置き換わる場合、コールバックでは、通常、コール・コンテキストに独自のエラー情報を維持し、これを使用して、OCIErrorGet()コールの置換コールバックのbufpパラメータおよびerrcodepパラメータにエラー情報を戻します。

ただし、コールバックがOCIコードの一部をオーバーライドするか、他のなんらかの後処理のみを行う場合は、最後のコールバックを使用して、エラー・テキストや OCIErrorGet()コールのerrcodepパラメータを、独自のエラー・メッセージやエラー番号で修正できます。最後のコールバックに渡される*errnopは、エラー・ハンドルまたは環境ハンドル内のエラー番号です。

最初のコールバックのエラー

最初のコールバックからOCIコールのコール元にエラーを戻す場合は、置換コールバックまたは最後のコールバックを登録する必要があります。これは、OCIコードが実行される場合、最初のコールバックのエラー・コードが無視されるためです。したがって、最初のコールバックから独自のコンテキストによって、置換コールバックまたは最後のコールバックにエラーが渡される必要があります。

動的なコールバック登録

ユーザー・コールバックは、OCI動作の監視または他のデータ・ソースへアクセスするために使用されることが多いので、コールバックの登録は、割込みが発生しないよう透過的に行われることが望まれます。これは、OCIの初期化時に、ユーザーが作成した動的リンク・ライブラリをロードすることで可能になります。動的にリンクされているこれらのライブラリはパッケージと呼ばれます。ユーザーが作成したパッケージは、選択したOCIコール用のユーザー・コールバックを登録します。これらのコールバックでは、実行時に制御を受け取ったときに、必要に応じてユーザー・コールバックの追加登録または登録解除を行うことができます。

OCIデモ・プログラムとともに、パッケージを作成するためのMakefile (Solarisのociucb.mk)が用意されています。このパッケージの正確な名前と位置は、オペレーティング・システムによって異なります。パッケージのソース・コードには、OCIの初期化時および環境作成時にコールされる特別なコールバックのコードを含める必要があります。

オペレーティング・システムの環境変数ORA_OCI_UCBPKGを設定することで、パッケージのロードを制御します。この変数によって、汎用的な方法でパッケージに名前が付けられます。パッケージは、$ORACLE_HOME/libディレクトリに格納してください。

複数のパッケージのロード

ORA_OCI_UCBPKG変数には、パッケージ名をセミコロンで区切ったリストを含めることができます。パッケージは、リストに指定されている順序でロードされます。

たとえば、以前パッケージは次のように指定されました。

setenv ORA_OCI_UCBPKG mypkg

現在でも前述の指定はできますが、さらに複数のパッケージを次のように指定できます。

setenv ORA_OCI_UCBPKG "mypkg;yourpkg;oraclepkg;sunpkg;msoftpkg"

これらのパッケージはすべて順番にロードされます。つまり、最初にmypkgがロードされ、最後にmsoftpkgがロードされます。

最大5パッケージまで指定できます。

注意:
サンプルのMakefile ociucb.mkによって、Solarisではociucb.so.1.0、Windowsシステムではociucb.dllが作成されます。ociucbパッケージをロードするには、環境変数ORA_OCI_UCBPKGにociucbを設定する必要があります。パッケージ名が.soで終わっている場合、SolarisではOCIEnvCreate()または OCIEnvNlsCreate()がエラーになります。パッケージ名は、.so.1.0で終わる必要があります。
動的リンク・ライブラリの作成の詳細は、オペレーティング・システムのデモ・ディレクトリにあるMakefileをお読みください。ユーザー定義のコールバックの詳細は、使用されているオペレーティング・システムのドキュメントでアプリケーションのコンパイルとリンクの項を参照してください。

パッケージ・フォーマット

以前は、パッケージによりOCIEnvCallback()関数のソース・コードを指定する必要がありました。ただし、OCIEnvCallback()関数は廃止されています。かわりに、パッケージ・ソースにより2つの関数を指定する必要があります。最初の関数の名前はpackagenameにして、Initという接尾辞を付ける必要があります。たとえば、パッケージの名前がfooの場合、ソース・ファイル(たとえば、必ずしもfoo.cというわけではない)には、次のように正確に指定されたOCISharedLibInit()関数のコールが記述されたfooInit()関数が含まれている必要があります。

sword fooInit(metaCtx, libCtx, argfmt, argc, argv)
void *     metaCtx;         /* The metacontext */
void *     libCtx;          /* The context for this package. */
ub4        argfmt;          /* package argument format */
sword      argc;            /* package arg count*/
void *     argv[];          /* package arguments */
{
return  (OCISharedLibInit(metaCtx, libCtx, argfmt, argc, argv,
fooEnvCallback));
}

この場合、OCISharedLibInit()関数の最後のパラメータであるfooEnvCallback()は、第2の関数の名前になります。任意の名前にできますが、通常はpackagenameにして、EnvCallbackという接尾辞を付けます。

この関数は、OCIEnvCallback()にかわるものです。現在のところ、すべての動的なユーザー・コールバックは、この関数に登録する必要があります。関数は、次のように指定されるOCIEnvCallbackType型にしてください。

typedef sword (*OCIEnvCallbackType)(OCIEnv *env, ub4 mode,
size_t xtramem_sz, void *usrmemp,
OCIUcb *ucbDesc);

環境ハンドルが作成されると、このコールバック関数が最後にコールされます。envパラメータは、新しく作成された環境ハンドルです。

mode、xtramem_szおよびusrmemppは、OCIEnvCreate()コールに渡されるパラメータです。最後のパラメータucbDescは、パッケージに渡される記述子です。後述するように、パッケージではこの記述子を使用して、ユーザー・コールバックを登録します。

サンプルのociucb.cファイルがdemoディレクトリにあります。Solarisでは、パッケージ作成用のMakefile ociucb.mkも、demoディレクトリに用意されています。これはオペレーティング・システムによって異なりますので、注意してください。さらにdemoディレクトリには、これを説明するユーザー・コールバックのデモ・プログラムがすべて(cdemoucb.c、cdemoucbl.c)揃っています。

ユーザー・コールバックの連鎖

ユーザー・コールバックは、アプリケーション自体に静的に登録することも、実行時にDLL内に動的に登録することもできます。動的な登録の目的の動作を維持するには、以前に登録されていたコールバックを上書きした後に、上書きしたコールバックを新しく登録したコールバック内でコールするという、アプリケーションのメカニズムが必要です。この結果、ユーザー・コールバックが連鎖することがあります。

OCIUserCallbackGet()関数により、どの関数およびコンテキストをOCIコール用に登録するかが決まります。

関連項目:
「OCIUserCallbackGet()」

OCIを介した他のデータ・ソースへのアクセス

Oracle Databaseはアクセス対象となる最も重要なデータベース・ソフトウェアであるため、アプリケーションはOCIインタフェースを有効に利用し、ユーザー・コールバックを使用してOracle以外のデータにアクセスできます。これにより、OCIで記述されたアプリケーションは、パフォーマンスを低下させずにOracleデータにアクセスできます。ユーザー・コールバックでは、Oracle以外のデータにアクセスするためのドライバを記述できます。OCIには非常に強力なインタフェースが備えられているため、通常、大部分のデータ・ソースに対してOCIコールを直接マッピングできます。このソリューションは、すべてのデータ・ソースに対してパフォーマンスの低下を引き起こす、ODBCのような他の中間層用のアプリケーションを記述することより優れています。OCIを使用するとOracleデータ・ソースにアクセスするのに特に問題は発生しませんが、ODBCがOracle以外のデータ・ソースにアクセスする場合と同じ問題が発生します。

コールバック関数の制限

OCIEnvCallback()などのコールバック関数の使用方法には、いくつかの制約があります。

- コールバックからは、OCIUserCallbackRegister()、OCIUserCallbackGet()、OCIHandleAlloc()およびOCIHandleFree()以外のOCI関数をコールできません。これらの関数であっても、ユーザー・コールバックでコールされている場合、コールバックは再帰を避けるためにコールされません。たとえば、OCIHandleFree()がOCILogoff()のコールバックでコールされている場合は、OCILogoff()のコールバックの実行中にOCIHandleFree()のコールバックを行うことはできません。

- コールバックでは、環境ハンドルまたはエラー・ハンドルなどのOCIデータ構造を変更できません。

- OCIUserCallbackRegister()コール自体または次のいずれのコールに対しても、コールバックは登録できません。

- OCIUserCallbackGet()

- OCIEnvCreate()

- OCIInitialize() (非推奨)

- OCIEnvCreate()

OCIコールバックの例

OCIStmtPrepare()コールに対してそれぞれ最初のコールバック、置換コールバックおよび最後のコールバックを登録している5つのパッケージがあるとします。つまり、ORA_OCI_UCBPKG変数が、例9-11のように設定されています。

例9-11 ORA_OCI_UCBPKG変数に対する環境変数の設定

setenv ORA_OCI_UCBPKG "pkg1;pkg2;pkg3;pkg4;pkg5"

各パッケージpkgN (Nは1から5)では、pkgNInit()関数およびPkgNEnvCallback()関数を、例9-12のように指定します。

例9-12 pkgNInit()関数とPkgNEnvCallback()関数の指定

pkgNInit(void *metaCtx, void *libCtx, ub4 argfmt, sword argc, void **argv)
{
return OCISharedLibInit(metaCtx, libCtx, argfmt, argc, argv, pkgNEnvCallback);
}

例9-13では、pkgNEnvCallback()関数での最初、置換および最後のコールバックの登録方法を示しています。

例9-13 pkgNEnvCallback()を使用した最初、置換および最後のコールバックの登録

pkgNEnvCallback(OCIEnv *env, ub4 mode, size_t xtramemsz,
void *usrmemp, OCIUcb *ucbDesc)
{
OCIHandleAlloc((void *)env, (void **)&errh, OCI_HTYPE_ERROR, (size_t) 0,
(void **)NULL);

OCIUserCallbackRegister(env, OCI_HTYPE_ENV, errh, pkgN_entry_callback_fn,
pkgNctx, OCI_FNCODE_STMTPREPARE, OCI_UCBTYPE_ENTRY, ucbDesc);

OCIUserCallbackRegister(env, OCI_HTYPE_ENV, errh, pkgN_replace_callback_fn,
pkgNctx, OCI_FNCODE_STMTPREPARE, OCI_UCBTYPE_REPLACE, ucbDesc);

OCIUserCallbackRegister(env, OCI_HTYPE_ENV, errh, pkgN_exit_callback_fn,
pkgNctx, OCI_FNCODE_STMTPREPARE, OCI_UCBTYPE_EXIT, ucbDesc);

return OCI_CONTINUE;
}

最後に、例9-14では、アプリケーションのソース・コードで、ユーザー・コールバックをNULL ucbDescに登録する方法を示しています。

例9-14 ユーザー・コールバックのNULL ucbDescへの登録

OCIUserCallbackRegister(env, OCI_HTYPE_ENV, errh, static_entry_callback_fn,
pkgNctx, OCI_FNCODE_STMTPREPARE, OCI_UCBTYPE_ENTRY, (OCIUcb *)NULL);

OCIUserCallbackRegister(env, OCI_HTYPE_ENV, errh, static_replace_callback_fn,
pkgNctx, OCI_FNCODE_STMTPREPARE, OCI_UCBTYPE_REPLACE, (OCIUcb *)NULL);

OCIUserCallbackRegister(env, OCI_HTYPE_ENV, errh, static_exit_callback_fn,
pkgNctx, OCI_FNCODE_STMTPREPARE, OCI_UCBTYPE_EXIT, (OCIUcb *)NULL);

例9-15では、OCIStmtPrepare()コールが実行されると、コールバックが次の順にコールされることを示しています。

例9-15 コールバックを順にコールするためのOCIStmtPrepare()の使用

static_entry_callback_fn()
pkg1_entry_callback_fn()
pkg2_entry_callback_fn()
pkg3_entry_callback_fn()
pkg4_entry_callback_fn()
pkg5_entry_callback_fn()

static_replace_callback_fn()
pkg1_replace_callback_fn()
pkg2_replace_callback_fn()
pkg3_replace_callback_fn()
pkg4_replace_callback_fn()
pkg5_replace_callback_fn()

OCI code for OCIStmtPrepare call

pkg5_exit_callback_fn()
pkg4_exit_callback_fn()
pkg3_exit_callback_fn()
pkg2_exit_callback_fn()
pkg1_exit_callback_fn()

static_exit_callback_fn()

注意:
最後のコールバックは、最初のコールバックおよび置換コールバックとは逆の順にコールされます。

最初のコールバックと最後のコールバックからは任意のリターン・コードが戻され、続いて次のコールバックが処理されます。ただし、置換コールバックからOCI_CONTINUE以外のリターン・コードが戻された場合は、連鎖の次のコールバック(または、最後の置換コールバックの場合はOCIコード)が無視され、最後のコールバックの処理に移ります。たとえば、pkg3_replace_callback_fn()からOCI_SUCCESSが戻された場合、pkg4_replace_callback_fn()、pkg5_replace_callback_fn()およびOCIStmtPrepare()コールのOCI処理は無視されます。かわりに、pkg5_exit_callback_fn()が次に実行されます。

外部プロシージャからのOCIコールバック

外部プロシージャからコールバックとして使用できるいくつかのOCI関数があります。これらの関数については、第20章のリストを参照してください。PL/SQLコードからコールできるCサブルーチンの作成方法の詳細は、使用可能なOCIコールのリストおよびコード例も含め、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』を参照してください。

OCIでの透過的アプリケーション・フェイルオーバー

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

- 透過的アプリケーション・フェイルオーバーの構成

- OCIでの透過的アプリケーション・フェイルオーバー・コールバック

- フェイルオーバー・コールバック構造およびパラメータ

- フェイルオーバー・コールバックの登録

- フェイルオーバー・コールバックの例

- OCI_FO_ERRORの処理

透過的アプリケーション・フェイルオーバー(TAF)はクライアント側の機能であり、インスタンスまたはネットワークの障害によりデータベース接続に失敗すると発生するエンドユーザー・アプリケーションに対する障害を最小限にするために設計されています。TAFは、Oracle Real Application Clusters (Oracle RAC)およびOracle Data Guardフィジカル・スタンバイ・データベースなどの各種システム構成に実装できます。TAFは、単一インスタンス・システムの再起動後(修復時など)にも使用できます。

TAFは、データベース・セッションをリストアし、オプションでオープン問合せを再実行するよう構成できます。Oracle Database 10gリリース2 (10.2)より前のリリースでは、SELECTフェイルオーバー・オプションを持つTAFは、障害時に使用されていた文でのみ実行されていました。たとえば、アプリケーションで10個の文ハンドルが使用中で、7番目の文が障害時の文(障害発生時に使用中の文)だった場合は、7番目の文がTAFを使用してフェイルオーバーされた後に、1番目から6番目までの文と8番目から10番目までの文を再実行する必要がありました。

Oracle Database 10gリリース2 (10.2)以降、これが改善されています。このリリースでは、アプリケーションが障害後に使用するすべての文で、フェイルオーバーが試行されます。つまり、他の文に対する実行またはフェッチの試行により、障害時文の場合と同様にTAFリカバリが実行されます。後続の文が今回成功する(前回は失敗)か、または試行されたTAFリカバリに対応するエラー(ORA-25401など)をアプリケーションで受信する可能性があります。

注意:
リモート・データベース・リンクまたはDML文については、TAFはサポートされていません。

透過的アプリケーション・フェイルオーバーの構成

TAFは、クライアント側とサーバー側のどちらでも構成できます。両方とも構成した場合、サーバー側の設定が優先されます。

クライアント側でTAFを構成するには、接続記述子のCONNECT_DATAの部分にFAILOVER_MODEパラメータを含めます。

関連項目:
TAF (接続データ・セクション1)のクライアント側における構成の詳細は、『Oracle Database Net Servicesリファレンス』を参照してください。

サーバー側でTAFを構成するには、DBMS_SERVICE.MODIFY_SERVICEパッケージ・プロシージャによりターゲット・サービスを変更します。

最初のフェイルオーバーは成功しないことがあります。OCIでは、失敗した後にフェイルオーバーを再試行するメカニズムを提供しています。

関連項目:
TAF (DBMS_SERVICE)のサーバー側における構成の詳細は、『Oracle Database PL/SQLパッケージおよびタイプ・リファレンス』を参照してください。

OCIでの透過的アプリケーション・フェイルオーバー・コールバック

フェイルオーバー中に遅延が発生する可能性があるため、アプリケーション開発者は、フェイルオーバーが進行中であることをユーザーに知らせ、フェイルオーバーの完了通知をユーザーが待機するよう要求した方がよい場合があります。さらに、最初のインスタンスのセッションで、いくつかのALTER SESSIONコマンドを受け取る可能性もあります。これらのALTER SESSIONコマンドが、2番目のインスタンスで自動的に再実行されることはありません。したがって、開発者は、これらを2番目のインスタンスで再実行する可能性があります。セッションに影響を与えるOCIAttrSet()コールも再実行する必要があります。

これらの要件に対応するため、アプリケーションの開発者は、フェイルオーバー・コールバック関数を登録できます。フェイルオーバーが発生すると、コールバック関数が、ユーザーのセッションを再確立する間に数回呼び出されます。

コールバック関数が最初にコールされるのは、データベースがインスタンスの接続中断を最初に検出したときです。このコールバックは、アプリケーションがユーザーに対して遅延の発生を通知することを目的にしています。フェイルオーバーが正常終了すると、コールバック関数の2番目のコールは、接続が再確立して使用可能になったときに発生します。

接続が再確立されると、クライアントではALTER SESSIONコマンドを再実行し、ユーザーにフェイルオーバーが発生したことを通知できます。フェイルオーバーが失敗すると、フェイルオーバーが発生しなかったことをアプリケーションに通知するために、コールバックがコールされます。さらに、1次ハンドル以外のユーザー・ハンドルが新しい接続で再認証されるたびに、コールバックがコールされます。各ユーザー・ハンドルはサーバー側セッションを表すため、クライアントでは、そのセッションのためにALTER SESSIONコマンドを再実行できます。

関連項目:
このシナリオの詳細は、「OCI_FO_ERRORの処理」を参照してください。

フェイルオーバー・コールバック構造およびパラメータ

ユーザー定義のアプリケーション・フェイルオーバー・コールバック関数の基本的な構造は次のとおりです。

sb4 appfocallback_fn ( void       * svchp,
void       * envhp,
void       * fo_ctx,
ub4        fo_type,
ub4        fo_event );

次のパラメータの例は、「フェイルオーバー・コールバックの例」で提供されています。

svchp

最初のパラメータのsvchpは、サービス・コンテキスト・ハンドルです。これはvoid *型です。

envhp

2番目のパラメータのenvhpは、OCI環境ハンドルです。これはvoid *型です。

fo_ctx

3番目のパラメータのfo_ctxは、クライアント・コンテキストです。これは、クライアントが指定するメモリーへのポインタです。この領域には、クライアントが必要な状態またはコンテキストを保管できます。このパラメータはvoid *型です。

fo_type

4番目のパラメータのfo_typeは、フェイルオーバーの種類です。このパラメータにより、クライアントが要求したフェイルオーバーの種類をコールバックが判断できます。通常の値は次のとおりです。

- OCI_FO_SESSION－ ユーザーがセッションのフェイルオーバーのみを要求したことを示します。

- OCI_FO_SELECT－ ユーザーが選択フェイルオーバーも要求したことを示します。

fo_event

最後のパラメータは、フェイルオーバーのイベントです。このパラメータは、コールバックがコールされた理由を示します。次の値をとることができます。

- OCI_FO_BEGIN－ フェイルオーバーが中断した接続を検出し、フェイルオーバーが開始することを示します。

- OCI_FO_END－ フェイルオーバーが正常終了したことを示します。

- OCI_FO_ABORT－ フェイルオーバーが失敗し、再試行できないことを示します。

- OCI_FO_ERROR－ 同様にフェイルオーバーが失敗したことを示しますが、アプリケーションでエラーを処理してフェイルオーバーを再試行する機会が与えられます。

- OCI_FO_REAUTH- 複数の認証ハンドルがあり、最初の認証の後にフェイルオーバーが発生したことを示します。ユーザー・ハンドルが再認証されたことを示します。どのユーザー・ハンドルかを調べるために、アプリケーションで、最初のパラメータであるサービス・コンテキスト・ハンドルのOCI_ATTR_SESSION属性をチェックします。

フェイルオーバー・コールバックの登録

フェイルオーバー・コールバックを使用するには、それをサーバー・コンテキスト・ハンドルに登録する必要があります。この登録は、コールバック定義構造体を作成し、サーバー・ハンドルのOCI_ATTR_FOCBK属性にこの構造体を設定することにより行います。

コールバック定義構造の型はOCIFocbkStructにする必要があります。ここには、2つのフィールドがあり、フィールドcallback_functionにはコールする関数のアドレスが含まれており、フィールドfo_ctxにはクライアント・コンテキストのアドレスが含まれています。

コールバック登録の例は、例9-17の一部として含まれています。

フェイルオーバー・コールバックの例

この項では、簡単なユーザー定義コールバック関数の定義の例(例9-16を参照)、フェイルオーバー・コールバックの登録の例(例9-17を参照)およびフェイルオーバー・コールバックの登録解除の例(例9-18を参照)を示しています。

例9-16 ユーザー定義フェイルオーバー・コールバック関数の定義

sb4  callback_fn(svchp, envhp, fo_ctx, fo_type, fo_event)
void * svchp;
void * envhp;
void *fo_ctx;
ub4 fo_type;
ub4 fo_event;
{
switch (fo_event)
{
case OCI_FO_BEGIN:
{
printf(" Failing Over ... Please stand by \n");
printf(" Failover type was found to be %s \n",
((fo_type==OCI_FO_SESSION) ? "SESSION"
:(fo_type==OCI_FO_SELECT) ? "SELECT"
: "UNKNOWN!"));
printf(" Failover Context is :%s\n",
(fo_ctx?(char *)fo_ctx:"NULL POINTER!"));
break;
}
case OCI_FO_ABORT:
{
printf(" Failover stopped. Failover will not occur.\n");
break;
}
case    OCI_FO_END:
{
printf(" Failover ended ...resuming services\n");
break;
}
case OCI_FO_REAUTH:
{
printf(" Failed over user. Resuming services\n");
break;
}
default:
{
printf("Bad Failover Event: %d.\n",  fo_event);
break;
}
}
return 0;
}

例9-17 フェイルオーバー・コールバックの登録

int register_callback(srvh, errh)
void *srvh; /* the server handle */
OCIError *errh; /* the error handle */
{
OCIFocbkStruct failover;                 /*  failover callback structure */
/* allocate memory for context */
if (!(failover.fo_ctx = (void *)malloc(strlen("my context.")+1)))
return(1);
/* initialize the context. */
strcpy((char *)failover.fo_ctx, "my context.");
failover.callback_function = &callback_fn;
/* do the registration */
if (OCIAttrSet(srvh, (ub4) OCI_HTYPE_SERVER,
(void *) &failover, (ub4) 0,
(ub4) OCI_ATTR_FOCBK, errh)  != OCI_SUCCESS)
return(2);
/* successful conclusion */
return (0);
}

例9-18 フェイルオーバー・コールバックの登録解除

OCIFocbkStruct failover;   /*  failover callback structure */
sword status;

/* set the failover context to null */
failover.fo_ctx = NULL;
/* set the failover callback to null */
failover.callback_function = NULL;
/* unregister the callback */
status = OCIAttrSet(srvhp, (ub4) OCI_HTYPE_SERVER,
(void *) &failover, (ub4) 0,
(ub4) OCI_ATTR_FOCBK, errhp);

OCI_FO_ERRORの処理

フェイルオーバーは、成功しないことがあります。失敗した場合は、コールバック関数には、fo_eventパラメータにOCI_FO_ABORTまたはOCI_FO_ERRORの値が戻されます。OCI_FO_ABORTの場合は、フェイルオーバーが失敗し、フェイルオーバーを続行できないことを示します。ただし、OCI_FO_ERRORは、エラーを処理する機会のあるコールバック関数を提供します。たとえば、一定時間待機してから、コールバックからOCIライブラリにフェイルオーバーの再試行を指示する必要があります。

注意:
この機能が利用できるのは、Oracle Databaseサーバーに対して実行されている、リリース8.0.5以上のOCIライブラリにリンクしているアプリケーションのみです。
LOB列が選択リストの一部である場合、フェイルオーバーは機能しません。

表9-2で提示されているイベントの時系列について考えます。

表9-2 時間およびイベント

時間

イベント

T0

データベースに障害が発生します(障害はT5まで続きます)。

T1

ユーザーの操作によってフェイルオーバーが動作します。

T2

ユーザーが再接続を試行します。試行が失敗します。

T3

OCI_FO_ERRORによってフェイルオーバー・コールバックがコールされます。

T4

フェイルオーバー・コールバックは事前に定義されたスリープ状態になります。

T5

データベースがリストアされます。

T6

フェイルオーバー・コールバックによって新しいフェイルオーバーが動作し、成功します。

T7

ユーザーは再接続に成功します。

コールバック関数からOCI_FO_RETRYの値が戻されると、新しいフェイルオーバーが動作します。

例9-19では、前述のシナリオと類似したフェイルオーバー手法の実装に使用できるコールバック関数を示しています。この場合、フェイルオーバー・コールバックはループに入り、スリープ状態になってから、成功するまでフェイルオーバーを再試行します。

例9-19 フェイルオーバー手法を実装するコールバック関数

/*--------------------------------------------------------------------*/
/* the user-defined failover callback  */
/*--------------------------------------------------------------------*/
sb4  callback_fn(svchp, envhp, fo_ctx, fo_type, fo_event )
void * svchp;
void * envhp;
void *fo_ctx;
ub4 fo_type;
ub4 fo_event;
{
OCIError *errhp;
OCIHandleAlloc(envhp, (void **)&errhp, (ub4) OCI_HTYPE_ERROR,
(size_t) 0, (void **) 0);
switch (fo_event)
{
case OCI_FO_BEGIN:
{
printf(" Failing Over ... Please stand by \n");
printf(" Failover type was found to be %s \n",
((fo_type==OCI_FO_NONE) ? "NONE"
:(fo_type==OCI_FO_SESSION) ? "SESSION"
:(fo_type==OCI_FO_SELECT) ? "SELECT"
:(fo_type==OCI_FO_TXNAL) ? "TRANSACTION"
: "UNKNOWN!"));
printf(" Failover Context is :%s\n",
(fo_ctx?(char *)fo_ctx:"NULL POINTER!"));
break;
}
case OCI_FO_ABORT:
{
printf(" Failover aborted. Failover will not occur.\n");
break;
}
case    OCI_FO_END:
{
printf("\n Failover ended ...resuming services\n");
break;
}
case OCI_FO_REAUTH:
{
printf(" Failed over user. Resuming services\n");
break;
}
case OCI_FO_ERROR:
{
/* all invocations of this can only generate one line. The newline
* will be put at fo_end time.
*/
printf(" Failover error gotten. Sleeping...");
sleep(3);
printf("Retrying. ");
return (OCI_FO_RETRY);
break;
}
default:
{
printf("Bad Failover Event: %d.\n",  fo_event);
break;
}
}
return 0;
}

HAイベント通知

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

- OCIEventハンドル

- 接続プールおよびセッション・プールのOCIフェイルオーバー

- 独立した接続のOCIフェイルオーバー

- イベント・コールバック

- カスタム・プーリング: タグ付けされたサーバー・ハンドル

- 透過的アプリケーション・フェイルオーバー(TAF)機能の決定

バックエンド・データベース・サーバーにアクセスするアプリケーション・サーバーにログインするのにWebブラウザをユーザーが使用するとします。データベース・インスタンスに障害が発生した場合、障害がユーザーに通知されるまでに最大で数分かかる場合があります。HAイベント通知には、サーバー・インスタンスの障害を迅速に検出する機能、これをクライアントに通知する機能、および接続プールのアイドル状態の接続をクリーン・アップする機能が用意されています。

Oracle RACデータベースに接続された項可用性のクライアントの場合、データベース障害が発生したときに、HAイベント通知を使用して、ベストエフォート型プログラム・シグナルをクライアントに提供できます。クライアント・アプリケーションは、環境ハンドルにコールバックを登録し、この情報に興味があることを伝えます。このクライアントによって確立された接続に重大な障害イベントが発生すると、そのイベントに関する情報(イベント・ペイロード)や、障害によって切断された接続(サーバー・ハンドル)のリストとともにこのコールバックが呼び出されます。

たとえば、インスタンスAに対する2つの接続と、同じデータベースのインスタンスBに対する2つの接続を持つクライアント・アプリケーションを考えてみます。インスタンスAに障害が発生すると、イベント通知がクライアントに送信され、次に、クライアントにより、インスタンスBに対する2つの接続が切断され、かつ登録されているコールバックが呼び出されます。この場合、同じデータベースの別のインスタンスCに障害が発生しても、クライアントには通知されません(この障害がこのクライアントの接続に影響しないためです)。

HAイベント通知メカニズムにより、障害が発生した際のアプリケーションの応答時間が短縮されます。Oracle Database 10gリリース2 (10.2)でメカニズムが導入される以前は、障害が発生した場合、TCPタイムアウトの期限が切れるまで接続は切断されず、これには数分かかることがありました。HAイベント通知を使用すると、スタンドアロン、接続プールおよびセッション・プール接続はOCIによって自動的に切断されてクリーン・アップされ、障害イベントが発生してから数秒以内にアプリケーション・コールバックが呼び出されます。これらのサーバー・ハンドルのいずれかがTAFに対応している場合は、フェイルオーバーもOCIによって自動的に実行されます。

HAイベント通知を有効化するには、アプリケーションはOracle RACインスタンスに接続する必要があります。また、これらのアプリケーションで次を行う必要があります。

- OCI_EVENTSモードでのOCI環境の初期化

- 通知が有効化されたサービスへの接続(DBMS_SERVICE.MODIFY_SERVICEプロシージャを使用してAQ_HA_NOTIFICATIONSをTRUEに設定する)

- スレッド・ライブラリとのリンク

これにより、これらのアプリケーションはコールバックを登録でき、このコールバックが、HAイベントの発生のたびに呼び出されるようになります。

OCIEventハンドル

OCIEventハンドルは、イベント・ペイロードの属性をカプセル化します。OCIでは、イベント・コールバックを呼び出す前にこのハンドルを暗黙的に割り当て、その結果イベント・コールバックでは、OCIAttrGet()を呼び出すことにより、イベントの読取り専用属性を取得できます。これらの属性に関連するメモリーが有効なのは、イベント・コールバック期間中のみです。

関連項目:
「イベント・ハンドル属性」

接続プールおよびセッション・プールのOCIフェイルオーバー

Oracle RACのインスタンス内の接続プールは、Oracle RACの別のインスタンスに接続されている接続のプールから構成されます。ノード障害の通知を受け取った場合は、特定のインスタンスに接続されているすべての接続をクリーンアップする必要があります。接続が使用されている場合、OCIで接続を閉じる必要があります。これにより、即座に透過的アプリケーション・フェイルオーバー(TAF)が発生し、これらの接続が再確立されます。アイドル状態でプールの空きリストに入っている接続は消去する必要があるため、不適切な接続はプールからユーザーには戻されません。

カスタム接続プールに対応するために、OCIには、環境ハンドルに登録可能なコールバック関数が用意されています。登録すると、このコールバックはHAイベントが発生したときに呼び出されます。セッション・プールは、接続プールと同じように処理されます。OCI接続プールまたはセッション・プールのサーバー・ハンドルは、コールバックには渡されません。このため、場合によっては、空の接続リストを使用してコールバックが呼び出されることがあります。

独立した接続のOCIフェイルオーバー

独立した接続に対しては特別な処理は必要なく、障害の発生したインスタンスに接続されている接続はすべて即座に切断されます。アイドル状態の接続に対しては、TAFにより、この接続が後続のOCIコールで使用された際に再確立されます。接続が失敗イベントで使用されている場合は即座に切断されるため、TAFを開始できます。これは、接続の「使用中」の接続およびセッション・プールにも当てはまります。

イベント・コールバック

OCIEventCallback型のイベント・コールバックには、次のシグネチャがあります。

void evtcallback_fn (void      *evtctx,
OCIEvent  *eventhp );

このシグネチャでは、evtctxはクライアントのコンテキストで、OCIEventは、OCIライブラリに対しては不透明なイベント・ハンドルです。もう1つの入力引数は、イベント・ハンドルであるeventhpです(イベントに関連付けられている属性)。

この関数は、登録されると、イベントのたびに1回ずつ呼び出されます。Oracle RAC HAイベントの場合、このコールバックは、影響を受けた接続が切断されてから呼び出されます。次の環境ハンドル属性を使用して、イベントのコールバックとコンテキストをそれぞれ登録します。

- OCI_ATTR_EVTCBKのデータ型はOCIEventCallback *です。これは読取り専用です。

- OCI_ATTR_EVTCTXのデータ型はvoid *です。これも読取り専用です。

text *myctx = "dummy context"; /* dummy context passed to callback fn */
...
/* OCI_ATTR_EVTCBK and OCI_ATTR_EVTCTX are read-only. */
OCIAttrSet(envhp, (ub4) OCI_HTYPE_ENV, (void *) evtcallback_fn,
(ub4) 0, (ub4) OCI_ATTR_EVTCBK, errhp);
OCIAttrSet(envhp, (ub4) OCI_HTYPE_ENV, (void *) myctx,
(ub4) 0, (ub4) OCI_ATTR_EVTCTX, errhp);
...

OCIイベント・コールバック内では、影響を受けるサーバー・ハンドルのリストは、OCIEventハンドルにカプセル化されます。Oracle RAC HA DOWNイベントの場合、クライアント・アプリケーションは、属性タイプOCI_ATTR_HA_SRVFIRSTおよびOCI_ATTR_HA_SRVNEXTとともにOCIAttrGet()を使用することにより、イベントの影響を受けるサーバー・ハンドルのリストを反復できます。

OCIAttrGet(eventhp, OCI_HTYPE_EVENT, (void *)&srvhp, (ub4 *)0,
OCI_ATTR_HA_SRVFIRST, errhp);
/* or, */
OCIAttrGet(eventhp, OCI_HTYPE_EVENT, (void *)&srvhp, (ub4 *)0,
OCI_ATTR_HA_SRVNEXT, errhp);

この関数は、属性OCI_ATTR_HA_SRVFIRSTを使用して呼び出されると、影響を受けるサーバー・ハンドルのリスト内の最初のサーバー・ハンドルを取得します。この関数は、属性OCI_ATTR_HA_SRVNEXTを使用して呼び出されると、リスト内の次のサーバー・ハンドルを取得します。戻すサーバー・ハンドルがなくなると、この関数はOCI_NO_DATAを戻し、srvhpはNULLポインタになります。

srvhpは、HAイベントにより接続が閉じられたサーバー・ハンドルへの出力ポインタです。errhpは、移入されるエラー・ハンドルです。アプリケーションは、取得する影響を受けたサーバー・ハンドルがなくなると、OCI_NO_DATAエラーを戻します。

HAイベントの影響を受けたサーバー・ハンドルのリストを取得する場合、接続はクローズ済でありかつ多くのサーバー・ハンドル属性が無効になっていることに注意してください。かわりに、イベント通知コールバックに必要な接続ごとの属性を、サーバー・ハンドルのユーザー・メモリー・セグメントに格納します。このメモリーは、サーバー・ハンドルが解放されるまで有効です。

カスタム・プーリング: タグ付けされたサーバー・ハンドル

次の機能は、カスタム・プールに適用されます。

- サーバー・ハンドルをカスタム・プールのかわりに作成する場合、サーバー・ハンドルに親接続オブジェクトのタグを付けることができます。OCIHandleAlloc()のユーザー・メモリー・パラメータを使用して、ユーザー・メモリー・セグメントをサーバー・ハンドルに割り当てるよう要求します。ユーザー・メモリー・セグメントのポインタは、OCIHandleAlloc()によって戻されます。

- HAイベントが発生し、影響を受けるサーバー・ハンドルが取得された場合、適切なクリーン・アップを実行できるようサーバー・ハンドルのタグ情報を取得するための方法があります。OCI_ATTR_USER_MEMORY属性を使用して、ハンドルのユーザー・メモリー・セグメントのポインタを取得します。OCI_ATTR_USER_MEMORYは、ユーザーが割り当てたすべてのハンドルに対して有効です。ハンドルに追加メモリーが割り当てられている場合、ユーザー・メモリーへのポインタが戻されます。追加メモリーが割り当てられていないハンドルに関しては、NULLポインタが戻されます。この属性は読取り専用で、データ型はvoid*です。

注意:
サーバー・ハンドルのユーザー・メモリー・セグメントの正確な内容は自由に定義できます。OCIは、このメモリーからは書込みまたは読取りを行わないため、これにより、HAイベント・コールバックからのクリーン・アップ・アクティビティ(必要な場合は、その他の目的)が簡単になります。ユーザー・メモリー・セグメントは、サーバー・ハンドルに対するOCIHandleFree()のコールによって解放されます。

例9-20では、イベント通知の例を示しています。

例9-20 イベント通知

sword retval;
OCIServer *srvhp;
struct myctx {
void *parentConn_myctx;
uword numval_myctx;
};
typedef struct myctx myctx;
myctx  *myctxp;
/* Allocate a server handle with user memory - pre 10.2 functionality */
if (retval = OCIHandleAlloc(envhp, (void **)&srvhp, OCI_HTYPE_SERVER,
(size_t)sizeof(myctx), (void **)&myctxp)
/* handle error */
myctxp->parentConn_myctx = <parent connection reference>;

/* In an event callback function, retrieve the pointer to the user memory */
evtcallback_fn(void *evtctx, OCIEvent *eventhp)
{
myctx *ctxp = (myctx *)evtctx;
OCIServer *srvhp;
OCIError *errhp;
sb4       retcode;
retcode = OCIAttrGet(eventhp, OCI_HTYPE_SERVER, &srvhp, (ub4 *)0,
OCI_ATTR_HA_SRVFIRST, errhp);
while (!retcode) /* OCIAttrGet will return OCI_NO_DATA if no more srvhp */
{
OCIAttrGet((void *)srvhp, OCI_HTYPE_SERVER, (void *)&ctxp,
(ub4)0, (ub4)OCI_ATTR_USER_MEMORY, errhp);
/* Remove the server handle from the parent connection object */
retcode = OCIAttrGet(eventhp, OCI_HTYPE_SERVER, &srvhp, (ub4 *)0,
OCI_ATTR_HA_SRVNEXT, errhp);
...
}
...
}

透過的アプリケーション・フェイルオーバー(TAF)機能の決定

接続がTAFに対応している場合もいない場合も、アプリケーションにその動作を調整させることができます。次のようにOCIAttrGet()を使用して、サーバー・ハンドルがTAFに対応しているかどうかを確認します。

boolean taf_capable;
...
OCIAttrGet(srvhp, (ub4) OCI_HTYPE_SERVER, (void *) &taf_capable,
(ub4) sizeof(taf_capable), (ub4)OCI_ATTR_TAF_ENABLED, errhp);
...

この例では、taf_capableはブール変数で、サーバー・ハンドルがTAFに対応している場合はTRUE、対応していない場合はFALSEに設定されます。srvhpは、入力ターゲットのサーバー・ハンドルです。OCI_ATTR_TAF_ENABLEDは、ブール変数のポインタで読取り専用です。errhpは、入力エラー・ハンドルです。

OCIおよびStreamsアドバンスト・キューイング

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

- OCI Streamsアドバンスト・キューイング関数

- OCI Streamsアドバンスト・キューイングの説明

- OCI Streamsアドバンスト・キューイングとPL/SQL

- バッファ・メッセージ

OCIでは、Streams Advanced Queuing (Streams AQ)機能へのインタフェースを提供します。Streams AQは、Oracle Databaseと統合されたメッセージ・キューイングです。Streams AQでは、キューイング・システムをデータベースに統合することによりこの機能を実現しており、その結果メッセージ対応データベースが作成されます。Streams AQでは統合された解決策が提供されるため、アプリケーション開発者がメッセージ・インフラストラクチャを構築する必要がなくなり、特定のビジネス・ロジックに専念できるようになりました。

注意:
Streamsアドバンスト・キューイングを使用するには、Oracle DatabaseのEnterprise Editionを使用している必要があります。

関連項目:

- 『Oracle Streamsアドバンスト・キューイング・ユーザーズ・ガイドおよびリファレンス』

- 『Oracle XML Developer's Kitプログラマーズ・ガイド』

- OCIでのAQの使用方法を示すコード例は、「OCIAQEnq()」の説明を参照してください。

OCI Streamsアドバンスト・キューイング関数

OCIライブラリには、Streamsアドバンスト・キューイングに関して次の関数が含まれています。

- OCIAQEnq()

- OCIAQDeq()

- OCIAQListen() (非推奨)

- OCIAQListen2()

- OCIAQEnqArray()

- OCIAQDeqArray()

シングル・キューにメッセージの配列をエンキューできます。メッセージはすべて、同じエンキュー・オプションを共有しますが、配列内の各メッセージには異なるメッセージ・プロパティを含めることができます。シングル・キューからメッセージの配列をデキューすることもできます。トランザクション・グループ・キューの場合は、1回のコールでシングル・トランザクション・グループにすべてのメッセージをデキューできます。

関連項目:
「Streamsアドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数」

OCI Streamsアドバンスト・キューイングの説明

次の記述子がOCI Streams AQ操作に使用されます。

- OCIAQEnqOptions

- OCIAQDeqOptions

- OCIAQMsgProperties

- OCIAQAgent

標準OCIDescriptorAlloc()コールを使用して、サービス・ハンドルに対してこれらの記述子を割り当てられます。次のコードでこの例を示します。

OCIDescriptorAlloc(svch, &enqueue_options, OCI_DTYPE_AQENQ_OPTIONS, 0, 0 );
OCIDescriptorAlloc(svch, &dequeue_options, OCI_DTYPE_AQDEQ_OPTIONS, 0, 0 );
OCIDescriptorAlloc(svch, &message_properties, OCI_DTYPE_AQMSG_PROPERTIES, 0, 0);
OCIDescriptorAlloc(svch, &agent, OCI_DTYPE_AQAGENT, 0, 0 );

各記述子には、設定または読取りができる様々な属性が含まれます。

関連項目:
「Streamsアドバンスト・キューイング記述子の属性」

OCI Streamsアドバンスト・キューイングとPL/SQL

次の表は、OCI Streams AQ関数および記述子の関数、パラメータ、オプションと、DBMS_AQパッケージのPL/SQL AQ関数との比較を表します。表9-3では、AQ関数を比較しています。

表9-3 AQ関数

PL/SQLファンクション

OCI関数

DBMS_AQ.ENQUEUE

OCIAQEnq()

DBMS_AQ.DEQUEUE

OCIAQDeq()

DBMS_AQ.LISTEN

OCIAQListen()、OCIAQListen2()

DBMS_AQ.ENQUEUE_ARRAY

OCIAQEnqArray()

DBMS_AQ.DEQUEUE_ARRAY

OCIAQDeqArray()

表9-4では、エンキュー関数のパラメータを比較しています。

表9-4 エンキュー・パラメータ

DBMS_AQ.ENQUEUEパラメータ

OCIAQEnq()パラメータ

queue_name

queue_name

enqueue_options

enqueue_options

message_properties

message_properties

payload

payload

msgid

msgid

-

注意: OCIAQEnq()では、さらにsvch、errh、payload_tdo、payload_indおよびflagsの各パラメータが必要です。

表9-5では、デキュー関数のパラメータを比較しています。

表9-5 デキュー・パラメータ

DBMS_AQ.DEQUEUEパラメータ

OCIAQDeq()パラメータ

queue_name

queue_name

dequeue_options

dequeue_options

message_properties

message_properties

payload

payload

msgid

msgid

-

注意: OCIAQDeq()では、さらにsvch、errh、dequeue_options、message_properties、payload_tdo、payload、payload_indおよびflagsの各パラメータが必要です。

表9-6では、リスニング関数のパラメータを比較しています。

表9-6 リスニング・パラメータ

DBMS_AQ.LISTENパラメータ

OCIAQListen2()パラメータ

agent_list

agent_list

wait

wait

agent

agent

listen_delivery_mode

lopts

-

OCIAQListen2()では、さらにsvchp、errhp、agent_list、num_agents、agent、lmopsおよびflagsの各パラメータが必要です。

表9-7では、配列エンキュー関数のパラメータを比較しています。

表9-7 配列エンキュー・パラメータ

DBMS_AQ.ENQUEUE_ARRAYパラメータ

OCIAQEnqArray()パラメータ

queue_name

queue_name

enqueue_options

enqopt

array_size

iters

message_properties_array

msgprop

payload_array

payload

msgid_array

msgid

-

注意: OCIAQEnqArray()では、さらにsvch、errh、payload_tdo、payload_ind、ctxp、enqcbfpおよびflagsの各パラメータが必要です。

表9-8では、配列デキュー関数のパラメータを比較しています。

表9-8 配列デキュー・パラメータ

DBMS_AQ.DEQUEUE_ARRAYパラメータ

OCIAQDeqArray()パラメータ

queue_name

queue_name

dequeue_options

deqopt

array_size

iters

message_properties_array

msgprop

payload_array

payload

msgid_array

msgid

-

注意: OCIAQDeqArray()では、さらにsvch、errh、msgprop、payload_tdo、payload_ind、ctxp、deqcbfpおよびflagsの各パラメータが必要です。

表9-9では、エージェント属性のパラメータを比較しています。

表9-9 エージェント・パラメータ

PL/SQL Agentパラメータ

OCIAQAgent属性

name

OCI_ATTR_AGENT_NAME

address

OCI_ATTR_AGENT_ADDRESS

protocol

OCI_ATTR_AGENT_PROTOCOL

表9-10では、メッセージ・プロパティのパラメータを比較しています。

表9-10 メッセージ・プロパティ

PL/SQLメッセージ・プロパティ

OCIAQMsgProperties属性

priority

OCI_ATTR_PRIORITY

delay

OCI_ATTR_DELAY

expiration

OCI_ATTR_EXPIRATION

correlation

OCI_ATTR_CORRELATION

attempts

OCI_ATTR_ATTEMPTS

recipient_list

OCI_ATTR_RECIPIENT_LIST

exception_queue

OCI_ATTR_EXCEPTION_QUEUE

enqueue_time

OCI_ATTR_ENQ_TIME

state

OCI_ATTR_MSG_STATE

sender_id

OCI_ATTR_SENDER_ID

transaction_group

OCI_ATTR_TRANSACTION_NO

original_msgid

OCI_ATTR_ORIGINAL_MSGID

delivery_mode

OCI_ATTR_MSG_DELIVERY_MODE

表9-11では、エンキュー・オプション属性を比較しています。

表9-11 エンキュー・オプション属性

PL/SQLエンキュー・オプション

OCIAQEnqOptions属性

visibility

OCI_ATTR_VISIBILITY

relative_msgid

OCI_ATTR_RELATIVE_MSGID

sequence_deviation

OCI_ATTR_SEQUENCE_DEVIATION

(非推奨)

transformation

OCI_ATTR_TRANSFORMATION

delivery_mode

OCI_ATTR_MSG_DELIVERY_MODE

表9-12では、デキュー・オプション属性を比較しています。

表9-12 デキュー・オプション属性

PL/SQLデキュー・オプション

OCIAQDeqOptions属性

consumer_name

OCI_ATTR_CONSUMER_NAME

dequeue_mode

OCI_ATTR_DEQ_MODE

navigation

OCI_ATTR_NAVIGATION

visibility

OCI_ATTR_VISIBILITY

wait

OCI_ATTR_WAIT

msgid

OCI_ATTR_DEQ_MSGID

correlation

OCI_ATTR_CORRELATION

deq_condition

OCI_ATTR_DEQCOND

transformation

OCI_ATTR_TRANSFORMATION

delivery_mode

OCI_ATTR_MSG_DELIVERY_MODE

注意:
OCIAQEnq()は、エンキュー・オプションOCI_ATTR_SEQUENCEをOCI_ATTR_RELATIVE_MSGIDとともに指定している間は、エラーORA-25219を戻します。これは、2つのメッセージをエンキューした場合に発生します。2番目のメッセージに対しては、最初のメッセージの前にこのメッセージをデキューするように、エンキュー・オプションOCI_ATTR_SEQUENCEおよびOCI_ATTR_RELATIVE_MSGIDが設定されます。順序を指定していない場合エラーは戻されませんが、関連メッセージの前にこのメッセージはデキューされません。
OCI_ATTR_SEQUENCE属性が設定されていない場合、OCIAQEnq()はエラーを戻しませんが、このメッセージは、関連メッセージIDを持つメッセージより前にデキューされません。

バッファ・メッセージ

バッファ・メッセージは、Streams AQ内の非永続型メッセージ機能で、Oracle Database 10gリリース2から使用可能になりました。バッファ・メッセージは、共有メモリーに格納され、インスタンスに障害が発生すると失われることがあります。永続型メッセージとは異なり、ディスクにはREDOが書き込まれません。永続型メッセージ操作より、バッファ・メッセージのエンキューとデキューの方がはるかに高速です。共有メモリーには制限があるため、バッファ・メッセージをディスクにオーバーフローさせることが必要になる場合があります。メッセージ・コンシューマが低速である場合や、なんらかの理由により停止した場合、フロー制御を有効にすることにより、アプリケーションによって共有メモリーが許容オーバーになるのを阻止できます。バッファ・メッセージには、次の関数が使用されます。

- 「OCIAQEnq()」

- 「OCIAQDeq()」

- 「OCIAQListen2()」

例9-21では、エンキュー・バッファ・メッセージの例を示しています。

例9-21 エンキュー・バッファ・メッセージ

...
OCIAQMsgProperties  *msgprop;
OCIAQEnqueueOptions *enqopt;
message              msg;    /* message is an object type */
null_message         nmsg;   /* message indicator */
...
/* Allocate descriptors */
OCIDescriptorAlloc(envhp, (void **)&enqopt, OCI_DTYPE_AQENQ_OPTIONS, 0,
(void **)0));

OCIDescriptorAlloc(envhp, (void **)&msgprop,OCI_DTYPE_AQMSG_PROPERTIES, 0,
(void **)0));

/* Set delivery mode to buffered */
dlvm = OCI_MSG_BUFFERED;
OCIAttrSet(enqopt,  OCI_DTYPE_AQENQ_OPTIONS, (void *)&dlvm, sizeof(ub2),
OCI_ATTR_MSG_DELIVERY_MODE, errhp);
/* Set visibility to Immediate (visibility must always be immediate for buffered
messages) */
vis = OCI_ENQ_ON_COMMIT;

OCIAttrSet(enqopt, OCI_DTYPE_AQENQ_OPTIONS,(void *)&vis, sizeof(ub4),
OCI_ATTR_VISIBILITY, errhp)

/* Message was an object type created earlier, msg_tdo is its type
descriptor object */
OCIAQEnq(svchp, errhp, "Test_Queue", enqopt, msgprop, msg_tdo, (void **)&mesg,
(void **)&nmesg, (OCIRaw **)0, 0));
...

例9-22では、デキュー・バッファ・メッセージの例を示しています。

例9-22 デキュー・バッファ・メッセージ

...
OCIAQMsgProperties  *msgprop;
OCIAQDequeueOptions *deqopt;
...
OCIDescriptorAlloc(envhp, (void **)&mprop, OCI_DTYPE_AQMSG_PROPERTIES, 0,
(void **)0));
OCIDescriptorAlloc(envhp, (void **)&deqopt, OCI_DTYPE_AQDEQ_OPTIONS, 0,
(void **)0);

/* Set visibility to Immediate (visibility must always be immediate for buffered
message operations) */
vis = OCI_ENQ_ON_COMMIT;
OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS,(void *)&vis, sizeof(ub4),
OCI_ATTR_VISIBILITY, errhp)
/* delivery mode is buffered */
dlvm  = OCI_MSG_BUFFERED;
OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS, (void *)&dlvm,  sizeof(ub2),
OCI_ATTR_MSG_DELIVERY_MODE, errhp);
/* Set the consumer for which to dequeue the message (this must be specified
regardless of the type of message being dequeued).
*/
consumer = "FIRST_SUBSCRIBER";
OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS, (void *)consumer,
(ub4)strlen((char*)consumer), OCI_ATTR_CONSUMER_NAME, errhp);
/* Dequeue the message but do not return the payload (to simplify the code
fragment)
*/
OCIAQDeq(svchp, errhp,  "test_queue", deqopt, msgprop, msg_tdo, (void **)0,
(void **)0, (OCIRaw**)0, 0);
...

注意:
配列操作は、バッファ・メッセージに対してはサポートされません。アプリケーションでは、配列サイズを1に設定してOCIAQEnqArray()およびOCIAQDeqArray()関数を使用できます。

OCIでのパブリッシュ・サブスクライブの通知

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

- OCIでのパブリッシュ・サブスクライブの登録関数

- OCIでの通知コールバック

- 通知プロシージャ

- パブリッシュ・サブスクライブの直接登録の例

- パブリッシュ・サブスクライブのLDAP登録の例

パブリッシュ・サブスクライブの通知機能により、OCIアプリケーションでは、クライアント通知の直接受信、通知を送信できる電子メール・アドレスの登録、通知を送信できるHTTP URLの登録、あるいは通知に対してコールされるPL/SQLプロシージャの登録を行うことができます。図9-2は、そのプロセスを示しています。

図9-2 パブリッシュ・サブスクライブのモデル

OCIアプリケーションでは次の処理を行います。

- AQネームスペースに通知の実行を登録し、エンキューが発生したときに通知を受け取ります。

- データベース・イベントのサブスクリプションの実行を登録し、そのイベントがトリガーされたときに通知を受け取ります。

- 一時的な登録の解除またはすべての登録の破棄など、登録を管理します。

- 登録されたクライアントに通知を送信します。

前述のすべての場合において、OCIアプリケーションでの通知の直接受信、事前に指定された電子メール・アドレスへの通知の送信、事前に定義されたHTTP URLへの通知の送信、または通知の結果として、事前に指定したデータベースPL/SQLプロシージャのコールが可能です。

登録されたクライアントは、イベントが発生した時、または明示的なAQエンキューにあるとき、非同期に通知を受け取ります。クライアントは、データベースに接続する必要はありません。

関連項目:

- Streamsアドバンスト・キューイングの詳細は、「OCIおよびStreamsアドバンスト・キューイング」を参照してください。

- キューの作成の詳細と、概念、機能、例を含むStreams AQの詳細は、『Oracle Streamsアドバンスト・キューイング・ユーザーズ・ガイド』を参照してください。

- トリガー作成の詳細は、『Oracle Database SQL言語リファレンス』のCREATE TRIGGERに関する章を参照してください。

OCIでのパブリッシュ・サブスクライブの登録関数

登録する方法には、次の2通りがあります。

- 直接登録。直接データベースに登録します。この方法は単純で、登録は即時に有効になります。「データベースへのパブリッシュ・サブスクライブの直接登録」を参照してください。

- オープン登録。Lightweight Directory Access Protocol (LDAP)を使用して登録し、データベースはここから登録要求を受け取ります。これは、クライアントがデータベースに接続できない場合(データベースの停止中にクライアントがデータベースのオープン・イベントに登録する場合)、またはクライアントが複数のデータベース内の同じイベントまたは複数のイベントに同時に登録する場合に役立ちます。「パブリッシュ・サブスクライブのオープン登録」を参照してください。

データベースへのパブリッシュ・サブスクライブの直接登録

イベント通知の直接登録および受信を行うには、OCIアプリケーションで次の手順を実行する必要があります。適切なイベント・トリガーまたはAQエンキューがセットアップされていることを前提としています。初期化パラメータCOMPATIBLEはリリース8.1以上に設定されている必要があります。

関連項目:

- 「Streamsアドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数」

- アプリケーション内でのこれらの関数の使用例は、「パブリッシュ・サブスクライブの直接登録の例」を参照してください。

注意:
パブリッシュ・サブスクライブ機能は、マルチスレッド・オペレーティング・システム上でのみ使用できます。

1. OCI_EVENTSモードでOCIEnvCreate()またはOCIEnvNlsCreate()をコールし、アプリケーションで通知の登録および受信を行うことを指定します。クライアント上で、通知専用のリスニング・スレッドが起動します。

2. ハンドル・タイプをOCI_HTYPE_SUBSCRIPTIONに指定してOCIHandleAlloc()をコールし、サブスクリプション・ハンドルを割り当てます。

3. OCIAttrSet()をコールし、次のサブスクリプション・ハンドル属性を設定します。

- OCI_ATTR_SUBSCR_NAME－ サブスクリプション名。

- OCI_ATTR_SUBSCR_NAMESPACE－ サブスクリプションのネームスペース。

- OCI_ATTR_SUBSCR_HOSTADDR－ 通信の送信先であるクライアントIP (IPv4またはIPv6書式)を設定する環境ハンドル属性。
Oracle Databaseコンポーネントおよびユーティリティでは、インターネット・プロトコル・バージョン6 (IPv6)アドレスをサポートします。

関連項目:
IPアドレスのIPv6書式の詳細は、「OCI_ATTR_SUBSCR_HOSTADDR」、「OCI_ATTR_SUBSCR_IPADDR」および『Oracle Database Net Services管理者ガイド』を参照してください。

- OCI_ATTR_SUBSCR_CALLBACK－ 通知コールバック。

- OCI_ATTR_SUBSCR_CTX－ コールバック・コンテキスト。

- OCI_ATTR_SUBSCR_PAYLOAD－ 送信用ペイロード・バッファ。

- OCI_ATTR_SUBSCR_RECPT－ 受信者名。

- OCI_ATTR_SUBSCR_RECPTPROTO－ 通知を受信するプロトコル。

- OCI_ATTR_SUBSCR_RECPTPRES－ 通知を受信するための表示。

- OCI_ATTR_SUBSCR_QOSFLAGS－ QOS (サービス品質)レベルで、次の値を設定します。

- OCI_SUBSCR_QOS_PURGE_ON_NTFNを設定すると、最初の通知で登録が削除されます。

- OCI_SUBSCR_QOS_RELIABLEを設定すると、通知は永続的になります。ノードに障害が発生した後でも、この登録に関連付けられた無効化メッセージがデータベースのキューに永続的に残っているために、残存しているOracle RACのインスタンスを使用して変更通知メッセージを送受信できます。FALSEである場合、無効化されたメッセージは高速メモリー内キューにエンキューされます。このオプションは、登録の永続性ではなく通知の永続性を指定するものです。デフォルトでは、登録は自動的に永続的になります。

- OCI_ATTR_SUBSCR_TIMEOUT－ 登録のタイムアウト間隔 (秒単位)。タイムアウトが設定されていない場合、デフォルトは0 (ゼロ)です。

- OCI_ATTR_SUBSCR_NTFN_GROUPING_CLASS－ 通知グループ化クラス。
次の定数でNTFNグループ化オプションを使用することで、通知の間隔を置くことができます。通知グループ化クラスでサポートされる値は、次のとおりです。

#define OCI_SUBSCR_NTFN_GROUPING_CLASS_TIME   1 /* time  */

- OCI_ATTR_SUBSCR_NTFN_GROUPING_VALUE－ 通知グループ化の値(秒単位)。

- OCI_ATTR_SUBSCR_NTFN_GROUPING_TYPE－ 通知グループ化タイプ。
通知グループ化タイプでサポートされる値は、次のとおりです。

#define OCI_SUBSCR_NTFN_GROUPING_TYPE_SUMMARY 1  /* summary */
#define OCI_SUBSCR_NTFN_GROUPING_TYPE_LAST    2  /* last */

- OCI_ATTR_SUBSCR_NTFN_GROUPING_START_TIME－ 通知グループ化開始時間。

- OCI_ATTR_SUBSCR_NTFN_GROUPING_REPEAT_COUNT－ 通知グループ化繰返し回数。

サブスクリプションを登録する前に、OCI_ATTR_SUBSCR_NAME、OCI_ATTR_SUBSCR_NAMESPACEおよびOCI_ATTR_SUBSCR_RECPTPROTOを設定しておく必要があります。

OCI_ATTR_SUBSCR_RECPTPROTOをOCI_SUBSCR_PROTO_OCIに設定した場合は、OCI_ATTR_SUBSCR_CALLBACKおよびOCI_ATTR_SUBSCR_CTXも設定する必要があります。

OCI_ATTR_SUBSCR_RECPTPROTOをOCI_SUBSCR_PROTO_MAIL、OCI_SUBSCR_PROTO_SERVERまたはOCI_SUBSCR_PROTO_HTTPに設定した場合は、OCI_ATTR_SUBSCR_RECPTも設定する必要があります。

OCI_ATTR_SUBSCR_CALLBACKとOCI_ATTR_SUBSCR_RECPTを同時に設定すると、アプリケーション・エラーが発生します。

アプリケーションでサブスクリプションに対する通知の送信を実行するには、OCI_ATTR_SUBSCR_PAYLOADが必要です。

関連項目:
mode = OCI_EVENTS | OCI_OBJECTによる環境の設定については、「サブスクリプション・ハンドル属性」および「OCI環境の作成」を参照してください。OCI_OBJECTは通知のグループ化に必須です。

4. QOS、タイムアウト間隔、ネームスペースおよびポートの値を設定します(例9-23を参照)。

関連項目:
「QOS、タイムアウト間隔、ネームスペース、クライアント・アドレスおよびポート番号の設定」

5. OCI_ATTR_SUBSCR_RECPTPROTOをOCI_SUBSCR_PROTO_OCIに設定し、サブスクリプション・ハンドルで使用するコールバック・ルーチンを定義します。

関連項目:
「OCIでの通知コールバック」

6. OCI_ATTR_SUBSCR_RECPTPROTOをOCI_SUBSCR_PROTO_SERVERに設定し、通知に対してコールするPL/SQLプロシージャをデータベースに定義します。

関連項目:
「通知プロシージャ」

7. OCISubscriptionRegister()をコールし、サブスクリプションを登録します。このコールにより、複数のサブスクリプションを同時に登録できます。

例9-23では、QOSレベルの設定の例を示しています。

例9-23 QOSレベル、通知グループ化のクラス、値およびタイプ、ネームスペース固有のコンテキストの設定

/* Set QOS levels */
ub4 qosflags = OCI_SUBSCR_QOS_PAYLOAD;

/* Set QOS flags in subscription handle */
(void) OCIAttrSet((dvoid *) subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(dvoid *) &qosflags, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_QOSFLAGS, errhp);

/* Set notification grouping class */
ub4 ntfn_grouping_class = OCI_SUBSCR_NTFN_GROUPING_CLASS_TIME;
(void) OCIAttrSet((dvoid *) subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(dvoid *) &ntfn_grouping_class, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_NTFN_GROUPING_CLASS, errhp);

/* Set notification grouping value of 10 minutes */
ub4 ntfn_grouping_value = 600;
(void) OCIAttrSet((dvoid *) subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(dvoid *) &ntfn_grouping_value, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_NTFN_GROUPING_VALUE, errhp);

/* Set notification grouping type */
ub4 ntfn_grouping_type = OCI_SUBSCR_NTFN_GROUPING_TYPE_SUMMARY;

/* Set notification grouping type in subscription handle */
(void) OCIAttrSet((dvoid *) subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(dvoid *) &ntfn_grouping_type, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_NTFN_GROUPING_TYPE, errhp);

/* Set namespace specific context */
(void) OCIAttrSet((dvoid *) subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(dvoid *) NULL, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_NAMESPACE_CTX, errhp);

パブリッシュ・サブスクライブのオープン登録

パブリッシュ・サブスクライブのオープン登録の前提条件は、次のとおりです。

- LDAP (オープン登録)を使用する登録では、クライアントがエンタープライズ・ユーザーであることが必要です。

関連項目:
『Oracle Database Advanced Security管理者ガイド』のエンタープライズ・ユーザー・セキュリティの管理に関する項

- データベースの互換性は、9.0以上であることが必要です。

- LDAP_REGISTRATION_ENABLEDをTRUEに設定する必要があります。次のように設定します。

ALTER SYSTEM SET LDAP_REGISTRATION_ENABLED=TRUE

デフォルトはFALSEです。

- LDAP_REG_SYNC_INTERVALをLDAPからの登録をリフレッシュする時間隔(秒単位)に設定します。

ALTER SYSTEM SET LDAP_REG_SYNC_INTERVAL =  time_interval

デフォルトは0 (ゼロ)で、この場合リフレッシュは行われません。

- データベースでLDAPの登録情報を即時にリフレッシュするには、次のように設定します。

ALTER SYSTEM REFRESH LDAP_REGISTRATION

Oracle Enterprise Security Manager (OESM)を使用したオープン登録の手順は、次のとおりです。

1. 各エンタープライズ・ドメインで、エンタープライズ・ロールのENTERPRISE_AQ_USER_ROLEを作成します。

2. エンタープライズ・ドメイン内の各データベースについて、グローバル・ロールのGLOBAL_AQ_USER_ROLEをエンタープライズ・ロールのENTERPRISE_AQ_USER_ROLEに追加します。

3. 各エンタープライズ・ドメインについて、エンタープライズ・ロールのENTERPRISE_AQ_USER_ROLEを、管理コンテキストの下のcn=oraclecontextの下にある権限グループのcn=OracleDBAQUsersに追加します。

4. データベース内のイベントへの登録が承認される各エンタープライズ・ユーザーに対して、エンタープライズ・ロールのENTERPRISE_AQ_USER_ROLEを付与します。

OCIを使用したLDAPのオープン登録

1. modeをOCI_EVENTS | OCI_USE_LDAPに設定したOCIEnvCreate()または OCIEnvNlsCreate()をコールします。

2. OCIAttrSet()をコールし、次の環境ハンドル属性を設定してLDAPにアクセスします。

- OCI_ATTR_LDAP_HOST－ LDAPサーバーが常駐しているホスト名。

- OCI_ATTR_LDAP_PORT－ LDAPサーバーがリスニングしているポート。

- OCI_ATTR_BIND_DN－ LDAPサーバーにログインするための識別名で、通常はエンタープライズ・ユーザーのDNです。

- OCI_ATTR_LDAP_CRED－ クライアントの認証に使用する資格証明で、簡易認証(ユーザー名およびパスワード)のパスワードなどです。

- OCI_ATTR_WALL_LOC－ SSL認証の場合のクライアントWalletの場所。

- OCI_ATTR_LDAP_AUTH－ 認証方式コード。

関連項目:
認証モードの完全なリストは、「環境ハンドル属性」を参照してください。

- OCI_ATTR_LDAP_CTX－ LDAPサーバーのOracle Databaseに対する管理コンテキスト。

3. ハンドル・タイプをOCI_HTYPE_SUBSCRIPTIONに指定してOCIHandleAlloc()をコールし、サブスクリプション・ハンドルを割り当てます。

4. 記述子タイプをOCI_DTYPE_SRVDNに指定してOCIArrayDescriptorAlloc()をコールし、サーバーのDN記述子を割り当てます。

5. OCIAttrSet()をコールし、サーバーのDN記述子属性を、クライアントが通知を受信するデータベースの識別名であるOCI_ATTR_SERVER_DNに設定します。OCIAttrSet()は、この属性について複数回コールできるため、登録には複数のデータベース・サーバーが含まれます。

6. OCIAttrSet()をコールし、次のサブスクリプション・ハンドル属性を設定します。

- OCI_ATTR_SUBSCR_NAME－ サブスクリプション名。

- OCI_ATTR_SUBSCR_NAMESPACE－ サブスクリプションのネームスペース。

- OCI_ATTR_SUBSCR_CALLBACK－ 通知コールバック。

- OCI_ATTR_SUBSCR_CTX－ コールバック・コンテキスト。

- OCI_ATTR_SUBSCR_PAYLOAD－ 送信用ペイロード・バッファ。

- OCI_ATTR_SUBSCR_RECPT－ 受信者名。

- OCI_ATTR_SUBSCR_RECPTPROTO－ 通知を受信するプロトコル。

- OCI_ATTR_SUBSCR_RECPTRES－ 通知を受信するための表示。

- OCI_ATTR_SUBSCR_QOSFLAGS－ QOS (サービス品質)レベル。

- OCI_ATTR_SUBSCR_TIMEOUT－ 登録のタイムアウト間隔 (秒単位)。タイムアウトが設定されていない場合、デフォルトは0 (ゼロ)です。

- OCI_ATTR_SUBSCR_SERVER_DN－ ステップ5で設定した記述子ハンドル。

7. QOS、タイムアウト間隔、ネームスペースおよびポートの値を設定します。「QOS、タイムアウト間隔、ネームスペース、クライアント・アドレスおよびポート番号の設定」を参照してください。

8. OCISubscriptionRegister()をコールし、サブスクリプションを登録します。データベースがLDAPにアクセスして新規登録を取り出すと、登録が有効になります。取り出す頻度は、LDAP_REG_SYNC_INTERVALの値によって決まります。

QOS、タイムアウト間隔、ネームスペース、クライアント・アドレスおよびポート番号の設定

OCIAttrSet()を使用して、QOSFLAGSを次のQOSレベルに設定できます。

- OCI_SUBSCR_QOS_RELIABLE－ 信頼性のある通知は、インスタンスやデータベースが再起動しても持続します。信頼性とは、サーバーの信頼性のことであり、それも永続的なキューやバッファ・メッセージについての信頼性です。このオプションは、通知の永続性を記述します。デフォルトでは、登録は永続的です。

- OCI_SUBSCR_QOS_PURGE_ON_NTFN－ 通知を受信すると、最初の通知で登録を削除します。(サブスクリプションの登録は解除されます。)

/* Set QOS levels */
ub4 qosflags = OCI_SUBSCR_QOS_RELIABLE | OCI_SUBSCR_QOS_PURGE_ON_NTFN;

/* Set flags in subscription handle */
(void)OCIAttrSet((void *)subscrhp, (ub4)OCI_HTYPE_SUBSCRIPTION,
(void *)&qosflags, (ub4)0, (ub4)OCI_ATTR_SUBSCR_QOSFLAGS, errhp);

/* Set auto-expiration after 30 seconds */
ub4 timeout = 30;
(void)OCIAttrSet((void *)subscrhp, (ub4)OCI_HTYPE_SUBSCRIPTION,
(void *)&timeout, (ub4)0, (ub4)OCI_ATTR_SUBSCR_TIMEOUT, errhp);

タイムアウトを過ぎると、登録が削除され、通知がクライアントに送信されるため、クライアントはコールバックを呼び出し、必要なアクションを実行できるようになります。タイムアウト前にクライアントに障害が発生した場合、登録は消去されます。

環境ハンドルにはポート番号を設定でき、クライアントがファイアウォールの背後のシステム上にあり、特定のポートの通知のみを受信できる場合に、この番号が重要になります。クライアントは、環境ハンドルの属性を使用して、最初の登録の前にリスナー・スレッドのポートを指定できます。このスレッドは、OCISubscriptionRegister()の初回のコール時に開始されます。指定されたこのポート番号が使用可能な場合、この番号が使用されます。クライアントが異なる環境ハンドルを使用して異なるポートで別のスレッドを開始しようとすると、エラーが戻されます。

ub4 port = 1581;
(void)OCIAttrSet((void *)envhp, (ub4)OCI_HTYPE_ENV, (void *)&port, (ub4)0,
(ub4)OCI_ATTR_SUBSCR_PORTNO, errhp);

これとは異なりポートが自動的に決定される場合は、環境ハンドルから属性を取得することにより、クライアント・スレッドが通知をリスニングしているポート番号を取得できます。

(void)OCIAttrGet((void *)subhp, (ub4)OCI_HTYPE_ENV, (void *)&port, (ub4)0,
(ub4)OCI_ATTR_SUBSCR_PORTNO, errhp);

クライアント・アドレス設定の例

text ipaddr[16] = "10.177.246.40";
(void)(OCIAttrSet((dvoid *) envhp, (ub4) OCI_HTYPE_ENV,
(dvoid *) ipaddr, (ub4) strlen((const char *)ipaddr),
(ub4) OCI_ATTR_SUBSCR_IPADDR, errhp));

関連項目:
「OCI_ATTR_SUBSCR_IPADDR」

パブリッシュ・サブスクライブ通知の管理に使用するOCI関数

表9-13は、パブリッシュ・サブスクライブ通知に使用される関数のリストです。

表9-13 パブリッシュ・サブスクライブの関数

関数

用途

OCISubscriptionDisable()

サブスクリプションを無効にします。

OCISubscriptionEnable()

サブスクリプションを有効にします。

OCISubscriptionPost()

サブスクリプションを送信します。

OCISubscriptionRegister()

サブスクリプションを登録します。

OCISubscriptionUnRegister()

サブスクリプションの登録を解除します。

OCIでの通知コールバック

クライアントは、登録したサブスクリプションに対してアクティビティが発生したときにコールされる、通知コールバックを登録する必要があります。たとえば、AQネームスペースでは、目的のメッセージがエンキューされたときに通知コールバックが発生します。

このコールバックは通常、サブスクリプション・ハンドルのOCI_ATTR_SUBSCR_CALLBACK属性によって設定されます。

関連項目:
「サブスクリプション・ハンドル属性」

通知コールバックからは、OCI_CONTINUE値が戻される必要があります。また、次の仕様に準拠している必要があります。

typedef ub4 (*OCISubscriptionNotify) ( void            *pCtx,
OCISubscription *pSubscrHp,
void            *pPayload,
ub4             iPayloadLen,
void            *pDescriptor,
ub4             iMode);

パラメータは次のように記述します。

pCtx (IN)

コールバックが登録されたときに指定されたユーザー定義コンテキスト。

pSubscrHp (IN)

コールバックが登録されたときに指定されたサブスクリプション・ハンドル。

pPayload (IN)

この通知のペイロード。現在のところ、ペイロードのub1 * (バイト・シーケンス)のみがサポートされています。

iPayloadLen (IN)

この通知のペイロードの長さ。

pDescriptor (IN)

ネームスペース固有の記述子。この記述子からネームスペース指定のパラメータを抽出できます。この記述子の構造はユーザーには不透明で、型はネームスペースによって異なります。

記述子の属性は、ネームスペース固有です。アドバンスト・キューイング(AQ)の場合、記述子はOCI_DTYPE_AQNFYです。AQネームスペースの場合、グループで受信する通知の数は通知記述子に提供されます。pDescriptorの属性は次のとおりです。

- 通知フラグ(通常=0、タイムアウト=1、通知のグループ化=2)－ OCI_ATTR_NFY_FLAGS

- キュー名－ OCI_ATTR_QUEUE_NAME

- コンシューマ名－ OCI_ATTR_CONSUMER_NAME

- メッセージID－ OCI_ATTR_NFY_MSGID

- メッセージ・プロパティ－ OCI_ATTR_MSG_PROP

- グループで受信する通知の数－ OCI_ATTR_AQ_NTFN_GROUPING_COUNT

- グループ(OCIコレクション)－ OCI_ATTR_AQ_NTFN_GROUPING_MSGID_ARRAY

関連項目:

- 「OCIおよびStreamsアドバンスト・キューイング」

- 「通知の記述子の属性」

iMode (IN)

コール固有モードです。有効な値はOCI_DEFAULTのみです。この値は、デフォルトのコールを実行します。

例9-24では、通知コールバックでのAQグループ化通信属性の使用方法を示しています。

例9-24 OCI通知コールバックでのAQグループ化通信属性の使用

ub4 notifyCB1(void *ctx, OCISubscription *subscrhp, void *pay, ub4 payl,
void *desc, ub4 mode)
{
oratext            *subname;
ub4                 size;
OCIColl            *msgid_array = (OCIColl *)0;
ub4                 msgid_cnt = 0;
OCIRaw             *msgid;
void              **msgid_ptr;
sb4                 num_msgid = 0;
void               *elemind = (void *)0;
boolean             exist;
ub2                 flags;
oratext            *hexit = (oratext *)"0123456789ABCDEF";
ub4                 i, j;

/* get subscription name */
OCIAttrGet(subscrhp, OCI_HTYPE_SUBSCRIPTION, (void *)&subname, &size,
OCI_ATTR_SUBSCR_NAME,ctxptr->errhp);

/* print subscripton name */
printf("Got notification for %.*s\n", size, subname);
fflush((FILE *)stdout);

/* get the #ntfns received in this group */
OCIAttrGet(desc, OCI_DTYPE_AQNFY, (void *)&msgid_cnt, &size,
OCI_ATTR_AQ_NTFN_GROUPING_COUNT, ctxptr->errhp);

/* get the group - collection of msgids */
OCIAttrGet(desc, OCI_DTYPE_AQNFY, (void *)&msgid_array, &size,
OCI_ATTR_AQ_NTFN_GROUPING_MSGID_ARRAY, ctxptr->errhp);

/* get notification flag - regular, timeout, or grouping notification? */
OCIAttrGet(desc, OCI_DTYPE_AQNFY, (void *)&flags, &size,
OCI_ATTR_NFY_FLAGS, ctxptr->errhp);

/* print notification flag */
printf("Flag: %d\n", (int)flags);

/* get group (collection) size */
if (msgid_array)
checkerr(ctxptr->errhp,
OCICollSize(ctxptr->envhp, ctxptr->errhp,
CONST OCIColl *) msgid_array, &num_msgid),
"Inside notifyCB1-OCICollSize");
else
num_msgid =0;

/* print group size */
printf("Collection size: %d\n", num_msgid);

/* print all msgids in the group */
for(i = 0; i < num_msgid; i++)
{
ub4  rawSize;                                             /* raw size    */
ub1 *rawPtr;                                              /* raw pointer */
/* get msgid from group */
checkerr(ctxptr->errhp,
OCICollGetElem(ctxptr->envhp, ctxptr->errhp,
(OCIColl *) msgid_array, i, &exist,
(void **)(&msgid_ptr), &elemind),
"Inside notifyCB1-OCICollGetElem");
msgid = *msgid_ptr;
rawSize = OCIRawSize(ctxptr->envhp, msgid);
rawPtr = OCIRawPtr(ctxptr->envhp, msgid);

/* print msgid size */
printf("Msgid size: %d\n", rawSize);

/* print msgid in hexadecimal format */
for (j = 0; j < rawSize; j++)
{                                           /* for each byte in the raw */
printf("%c", hexit[(rawPtr[j] & 0xf0) >> 4]);
printf("%c", hexit[(rawPtr[j] & 0x0f)]);
}
printf("\n");
}

/* print #ntfns received in group */
printf("Notification Count: %d\n", msgid_cnt);
printf("\n");
printf("***********************************************************\n");
fflush((FILE *)stdout);
return 1;
}

通知プロシージャ

実行が登録されているサブスクリプションでなんらかのアクティビティが発生したときにコールするPL/SQLプロシージャは、データベース内に作成する必要があります。

このプロシージャは通常、サブスクリプション・ハンドルのOCI_ATTR_SUBSCR_RECPT属性によって設定されます。

関連項目:

- 「サブスクリプション・ハンドル属性」

- PL/SQLプロシージャの指定の詳細は、 『Oracle Database PL/SQLパッケージおよびタイプ・リファレンス』の「Oracle Streams AQ PL/SQLコールバック」を参照してください。

パブリッシュ・サブスクライブの直接登録の例

例9-25では、システム・イベント、クライアント通知およびアドバンスト・キューイングが連動して、パブリッシュ・サブスクライブ通知を実装する方法を示しています。

例9-25のPL/SQLコードでは、ユーザー・スキーマpubsub環境で公開サブスクライブ・メカニズムをサポートするために必要なすべてのオブジェクトを作成します。このコードでは、エージェントsnoopが、ログイン・イベント時にパブリッシュされるメッセージをサブスクライブします。ユーザーpubsubには、アドバンスト・キューイング機能を使用するためにAQ_ADMINISTRATOR_ROLEおよびAQ_USER_ROLEの権限が必要です。システム・イベントのトリガーを有効にするには、初期化パラメータ_SYSTEM_TRIG_ENABLEDをTRUE (デフォルト)に設定する必要があります。 例9-25を実行する前に、pubsubとして接続します。

例9-25 パブリッシュ・サブスクライブ通知の実装

----------------------------------------------------------
----create queue table for persistent multiple consumers
----------------------------------------------------------
---- Create or replace a queue table
begin
DBMS_AQADM.CREATE_QUEUE_TABLE(
QUEUE_TABLE=>'pubsub.raw_msg_table',
MULTIPLE_CONSUMERS => TRUE,
QUEUE_PAYLOAD_TYPE =>'RAW',
COMPATIBLE => '8.1.5');
end;
/
----------------------------------------------------------
---- Create a persistent queue for publishing messages
----------------------------------------------------------
---- Create a queue for logon events
begin
DBMS_AQADM.CREATE_QUEUE(QUEUE_NAME=>'pubsub.logon',
QUEUE_TABLE=>'pubsub.raw_msg_table',
COMMENT=>'Q for error triggers');
end;
/
----------------------------------------------------------
---- Start the queue
----------------------------------------------------------
begin
DBMS_AQADM.START_QUEUE('pubsub.logon');
end;
/
----------------------------------------------------------
---- define new_enqueue for convenience
----------------------------------------------------------
create or replace procedure new_enqueue(queue_name  in varchar2,
payload  in raw ,
correlation in varchar2 := NULL,
exception_queue in varchar2 := NULL)
as
enq_ct     dbms_aq.enqueue_options_t;
msg_prop   dbms_aq.message_properties_t;
enq_msgid  raw(16);
userdata   raw(1000);
begin
msg_prop.exception_queue := exception_queue;
msg_prop.correlation := correlation;
userdata := payload;
DBMS_AQ.ENQUEUE(queue_name,enq_ct, msg_prop,userdata,enq_msgid);
end;
/
----------------------------------------------------------
---- add subscriber with rule based on current user name,
---- using correlation_id
----------------------------------------------------------
declare
subscriber sys.aq$_agent;
begin
subscriber := sys.aq$_agent('SNOOP', null, null);
dbms_aqadm.add_subscriber(queue_name => 'pubsub.logon',
subscriber => subscriber,
rule => 'CORRID = ''ix'' ');
end;
/
----------------------------------------------------------
---- create a trigger on logon on database
----------------------------------------------------------
---- create trigger on after logon
create or replace trigger systrig2
AFTER LOGON
ON DATABASE
begin
new_enqueue('pubsub.logon', hextoraw('9999'), dbms_standard.login_user);
end;
/

----------------------------------------------------------
---- create a PL/SQL callback for notification of logon
---- of user 'ix' on database
----------------------------------------------------------
----
create or replace procedure plsqlnotifySnoop(
context raw, reginfo sys.aq$_reg_info, descr sys.aq$_descriptor,
payload raw, payloadl number)
as
begin
dbms_output.put_line('Notification : User ix Logged on\n');
end;
/

サブスクリプションが作成された後、クライアントはコールバック関数を使用して通知を登録する必要があります。例9-26では、登録に必要なステップを実行するサンプル・コードを示しています。ここでは、わかりやすくするために、セッション・ハンドルの割当ておよび初期化のステップを省略しています。

例9-26 コールバック関数を使用する通知の登録

...
static ub4 namespace = OCI_SUBSCR_NAMESPACE_AQ;

static OCISubscription *subscrhpSnoop = (OCISubscription *)0;
static OCISubscription *subscrhpSnoopMail = (OCISubscription *)0;
static OCISubscription *subscrhpSnoopServer = (OCISubscription *)0;

/* callback function for notification of logon of user 'ix' on database */

static ub4 notifySnoop(ctx, subscrhp, pay, payl, desc, mode)
void *ctx;
OCISubscription *subscrhp;
void *pay;
ub4 payl;
void *desc;
ub4 mode;
{
printf("Notification : User ix Logged on\n");
(void)OCIHandleFree((void *)subscrhpSnoop,
(ub4) OCI_HTYPE_SUBSCRIPTION);
return 1;
}

static void checkerr(errhp, status)
OCIError *errhp;
sword status;
{
text errbuf[512];
ub4 buflen;
sb4 errcode;

if (status == OCI_SUCCESS) return;

switch (status)
{
case OCI_SUCCESS_WITH_INFO:
printf("Error - OCI_SUCCESS_WITH_INFO\n");
break;
case OCI_NEED_DATA:
printf("Error - OCI_NEED_DATA\n");
break;
case OCI_NO_DATA:
printf("Error - OCI_NO_DATA\n");
break;
case OCI_ERROR:
OCIErrorGet ((void *) errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
printf("Error - %s\n", errbuf);
break;
case OCI_INVALID_HANDLE:
printf("Error - OCI_INVALID_HANDLE\n");
break;
case OCI_STILL_EXECUTING:
printf("Error - OCI_STILL_EXECUTING\n");
break;
case OCI_CONTINUE:
printf("Error - OCI_CONTINUE\n");
break;
default:
printf("Error - %d\n", status);
break;
}
}

static void initSubscriptionHn (subscrhp,
subscriptionName,
func,
recpproto,
recpaddr,
recppres)
OCISubscription **subscrhp;
char * subscriptionName;
void * func;
ub4 recpproto;
char * recpaddr;
ub4 recppres;
{
/* allocate subscription handle */
(void) OCIHandleAlloc((void *) envhp, (void **)subscrhp,
(ub4) OCI_HTYPE_SUBSCRIPTION,
(size_t) 0, (void **) 0);

/* set subscription name in handle */
(void) OCIAttrSet((void *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(void *) subscriptionName,
(ub4) strlen((char *)subscriptionName),
(ub4) OCI_ATTR_SUBSCR_NAME, errhp);

/* set callback function in handle */
if (func)
(void) OCIAttrSet((void *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(void *) func, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_CALLBACK, errhp);

/* set context in handle */
(void) OCIAttrSet((void *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(void *) 0, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_CTX, errhp);

/* set namespace in handle */
(void) OCIAttrSet((void *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(void *) &namespace, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_NAMESPACE, errhp);

/* set receive with protocol in handle */
(void) OCIAttrSet((void *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(void *) &recpproto, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_RECPTPROTO, errhp);

/* set recipient address in handle */
if (recpaddr)
(void) OCIAttrSet((void *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(void *) recpaddr, (ub4) strlen(recpaddr),
(ub4) OCI_ATTR_SUBSCR_RECPT, errhp);

/* set receive with presentation in handle */
(void) OCIAttrSet((void *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(void *) &recppres, (ub4) 0,
(ub4) OCI_ATTR_SUBSCR_RECPTPRES, errhp);

printf("Begining Registration for subscription %s\n", subscriptionName);
checkerr(errhp, OCISubscriptionRegister(svchp, subscrhp, 1, errhp,
OCI_DEFAULT));
printf("done\n");

}

int main( argc, argv)
int    argc;
char * argv[];
{
OCISession *authp = (OCISession *) 0;

/*****************************************************
Initialize OCI Process/Environment
Initialize Server Contexts
Connect to Server
Set Service Context
******************************************************/

/* Registration Code Begins */
/* Each call to initSubscriptionHn allocates
and initializes a Registration Handle */

/* Register for OCI notification */
initSubscriptionHn(    &subscrhpSnoop,    /* subscription handle*/
(char*) "PUBSUB.LOGON:SNOOP", /* subscription name */
/*<queue_name>:<agent_name> */
(void*)notifySnoop,  /* callback function */
OCI_SUBSCR_PROTO_OCI, /* receive with protocol */
(char *)0, /* recipient address */
OCI_SUBSCR_PRES_DEFAULT); /* receive with presentation */

/* Register for email notification */
initSubscriptionHn(    &subscrhpSnoopMail,  /* subscription handle */
(char*) "PUBSUB.LOGON:SNOOP",              /* subscription name */
/* <queue_name>:<agent_name> */
(void*)0, /* callback function */
OCI_SUBSCR_PROTO_MAIL, /* receive with protocol */
(char*)  "xyz@company.com", /* recipient address */
OCI_SUBSCR_PRES_DEFAULT); /* receive with presentation */

/* Register for server to server notification */
initSubscriptionHn(    &subscrhpSnoopServer, /* subscription handle */
(char*)  "PUBSUB.LOGON:SNOOP",            /* subscription name */
/* <queue_name>:<agent_name> */
(void*)0, /* callback function */
OCI_SUBSCR_PROTO_SERVER, /* receive with protocol */
(char*) "pubsub.plsqlnotifySnoop", /* recipient address */
OCI_SUBSCR_PRES_DEFAULT); /* receive with presentation */

checkerr(errhp, OCITransCommit(svchp, errhp, (ub4) OCI_DEFAULT));

/*****************************************************
The Client Process does not need a live Session for Callbacks.
End Session and Detach from Server.
******************************************************/

OCISessionEnd ( svchp,  errhp, authp, (ub4) OCI_DEFAULT);

/* detach from server */
OCIServerDetach( srvhp, errhp, OCI_DEFAULT);

while (1)    /* wait for callback */
sleep(1);
}

ユーザーIXがデータベースにログインした場合、クライアントは電子メールで通知を受け取り、コールバック関数notifySnoopがコールされます。電子メール通知は、アドレスxyz@company.comに送信され、PL/SQLプロシージャplsqlnotifySnoopもデータベースでコールされます。

パブリッシュ・サブスクライブのLDAP登録の例

例9-27では、LDAP登録の方法を説明するコード・フラグメントを示しています。プログラム・コメントはすべて目を通してください。

例9-27 LDAP登録

...

/* To use the LDAP registration feature, OCI_EVENTS | OCI_EVENTS |OCI_USE_LDAP*/
/*   must be set in OCIEnvCreate or OCIEnvNlsCreate */
/*     (Note: OCIInitialize is deprecated): */
(void) OCIInitialize((ub4) OCI_EVENTS|OCI_OBJECT|OCI_USE_LDAP, (void *)0,
(void * (*)(void *, size_t)) 0,
(void * (*)(void *, void *, size_t))0,
(void (*)(void *, void *)) 0 );

...

/* set LDAP attributes in the environment handle */

/* LDAP host name */
(void) OCIAttrSet((void *)envhp, OCI_HTYPE_ENV, (void *)"yow", 3,
OCI_ATTR_LDAP_HOST, (OCIError *)errhp);

/* LDAP server port */
ldap_port = 389;
(void) OCIAttrSet((void *)envhp, OCI_HTYPE_ENV, (void *)&ldap_port,
(ub4)0, OCI_ATTR_LDAP_PORT, (OCIError *)errhp);

/* bind DN of the client, normally the enterprise user name */
(void) OCIAttrSet((void *)envhp, OCI_HTYPE_ENV, (void *)"cn=orcladmin",
12, OCI_ATTR_BIND_DN, (OCIError *)errhp);

/* password of the client */
(void) OCIAttrSet((void *)envhp, OCI_HTYPE_ENV, (void *)"welcome",
7, OCI_ATTR_LDAP_CRED, (OCIError *)errhp);

/* authentication method is "simple", username/password authentication */
ldap_auth = 0x01;
(void) OCIAttrSet((void *)envhp, OCI_HTYPE_ENV, (void *)&ldap_auth,
(ub4)0, OCI_ATTR_LDAP_AUTH, (OCIError *)errhp);

/* administrative context: this is the DN above cn=oraclecontext */
(void) OCIAttrSet((void *)envhp, OCI_HTYPE_ENV, (void *)"cn=acme,cn=com",
14, OCI_ATTR_LDAP_CTX, (OCIError *)errhp);

...

/* retrieve the LDAP attributes from the environment handle */

/* LDAP host */
(void) OCIAttrGet((void *)envhp, OCI_HTYPE_ENV, (void *)&buf,
&szp,  OCI_ATTR_LDAP_HOST,  (OCIError *)errhp);

/* LDAP server port */
(void) OCIAttrGet((void *)envhp, OCI_HTYPE_ENV, (void *)&intval,
0,  OCI_ATTR_LDAP_PORT,  (OCIError *)errhp);

/* client binding DN */
(void) OCIAttrGet((void *)envhp, OCI_HTYPE_ENV, (void *)&buf,
&szp,  OCI_ATTR_BIND_DN,  (OCIError *)errhp);

/* client password */
(void) OCIAttrGet((void *)envhp, OCI_HTYPE_ENV, (void *)&buf,
&szp,  OCI_ATTR_LDAP_CRED,  (OCIError *)errhp);

/* administrative context */
(void) OCIAttrGet((void *)envhp, OCI_HTYPE_ENV, (void *)&buf,
&szp,  OCI_ATTR_LDAP_CTX,  (OCIError *)errhp);

/* client authentication method */
(void) OCIAttrGet((void *)envhp, OCI_HTYPE_ENV, (void *)&intval,
0,  OCI_ATTR_LDAP_AUTH,  (OCIError *)errhp);

...

/* to set up the server DN descriptor in the subscription handle */

/* allocate a server DN descriptor, dn is of type "OCIServerDNs **",
subhp is of type "OCISubscription **" */
(void) OCIDescriptorAlloc((void *)envhp, (void **)dn,
(ub4) OCI_DTYPE_SRVDN, (size_t)0, (void **)0);

/* now *dn is the server DN descriptor, add the DN of the first database
that you want to register */
(void) OCIAttrSet((void *)*dn, (ub4) OCI_DTYPE_SRVDN,
(void *)"cn=server1,cn=oraclecontext,cn=acme,cn=com",
42, (ub4)OCI_ATTR_SERVER_DN, errhp);
/* add the DN of another database in the descriptor */
(void) OCIAttrSet((void *)*dn, (ub4) OCI_DTYPE_SRVDN,
(void *)"cn=server2,cn=oraclecontext,cn=acme,cn=com",
42, (ub4)OCI_ATTR_SERVER_DN, errhp);

/* set the server DN descriptor into the subscription handle */
(void) OCIAttrSet((void *) *subhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(void *) *dn, (ub4)0, (ub4) OCI_ATTR_SERVER_DNS, errhp);

...

/* now you will try to get the server DN information from the subscription
handle */

/* first, get the server DN descriptor out */
(void) OCIAttrGet((void *) *subhp, (ub4) OCI_HTYPE_SUBSCRIPTION,
(void *)dn, &szp, OCI_ATTR_SERVER_DNS, errhp);

/* then, get the number of server DNs in the descriptor */
(void) OCIAttrGet((void *) *dn, (ub4)OCI_DTYPE_SRVDN, (void *)&intval,
&szp, (ub4)OCI_ATTR_DN_COUNT, errhp);

/* allocate an array of char * to hold server DN pointers returned by
an Oracle database*/
if (intval)
{
arr = (char **)malloc(intval*sizeof(char *));
(void) OCIAttrGet((void *)*dn, (ub4)OCI_DTYPE_SRVDN, (void *)arr,
&intval, (ub4)OCI_ATTR_SERVER_DN, errhp);
}

/* OCISubscriptionRegister() calls have two modes: OCI_DEFAULT and
OCI_REG_LDAPONLY. If OCI_DEFAULT is used, there should be only one
server DN in the server DN descriptor. The registration request will
be sent to the database. If a database connection is not available,
the registration request will be detoured to the LDAP server. However,
if mode OCI_REG_LDAPONLY is used, the registration request
will be directly sent to LDAP. This mode should be used when there is
more than one server DN in the server DN descriptor or you are sure
that a database connection is not available.

In this example, two DNs are entered, so you should use mode
OCI_REG_LDAPONLY in LDAP registration. */
OCISubscriptionRegister(svchp, subhp, 1, errhp, OCI_REG_LDAPONLY);

...

/* as OCISubscriptionRegister(), OCISubscriptionUnregister() also has
mode OCI_DEFAULT and OCI_REG_LDAPONLY. The usage is the same. */

OCISubscriptionUnRegister(svchp, *subhp, errhp, OCI_REG_LDAPONLY);
}
...

10 OCIに関する高度なトピック

OCIを使用して、Oracle TimesTen In-Memory DatabaseおよびOracle TimesTen Application-Tier Database Cacheにアクセスできます。Times TenでのOracle Call Interfaceサポートの詳細は、Oracle TimesTen In-Memory Database C開発者およびリファレンス・ガイドを参照してください。

この章は、次の項目で構成されています。

- 連続問合せ通知

- データベースの起動と停止

- ROWIDの暗黙的フェッチ

- クライアント結果キャッシュ

- OCIでの障害診断

- 異なるバージョンのタイムゾーン・ファイルで操作するクライアントとサーバー

連続問合せ通知

連続問合せ通知を使用すると、クライアント・アプリケーションがデータベースに問合せを登録し、オブジェクトでのDMLまたはDDL変更に応じて、あるいは問合せに関連付けられた結果セット変更に応じて通知を受信できます。通知は、DMLまたはDDLトランザクションがコミットされるときにデータベースによってパブリッシュされます。

登録時に、アプリケーションは通知ハンドラを指定し、登録する一連の問合せを通知ハンドラに関連付けます。通知ハンドラは、サーバー側のPL/SQLプロシージャでも、クライアント側のC言語のコールバックでもかまいません。登録は、オブジェクト・レベルまたは問合せレベルで作成されます。登録がオブジェクト・レベルにある場合、トランザクションで登録済オブジェクトのいずれかが変更されてコミットされると常に、通知ハンドラが起動されます。登録が問合せレベルにある場合、トランザクションで問合せの結果セットが変わるような変更内容がコミットされると常に、通知ハンドラが起動されますが、変更内容が問合せの結果セットに影響しない場合、通知ハンドラは起動されません。

関連項目:
この機能の概念の詳細は、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』の「連続問合せ通知の使用」を参照してください。

連続問合せ通知の用途の1つは、データをキャッシュし、そのキャッシュをバックエンド・データベースのためにできるだけ最新の状態で維持する必要がある中間層アプリケーションでの使用です。

通知には次の情報が含まれます。

- 結果セットが変更された問合せの問合せID。これは、登録が問合せの細分化レベルにあった場合です。

- 変更されたオブジェクトの名前または変更された行。

- 操作タイプ(INSERT、UPDATE、DELETE、ALTER TABLE、DROP TABLE)。

- 変更された行のROWIDと関連するDML操作(INSERT、UPDATE、DELETE)。

- グローバル・データベース・イベント(STARTUP、SHUTDOWN)。Oracle Real Application Clusters (Oracle RAC)では、データベースは最初のインスタンスの起動時または最後のインスタンスの停止時に通知を送信します。

関連項目:
「OCIでのパブリッシュ・サブスクライブの通知」

問合せ結果セット通知の使用

連続問合せ(CQ)通知固有のQOS (サービス品質フラグ)を記録するには、サブスクリプション・ハンドルOCI_HTYPE_SUBSCRに属性OCI_ATTR_SUBSCR_CQ_QOSFLAGSを設定します。オブジェクトの細分化レベルではなく問合せの細分化レベルで登録するようにリクエストするには、属性OCI_ATTR_SUBSCR_CQ_QOSFLAGSにOCI_SUBSCR_CQ_QOS_QUERYフラグ・ビットを設定します。

オプションで擬似列CQ_NOTIFICATION_QUERY_IDを指定して、登録済問合せの問合せIDを取得できます。この場合、細分化レベルが自動的には問合せレベルに変換されないことに注意してください。戻り時の擬似列の値は、問合せに割り当てられた一意の問合せIDに設定されます。OCIベースの登録の場合は問合せIDの擬似列を省略できますが、その場合は問合せIDが文ハンドルのREAD属性として戻されます。(この属性はOCI_ATTR_CQ_QUERYIDです)。

通知中に、クライアントが指定したコールバックが起動され、トップレベルの通知記述子が引数として渡されます。

変更された問合せの問合せIDに関する情報は、OCI_DTYPE_CQDESという特別な記述型を使用して送られます。問合せ記述子の集合(OCIColl)は、トップレベルの通知記述子内に埋め込まれます。各記述子はOCI_DTYPE_CQDES型です。問合せ記述子の属性は、次のとおりです。

- OCI_ATTR_CQDES_OPERATION: OCI_EVENT_QUERYCHANGEまたはOCI_EVENT_DEREGです。

- OCI_ATTR_CQDES_QUERYID: 変更された問合せの問合せIDです。

- OCI_ATTR_CQDES_TABLE_CHANGES: 問合せ結果セットが変更される原因となった表に対するDML操作を記述する表記述子の配列です。各表記述子はOCI_DTYPE_TABLE_CHDES型です。

関連項目:
「OCI_DTYPE_CQDES」

連続問合せ通知の登録

コール側セッションには、登録対象のすべてのオブジェクトに対するCHANGE NOTIFICATIONシステム権限およびSELECT権限が必要です。登録はデータベースに記録される永続エンティティであり、Oracle RACのすべてのインスタンスに表示されます。登録が問合せ精度の場合、Oracle RACインスタンスで問合せ結果セットが変更され、コミットされる原因となるトランザクションによって通知が生成されます。登録がオブジェクト精度の場合、Oracle RACインスタンスに登録済のオブジェクトを変更するトランザクションによって通知が生成されます。

マテリアライズド・ビューまたは非マテリアライズド・ビューが関係する問合せは、サポートされません。

登録インタフェースでは、問合せ対象オブジェクトでの変更に対応するためのコールバックと、AQのネームスペース拡張(DBCHANGE)を使用します。

登録を作成する手順は、次のとおりです。

1. OCI_EVENTSおよびOCI_OBJECTモードで環境を作成します。

2. サブスクリプション・ハンドル属性OCI_ATTR_SUBSCR_NAMESPACEをネームスペースOCI_SUBSCR_NAMESPACE_DBCHANGEに設定します。

3. サブスクリプション・ハンドル属性OCI_ATTR_SUBSCR_CALLBACKを、問合せハンドルに関連したOCIコールバックを格納するように設定します。このコールバックには、次のプロトタイプがあります。

void notification_callback (void *ctx, OCISubscription *subscrhp,
void *payload, ub4 paylen, void *desc, ub4 mode);

パラメータの詳細は、「OCIでの通知コールバック」を参照してください。

4. 必要に応じて、OCI_ATTR_SUBSCR_CTX属性を使用してクライアント固有のコンテキストを関連付けます。

5. OCI_ATTR_SUBSCR_TIMEOUT属性を設定して、ub4タイムアウト間隔を秒単位で指定します。設定しない場合、タイムアウトはありません。

6. OCI_ATTR_SUBSCR_QOSFLAGS属性に次の値を使用して、QOS (サービス品質)レベルを設定します。

- OCI_SUBSCR_QOS_PURGE_ON_NTFNフラグは、最初の通知で登録が消去されるようにします。

- OCI_SUBSCR_QOS_RELIABLEフラグは、通知が存続するようにします。ノードに障害が発生した後でも、この登録関連の無効化されたメッセージがデータベースのキューに永続的に残っているために、残存しているOracle RACのインスタンスを使用して連続問合せ通知メッセージを送受信できます。FALSEである場合、無効化されたメッセージは高速メモリー内キューにエンキューされます。このオプションは、登録の永続性ではなく通知の永続性を指定するものです。デフォルトでは、登録は自動的に永続的になります。

7. OCISubscriptionRegister()をコールし、DBCHANGEネームスペースに新しい登録を作成します。

8. 複数の問合せ文をサブスクリプション・ハンドルに関連付けるには、文ハンドルOCI_HTYPE_STMTのOCI_ATTR_CHNF_REGHANDLE属性を設定します。問合せが実行されると、登録が完了します。

関連項目:
「OCI_ATTR_CHNF_REGHANDLE」

9. 状況に応じて、サブスクリプションの登録を解除します。クライアントは、パラメータとしてサブスクリプション・ハンドルを指定して、OCISubscriptionUnRegister()関数をコールできます。

サブスクリプション・ハンドルへの文ハンドルのバインドが有効なのは、問合せの初回の実行時のみです。アプリケーションで後続の実行時に同じOCI文ハンドルを使用する必要がある場合は、文ハンドルの登録ハンドル属性に値を再移入する必要があります。文ハンドルをサブスクリプション・ハンドルにバインドできるのは、文が問合せである場合のみです(実行時に判別されます)。実行の一部としてDML文が実行されると、例外が発行されます。

連続問合せ通知のサブスクリプション・ハンドル属性

連続問合せ通知のサブスクリプション・ハンドル属性は、汎用属性(すべてのサブスクリプションに対して共通)と、ネームスペース固有の属性(連続問合せ通知に特有)に分けられます。

文ハンドルのWRITE属性を変更できるのは、登録の作成前のみです。

汎用属性: すべてのサブスクリプションに対して共通

OCI_ATTR_SUBSCR_NAMESPACE (WRITE): サブスクリプション・ハンドルの場合、OCI_SUBSCR_NAMESPACE_DBCHANGEに設定します。

OCI_ATTR_SUBSCR_CALLBACK (WRITE): サブスクリプション・ハンドルに関連するコールバックを格納するために使用します。通知を受信すると、コールバックが実行されます。

新しい連続問合せ通知メッセージが作成されると、無効化に関する詳細情報が含まれるOCI_DTYPE_CHDES型の記述子がdescに設定されてコールバックがリスナー・スレッド内で呼び出されます。

OCI_ATTR_SUBSCR_QOSFLAGS: この属性は、次の値を設定する汎用フラグです。

#define OCI_SUBSCR_QOS_RELIABLE             0x01                 /* reliable */
#define OCI_SUBSCR_QOS_PURGE_ON_NTFN        0x10      /* purge on first ntfn */

- OCI_SUBSCR_QOS_RELIABLE: 通知が永続的になるように設定します。したがって、ノード障害が発生した後でも、この登録IDに関連づけられた無効化メッセージがデータベースのキューに永続的に残っているために、残存しているOracle RACクラスタのインスタンスを使用して、無効化メッセージを送受信できます。これがFALSEである場合、無効化メッセージは高速メモリー内キューにエンキューされます。このオプションは、登録の永続性ではなく通知の永続性を指定するものです。デフォルトでは、登録は自動的に永続的になります。

- OCI_SUBSCR_QOS_PURGE_ON_NTFN: 最初の通知で登録が消去されるように設定します。

パラレルの例は、「OCIでのパブリッシュ・サブスクライブの登録関数」を参照してください。

OCI_ATTR_SUBSCR_CQ_QOSFLAGS: この属性では、連続問合せ通知固有の次のQOSフラグを記述します(モードはWRITE、データ型はub4)。

- 0x1 OCI_SUBSCR_CQ_QOS_QUERY: 問合せレベルの細分性が必須であることを示すために設定します。通知は、問合せ結果セットが変更される場合にのみ生成されます。デフォルトでは、このQOSレベルにFalseの正数はありません。

- 0x2 OCI_SUBSCR_CQ_QOS_BEST_EFFORT: このフラグを設定し、ベスト・エフォート・フィルタリングが許容されることを示します。アプリケーションをキャッシュすることで使用できます。データベースでは、評価のコストに基づく経験則を使用し、完全プルーニングを回避できる場合があります。

OCI_ATTR_SUBSCR_TIMEOUT: この属性を使用して、秒単位で定義したub4タイムアウト値を指定します。タイムアウト値が0(ゼロ)または未指定の場合、登録は明示的に解除されるまで有効です。

ネームスペース固有または機能固有の属性

次の属性は、ネームスペース固有または連続問合せ通知機能固有のものです。

OCI_ATTR_CHNF_TABLENAMES (データ型は(OCIColl *)): 登録された表名のリストを取り出すための属性です。これらの属性は、問合せの実行後にサブスクリプション・ハンドルから使用できます。

OCI_ATTR_CHNF_ROWIDS: ブール型属性(デフォルトはFALSE)です。TRUEに設定すると、連続問合せ通知メッセージには、操作タイプやROWIDなどの行レベルの詳細が含まれます。

OCI_ATTR_CHNF_OPERATIONS: このub4フラグを使用して、操作タイプに基づいて通知を選択的にフィルタします。登録が問合せレベルの細分性を持つ場合、このオプションは無視されます。格納されているフラグは、次のとおりです。

- OCI_OPCODE_ALL－ すべての操作

- OCI_OPCODE_INSERT－ 表に対する挿入操作

- OCI_OPCODE_UPDATE－ 表に対する更新操作

- OCI_OPCODE_DELETE－ 表に対する削除操作

OCI_ATTR_CHNF_CHANGELAG: クライアントは、このub4値を使用して、遅延させるトランザクション数を指定します。クライアントは、このオプションを連続問合せ通知メッセージのスロットル・メカニズムとしても使用できます。このオプションを選択すると、OCI_ATTR_CHNF_ROWIDSがTRUEに設定されていても、通知にROWIDレベルの細分性を持つ情報が含まれなくなります。登録が問合せレベルの細分性を持つ場合、このオプションは無視されます。

OCISubscriptionRegister()コールが呼び出されると、すでに作成されている登録では、前述のいずれの属性(汎用、ネームスペース固有または機能固有)も変更できなくなります。これらの属性への変更は、すでに作成されている登録には反映されませんが、新しく作成された、同じ登録ハンドルを使用する登録には反映されます。

関連項目:
「連続問合せ通知属性」

NTFNグループ化オプションを使用して、通知の間隔を置くことができます。関連する汎用通知属性は次のとおりです。

OCI_ATTR_SUBSCR_NTFN_GROUPING_VALUE
OCI_ATTR_SUBSCR_NTFN_GROUPING_TYPE
OCI_ATTR_SUBSCR_NTFN_GROUPING_START_TIME
OCI_ATTR_SUBSCR_NTFN_GROUPING_REPEAT_COUNT

関連項目:
これらの属性の詳細は、「データベースへのパブリッシュ・サブスクライブの直接登録」を参照してください。

OCI_ATTR_CQ_QUERYID属性の使用

OCIStmtExecute()のコールによる登録後、文ハンドルOCI_HTYPE_STMTのOCI_ATTR_CQ_QUERYID属性が登録済問合せの問合せIDを取得します。

関連項目:
「OCI_ATTR_CQ_QUERYID」

連続問合せ通知の記述子

連続問合せ通知の記述子は、アプリケーションによって指定された通知コールバックのdescパラメータに渡されます。次の属性は、連続問合せ通知に固有のものです。連続問合せ通知の記述子のOCI型定数は、OCI_DTYPE_CHDESです。

通知コールバックは、トップレベルの通知記述子OCI_DTYPE_CHDESを引数として受け取ります。この記述子には、イベント・タイプがOCI_EVENT_QUERYCHANGEであるかOCI_EVENT_OBJCHANGEであるかに基づいて、OCI_DTYPE_CQDESまたはOCI_DTYPE_TABLE_CHDES記述子のコレクションが含まれます。OCI_EVENT_QUERYCHANGE型の通知の場合、連続問合せ記述子には表連続問合せ記述子の配列が埋め込まれます。ROWIDレベルの細分性を持つ情報がリクエストされた場合、各OCI_DTYPE_TABLE_CHDESには変更された各ROWIDに対応する行レベルの連続問合せ記述子(OCI_DTYPE_ROW_CHDES)の配列が含まれます。

OCI_DTYPE_CHDES

これはトップレベルの連続問合せ通知記述子型です。

OCI_ATTR_CHDES_DBNAME (oratext *): データベースの名前(連続問合せ通知のソース)

OCI_ATTR_CHDES_XID (RAW(8)): メッセージのメッセージID

OCI_ATTR_CHDES_NFYTYPE－ 通知タイプを示すフラグ

- 0x0 OCI_EVENT_NONE: 連続問合せ通知に関する追加情報なし

- 0x1 OCI_EVENT_STARTUP: インスタンスの起動

- 0x2 OCI_EVENT_SHUTDOWN: インスタンスの停止

- 0x3 OCI_EVENT_SHUTDOWN_ANY: 任意のインスタンスの停止: Oracle Real Application Clusters (RAC)

- 0x5 OCI_EVENT_DEREG: 登録解除またはタイムアウト

- 0x6 OCI_EVENT_OBJCHANGE: オブジェクト変更通知

- 0x7 OCI_EVENT_QUERYCHANGE: 問合せ変更通知

OCI_ATTR_CHDES_TABLE_CHANGES: データ型(OCIColl *)の表への操作を示すコレクション型。この属性が存在するのはOCI_ATTR_CHDES_NFTYPE属性がOCI_EVENT_OBJCHANGE型だった場合のみで、それ以外の場合はNULLになります。コレクションの各要素は、OCI_DTYPE_TABLE_CHDES型の連続問合せ記述子の表です。

OCI_ATTR_CHDES_QUERIES: 無効化された問合せを記述するコレクション型。コレクションの各メンバーはOCI_DTYPE_CQDES型です。この属性が存在するのはOCI_ATTR_CHDES_NFTYPE属性がOCI_EVENT_QUERYCHANGE型だった場合のみで、それ以外の場合はNULLになります。

OCI_DTYPE_CQDES

この通知記述子は、通常はDMLトランザクションまたはDDLトランザクションのコミットに応じて、無効化された問合せを記述します。属性は次のとおりです。

- OCI_ATTR_CQDES_OPERATION (ub4, READ): 問合せで発生した操作。これは次の値のいずれかです。

- OCI_EVENT_QUERYCHANGE: 問合せ結果セットの変更

- OCI_EVENT_DEREG: 問合せの登録解除

- OCI_ATTR_CQDES_TABLE_CHANGES (OCIColl *, READ): 問合せ結果セットの変更原因となった表に対するDMLまたはDDL操作を記述する、表連続問合せ記述子のコレクション。コレクションの各要素はOCI_DTYPE_TABLE_CHDES型です。

- OCI_ATTR_CQDES_QUERYID (ub8, READ): 無効化された問合せの問合せID。

OCI_DTYPE_TABLE_CHDES

この通知記述子は、登録済問合せに関係する表の変更内容に関する情報を送信します。属性は次のとおりです。

- OCI_ATTR_CHDES_TABLE_NAME (oratext *): スキーマ注釈付き表名。

- OCI_ATTR_CHDES_TABLE_OPFLAGS (ub4): 表への操作を示すフラグのフィールド。次の各フラグ・フィールドは、属性内の個別のビット位置にあります。

- 0x1 OCI_OPCODE_ALLROWS: 表は完全に無効化されています。

- 0x2 OCI_OPCODE_INSERT: 表に対する挿入操作。

- 0x4 OCI_OPCODE_UPDATE: 表に対する更新操作。

- 0x8 OCI_OPCODE_DELETE: 表に対する削除操作。

- 0x10 OCI_OPCODE_ALTER: 表は変更されました(スキーマ変更)。これには、行の移行を引き起こしたDDL文と内部操作が含まれます。

- 0x20 OCI_OPCODE_DROP: 表は削除されました。

- OCI_ATTR_CHDES_TABLE_ROW_CHANGES: これは、表内の行の変更を示す埋込みコレクションです。コレクションの各要素は、次の属性を持つOCI_DTYPE_ROW_CHDES型の行連続問合せ記述子です。

- OCI_ATTR_CHDES_ROW_ROWID (OraText *): ROWIDの文字列表現。

- OCI_ATTR_CHDES_ROW_OPFLAGS: 操作タイプ(INSERT、UPDATE、DELETEまたはOTHER)を反映します。

関連項目:
「連続問合せ通知の記述子の属性」

連続問合せ通知の例

例10-1は、単純なOCIプログラム、demoquery.cです。リストにあるコメントを参照してください。コール側セッションには、登録対象のすべてのオブジェクトに対するCHANGE NOTIFICATIONシステム権限およびSELECT権限が必要です。

例10-1 連続問合せ通知を説明するプログラムのリスト

/* Copyright (c) 2010, Oracle. All rights reserved.  */

#ifndef S_ORACLE
# include <oratypes.h>
#endif

/**************************************************************************
*This is a DEMO program. To test, compile the file to generate the executable
*demoquery. Then demoquery can be invoked from a command prompt.
*It will have the following output:

Initializing OCI Process
Registering query : select last_name, employees.department_id, department_name
from employees, departments
where employee_id = 200
and employees.department_id = departments.department_id
Query Id 23
Waiting for Notifications

*Then from another session, log in as HR/HR and perform the following
* DML transactions. It will cause two notifications to be generated.

update departments set department_name ='Global Admin' where department_id=10;
commit;
update departments set department_name ='Adminstration' where department_id=10;
commit;

*The demoquery program will now show the following output corresponding
*to the notifications received.

Query 23 is changed
Table changed is HR.DEPARTMENTS table_op 4
Row changed is AAAMBoAABAAAKX2AAA row_op 4
Query 23 is changed
Table changed is HR.DEPARTMENTS table_op 4
Row changed is AAAMBoAABAAAKX2AAA row_op 4

*The demo program waits for exactly 10 notifications to be received before
*logging off and unregistering the subscription.

***************************************************************************/

/*---------------------------------------------------------------------------
PRIVATE TYPES AND CONSTANTS
---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------
STATIC FUNCTION DECLARATIONS
---------------------------------------------------------------------------*/

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <oci.h>

#define MAXSTRLENGTH 1024
#define bit(a,b) ((a)&(b))

static int notifications_processed = 0;
static OCISubscription *subhandle1 = (OCISubscription *)0;
static OCISubscription *subhandle2 = (OCISubscription *)0;
static void checker(/*_ OCIError *errhp, sword status _*/);
static void registerQuery(/*_ OCISvcCtx *svchp, OCIError *errhp, OCIStmt *stmthp,
OCIEnv *envhp _*/);
static void myCallback (/*_  dvoid *ctx, OCISubscription *subscrhp,
dvoid *payload, ub4 *payl, dvoid *descriptor,
ub4 mode _*/);
static int NotificationDriver(/*_ int argc, char *argv[]  _*/);
static sword status;
static boolean logged_on = FALSE;
static void processRowChanges(OCIEnv *envhp, OCIError *errhp, OCIStmt *stmthp,
OCIColl *row_changes);
static void processTableChanges(OCIEnv *envhp, OCIError *errhp,
OCIStmt *stmthp, OCIColl *table_changes);
static void processQueryChanges(OCIEnv *envhp, OCIError *errhp, OCIStmt *stmthp,
OCIColl *query_changes);
static int nonractests2(/*_ int argc, char *argv[] _*/);

int main(int argc, char **argv)
{

NotificationDriver(argc, argv);
return 0;
}

int NotificationDriver(argc, argv)
int argc;
char *argv[];
{
OCIEnv *envhp;
OCISvcCtx *svchp, *svchp2;
OCIError *errhp, *errhp2;
OCISession *authp, *authp2;
OCIStmt *stmthp, *stmthp2;
OCIDuration dur, dur2;
int i;
dvoid *tmp;
OCISession *usrhp;
OCIServer *srvhp;

printf("Initializing OCI Process\n");
/* Initialize the environment. The environment must be initialized
with OCI_EVENTS and OCI_OBJECT to create a continuous query notification
registration and receive notifications.
*/
OCIEnvCreate( (OCIEnv **) &envhp, OCI_EVENTS|OCI_OBJECT, (dvoid *)0,
(dvoid * (*)(dvoid *, size_t)) 0,
(dvoid * (*)(dvoid *, dvoid *, size_t))0,
(void (*)(dvoid *, dvoid *)) 0,
(size_t) 0, (dvoid **) 0 );

OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, OCI_HTYPE_ERROR,
(size_t) 0, (dvoid **) 0);
/* server contexts */
OCIHandleAlloc((dvoid *) envhp, (dvoid **) &srvhp, OCI_HTYPE_SERVER,
(size_t) 0, (dvoid **) 0);
OCIHandleAlloc((dvoid *) envhp, (dvoid **) &svchp, OCI_HTYPE_SVCCTX,
(size_t) 0, (dvoid **) 0);
checker(errhp,OCIServerAttach(srvhp, errhp, (text *) 0, (sb4) 0,
(ub4) OCI_DEFAULT));
/* set attribute server context in the service context */
OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *)srvhp,
(ub4) 0, (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);

/* allocate a user context handle */
OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp, (ub4) OCI_HTYPE_SESSION,
(size_t) 0, (dvoid **) 0);

OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION,
(dvoid *)((text *)"HR"), (ub4)strlen((char *)"HR"),
OCI_ATTR_USERNAME, errhp);

OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION,
(dvoid *)((text *)"HR"), (ub4)strlen((char *)"HR"),
OCI_ATTR_PASSWORD, errhp);
checker(errhp,OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_DEFAULT));
/* Allocate a statement handle */
OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &stmthp,
(ub4) OCI_HTYPE_STMT, 52, (dvoid **) &tmp);

OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX, (dvoid *)usrhp, (ub4)0,
OCI_ATTR_SESSION, errhp);

registerQuery(svchp, errhp, stmthp, envhp);
printf("Waiting for Notifications\n");
while (notifications_processed !=10)
{
sleep(1);
}
printf ("Going to unregister HR\n");
fflush(stdout);
/* Unregister HR */
checker(errhp,
OCISubscriptionUnRegister(svchp, subhandle1, errhp, OCI_DEFAULT));
checker(errhp, OCISessionEnd(svchp, errhp, usrhp, (ub4) 0));
printf("HR Logged off.\n");

if (subhandle1)
OCIHandleFree((dvoid *)subhandle1, OCI_HTYPE_SUBSCRIPTION);
if (stmthp)
OCIHandleFree((dvoid *)stmthp, OCI_HTYPE_STMT);
if (srvhp)
OCIHandleFree((dvoid *) srvhp, (ub4) OCI_HTYPE_SERVER);
if (svchp)
OCIHandleFree((dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX);
if (authp)
OCIHandleFree((dvoid *) usrhp, (ub4) OCI_HTYPE_SESSION);
if (errhp)
OCIHandleFree((dvoid *) errhp, (ub4) OCI_HTYPE_ERROR);
if (envhp)
OCIHandleFree((dvoid *) envhp, (ub4) OCI_HTYPE_ENV);

return 0;

}

void checker(errhp, status)
OCIError *errhp;
sword status;
{
text errbuf[512];
sb4 errcode = 0;
int retval = 1;

switch (status)
{
case OCI_SUCCESS:
retval = 0;
break;
case OCI_SUCCESS_WITH_INFO:
(void) printf("Error - OCI_SUCCESS_WITH_INFO\n");
break;
case OCI_NEED_DATA:
(void) printf("Error - OCI_NEED_DATA\n");
break;
case OCI_NO_DATA:
(void) printf("Error - OCI_NODATA\n");
break;
case OCI_ERROR:
(void) OCIErrorGet((dvoid *)errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), OCI_HTYPE_ERROR);
(void) printf("Error - %.*s\n", 512, errbuf);
break;
case OCI_INVALID_HANDLE:
(void) printf("Error - OCI_INVALID_HANDLE\n");
break;
case OCI_STILL_EXECUTING:
(void) printf("Error - OCI_STILL_EXECUTE\n");
break;
case OCI_CONTINUE:
(void) printf("Error - OCI_CONTINUE\n");
break;
default:
break;
}
if (retval)
{
exit(1);
}
}

void processRowChanges(OCIEnv *envhp, OCIError *errhp, OCIStmt *stmthp,
OCIColl *row_changes)
{
dvoid **row_descp;
dvoid *row_desc;
boolean exist;
ub2 i, j;
dvoid *elemind = (dvoid *)0;
oratext *row_id;
ub4 row_op;

sb4 num_rows;
if (!row_changes) return;
checker(errhp, OCICollSize(envhp, errhp,
(CONST OCIColl *) row_changes, &num_rows));
for (i=0; i<num_rows; i++)
{
checker(errhp, OCICollGetElem(envhp,
errhp, (OCIColl *) row_changes,
i, &exist, &row_descp, &elemind));

row_desc = *row_descp;
checker(errhp, OCIAttrGet (row_desc,
OCI_DTYPE_ROW_CHDES, (dvoid *)&row_id,
NULL, OCI_ATTR_CHDES_ROW_ROWID, errhp));
checker(errhp, OCIAttrGet (row_desc,
OCI_DTYPE_ROW_CHDES, (dvoid *)&row_op,
NULL, OCI_ATTR_CHDES_ROW_OPFLAGS, errhp));

printf ("Row changed is %s row_op %d\n", row_id, row_op);
fflush(stdout);
}
}

void processTableChanges(OCIEnv *envhp, OCIError *errhp, OCIStmt *stmthp,
OCIColl *table_changes)
{
dvoid **table_descp;
dvoid *table_desc;
dvoid **row_descp;
dvoid *row_desc;
OCIColl *row_changes = (OCIColl *)0;
boolean exist;
ub2 i, j;
dvoid *elemind = (dvoid *)0;
oratext *table_name;
ub4 table_op;

sb4 num_tables;
if (!table_changes) return;
checker(errhp, OCICollSize(envhp, errhp,
(CONST OCIColl *) table_changes, &num_tables));
for (i=0; i<num_tables; i++)
{
checker(errhp, OCICollGetElem(envhp,
errhp, (OCIColl *) table_changes,
i, &exist, &table_descp, &elemind));

table_desc = *table_descp;
checker(errhp, OCIAttrGet (table_desc,
OCI_DTYPE_TABLE_CHDES, (dvoid *)&table_name,
NULL, OCI_ATTR_CHDES_TABLE_NAME, errhp));
checker(errhp, OCIAttrGet (table_desc,
OCI_DTYPE_TABLE_CHDES, (dvoid *)&table_op,
NULL, OCI_ATTR_CHDES_TABLE_OPFLAGS, errhp));
checker(errhp, OCIAttrGet (table_desc,
OCI_DTYPE_TABLE_CHDES, (dvoid *)&row_changes,
NULL, OCI_ATTR_CHDES_TABLE_ROW_CHANGES, errhp));

printf ("Table changed is %s table_op %d\n", table_name,table_op);
fflush(stdout);
if (!bit(table_op, OCI_OPCODE_ALLROWS))
processRowChanges(envhp, errhp, stmthp, row_changes);
}
}

void processQueryChanges(OCIEnv *envhp, OCIError *errhp, OCIStmt *stmthp,
OCIColl *query_changes)
{
sb4 num_queries;
ub8 queryid;
OCINumber qidnum;
ub4 queryop;
dvoid *elemind = (dvoid *)0;
dvoid *query_desc;
dvoid **query_descp;
ub2 i;
boolean exist;
OCIColl *table_changes = (OCIColl *)0;

if (!query_changes) return;
checker(errhp, OCICollSize(envhp, errhp,
(CONST OCIColl *) query_changes, &num_queries));
for (i=0; i < num_queries; i++)
{
checker(errhp, OCICollGetElem(envhp,
errhp, (OCIColl *) query_changes,
i, &exist, &query_descp, &elemind));

query_desc = *query_descp;
checker(errhp, OCIAttrGet (query_desc,
OCI_DTYPE_CQDES, (dvoid *)&queryid,
NULL, OCI_ATTR_CQDES_QUERYID, errhp));
checker(errhp, OCIAttrGet (query_desc,
OCI_DTYPE_CQDES, (dvoid *)&queryop,
NULL, OCI_ATTR_CQDES_OPERATION, errhp));
printf(" Query %d is changed\n", queryid);
if (queryop == OCI_EVENT_DEREG)
printf("Query Deregistered\n");
checker(errhp, OCIAttrGet (query_desc,
OCI_DTYPE_CQDES, (dvoid *)&table_changes,
NULL, OCI_ATTR_CQDES_TABLE_CHANGES, errhp));
processTableChanges(envhp, errhp, stmthp, table_changes);

}
}

void myCallback (ctx, subscrhp, payload, payl, descriptor, mode)
dvoid *ctx;
OCISubscription *subscrhp;
dvoid *payload;
ub4 *payl;
dvoid *descriptor;
ub4 mode;
{
OCIColl *table_changes = (OCIColl *)0;
OCIColl *row_changes = (OCIColl *)0;
dvoid *change_descriptor = descriptor;
ub4 notify_type;
ub2 i, j;
OCIEnv *envhp;
OCIError *errhp;
OCIColl *query_changes = (OCIColl *)0;
OCIServer *srvhp;
OCISvcCtx *svchp;
OCISession *usrhp;
dvoid     *tmp;
OCIStmt *stmthp;

(void)OCIEnvInit( (OCIEnv **) &envhp, OCI_DEFAULT, (size_t)0, (dvoid **)0 );

(void) OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, OCI_HTYPE_ERROR,
(size_t) 0, (dvoid **) 0);
/* server contexts */
(void) OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, OCI_HTYPE_SERVER,
(size_t) 0, (dvoid **) 0);

(void) OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, OCI_HTYPE_SVCCTX,
(size_t) 0, (dvoid **) 0);

OCIAttrGet (change_descriptor, OCI_DTYPE_CHDES, (dvoid *) &notify_type,
NULL, OCI_ATTR_CHDES_NFYTYPE, errhp);
fflush(stdout);
if (notify_type == OCI_EVENT_SHUTDOWN ||
notify_type == OCI_EVENT_SHUTDOWN_ANY)
{
printf("SHUTDOWN NOTIFICATION RECEIVED\n");
fflush(stdout);
notifications_processed++;
return;
}
if (notify_type == OCI_EVENT_STARTUP)
{
printf("STARTUP NOTIFICATION RECEIVED\n");
fflush(stdout);
notifications_processed++;
return;
}

notifications_processed++;
checker(errhp, OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0,
(ub4) OCI_DEFAULT));

OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
52, (dvoid **) &tmp);
/* set attribute server context in the service context */
OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *)srvhp,
(ub4) 0, (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);

/* allocate a user context handle */
OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp, (ub4) OCI_HTYPE_SESSION,
(size_t) 0, (dvoid **) 0);

OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION,
(dvoid *)"HR", (ub4)strlen("HR"), OCI_ATTR_USERNAME, errhp);

OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION,
(dvoid *)"HR", (ub4)strlen("HR"),
OCI_ATTR_PASSWORD, errhp);

checker(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_DEFAULT));

OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX,
(dvoid *)usrhp, (ub4)0, OCI_ATTR_SESSION, errhp);

/* Allocate a statement handle */
OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &stmthp,
(ub4) OCI_HTYPE_STMT, 52, (dvoid **) &tmp);

if (notify_type == OCI_EVENT_OBJCHANGE)
{
checker(errhp, OCIAttrGet (change_descriptor,
OCI_DTYPE_CHDES, &table_changes, NULL,
OCI_ATTR_CHDES_TABLE_CHANGES, errhp));
processTableChanges(envhp, errhp, stmthp, table_changes);
}
else if (notify_type == OCI_EVENT_QUERYCHANGE)
{
checker(errhp, OCIAttrGet (change_descriptor,
OCI_DTYPE_CHDES, &query_changes, NULL,
OCI_ATTR_CHDES_QUERIES, errhp));
processQueryChanges(envhp, errhp, stmthp, query_changes);
}
checker(errhp, OCISessionEnd(svchp, errhp, usrhp, OCI_DEFAULT));
checker(errhp, OCIServerDetach(srvhp, errhp, OCI_DEFAULT));
if (stmthp)
OCIHandleFree((dvoid *)stmthp, OCI_HTYPE_STMT);
if (errhp)
OCIHandleFree((dvoid *)errhp, OCI_HTYPE_ERROR);
if (srvhp)
OCIHandleFree((dvoid *)srvhp, OCI_HTYPE_SERVER);
if (svchp)
OCIHandleFree((dvoid *)svchp, OCI_HTYPE_SVCCTX);
if (usrhp)
OCIHandleFree((dvoid *)usrhp, OCI_HTYPE_SESSION);
if (envhp)
OCIHandleFree((dvoid *)envhp, OCI_HTYPE_ENV);

}

void registerQuery(svchp, errhp, stmthp, envhp)
OCISvcCtx *svchp;
OCIError *errhp;
OCIStmt *stmthp;
OCIEnv *envhp;
{
OCISubscription *subscrhp;
ub4 namespace = OCI_SUBSCR_NAMESPACE_DBCHANGE;
ub4 timeout = 60;
OCIDefine *defnp1 = (OCIDefine *)0;
OCIDefine *defnp2 = (OCIDefine *)0;
OCIDefine *defnp3 = (OCIDefine *)0;
OCIDefine *defnp4 = (OCIDefine *)0;
OCIDefine *defnp5 = (OCIDefine *)0;
int mgr_id =0;
text query_text1[] = "select last_name, employees.department_id, department_name \
from employees,departments where employee_id = 200 and employees.department_id =\
departments.department_id";

ub4 num_prefetch_rows = 0;
ub4 num_reg_tables;
OCIColl *table_names;
ub2 i;
boolean rowids = TRUE;
ub4 qosflags = OCI_SUBSCR_CQ_QOS_QUERY  ;
int empno=0;
OCINumber qidnum;
ub8 qid;
char outstr[MAXSTRLENGTH], dname[MAXSTRLENGTH];
int q3out;

fflush(stdout);
/* allocate subscription handle */
OCIHandleAlloc ((dvoid *) envhp, (dvoid **) &subscrhp,
OCI_HTYPE_SUBSCRIPTION, (size_t) 0, (dvoid **) 0);

/* set the namespace to DBCHANGE */
checker(errhp, OCIAttrSet (subscrhp, OCI_HTYPE_SUBSCRIPTION,
(dvoid *) &namespace, sizeof(ub4),
OCI_ATTR_SUBSCR_NAMESPACE, errhp));

/* Associate a notification callback with the subscription */
checker(errhp, OCIAttrSet (subscrhp, OCI_HTYPE_SUBSCRIPTION,
(void *)myCallback, 0, OCI_ATTR_SUBSCR_CALLBACK, errhp));
/* Allow extraction of rowid information */
checker(errhp, OCIAttrSet (subscrhp, OCI_HTYPE_SUBSCRIPTION,
(dvoid *)&rowids, sizeof(ub4),
OCI_ATTR_CHNF_ROWIDS, errhp));

checker(errhp, OCIAttrSet (subscrhp, OCI_HTYPE_SUBSCRIPTION,
(dvoid *)&qosflags, sizeof(ub4),
OCI_ATTR_SUBSCR_CQ_QOSFLAGS, errhp));

/* Create a new registration in the DBCHANGE namespace */
checker(errhp,
OCISubscriptionRegister(svchp, &subscrhp, 1, errhp, OCI_DEFAULT));

/* Multiple queries can now be associated with the subscription */

subhandle1 = subscrhp;

printf("Registering query : %s\n", (const signed char *)query_text1);
/* Prepare the statement */
checker(errhp, OCIStmtPrepare (stmthp, errhp, query_text1,
(ub4)strlen((const signed char *)query_text1), OCI_V7_SYNTAX,
OCI_DEFAULT));

checker(errhp,
OCIDefineByPos(stmthp, &defnp1,
errhp, 1, (dvoid *)outstr, MAXSTRLENGTH * sizeof(char),
SQLT_STR, (dvoid *)0, (ub2 *)0, (ub2 *)0, OCI_DEFAULT));
checker(errhp,
OCIDefineByPos(stmthp, &defnp2,
errhp, 2, (dvoid *)&empno, sizeof(empno),
SQLT_INT, (dvoid *)0, (ub2 *)0, (ub2 *)0, OCI_DEFAULT));
checker(errhp,
OCIDefineByPos(stmthp, &defnp3,
errhp, 3, (dvoid *)&dname, sizeof(dname),
SQLT_STR, (dvoid *)0, (ub2 *)0, (ub2 *)0, OCI_DEFAULT));

/* Associate the statement with the subscription handle */
OCIAttrSet (stmthp, OCI_HTYPE_STMT, subscrhp, 0,
OCI_ATTR_CHNF_REGHANDLE, errhp);

/* Execute the statement, the execution performs object registration */
checker(errhp, OCIStmtExecute (svchp, stmthp, errhp, (ub4) 1, (ub4) 0,
(CONST OCISnapshot *) NULL, (OCISnapshot *) NULL ,
OCI_DEFAULT));
fflush(stdout);

OCIAttrGet(stmthp, OCI_HTYPE_STMT, &qid, (ub4 *)0,
OCI_ATTR_CQ_QUERYID, errhp);
printf("Query Id %d\n", qid);

/* commit */
checker(errhp, OCITransCommit(svchp, errhp, (ub4) 0));

}

static void cleanup(envhp, svchp, srvhp, errhp, usrhp)
OCIEnv *envhp;
OCISvcCtx *svchp;
OCIServer *srvhp;
OCIError *errhp;
OCISession *usrhp;
{
/* detach from the server */
checker(errhp, OCISessionEnd(svchp, errhp, usrhp, OCI_DEFAULT));
checker(errhp, OCIServerDetach(srvhp, errhp, (ub4)OCI_DEFAULT));

if (usrhp)
(void) OCIHandleFree((dvoid *) usrhp, (ub4) OCI_HTYPE_SESSION);
if (svchp)
(void) OCIHandleFree((dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX);
if (srvhp)
(void) OCIHandleFree((dvoid *) srvhp, (ub4) OCI_HTYPE_SERVER);
if (errhp)
(void) OCIHandleFree((dvoid *) errhp, (ub4) OCI_HTYPE_ERROR);
if (envhp)
(void) OCIHandleFree((dvoid *) envhp, (ub4) OCI_HTYPE_ENV);

}

データベースの起動と停止

OCI関数OCIDBStartup()およびOCIDBShutdown()には、Oracle Databaseを起動および停止するために最小限必要なインタフェースが用意されています。C言語のプログラムから、OCIDBStartup()をコールする前に、サーバーに接続し、事前認証モードでSYSDBAまたはSYSOPERセッションを開始する必要があります。インスタンスが起動していない場合はこのモードのみを使用でき、インスタンスを起動するためにのみ使用されます。OCIDBStartup()をコールすると、データベースをマウントまたはオープンせずに1つのサーバー・インスタンスが起動します。データベースをマウントまたはオープンするには、事前認証セッションを終了し、通常のSYSDBAまたはSYSOPERセッションを開始し、適切なALTER DATABASE文を実行します。

データベースを停止するには、アクティブなSYSDBAまたはSYSOPERセッションが必要です。OCI_DBSHUTDOWN_ABORT以外のすべてのモードにおいて、OCIDBShutdown()に2つのコールを実行します。1つめのコールは、データベースへのこれ以上の接続を禁止することにより停止を開始し、次に適切なALTER DATABASEコマンドによりデータベースをディスマウントして閉じるためのもので、もう1つのコールは、インスタンスを停止することにより停止を終了させるためのものです。特別な環境においては、データベースをできるかぎり迅速に停止させるために、OCIDBShutdown()をOCI_DBSHUTDOWN_ABORTモードでコールしますが、これはSQL*PlusでのSHUTDOWN ABORTに相当します。

これらの関数は両方とも、サーバーに対する専用接続を必要とします。ディスパッチャを介して共有サーバーに接続されている場合、データベースを起動または停止しようとすると、ORA-106が発生します。

OCIAdmin管理ハンドルCデータ型を使用して、インタフェースを拡張可能にします。OCIAdminは、ハンドル・タイプOCI_HTYPE_ADMINに関連付けられています。OCIAdminパラメータadmhpに値を渡すかどうかは、OCIDBStartup()ではオプションで選択できますが、OCIDBShutdown()では不要です。

関連項目:

- 「OCIDBStartup()」

- 「OCIDBShutdown()」

- 「管理ハンドル属性」

- 『Oracle Database管理者ガイド』

OCIでの起動と停止の例

起動するには、SYSOPERまたはSYSDBAとしてOCI_PRELIM_AUTHモードでデータベースに接続する必要があります。ディスパッチャを介して共有サーバーには接続できません。クライアント側のパラメータ・ファイル(pfile)を使用するには、OCIAttrSet()を使用して管理ハンドルで属性OCI_ATTR_ADMIN_PFILEを設定する必要があります。設定しない場合、サーバー側のパラメータ・ファイル(spfile)が使用されます。後者の場合は、(OCIAdmin *)0を渡します。OCIDBStartup()のコールにより、サーバー上で1つのインスタンスが起動します。

例10-2では、管理ハンドルで設定され、データベース起動操作を実行する、クライアント側のパラメータ・ファイル(pfile)を使用するサンプル・コードを示しています。

例10-2 データベースの起動操作を実行するOCIDBStartup()のコール

...

/*  Example 0 - Startup:  */
OCIAdmin *admhp;
text *mount_stmt = (text *)"ALTER DATABASE MOUNT";
text *open_stmt = (text *)"ALTER DATABASE OPEN";
text *pfile = (text *)"/ade/viewname/oracle/work/t_init1.ora";

/* Start the authentication session */
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp,
OCI_CRED_RDBMS, OCI_SYSDBA|OCI_PRELIM_AUTH));

/* Allocate admin handle for OCIDBStartup */
checkerr(errhp, OCIHandleAlloc((void *) envhp, (void **) &admhp,
(ub4) OCI_HTYPE_ADMIN, (size_t) 0, (void **) 0));

/* Set attribute pfile in the admin handle
(do not do this if you want to use the spfile) */
checkerr (errhp, OCIAttrSet( (void *) admhp, (ub4) OCI_HTYPE_ADMIN,
(void *) pfile, (ub4) strlen(pfile),
(ub4) OCI_ATTR_ADMIN_PFILE, (OCIError *) errhp));

/* Start up in NOMOUNT mode */
checkerr(errhp, OCIDBStartup(svchp, errhp, admhp, OCI_DEFAULT, 0));
checkerr(errhp, OCIHandleFree((void *) admhp, (ub4) OCI_HTYPE_ADMIN));

/* End the authentication session */
OCISessionEnd(svchp, errhp, usrhp, (ub4)OCI_DEFAULT);

/* Start the sysdba session */
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_SYSDBA));

/* Mount the database */
checkerr(errhp, OCIStmtPrepare2(svchp, &stmthp, errhp, mount_stmt, (ub4)
strlen((char*) mount_stmt),
(CONST OraText *) 0, (ub4) 0, (ub4) OCI_NTV_SYNTAX, (ub4)
OCI_DEFAULT));
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4)0,
(OCISnapshot *) NULL, (OCISnapshot *) NULL, OCI_DEFAULT));
checkerr(errhp, OCIStmtRelease(stmthp, errhp, (OraText *)0, 0, OCI_DEFAULT));

/* Open the database */
checkerr(errhp, OCIStmtPrepare2(svchp, &stmthp, errhp, open_stmt, (ub4)
strlen((char*) open_stmt),
(CONST OraText *)0, (ub4)0, (ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4)0,
(OCISnapshot *) NULL, (OCISnapshot *) NULL, OCI_DEFAULT));
checkerr(errhp, OCIStmtRelease(stmthp, errhp, (OraText *)0, 0, OCI_DEFAULT));

/* End the sysdba session */
OCISessionEnd(svchp, errhp, usrhp, (ub4)OCI_DEFAULT);
...

停止するには、SYSOPERまたはSYSDBAとしてデータベースに接続する必要があります。ディスパッチャを介して共有サーバーには接続できません。OCI_DBSHUTDOWN_ABORT以外のモードで停止する場合、次の手順を使用します。

1. OCIDBShutdown()をOCI_DEFAULT、OCI_DBSHUTDOWN_TRANSACTIONAL、OCI_DBSHUTDOWN_TRANSACTIONAL_LOCALまたはOCI_DBSHUTDOWN_IMMEDIATEモードでコールし、これ以上の接続を禁止します。

2. 必要なALTER DATABASEコマンドを使用し、データベースをクローズしてディスマウントします。

3. OCIDBShutdown()をOCI_DBSHUTDOWN_FINALモードでコールし、インスタンスを停止します。

例10-3では、データベースの順序正しい停止操作を実行する管理ハンドルで設定される、クライアント側のパラメータ・ファイル(pfile)を使用するサンプル・コードを示しています。

例10-3 OCI_DBSHUTDOWN_FINALモードでのOCIDBShutdown()のコール

/*  Example 1 - Orderly shutdown:  */
...
text *close_stmt = (text *)"ALTER DATABASE CLOSE NORMAL";
text *dismount_stmt = (text *)"ALTER DATABASE DISMOUNT";

/* Start the sysdba session */
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_SYSDBA));

/* Shutdown in the default mode (transactional, transactional-local,
immediate would be fine too) */
checkerr(errhp, OCIDBShutdown(svchp, errhp, (OCIAdmin *)0, OCI_DEFAULT));

/* Close the database */
checkerr(errhp, OCIStmtPrepare2(svchp, &stmthp, errhp, close_stmt, (ub4)
strlen((char*) close_stmt),
(CONST OraText *)0, (ub4)0, (ub4) OCI_NTV_SYNTAX,
(ub4) OCI_DEFAULT));
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4)0,
(OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT));
checkerr(errhp, OCIStmtRelease(stmthp, errhp, (OraText *)0, 0, OCI_DEFAULT));

/* Dismount the database */
checkerr(errhp, OCIStmtPrepare2(svchp, &stmthp, errhp, dismount_stmt,
(ub4) strlen((char*) dismount_stmt), (CONST OraText *)0, (ub4)0,
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4)0,
(OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT));
checkerr(errhp, OCIStmtRelease(stmthp, errhp, (OraText *)0, 0, OCI_DEFAULT));

/* Final shutdown */
checkerr(errhp, OCIDBShutdown(svchp, errhp, (OCIAdmin *)0,
OCI_DBSHUTDOWN_FINAL));

/* End the sysdba session */
checkerr(errhp, OCISessionEnd(svchp, errhp, usrhp, (ub4)OCI_DEFAULT));
...

例10-4では、OCI_DBSHUTDOWN_ABORTモードを使用する停止の例を示しています。

例10-4 OCI_DBSHUTDOWN_ABORTモードでのOCIDBShutdown()のコール

/*  Example 2 - Shutdown using abort:  */
...
/* Start the sysdba session */
...
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_SYSDBA));

/* Shutdown in the abort mode */
checkerr(errhp, OCIDBShutdown(svchp, errhp, (OCIAdmin *)0,
OCI_DBSHUTDOWN_ABORT));

/* End the sysdba session */
checkerr(errhp, OCISessionEnd(svchp, errhp, usrhp, (ub4)OCI_DEFAULT));
...

ROWIDの暗黙的フェッチ

ROWIDは、データベース内の行のグローバル一意識別子です。ROWIDは行が表に挿入されるときに作成され、行が削除されると破棄されます。ROWID値には、重要な用途がいくつかあります。これは、表の各行の一意識別子です。また、1行にアクセスする場合に最も高速な手段であり、表の行の格納方法を示すことができます。

SELECT ... FOR UPDATE文におけるROWIDの暗黙的フェッチとは、ROWIDがselect文で名前付きの列のいずれかではない場合でも、クライアント側で取得されるということです。OCIDefineByPos()のpositionパラメータは0 (ゼロ)に設定されます。ROWID疑似列値を取得する場合、次のホスト変数を指定できます。

- SQLT_CHR(VARCHAR2)

- SQLT_VCS(VARCHAR)

- SQLT_STR (NULL文字で終了する文字列)

- SQLT_LVC(LONG VARCHAR)

- SQLT_AFC(CHAR)

- SQLT_AVC(CHARZ)

- SQLT_VST (OCI文字列)

- SQLT_RDD (ROWID記述子)

SELECT ... FOR UPDATE文では、更新対象の行を識別し、結果セットの各行をロックします。これは、1行の既存の値に基づいて更新する必要がある場合に役立ちます。その場合は、別のユーザーにより行が変更されないことを確認する必要があります。

ROWIDの値を格納する文字バッファの指定時(SQLT_STR形式で取得する場合など)には、ROWIDを格納するのに十分なメモリーを割り当てます。ROWIDデータ型とUROWIDデータ型の違いを覚えておいてください。ROWIDデータ型に格納できるのは物理ROWIDのみですが、UROWID型には論理ROWID(索引構成表の行の識別子)も格納できます。ROWID型の最長内部長は10バイトですが、UROWIDデータ型の場合は3950バイトです。

動的定義は、OCI_DYNAMIC_FETCHとして設定されたmodeによるOCIDefineByPos()のコールと等価です。動的定義を使用すると、特定の定義ハンドルの属性を追加設定できます。実行時に起動され、取得されるフェッチ済データまたはそのピースを格納するバッファへのポインタを取得する、コールバック関数を指定します。

ROWIDの暗黙的フェッチを使用する前に、文ハンドルで属性OCI_ATTR_FETCH_ROWIDを次のように設定する必要があります。

OCIAttrSet(stmthp, OCI_HTYPE_STMT, 0, 0 , OCI_ATTR_FETCH_ROWID, errhp);

動的定義は、ROWIDの暗黙的フェッチとは互換性がありません。通常のシナリオの場合、このモードのアプリケーションでは1つの列の各行にバッファを提供できます。つまり、1つの列値がフェッチされるたびにコールバックが呼び出されます。

位置0 (ゼロ)についてOCIDefineByPos()を使用するこの機能は、データ配列を一度にユーザー・バッファにフェッチし、その各ROWIDを同時に取得することが目的です。この機能では、ROWIDがSELECTを使用した問合せの列のいずれかではなくても、SELECT....FOR UPDATE文によりROWIDのフェッチが可能です。データを1つずつユーザー・バッファにフェッチする場合は、既存のOCI_ATTR_ROWID属性を使用できます。

この機能を使用してROWIDをフェッチする場合、文ハンドルのOCI_ATTR_ROWID属性を同時に使用してROWIDを取得することはできません。特定の文ハンドルに対して一度に使用できるのは1つのみです。

関連項目:
「OCI_ATTR_FETCH_ROWID」

ROWIDの暗黙的フェッチの例

例10-5のCプログラムのフラグメントを基礎として使用します。

例10-5 ROWIDの暗黙的フェッチ

#include <oci.h>

int main()
{
...
text *mySql = (text *) "SELECT emp_name FROM emp FOR UPDATE";
text rowid[100][15] = {0};
text empName[100][15] = {0};
...

/* Set up the environment, error handle, etc. */
...

/* Prepare the statement -  select ... for update. */

if (OCIStmtPrepare (select_p, errhp,
mySql, strlen(mySql), OCI_NTV_SYNTAX, OCI_DEFAULT))
{
printf ("Prepare failed \n");
return (OCI_ERROR);
}

/* Set attribute for implicit fetching of ROWIDs on the statement handle. */
if (OCIAttrSet(select_p, OCI_HTYPE_STMT, 0, 0, OCI_ATTR_FETCH_ROWID, errhp))
{
printf ("Unable to set the attribute - OCI_ATTR_FETCH_ROWID \n");
return OCI_ERROR;
}
/*
* Define the positions: 0 for getting ROWIDs and other positions
* to fetch other columns.
* Also, get the define conversion done implicitly by fetching
* the ROWIDs in the string format.
*/

if (OCIDefineByPos ( select_p,
&defnp0,
errhp,
0,
rowid[0],
15,
SQLT_STR,
(void *) ind,
(void *) 0,
(void *) 0,
OCI_DEFAULT) ||
OCIDefineByPos(select_p,
&defnp1,
errhp,
1,
empName[0],
15,
SQLT_STR,
(void *) 0,
(void *) 0,
(void *) 0,
OCI_DEFAULT)
)
{
printf ("Failed to define\n");
return (OCI_ERROR);
}

/* Execute the statement. */

if (errr = OCIStmtExecute(svchp,
select_p,
errhp,
(ub4) 5,
(ub4) 0,
(OCISnapshot *) NULL,
(OCISnapshot *) NULL,
(ub4) OCI_DEFAULT))
{
if (errr != OCI_NO_DATA)
return errr;
}

printf ("Column 0  \t Column 1\n");
printf ("_________ \t ________\n");

for (i =0 ;i<5 i++)
{
printf("%s \t %s \n", rowid[i], empName[i]);
}

return OCI_SUCCESS;
}

クライアント結果キャッシュ

OCIアプリケーションでは、OCI結果キャッシュを活用するためのクライアント・メモリーを使用して、繰返しの多い問合せの応答時間を短縮できます。

クライアント結果キャッシュにより、クライアント・メモリーにおけるSQL問合せ結果セットのクライアント側のキャッシュが可能になります。OCI結果キャッシュはOCIアプリケーションに対して完全に透過的であり、結果セット・データのキャッシュは、結果セットに影響するセッションまたはデータベースのすべての変更内容と整合性が保たれます。

この機能を使用するアプリケーションでは、キャッシュ・ヒットがある問合せのパフォーマンスが向上します。OCIでは、これらの問合せを将来実行する際に、キャッシュ内の結果を透過的に使用できます。OCIクライアント・プロセスからローカルに結果を取り出す処理は、データベース・コールの実行および問合せの再実行よりも高速で行われるため、頻繁な問合せの実行では、結果がキャッシュされている場合パフォーマンスが大幅に向上します。

OCIキャッシュを使用すると、問合せの処理で消費されていたサーバーのCPUも節減されるため、サーバーの拡張性が向上します。複数のセッションのOCI文が、スキーマ、SQLテキスト、バインド値およびセッションの設定が類似していれば、OCIプロセス・メモリー内のキャッシュされた同じ結果セットと一致することがあります。類似していなければ、サーバーに対して問合せの実行が指示されます。

クライアント結果キャッシュを使用する場合、アプリケーション・レベルでOCI文キャッシュまたはキャッシュ文を有効化する必要があります。

クライアント結果キャッシュは、OCIセッション・プーリング、OCI接続プーリング、データベース常駐接続プーリング、OCI透過的アプリケーション・フェイルオーバー(TAF)などのOCI機能と連動します。

関連項目:
「OCIでの文キャッシュ」

クライアント結果キャッシュの利点

OCIクライアント問合せ結果キャッシュの利点は次のとおりです。

- 結果キャッシュはクライアント側にあるため、キャッシュ・ヒットが存在すると、OCIStmtExecute()およびOCIStmtFetch2()のコールが、サーバー・ラウンドトリップを実行せずにローカルで処理されます。これにより、サーバーCPUおよびサーバーI/Oなどのサーバー・リソースにおいて、パフォーマンスが大幅に節減されます。

- OCIのクライアント側の問合せ結果セット・キャッシュは、透過的かつ一貫性のあるキャッシュです。

- OCIクライアントの結果キャッシュはプロセス単位であるため、複数のクライアント・セッションで一致するキャッシュ内の結果セットを同時に使用できます。

- 各OCIアプリケーションで独自のカスタム結果セット・キャッシュを保持する必要性が最小限になります。

- キャッシュ内の結果セットのキャッシュに関する各局面(つまり、複数のスレッド、文、セッションによる同時アクセス、キャッシュ内の結果セットの無効化またはリフレッシュ、およびキャッシュ・メモリー管理)が透過的に管理されます。

- OCIプロセスでサーバーに対してラウンド・トリップが発生した場合、結果セットに影響するデータベースの変更内容について、キャッシュ内の結果セットが透過的に無効化されます。

- この一貫性のあるキャッシュは、OCIを使用して構築されたすべてのOCIアプリケーションおよびドライバ(JDBC-OCI、ODP.Net、OCCI、Pro*C/C++、Pro*COBOL、ODBCなど)に対して自動的に使用可能になります。

- キャッシュには、サーバー・メモリーよりコストがかからないOCIクライアント・メモリーが使用されます。

- クライアントのローカル・キャッシュでは、そのクライアントにより実行される問合せの局所参照性が向上します。

クライアント結果キャッシュ使用のガイドライン

クライアント結果キャッシュは、アプリケーションに対していくつかの方法で有効化でき、選択した方法に基づいて、使用時の優先順位が決まります。使用方法の詳細は、「キャッシュ例の使用例」を参照してください。

- SQLヒント: 結果を問合せ結果キャッシュに格納することを示すには、問合せに/*+ result_cache */というヒントの注釈を付けます。SQLヒントを使用する方法の優先順位が最も高く、表注釈およびセッション・パラメータより優先されます。これは、単一の問合せに適用されます。アプリケーション・レベルの変更が必要です。

- 表注釈: デプロイ時に、ALTER TABLE文とCREATE TABLE文の結果キャッシュ・ヒントを使用して表に注釈を付けます。表注釈を使用する方法の優先順位は、SQLヒントより下で、MODE FORCEを使用するときのセッション・パラメータより上です。これは、その表に対するすべての問合せに適用されます。アプリケーション・レベルの変更は必要ありません。

- セッション・パラメータ: すべての表ですべての問合せに対して機能します。可能なかぎりこの方法を使用してください。サーバー・パラメータ・ファイル(init.ora)でRESULT_CACHE_MODE初期化パラメータを設定するか、ALTER SESSION文とALTER SYSTEM文でRESULT_CACHE_MODE句を使用します。セッション・パラメータを使用する方法の優先順位は最も低く、セッション・パラメータよりSQLヒントと表注釈の方が優先されます。すべての表に適用でき、最も有効範囲が広い方法です。アプリケーション・レベルの変更は必要ありません。

読取り専用またはほぼ読取りのみのデータベース・オブジェクトの場合、アプリケーションで表および問合せに結果キャッシュ・ヒントの注釈を付けることをお薦めします。結果キャッシュが、結果のサイズが大きい問合せに関するものである場合、これらの結果では大量のキャッシュ・メモリーが使用されることがあります。

アプリケーションで指定されたバインド値の各セットにより、(同じSQLテキストに対して)異なるキャッシュ結果セットが作成されるため、これらのすべての結果セットで大量のクライアント結果キャッシュ・メモリーが使用される場合があります。

クライアント結果キャッシュが有効である場合、問合せ結果セットをクライアントまたはサーバー(あるいはその両方)にキャッシュできます。クライアント結果キャッシュは、サーバー結果キャッシュ(デフォルトで有効)が無効化されている場合でも有効化できます。

すべてのOCI文ハンドル・コールにおける最初のOCIStmtExecute()のコールは、キャッシュ内に有効な結果セットがある場合でも、必ずサーバーに対して行われます。各文ハンドルをキャッシュ内の結果セットと照合できるようにするには、OCIStmtExecute()をコールする必要があります。アプリケーションがOCI文ハンドルについて独自の文キャッシュを持つようにするか、またはOCI文キャッシュを使用し、OCIStmtPrepare2()が一度実行されたOCI文ハンドルを戻せるようにすることをお薦めします。同一または異なるセッションからの複数のOCI文ハンドルは、キャッシュ内の同一の結果セットからデータを同時にフェッチできます。

結果セットをキャッシュするには、このキャッシュ結果セットを透過的に作成するOCIStmtExecute()または OCIStmtFetch2()のコールで、ORA-01403「データが見つかりません」エラーが戻されるまで行をフェッチする必要があります。ローカルにキャッシュされた結果セットと一致する後続のOCIStmtExecute()またはOCIStmtFetch2()のコールでは、最後までフェッチする必要はありません。

SQLヒント

RESULT_CACHE_MODEサーバー初期化パラメータがFORCEに設定されている場合を除き、SQLヒントによりキャッシュする問合せを明示的に指定する必要があります。OCIStmtPrepare()およびOCIStmtPrepare2()コールに渡されるSQLテキストで、SQLの/*+ result_cache */または/*+ no_result_cache */ヒントを設定する必要があります。

表注釈

ALTER TABLEおよびCREATE TABLE文により、表に結果キャッシュ・モードの注釈を付けることができます。後の項で説明するとおり、セッション・パラメータもあります。表注釈とセッション・パラメータのマトリックスでは、その表に対する問合せの有効な結果キャッシュ・モードを示しています。SQLヒントは表注釈およびセッション・パラメータに優先するので注意してください。構文は次のとおりです。

CREATE|ALTER TABLE [<schema>.]<table> ... [RESULT_CACHE (MODE {FORCE|DEFAULT})]

CREATE TABLEの例を示します。ここでは表の列を定義しています。

CREATE TABLE foo (a NUMBER, b VARCHAR2(20)) RESULT_CACHE (MODE FORCE);

次にALTER TABLEの例を示します。

ALTER TABLE foo RESULT_CACHE (MODE DEFAULT);

ALTER TABLE文は、これらの表を使用した(サーバー結果キャッシュの)文または問合せブロックの結果が結果キャッシュに格納されるよう、これらの表に注釈を付けるために使用されます。指定の問合せにSQLヒント/*+ result_cache /または/*+ no_result_cache */がある場合、またはパラメータRESULT_CACHE_MODEがFORCEに設定されている場合、ヒントまたはセッション変数は表注釈より優先されます。

結果キャッシュに格納するすべての表に注釈を付ける必要があります。これで、単一表を選択したか結合を含むかにかかわらず、キャッシュ・ヒントを含むこれらの表についてのすべてのSQL問合せに対し、キャッシュの価値があることを前提にキャッシュが検討されます。

関連項目:

- RESULT_CACHE句、SQLヒント、ALTER TABLEおよびCREATE TABLEの詳細は、Oracle Database SQL言語リファレンス』を参照してください。

- RESULT_CACHE_MODEの詳細は、『Oracle Databaseリファレンス』を参照してください。

表10-1に、結果キャッシュ注釈のモード値をまとめています。

表10-1 DDL表の結果キャッシュ注釈モード

モード値

説明

DEFAULT

デフォルト値です。結果キャッシュは表レベルで決定されません。この値を使用して、あらゆる表注釈を消去できます。

FORCE

問合せ内のすべての表名にこの設定が含まれる場合、その問合せにNO_RESULT_CACHEヒントが指定されていないかぎり、その問合せは常にキャッシュについて検討されます。問合せで指定された1つ以上の表がDEFAULTに設定されている場合、その問合せの有効な表注釈はDEFAULTです。

表注釈モードのチェック

DBAビューDBA_TABLES、USER_TABLESおよびALL_TABLESのRESULT_CACHE列には、その表の結果キャッシュ・モードの注釈が表示されます。表に注釈が付けられていない場合、DEFAULTと表示されます。

emp表に、ALTER TABLE emp RESULT_CACHE (MODE FORCE)の注釈が付いているとします。

そして、次の問合せをセッションで実行します。

SELECT table_name, result_cache FROM user_tables

出力は次のとおりです。

TABLE_NAME    RESULT_CACHE
----------    ------------
EMP           FORCE
FOO           DEFAULT

出力は、次の文を使用して、FOO表に注釈が付いているか、付いていないかを示します。

ALTER TABLE foo RESULT_CACHE (MODE DEFAULT);

関連項目:
これらのDBAビューのRESULT_CACHE列の詳細は、『Oracle Databaseリファレンス』を参照してください。

セッション・パラメータ

RESULT_CACHE_MODEパラメータにより、問合せで複数の表間の結果キャッシュ・モードを決定できます。この句をALTER SESSIONおよびALTER SYSTEM文内またはサーバー・パラメータ・ファイル(init.ora)内で使用し、結果キャッシュを決定します。

関連項目:
RESULT_CACHE_MODEの詳細は、『Oracle Databaseリファレンス』を参照してください。

有効な結果キャッシュ表モード

SQL問合せレベルの結果キャッシュ・ヒントは、セッション・パラメータRESULT_CACHE_MODEおよび結果キャッシュ表注釈より優先されます。さらに、表注釈FORCEは、表10-2に示すように、セッション・パラメータMANUALに優先します。表10-2では、セッション・パラメータRESULT_CACHE_MODEのモード(MANUALおよびFORCE)を、比較可能な表注釈モードと比較し、効果的な結果キャッシュ・モードを示しています。

表10-2 有効な結果キャッシュ表モード

RESULT_CACHE_MODEパラメータ

MANUAL

FORCE

表注釈 = FORCE

FORCE

FORCE

表注釈 = DEFAULT

MANUAL

FORCE

有効なモードがFORCEの場合、実際のキャッシュはクライアントとサーバーのキャッシュの内部制限、問合せキャッシュの意味(たとえば、問合せにSYSDATEが存在しない)、およびキャッシュで使用可能な領域によって異なります。これはSQL問合せヒント/*+ result_cache */でも同様で、単なるヒントです。問合せが実際にキャッシュされることは意味しません。表注釈DEFAULTは結果キャッシュが表レベルでは決定されないことを示し、セッション・パラメータのMANUALモードは、SQLヒントを優先するために問合せに注釈する必要があることを示しているため、実質的にこれらは、この設定については同等の方法ということになります。

キャッシュ例の使用例

次に、SQLヒントが表注釈とセッション・パラメータに優先する場合を示すいくつかの使用例を示します。

- emp表にALTER TABLE emp RESULT_CACHE(MODE FORCE)と注釈が付けられており、セッション・パラメータが設定されていない(デフォルト値MANUALが指定されている)場合、emp表の問合せについて問合せキャッシュが検討されることを意味します。

- 例で、SQL問合せがSELECT /*+ no_result_cache */ empno FROM empである場合、この問合せはキャッシュされません。これは、SQLヒントが表注釈およびセッション・パラメータより優先されるためです。

- emp表に注釈が付けられていないか、ALTER TABLE emp RESULT_CACHE (MODE DEFAULT)と注釈が付けられており、セッション・パラメータが設定されていない(デフォルト値MANUALが指定されている)場合、問合せがキャッシュされないことを意味します。

- 例で、SQL問合せにSELECT /*+ result_cache */ * FROM empというヒントが付いている場合、この問合せについて問合せキャッシュが検討されます。

- 表注釈がなくSQL問合せヒントがないが、セッション・パラメータまたはシステム・パラメータがFORCEに設定されている場合、あらゆる表のすべての問合せについて問合せキャッシュが検討されます。

関連項目:
キャッシュの詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

キャッシュされない問合せ

結果キャッシュ・ヒントが指定されている場合でも、OCIクライアントにキャッシュされない問合せがあります。このような問合せは、サーバー結果キャッシュ機能が有効な場合、データベースにキャッシュされます(詳細は、『Oracle Database概要』のSQL問合せに関する説明を参照してください)。SQL問合せに次のいずれかが含まれる場合、その問合せの結果セットはOCIクライアント結果キャッシュにキャッシュされません。

- リモート・オブジェクト

- 選択リストの複合型

- スナップショットベースの問合せまたはフラッシュバック問合せ

- シリアライズ可能の読取り専用トランザクション内またはフラッシュバック・セッション内で実行される問合せ

- PL/SQLファンクションが含まれる問合せ

- 表で仮想プライベート・データベース(VPD)ポリシーが有効となっている問合せ

クライアント・キャッシュの一貫性

クライアント・キャッシュでは、キャッシュ内の結果セットに影響する可能性のあるセッションの状態またはデータベースの変更内容と結果セットの一貫性が透過的に保たれます。

トランザクションにより、そのキャッシュ結果の作成に使用されたデータベース・オブジェクトのデータまたはメタデータが変更された場合、後続のサーバーへのラウンドトリップ時にOCIクライアントに無効化されたデータが送信されます。OCIアプリケーションで一定時間にわたりデータベース・コールが行われない場合、こうした無効化の有無を確認するため、クライアント・キャッシュの遅延設定により次のOCIStmtExecute()コールによるデータベース・コールが強制的に実行されます。

データベースの無効化に関連するキャッシュ内の結果セットはただちに無効化され、後続のOCIStmtExecute()コールはこうした結果セットと照合されません。現在これらのキャッシュ内の結果セットからフェッチしているOCI文ハンドルは、こうした無効化データを受信した際に、この(無効化された)キャッシュ内の結果セットから引き続きフェッチできます。

キャッシュ内に使用可能な領域がある場合、プロセスによる次回のOCIStmtExecute()コールにより、新規結果セットをキャッシュできます。OCIクライアント結果キャッシュでは、未使用のメモリーが定期的に再生されます。

セッションにオープン・トランザクションがある場合、OCIでは、このトランザクションで変更されたデータベース・オブジェクトを参照する問合せが、クライアント・キャッシュではなくサーバーに対して行われます。

一貫性を保つこのメカニズムにより、OCIキャッシュはコミットされたデータベースの変更に常に近い状態になります。キャッシュできない問合せ(DML、OCILobコールなど)のため、データベース・ラウンドトリップに必要なコールをOCIアプリケーションで頻繁に実行する場合、これらのコールによりクライアント・キャッシュがデータベースの変更を反映して透過的に最新の状態に保たれます。

表が変更されるとき、トリガーにより別の表が変更されることがあります。OCIクライアント結果キャッシュは、そのような変更すべてに敏感です。

セッション状態が変わる、たとえばNLSセッション・パラメータが変更されると、問合せ結果が異なる場合があります。OCI結果キャッシュはこのような変化の影響を受けやすく、それ以降に問合せを実行すると、正しい問合せ結果セットが返されます。現在のキャッシュ結果セットは、一致するプロセスの他のセッションで維持されます(無効化されない)。それ以外の場合、これらの結果セットはしばらくして「支配」状態になります。新しいセッション状態に対応して、新しい結果セットがキャッシュされます。

アプリケーションでそのようなデータベースおよびセッションの変更をすべて追跡する必要がある場合、面倒で、エラーが発生する可能性があります。したがって、OCI結果キャッシュでは、データベースまたはセッションのどの変更についても、結果セットの一貫性を透過的に維持します。

OCIクライアント結果キャッシュでは、クライアントにおけるスレッドのサポートは必要ありません。

クライアント結果キャッシュに関するデプロイメント時設定

クライアント結果キャッシュには、デプロイメント時設定に関するサーバー初期化パラメータおよびクライアント構成パラメータがあります。

サーバー初期化パラメータは次のとおりです。

- CLIENT_RESULT_CACHE_SIZE
デフォルト値は0(ゼロ)であり、クライアント・キャッシュ機能が無効であることを示します。クライアント結果キャッシュ機能を有効にするには、サイズを32768バイト(32KB)以上に設定してください。これは、クライアントのプロセス単位の結果セット・キャッシュの最小サイズです。すべてのOCIクライアント・プロセスは、この最小サイズを取得します。CLIENT_RESULT_CACHE_SIZE初期化パラメータを使用してこの機能をサーバーで有効化している場合にかぎり、sqlnet.ora構成パラメータOCI_RESULT_CACHE_MAX_SIZEでこの値をオーバーライドできます。

現在のデフォルト最大サイズを調べるには、CLIENT_RESULT_CACHE_SIZEパラメータの値を表示します。この最大サイズを大きくするには、CLIENT_RESULT_CACHE_SIZEを設定します。ただし、CLIENT_RESULT_CACHE_SIZEは静的なパラメータであるため、ALTER SYSTEM文を使用する場合には、SCOPE = SPFILE句を含める必要があり、このパラメータに対する変更を有効にするにはデータベースの再起動が必要です。

クライアント結果キャッシュ機能がサーバーで無効化されている場合、クライアント構成パラメータOCI_RESULT_CACHE_MAX_SIZEは無視され、クライアントではクライアント結果キャッシュを有効化できないことに注意してください。

設定可能なキャッシュ・サイズの最小値は次のようになります。

(使用可能なクライアント・メモリー)＋

((キャッシュされる見込み結果セット数)

*(結果セット内の1行の平均サイズ)

* (結果セット内の平均行数))

注意:
クライアント結果キャッシュの最大値は2GBです。この値よりも大きな値を設定すると、2GBに切り捨てられます。
エラーが発生する可能性があるため、データベースの作成時にはCLIENT_RESULT_CACHE_SIZEパラメータを設定しないでください。

- CLIENT_RESULT_CACHE_LAG
初期化パラメータCLIENT_RESULT_CACHE_LAGを使用すると、結果セットに影響するデータベース内の変更からクライアント結果キャッシュが遅延可能な最大時間をミリ秒で指定できます。デフォルトは3000ミリ秒です。

CLIENT_RESULT_CACHE_LAGパラメータの値を表示すると、現在の遅延を確認できます。この値を変更するには、CLIENT_RESULT_CACHE_LAGを設定します。ただし、CLIENT_RESULT_CACHE_LAGは静的なパラメータであるため、ALTER SYSTEM文を使用する場合には、SCOPE = SPFILE句を含める必要があり、このパラメータに対する変更を有効にするにはデータベースの再起動が必要です。

- 表注釈。オプションです。デプロイメント時に、結果キャッシュについて読取り専用またはほぼ読取りのみの表に注釈を付けることができます。アプリケーションレベルの変更は不要です。SQL結果キャッシュ・ヒントが指定されている場合、表注釈がオーバーライドされるので注意してください。詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

- compatible
Oracle Databaseで互換性を維持する必要のあるリリースを指定します。クライアント結果キャッシュを有効にするには、このパラメータを11.0.0.0以上に設定する必要があります。ビューでクライアント・キャッシュを使用する場合、compatibleを11.2.0.0以上に設定する必要があります。

クライアント構成ファイル

クライアント構成ファイルはオプションであり、サーバーのinit.ora初期化ファイル内で設定されているキャッシュ・パラメータを上書きします。これらのパラメータは、sqlnet.oraファイルに含まれます。クライアント構成には、次のオプション・パラメータを使用できます。

- OCI_RESULT_CACHE_MAX_SIZE(オプション): プロセス単位の問合せキャッシュの最大サイズ(バイト数)。クライアントのsqlnet.oraファイルで32768未満のサイズを指定すると、このsqlnet.oraファイルを読み取るクライアント・プロセスのクライアント結果キャッシュ機能が無効になります。

- OCI_RESULT_CACHE_MAX_RSET_SIZE (オプション): プロセス単位の問合せキャッシュ内の結果セットの最大サイズ(バイト数)。

- OCI_RESULT_CACHE_MAX_RSET_ROWS (オプション): プロセス単位の問合せキャッシュ内の結果セットの最大サイズ(行数)。

クライアントではキャッシュの遅延を設定できないので注意してください。

クライアント・キャッシュの統計

OCIクライアントからの既存のラウンドトリップでは、OCIからクライアント・キャッシュに関する統計がサーバーに対して定期的に送信されます。これらの統計は、CLIENT_RESULT_CACHE_STATS$ビューに格納されます。正常にキャッシュされた結果セット数、キャッシュ・ヒット数およびキャッシュ内の無効化された結果セット数などの情報がここに格納されます。問合せのキャッシュ・ミスの数は、クライアント結果キャッシュ統計内の「作成数」の数以上になります。より正確なキャッシュ・ミス数は、サーバーの自動ワークロード・リポジトリ(AWR)レポートに示されるサーバー実行数と等しくなります。

関連項目:

- CLIENT_RESULT_CACHE_STAT$ビューの詳細は、『Oracle Databaseリファレンス』を参照してください。

- クライアント・キャッシュを実行しているセッションのクライアント・プロセスIDおよびセッションIDについては、『Oracle Databaseパフォーマンス・チューニング・ガイド』を参照してください。

クライアント結果キャッシュの検証

この後の各項では、クライアント結果キャッシュの検証実行について詳しく説明します。

タイミングの測定

まず、問合せに結果キャッシュ・ヒントを付け加えることによるパフォーマンスの向上を確認するには、/*+ result_cache */ヒントなしで問合せ実行にかかる時間を測定します。次に、問合せに/*+ result_cache */ヒントを追加して、再び時間を測定します。その時間差が、パフォーマンスの向上分です。

v$mystatの使用

v$mystatビューに問い合せます。このビューに問い合せるには、権限が必要です。次の2つの問合せを実行します。

問合せ1: v$mystatからクライアントとの間のSQL*Netラウンドトリップ数を測定します。

問合せ2: SQL結果キャッシュ・ヒントなしで、クライアントとの間のSQL*Netラウンドトリップ数を測定します。

問合せ2と問合せ1の差が、クライアント結果キャッシュを有効化せずに、通常必要なラウンドトリップ数です。

この計算では、問合せ1の問合せ自体が数回のラウンドトリップ(約2回)を行うことに注意してください。

問合せに結果キャッシュ・ヒントを追加するか、emp表に対する問合せにFORCE表注釈を追加して再度問合せを実行すると、問合せ2と問合せ1の差は大幅に小さくなります。

v$sqlareaの使用

v$sqlareaビューに問い合せます。このビューに問い合せるには、権限が必要です。

次のSQL文を実行します。

SELECT COUNT(*) FROM emp

このSQL文を数回再実行します。

その後、v$sqlareaから'% from emp';のようなsql_textで選択実行、フェッチ、parse_callsを問い合せます。

次に、empの結果キャッシュ表ヒントを問合せに追加します。

この問合せを数回再実行します。

クライアント・キャッシュにより、column1、column2の値は少なくなります。

前述の検証は、結果キャッシュ表注釈によっても実行できることに注意してください。

OCIクライアント側結果キャッシュおよびサーバー結果キャッシュ

クライアント側の結果キャッシュは、サーバー結果キャッシュとは別の機能です。クライアント側結果キャッシュでは、トップレベルのSQL問合せの結果がOCIクライアント・メモリーにキャッシュされますが、サーバー結果キャッシュでは、結果セットがサーバーSGAメモリーにキャッシュされます。

また、サーバー結果キャッシュでは問合せの一部をキャッシュできます。クライアント側結果キャッシュはサーバー結果キャッシュとは関係なく有効化できますが、どちらも結果キャッシュSQLヒント、表注釈およびセッション・パラメータRESULT_CACHE_MODEを共有します。SQL問合せ結果キャッシュの詳細は、『Oracle Database概要』を参照してください。表10-3では、クライアント側結果キャッシュ、サーバー結果キャッシュまたはその両方について、特定の結果キャッシュの関連付けを、特定のパラメータ、特定のPL/SQLパッケージの実行、特定のOracle Databaseビューへの問合せに関して示しています。

表10-3 クライアント側結果キャッシュとサーバー結果キャッシュの設定

パラメータ、PL/SQLパッケージおよびデータベース・ビュー

結果キャッシュの関連付け

client_result_cache_*パラメータ

client_result_cache_size、

client_result_cache_lag

クライアント結果キャッシュ

SQLヒント/*+ result_cache */、

/*+ no_result_cache */

クライアント結果キャッシュ、サーバー結果キャッシュ

sqlnet.ora OCI_RESULT_CACHE* パラメータ:

OCI_RESULT_CACHE_MAX_SIZE

OCI_RESULT_CACHE_MAX_RSET_SIZE

OCI_RESULT_CACHE_MAX_RSET_ROWS

クライアント結果キャッシュ

統計ビュー: client_result_cache_stats$

クライアント結果キャッシュ

result_cache_modeパラメータ

クライアント結果キャッシュ、サーバー結果キャッシュ

他のすべてのresult_cache*パラメータ(result_cache_max_sizeなど)

サーバー結果キャッシュ

パッケージDBMS_RESULT_CACHE

サーバー結果キャッシュ

統計ビューv$result_cache_*、gv$result_cache_*

v$result_cache_statistics、gv$result_cache_memoryなど

サーバー結果キャッシュ

表注釈の作成

クライアント結果キャッシュ、サーバー結果キャッシュ

表注釈の変更

クライアント結果キャッシュ、サーバー結果キャッシュ

クライアント結果キャッシュ・デモ・ファイル

この機能のデモ・ファイルについては、cdemoqc.sql、cdemoqc.cおよびcdemoqc2.cファイル(すべてオペレーティング・システムのdemoディレクトリにあります)を参照してください。

以前のリリースとの互換性

クライアント結果キャッシュを使用するには、アプリケーションをOracle Databaseリリース11.1以上のクライアント・ライブラリと再リンクし、Oracle Databaseリリース11.1以上のデータベース・サーバーに接続する必要があります。この機能は、JDBC Type IIドライバ、OCCI、Pro*C/C++およびODP.NETを含むすべてのOCIアプリケーションで使用できます。OCIドライバは、OCIStmtPrepare()およびOCIStmtPrepare2()コールに結果キャッシュ・ヒントを自動的に渡すため、キャッシュの恩恵を受けることができます。

OCIでの障害診断

OCIの11gリリース1 (11.1)では、障害診断が導入されました。OCIクライアント上のインシデント(問題の発生)は、ユーザーの介入なしで診断データの形式(ダンプ・ファイルまたはコア・ダンプ・ファイル)で取得されます。診断データは、インシデントについて作成された自動診断リポジトリ(ADR)サブディレクトリに格納されます。たとえば、LinuxまたはUNIXアプリケーションがNULLポインタ参照で失敗した場合、コア・ファイルはオペレーティング・システム・ディレクトリではなくADRホーム・ディレクトリ(存在する場合)に書き込まれます。ADRサブディレクトリ構造および出力を処理するためのユーティリティであるADRコマンド・インタプリタ(ADRCI)について、次の各項で説明します。

ADRホームは、OCIなどの特定の製品のインスタンスおよび特定のオペレーティング・システム・ユーザーに関するすべての診断データのルート・ディレクトリです。ADRホームは、ADRベースという同一のルート・ディレクトリの下でグループ化されます。

障害診断およびOracle DatabaseのADR構造については、『Oracle Database管理者ガイド』の診断データの管理に関する解説で詳しく説明されています。

ADRベースの場所

ADRベースの場所は、OCIにより次の順序で決定されます。

1. OCIは、最初にsqlnet.oraファイル(存在する場合)で次のような文を検索します(LinuxまたはUNIX)。

ADR_BASE=/foo/adr

adr (ディレクトリの名前)が存在し、OCIアプリケーションを実行して同じADRベースを共有するすべてのオペレーティング・システム・ユーザーによって書込み可能である必要があります。fooはパス名を表します。sqlnet.oraの場所は、ディレクトリ$TNS_ADMIN (Windowsの場合は%TNS_ADMIN%)で指定されます。$TNS_ADMINが存在しない場合は、現在のディレクトリが使用されます。ADR_BASEが設定されており、すべてのユーザーが1つのsqlnet.oraを共有する場合、ディレクトリadrが存在しない、またはユーザーによる書込みができないと、OCIは検索を停止します。ADR_BASEが設定されていない場合、OCIは検索を続行し、他の特定のディレクトリの有無をテストします。

たとえば、sqlnet.oraにエントリADR_BASE=/home/chuck/testが含まれる場合、ADRベースは/home/chuck/test/oradiag_chuckであり、ADRホームは/home/chuck/test/oradiag_chuck/diag/clients/user_chuck/host_4144260688_11のようになります。

2. $ORACLE_BASE (Windowsでは%ORACLE_BASE%)が存在します。この場合、Oracle Universal Installerを使用したデータベースのインストール時にクライアント・サブディレクトリが作成されているため、これが存在します。
たとえば、$ORACLE_BASEが/home/chuck/obaseである場合、ADRベースは/home/chuck/obaseであり、ADRホームは/home/chuck/obase/diag/clients/user_chuck/host_4144260688_11のようになります。

3. $ORACLE_HOME (Windowsでは%ORACLE_BASE%)が存在します。この場合、Oracle Universal Installerを使用したデータベースのインストール時にクライアント・サブディレクトリが作成されているため、これが存在します。
たとえば、$ORACLE_HOMEが/ade/chuck_l1/oracleである場合、ADRベースは/ade/chuck_l1/oracle/logであり、ADRホームは/ade/chuck_l1/oracle/log/diag/clients/user_chuck/host_4144260688_11のようになります。

4. オペレーティング・システムのホーム・ディレクトリは、LinuxまたはUNIXでは$HOME、Windowsでは%USERPROFILE%です。LinuxまたはUNIXでは、ユーザーchuckの場所は/home/chuck/oradiag_chuckのようになります。Windowsでは、C:\Documents and Settings\chuckの下にOracleというフォルダが作成されます。
たとえば、Instant Clientでは、$HOMEが/home/chuckである場合、ADRベースは/home/chuck/oradiag_chuckであり、ADRホームは/home/chuck/oradiag_chuck/diag/clients/user_chuck/host_4144260688_11です。

関連項目:
「OCI Instant Client」

5. Windowsでは、アプリケーションがサービスとして動作している場合、ホーム・ディレクトリ・オプションはスキップされます。

6. LinuxまたはUNIXオペレーティング・システムの一時ディレクトリは/var/tmpです。
たとえば、Instant Clientでは、$HOMEが書込み不可である場合、ADRベースは/var/tmp/oradiag_chuckであり、ADRホームは/var/tmp/oradiag_chuck/diag/clients/user_chuck/host_4144260688_11です。

Windowsオペレーティング・システムの一時ディレクトリは、次の順序で検索されます。

1. %TMP%

2. %TEMP%

3. %USERPROFILE%

4. Windowsシステム・ディレクトリ

これらのディレクトリの選択肢がいずれも使用不可および書込み不可である場合、ADRベースは作成されず、診断は実行されません。

関連項目:
『Oracle Database Net Servicesリファレンス』

ADRCIの使用

ADRCIは、ADR内の診断データを表示し、インシデントおよび問題に関する情報をOracleサポートが使用できるようzipファイルに圧縮できるコマンドライン・ツールです。ADRCIは対話式に、またスクリプトから使用できます。問題が発生すると、OCIまたはクライアントで重大なエラーとなります。各問題には問題キーがあります。1つのインシデントは問題の1回の発生を意味し、数字を使用した一意のインシデントIDで識別されます。各インシデントには、属性のセット(ORAエラー番号、エラー・パラメータ値およびその他の情報)である問題キーが割り当てられています。2つのインシデントの問題キーが一致する場合、根本的な原因は同じです。

関連項目:
ADRCIの概要は、『Oracle Databaseユーティリティ』を参照してください。

次に、LinuxシステムでADRCIを起動し、SHOW BASEコマンドについてHELPコマンドを使用し、SHOW BASEコマンドを-PRODUCT CLIENTオプション(OCIアプリケーションに必要)とともに使用する方法を示します。ADRCIコマンドは大/小文字の区別はありません。ユーザー入力は太字で表示されます。

% adrci

ADRCI: Release 11.1.0.5.0 - Beta on Wed May 2 15:53:06 2007

Copyright (c) 1982, 2007, Oracle.  All rights reserved.

adrci> help show base

Usage: SHOW BASE [-product <product_name>]

Purpose: Show the current ADR base setting.

Options:
[-product <product_name>]: This option allows users to show the
given product's ADR Base location. The current registered products are
"CLIENT" and "ADRCI".

Examples:
show base -product client
show base

adrci> show base -product client
ADR base is "/ade/chuck_l3/oracle/log/oradiag_chuck"

次に、SET BASEコマンドを記述しています。

adrci> help set base

Usage:  SET BASE <base_str>

Purpose: Set the ADR base to use in the current ADRCI session.
If there are valid ADR homes under the base, all homes will
will be added to the current ADRCI session.

Arguments:
<base_str>: It is the ADR base directory, which is a system-dependent
directory path string.

Notes:
On platforms that use "." to signify current working directory,
it can be used as base_str.

Example:
set base /net/sttttd1/scratch/someone/view_storage/someone_v1/log
set base .

adrci> quit

ADRCIを起動すると、デフォルトのADRベースはrdbmsサーバーに対するものとなります。 $ORACLE_HOMEは/ade/chuck_l3/oracleに設定されます。

% adrci

ADRCI: Release 11.1.0.5.0 - Beta on Wed May 2 16:16:55 2007

Copyright (c) 1982, 2007, Oracle.  All rights reserved.

ADR base = "/ade/chuck_l3/oracle/log"

OCIアプリケーションのインシデントの場合、ベースを次のようにチェックおよび設定する必要があります。

adrci> show base -product client
ADR base is "/ade/chuck_l3/oracle/log"
adrci> set base /ade/chuck_l3/oracle/log

Instant Clientの場合、$ORACLE_HOMEがないため、デフォルトのベースはユーザーのホーム・ディレクトリです。

adrci> show base -product client
ADR base is "/home/chuck/oradiag_chuck"
adrci> set base /home/chuck/oradiag_chuck
adrci> show incidents

ADR Home = /home/chuck/oradiag_chuck/diag/clients/user_chuck/host_4144260688_11:
*************************************************************************
INCIDENT_ID    PROBLEM_KEY           CREATE_TIME
-------------------------------------------------------------------------
1                     oci 24550 [6]              2007-05-01 17:20:02.803697 -07:00
1 rows fetched

adrci>

関連項目:
「OCI Instant Client」

sqlnet.oraを使用したADRの作成の管理および障害診断の無効化

診断能力を無効にするには、sqlnet.oraで次のパラメータを設定し(デフォルトはTRUE)、診断をオフにします。

DIAG_ADR_ENABLED=FALSE
DIAG_DDE_ENABLED=FALSE

OCIシグナル・ハンドラをオフにし、標準オペレーティング・システムの障害処理を再度有効化するには、sqlnet.oraで次のパラメータを設定します。

DIAG_SIGHANDLER_ENABLED=FALSE

前述のように、sqlnet.oraでADR_BASEを使用し、ADRベースの場所を設定します。

Oracle Databaseクライアントには、重要なエラーが検出された際に診断情報をダンプする機能など、問題を診断するための高度な機能が備えられています。デフォルトでは、これらのダンプは、使用可能な情報の小規模なサブセットに制限されており、アプリケーション・データはダンプされません。ただし、大部分のインストールでは、ダンプ・ファイルに対して安全な場所が構成され、このログのプライバシが確保されます。この場合は、フル・ダンプをオンにすることをお薦めします。これにより、問題の解決速度が大幅に向上します。フル・ダンプを有効にするには、Oracle Databaseクライアント・インストールで使用したsqlnet.oraファイルに次の行を追加します。

DIAG_RESTRICTED=FALSE

診断機能が正しく機能していることを確認するには、次のようにします。

1. 最新のクライアント・ライブラリを使用するように、アプリケーションをアップグレードします。

2. アプリケーションを起動します。

3. アプリケーションのTNS_ADMINディレクトリにあるsqlnet.logファイルに、診断機能を起動できなかったこと(通常、これは無効なディレクトリ名または権限が原因です)を示すエラー・メッセージがないか調べます。

関連項目:

- sqlnet.oraでのADRパラメータの設定については、『Oracle Database Net Servicesリファレンス』を参照してください。

- ADRの構造に関する詳細は、『Oracle Database Net Services管理者ガイド』を参照してください。

異なるバージョンのタイムゾーン・ファイルで操作するクライアントとサーバー

Oracle Databaseリリース11.2以上では、クライアントとサーバーで異なるバージョンのタイム・ゾーン・ファイルを使用できます。この動作モードはOracle Database 11.2より前のリリースではサポートされていませんでした。このような混在モードで作業するには、クライアントとサーバーの両方が11.2以上であることが必要です。この項では、このようなモードで作業する場合に発生する問題について説明します。これらの問題を回避するには、クライアントとサーバーで同じバージョンのタイム・ゾーン・ファイルを使用します。

クライアントとサーバーで異なるバージョンのタイムゾーン・ファイルを使用している場合、次の動作が見られます。異なるバージョンのタイムゾーン・ファイルを使用すると、TIMESTAMP WITH TIMEZONE (TSTZ)データ型の値の処理にのみ影響が出ることに注意してください。

- 次に示すOCIの日時および時間隔のAPIでは、入力パラメータがTSTZ型の場合、無条件にエラーが発生します。これは、これらの操作が、データベースと同期していないクライアント上のローカル・タイムゾーン・ファイルに依存するためです。そのような構成で計算を続けると、クライアント層とデータベース層間で計算の一貫性がなくなる可能性があります。

OCIDateTimeCompare()
OCIDateTimeConstruct()
OCIDateTimeConvert()
OCIDateTimeSubtract()
OCIIntervalAdd()
OCIIntervalSubtract()
OCIIntervalFromTZ()
OCIDateTimeGetTimeZoneName()
OCIDateTimeGetTimeZoneOffset()Foot 1
OCIDateTimeSysTimeStamp()

- TSTZ値の取得または変更時に、パフォーマンスが低下します。パフォーマンスの低下は、異なるバージョンのタイムゾーン・ファイルを使用するクライアントとサーバーの補正に、追加の変換が必要であることから生じます。

- より新しいタイムゾーン・ファイルで新規タイムゾーン・リージョンが定義される場合、新規タイムゾーン・リージョンを認識しないバージョンのタイムゾーン・ファイルを持つノードで、新規リージョンに属するTIMESTAMP WITH TIMEZONE値に対してエラーが発生する可能性があります。

TSTZ型属性を含む不透明型またはXMLTypeのインスタンス、あるいはその両方を操作するアプリケーションでは、データ損失を避けるために、クライアントとサーバーで同じバージョンのタイムゾーン・ファイルを使用する必要があります。

関連項目:
タイムゾーン・ファイルとタイムスタンプのタイムゾーン・データによるアップグレードの詳細は、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

脚注の凡例

脚注 1: クライアントとサーバーのタイム・ゾーン・ファイルが一致しない(リージョンが同期化されていない)場合は、ORA-01805エラーが戻されます。リージョン・タイム・ゾーン値が同じ(UTCで同じインスタントを示す)場合は、TIME ZONEオフセットが異なっていてもOCI_SUCCESSが戻されます。

11 OCIオブジェクト・リレーショナル・プログラミング

この章では、オブジェクトをOracle Databaseで操作するためのOCIの機能を紹介します。また、OCIのオブジェクト・ナビゲーショナル関数コールについても説明します。

この章は、次の項目で構成されています。

- OCIオブジェクトの概要

- OCIでのオブジェクトの操作

- OCIオブジェクト・アプリケーションの開発

- 型の継承

- 型の変更

OCIオブジェクトの概要

OCIによって、アプリケーションは、スカラー値、コレクション、任意のオブジェクト型のインスタンスなど、Oracle Database内のすべてのデータ型にアクセスできます。次のデータ型があります。

- オブジェクト

- 可変長配列(varray)

- ネストした表(多重集合)

- 参照(REF)

- LOB

Oracle Databaseのオブジェクト機能を十分に活用するには、ほとんどのアプリケーションでは単にオブジェクトにアクセスするのみでは十分ではありません。アプリケーションでは、オブジェクトを取り出した後、そのオブジェクトから他のオブジェクトへ参照を通してナビゲートする必要があります。OCIはそのための機能を提供します。OCIのオブジェクト・ナビゲーショナル・コールを使用すると、アプリケーションはオブジェクトに対して次の関数を実行できます。

- オブジェクトの作成、アクセス、ロック、削除、コピーおよびフラッシュ

- オブジェクトとそのメタオブジェクトへの参照の取得

- オブジェクト属性の値の動的な取得および設定

OCIナビゲーショナル・コールについては、「OCIオブジェクト・アプリケーションの開発」でより詳しく説明しています。

また、OCIは、Oracleのデータベースに格納されている型情報にアクセスする機能も備えています。アプリケーションでは、OCIDescribeAny()関数を使用して、データベースに格納されている型に関するほとんどの情報(メソッド、属性、型メタデータなど)にアクセスできます。

関連項目:
OCIDescribeAny()の詳細は、第6章を参照してください。

Oracle Databaseオブジェクトを操作するアプリケーションでは、オブジェクトをホスト言語形式で表現する手段が必要です。Oracle Databaseには、Object Type Translator (OTT)というユーティリティがあり、データベース内の型定義をCの構造体宣言に変換できます。宣言はヘッダー・ファイルに格納され、それをOCIアプリケーションに組み込むことができます。

型定義がCで表現されている場合、属性の型は特別なC変数型にマップされます。OCIには、アプリケーションによるこれらのデータ型の操作とそれによるオブジェクトの属性の操作を可能にする、一連のデータ型マッピング関数および操作関数が含まれています。

関連項目:
関数の詳細は、第12章を参照してください。

オブジェクトに関する用語は混同することがあります。この章の残りの部分では、オブジェクトおよびインスタンスという用語の両方が、データベースに格納されているか、またはオブジェクト・キャッシュ内にあるオブジェクトのことを示しています。

OCIでのオブジェクトの操作

リレーショナルOCIアプリケーションを制御するプログラミング原理の多くは、オブジェクト・リレーショナル・アプリケーションにも適用されます。オブジェクト・リレーショナル・アプリケーションでは、標準OCIコールを使用してデータベース接続を確立し、SQL文を処理します。その違いは、発行したSQL文でオブジェクト参照を取り出し、その参照をOCIのオブジェクト関数で操作できる点にあります。オブジェクトは、値インスタンスとして(オブジェクト参照を使用せずに)直接操作することもできます。

基本的なオブジェクト・プログラム構造体

オブジェクトを使用するOCIアプリケーションの基本的な構造体は、「OCIプログラムのプログラミングの概要」で説明しているように、本質的にはリレーショナルOCIアプリケーションと同じです。ここでは、基本的なオブジェクト機能についての追加情報とともに、そのモデルをもう一度示します。

1. OCIプログラミング環境を初期化します。オブジェクト・モードで環境を初期化する必要があります。
アプリケーションでは、ヘッダー・ファイルにデータベース・オブジェクトのC構造体表現が含まれている必要があります。これらの構造体はプログラマであれば作成できますが、より簡単な方法として、第15章で説明するように、Object Type Translator (OTT)でも生成できます。

2. 必要なハンドルを割り当て、サーバーとの接続を確立します。

3. SQL文を準備して実行します。これは、ローカル・ (クライアント側)ステップで、プレースホルダのバインドと出力変数の定義を行います。オブジェクト・リレーショナル・アプリケーションの場合、このSQL文はオブジェクトへの参照(REF)を戻します。

注意:
オブジェクトは参照(REF)のみでなく、オブジェクト全体をフェッチすることもできます。参照可能なオブジェクトを選択する場合は、それを確保するのではなく、そのオブジェクトを値によって取得します。参照不可能なオブジェクトを選択することもできます。「埋込みオブジェクトのフェッチ」では、オブジェクト全体のフェッチについて説明しています。

4. プリペアド文をデータベース・サーバーに関連付けて実行します。

5. 戻された結果をフェッチします。
オブジェクト・リレーショナル・アプリケーションでは、このステップでREFを取り出し、参照対象のオブジェクトを確保します。オブジェクトを確保すると、アプリケーションでは次の操作の一部またはすべてを実行できます。

- オブジェクトの属性を操作し、それに使用済(変更済)のマークを設定します。

- 別の1個のオブジェクトまたは一連のオブジェクトへのREFをたどります。

- 型および属性の情報にアクセスします。

- 複合オブジェクト検索グラフをナビゲートします。

- 変更したオブジェクトをサーバーにフラッシュします。

6. トランザクションをコミットします。このステップでは暗黙的に、変更されたすべてのオブジェクトをサーバーにフラッシュし、変更をコミットします。

7. 再利用しない文とハンドルを解放するか、プリペアド文を再実行します。

この章の残りの項で、こららの手順について詳しく説明します。

関連項目:

- OCIを使用したサーバーへの接続、SQL文の処理およびハンドルの割当ての詳細は第2章を、OCIリレーショナル関数の詳細は第16章を参照してください。

- OTTの詳細は、「Cアプリケーションでのオブジェクトの表現」および第15章を参照してください。

永続オブジェクト、一時オブジェクトおよび値

Oracle型のインスタンスは、その存続期間に応じて永続オブジェクトと一時オブジェクトに分類されます。永続オブジェクトのインスタンスは、オブジェクト識別子による参照が可能かどうかによって、スタンドアロン・オブジェクトと埋込みオブジェクトに分割されます。

注意:
このマニュアルでは、オブジェクトとインスタンスという用語は代替可能に使用されます。

関連項目:
オブジェクトの詳細は、『Oracle Databaseオブジェクト・リレーショナル開発者ガイド』を参照してください。

永続オブジェクト

永続オブジェクトは、Oracle Databaseに格納されているオブジェクトです。永続オブジェクトは、OCIアプリケーションによってオブジェクト・キャッシュにフェッチされ、変更されます。永続オブジェクトは、それにアクセスしているアプリケーションの存続期間を超えて存続できます。作成された永続オブジェクトは、明示的に削除されるまでデータベースに残留します。永続オブジェクトには次の2種類があります。

- スタンドアロン・インスタンスは、オブジェクト表の行に格納され、それぞれが一意のオブジェクト識別子を持っています。OCIアプリケーションでは、スタンドアロン・インスタンスへのREFを取り出してオブジェクトを確保し、確保したオブジェクトからその他の関連オブジェクトにナビゲートできます。スタンドアロン・オブジェクトは、参照可能オブジェクトとも呼ばれます。
参照可能オブジェクトの選択も可能で、その場合はREFをフェッチするかわりに、オブジェクトを値によってフェッチします。

- 埋込みインスタンスは、オブジェクト表の行として格納されません。埋込みインスタンスは、他の構造体の中に埋め込まれます。埋込みオブジェクトの例は、別のオブジェクトの属性であるオブジェクトや、データベースの表のオブジェクト列に存在するインスタンスなどです。埋込みインスタンスにはオブジェクト識別子がないため、OCIアプリケーションでは、埋込みインスタンスへのREFを取得できません。
埋込みオブジェクトは、参照不可能なオブジェクトまたは値インスタンスとも呼ばれます。埋込みオブジェクトは値と呼ばれることもありますが、それをスカラー・データ値と混同しないでください。どちらの意味であるかは文脈で判断できます。

例11-1と例11-2では、これら2種類の永続オブジェクトの違いを説明するSQLの例を示しています。

例11-1 スタンドアロン・オブジェクトのSQL定義

CREATE TYPE person_t AS OBJECT
(name      varchar2(30),
age       number(3));
CREATE TABLE person_tab OF person_t;

オブジェクト表person_tabに格納されるオブジェクトは、スタンドアロン・インスタンスです。このオブジェクトはオブジェクト識別子を持ち、参照可能です。したがって、OCIアプリケーションで確保できます。

例11-2 埋込みオブジェクトのSQL定義

CREATE TABLE department
(deptno     number,
deptname   varchar2(30),
manager    person_t);

department表のmanager列に格納されるオブジェクトは、埋込みオブジェクトです。このオブジェクトは、オブジェクト識別子を持たず、参照可能でもありません。つまり、OCIアプリケーション内には確保できず、確保解除する必要もありません。常に、値によってオブジェクト・キャッシュに取り込まれます。

一時オブジェクト

一時オブジェクトは一時インスタンスであり、アプリケーションの存続期間を超えて存続せず、サーバーに格納またはフラッシュできません。一時オブジェクトはいつでもアプリケーションで削除できます。

アプリケーションでは、OCIObjectNew()関数を使用して一時オブジェクトを作成し、計算のための一時的な値を格納することがよくあります。一時オブジェクトを永続オブジェクトに変換することはできません。オブジェクトのロールは、インスタンス化されたときに決定されます。

関連項目:
OCIObjectNew()の使用方法の詳細は、「オブジェクトの作成」を参照してください。

値

このマニュアルでは、値は次のいずれかを意味します。

- データベースの表の非オブジェクト列に格納されるスカラー値。OCIアプリケーションでは、SQL文を発行してデータベースから値をフェッチできます。

- 埋込みまたは参照不可能オブジェクト。

どちらを指しているのかは文脈で判断できます。

注意:
参照可能オブジェクトは、確保するかわりにオブジェクト・キャッシュ内で選択することができ、その場合は、REFをフェッチせずに、オブジェクトを値によってフェッチします。

OCIオブジェクト・アプリケーションの開発

この項では、基本的なOCIオブジェクト・アプリケーションの開発に伴うステップを説明します。「基本的なオブジェクト・プログラム構造体」で説明している各ステップについて、ここではさらに詳しく説明します。

図11-1は、アプリケーションがオブジェクトを操作する方法について、そのプログラム・ロジックのフローを簡単に示しています。図を簡略にするために、必要なステップの一部が省略されています。この図にある各ステップについては、後の項で説明します。

図11-1 基本的なオブジェクト操作のフロー

Cアプリケーションでのオブジェクトの表現

OCIアプリケーションでオブジェクト型を操作するには、データベースにそのオブジェクト型が存在している必要があります。通常は、CREATE TYPEなど、SQLのDDL文で型を作成します。

型定義DDLコマンドがOracle Databaseで処理されると、型定義は型記述子オブジェクト(TDO)としてデータ・ディクショナリに格納されます。

アプリケーションでデータベースからオブジェクト・タイプのインスタンスを取り出す場合は、クライアント側のオブジェクト表現を使用する必要があります。C言語のプログラムでは、オブジェクト型の表現はstructです。OCIオブジェクト・アプリケーションには、各オブジェクト型構造体に対応するNULLインジケータ構造体があります。

注意:
アプリケーション・プログラマが、オブジェクトのキャッシュによって生成されるデフォルトの構造体以外のオブジェクト表現を利用する場合は、「オブジェクト・キャッシュおよびメモリー管理」を参照してください。

Oracle Databaseには、データベースのオブジェクト型のC構造体表現を生成するObject Type Translator (OTT)というユーティリティがあります。たとえば、次のように宣言した型がデータベースにあるとします。

CREATE TYPE emp_t AS OBJECT
( name       VARCHAR2(30),
empno      NUMBER,
deptno     NUMBER,
hiredate   DATE,
salary     NUMBER);

OTTでは、次のC構造体と、対応するNULLインジケータ構造体が生成されます。

struct emp_t
{
OCIString    * name;
OCINumber    empno;
OCINumber    deptno;
OCIDate      hiredate;
OCINumber    salary;
};
typedef struct emp_t emp_t

struct emp_t_ind
{
OCIInd     _atomic;
OCIInd     name;
OCIInd     empno;
OCIInd     deptno;
OCIInd     hiredate;
OCIInd     salary;
};
typedef struct emp_t_ind emp_t_ind;

この構造体宣言で使用している変数型は、OCIオブジェクト・コールで採用されている特殊な型です。OCI関数のサブセットでは、このデータ型のデータを操作します。これらの関数については、この章の後半に説明がありますが、第12章でも詳しく説明します。

これらの構造体宣言は自動的にヘッダー・ファイルに書き込まれ、このファイルの名前はOTT入力パラメータによって決定されます。このヘッダー・ファイルをアプリケーションのコード・ファイルにインクルードすると、オブジェクトにアクセスできます。

関連項目:

- 「NULLインジケータ構造体」

- OTTの詳細は、第15章を参照してください。

環境およびオブジェクト・キャッシュの初期化

OCIアプリケーションでオブジェクトにアクセスして操作する場合は、OCIアプリケーションの最初のOCIコールであるOCIEnvCreate()コールのmodeパラメータに、OCI_OBJECTの値を指定する必要があります。modeにこの値を指定して、アプリケーションでオブジェクトを操作することをOCIライブラリに通知します。この通知には次の重要な効果があります。

- オブジェクト・ランタイム環境を確立します。

- オブジェクト・キャッシュを設定します。

オブジェクト・キャッシュ用のメモリーは、オブジェクトがキャッシュ内にロードされたときに、必要に応じて割り当てられます。

OCIEnvCreate()またはOCIEnvNlsCreate()のmodeパラメータにOCI_OBJECTを設定しないと、オブジェクト関連関数を使用しても結果はエラーになります。

クライアント側のオブジェクト・キャッシュは、プログラムのプロセス領域に割り当てられます。このキャッシュは、サーバーから取り出してアプリケーションで使用できるオブジェクトのメモリーです。

注意:
OCI環境をオブジェクト・モードで初期化すると、実際にオブジェクト・コールを使用するかどうかに関係なく、オブジェクト・キャッシュ用のメモリーを割り当てることになります。

関連項目:
オブジェクト・キャッシュの詳細は、第14章を参照してください。

データベース接続の実行

OCI環境が適切に初期化されると、アプリケーションはサーバーに接続できるようになります。この接続は、「OCIプログラミング・ステップ」で説明されている標準のOCI接続コールによって確立されます。これらのコールを使用する場合、このアプリケーションはオブジェクトにアクセスしているため、追加の考慮事項は必要ありません。

OCI環境ごとに、1つのオブジェクト・キャッシュが割り当てられます。1つの環境内で異なる接続を通じて取出しまたは作成されたオブジェクトは、すべて同じ物理的なオブジェクト・キャッシュを使用します。各接続には、それぞれ専用の論理的なオブジェクト・キャッシュがあります。

サーバーからのオブジェクト参照の取出し

オブジェクトを操作するには、アプリケーションでまずサーバーから1つ以上のオブジェクトを取り出す必要があります。これは、1つ以上のオブジェクトへのREFを戻すSQL文を発行して行います。

注意:
SQL文によって、データベースからREFではなく、埋込みオブジェクトをフェッチすることもできます。詳細は、「埋込みオブジェクトのフェッチ」を参照してください。

次の例では、アプリケーションでテキスト・ブロックが宣言されていて、ここには、実行時に入力変数(:emp_num)として渡される特定の従業員番号を指定したときに、データベース内の従業員のオブジェクト表(emp_tab)から1つの従業員オブジェクトへのREFを取り出すように設計されたSQL文が格納されています。

text *selemp = (text *) "SELECT REF(e)
FROM emp_tab e
WHERE empno = :emp_num";

アプリケーションでは、第2章で説明したリレーショナルSQL文の操作と同じ方法で、この文を準備し処理します。

1. OCIStmtPrepare()を使用してアプリケーション要求を準備します。

2. 1つ以上の適切なバインド・コールを使用して、ホスト入力変数をバインドします。

3. 従業員オブジェクト参照を受け取る出力変数を宣言し、準備します。ここでは、「Cアプリケーションでのオブジェクトの表現」で宣言した参照に類似した従業員オブジェクト参照を使用します。

OCIRef  *emp1_ref = (OCIRef *) 0; /* reference to an employee object */

出力変数の定義時に、定義コールのdtyデータ型パラメータをSQLT_REF (REFのデータ型定数)に設定します。

4. OCIStmtExecute()で文を実行します。

5. OCIStmtFetch2()を使用して、結果のREFをemp1_refにフェッチします。

これで、オブジェクト参照を使用して、オブジェクトまたはデータベースからのオブジェクトにアクセスして操作できます。

関連項目:

- SQL文の準備と実行の一般的な情報は、「OCIプログラミング・ステップ」を参照してください。

- REF変数のバインドおよび定義の特殊情報は、「OCIでの拡張バインド操作」および「OCIでの拡張定義操作」を参照してください。

- REFの取出しおよびその確保を示すコード例については、Oracleのインストールに付属のデモンストレーション・プログラムを参照してください。詳細は、付録Bを参照してください。

オブジェクトの確保

フェッチを行うステップが完了すると、アプリケーションでは、オブジェクトへのREF、つまりポインタを取得します。この時点ではまだ実際のオブジェクトは操作できません。オブジェクトを操作する前にオブジェクトを確保する必要があります。オブジェクトの確保では、オブジェクト・インスタンスをオブジェクト・キャッシュにロードすることにより、必要に応じて、インスタンスの属性へのアクセスおよび変更や、1オブジェクトからその他のオブジェクトへの参照追跡を可能にします。さらにアプリケーションでは、変更したオブジェクトをいつサーバーに書き込むか制御することもできます。

注意:
この項では、一度に1つのオブジェクトを確保する単純な操作の例を示します。複合オブジェクト検索を介した複数オブジェクトの取出しの詳細は、「複合オブジェクト検索」を参照してください。

アプリケーションでオブジェクトを確保するには、関数OCIObjectPin()をコールします。この関数のパラメータでは、オブジェクトの確保オプション、確保時間およびロック・オプションを指定できます。

例11-3は、前の「サーバーからのオブジェクト参照の取出し」の項でアプリケーションにより取り出された従業員参照に対する確保操作を説明するサンプル・コードです。

例11-3 オブジェクトの確保

if (OCIObjectPin(env, err, emp1_ref, (OCIComplexObject *) 0,
OCI_PIN_ANY,
OCI_DURATION_TRANS,
OCI_LOCK_X,  &emp1) != OCI_SUCCESS)
process_error(err);

この例のprocess_error()はエラー処理関数を表しています。OCIObjectPin()関数で、OCI_SUCCESS以外の値が戻された場合、このエラー処理関数がコールされます。OCIObjectPin()関数のパラメータは次のとおりです。

- envはOCI環境ハンドルです。

- errはOCIエラー・ハンドルです。

- emp1_refは、SQLによって取り出された参照です。

- (OCIComplexObject *)0は、このPINオペレーションで複合オブジェクト検索を行わないことを示します。

- OCI_PIN_ANYはPINオプションです。詳細は、「オブジェクト・コピーの確保」を参照してください。

- OCI_DURATION_TRANSは確保継続時間です。詳細は、「オブジェクト継続時間」を参照してください。

- OCI_LOCK_Xはロック・オプションです。詳細は、「更新するためのオブジェクトのロック」を参照してください。

- emp1は出力パラメータで、確保したオブジェクトへのポインタを戻します。

これでオブジェクトが確保され、OCIアプリケーションでは、そのオブジェクトを変更できます。この単純な例では、オブジェクトは他のオブジェクトへの参照を含んでいません。

関連項目:
1つのインスタンスから別のインスタンスへのナビゲーションの例は、「単純なオブジェクト・ナビゲーション」を参照してください。

配列確保

OCIアプリケーションでは、OCIObjectArrayPin()をコールすることによって、参照の配列にはオブジェクトの配列を確保できます。参照は、異なる種類のオブジェクトを指し示すことができます。この関数によって、異なる表から異なる型のオブジェクトを1回のネットワーク・ラウンドトリップでフェッチできます。

オブジェクト属性の操作

これでオブジェクトが確保され、OCIアプリケーションでは、その属性を変更できます。OCIには、オブジェクト型構造体のデータ型を操作する一連の関数である、OCIデータ型マッピング関数および操作関数があります。

注意:
オブジェクト・キャッシュ内に確保されているオブジェクトに対して変更を加えた場合、影響を受けるのはそのオブジェクトのコピー(インスタンス)のみで、データベース内の元のオブジェクトは影響を受けません。アプリケーションで行った変更をデータベースに反映するには、変更内容をサーバーにフラッシュまたはコミットする必要があります。詳細は、「オブジェクトのマークおよび変更のフラッシュ」を参照してください。

たとえば、従業員給与を増額できるよう前項で従業員オブジェクトを確保したとします。また、この会社では、入社して180日間未満の従業員には、年間昇給率が案分比例されるとします。

この例の場合、従業員の入社日にアクセスし、現在の日付の180日前より前か後かをチェックする必要があります。その計算を基盤として、従業員の給与を$5000 (180日より前)または$3000 (180日より後)分増額します。例11-4のサンプル・コードでは、このプロセスを説明しています。

データ型マッピング関数および操作関数で操作できるのは特定のいくつかのデータ型であり、int型などのその他の型は、適切なOCI型に変換しなければ計算で使用できないことに注意してください。

例11-4 OCIでのオブジェクト属性の操作

/* assume that sysdate has been fetched into sys_date, a string. */
/* emp1 and emp1_ref are the same as in previous sections. */
/* err is the OCI error handle. */
/* NOTE: error handling code is not included in this example. */

sb4 num_days;        /* the number of days between today and hiredate */
OCIDate curr_date;          /* holds the current date for calculations */
int raise;   /* holds the employee's raise amount before calculations */
OCINumber raise_num;       /* holds employee's raise for calculations */
OCINumber new_sal;                 /* holds the employee's new salary */

/* convert date string to an OCIDate */
OCIDateFromText(err, (text *) sys_date, (ub4) strlen(sys_date), (text *)
NULL, (ub1) 0, (text *) NULL, (ub4) 0, &curr_date);

/* get number of days between hire date and today */
OCIDateDaysBetween(err, &curr_date, &emp1->hiredate, &num_days);

/* calculate raise based on number of days since hiredate */
if (num_days > 180)
raise = 5000;
else
raise = 3000;

/* convert raise value to an OCINumber */
OCINumberFromInt(err, (void  *)&raise, (uword)sizeof(raise),
OCI_NUMBER_SIGNED, &raise_num);

/* add raise amount to salary */
OCINumberAdd(err, &raise_num, &emp1->salary, &new_sal);
OCINumberAssign(err, &new_sal, &emp1->salary);

例11-4は、値をパラメータとしてOCIデータ型マッピング関数および操作関数に渡す前に、どのようにOCIデータ型(OCIDate、OCINumberなど)に変換する必要があるかを示しています。

関連項目:
OCIデータ型とデータ型マッピング関数および操作関数の詳細は、第12章を参照してください。

オブジェクトのマークおよび変更のフラッシュ

例11-4では、1つのオブジェクト・インスタンスの1つの属性が変更されました。ただし、この時点では変更はクライアント側のオブジェクト・キャッシュにのみ存在しています。変更をデータベースに確実に書き込むために、アプリケーションで特定のステップを実行する必要があります。

最初のステップでは、オブジェクトが変更されたことを示します。これは、OCIObjectMarkUpdate()関数を使用して行います。この関数は、オブジェクトに使用済(変更済)のマークを付けます。

使用済フラグが設定されているオブジェクトは、変更をデータベースに記録するために、サーバーにフラッシュする必要があります。次の3つの方法でこれを実行します。

- 単一の使用済オブジェクトは、OCIObjectFlush()をコールしてフラッシュします。

- OCICacheFlush()を使用して、キャッシュ全体をフラッシュします。この場合、OCIはキャッシュで管理されている使用済リストを横断して、使用済オブジェクトをサーバーにフラッシュします。

- OCITransCommit()をコールして、トランザクションをコミットします。この方法でも、使用済リストを横断して使用済オブジェクトをサーバーにフラッシュします。

フラッシュ操作は、キャッシュの永続オブジェクトのみに作用します。一時オブジェクトはサーバーにフラッシュされません。

オブジェクトをサーバーにフラッシュすることで、データベースのトリガーをアクティブにすることができます。実際、アプリケーションでオブジェクトを明示的にフラッシュし、サーバー側のトリガーを起動することが必要な場合があります。

関連項目:

- OCITransCommit()の詳細は、「OCIでのトランザクションのサポート」を参照してください。

- 一時オブジェクトと永続オブジェクトの詳細は、「オブジェクトの作成」を参照してください。

- オブジェクトのメタ属性(dirtyなど)の表示およびチェックの詳細は、「オブジェクトのメタ属性」を参照してください。

埋込みオブジェクトのフェッチ

使用しているアプリケーションで、埋込みオブジェクト・インスタンス(オブジェクト表でなく、通常の表の列に格納されているオブジェクト)をフェッチする必要がある場合、「サーバーからのオブジェクト参照の取出し」で説明されているREF検索機能は使用できません。埋込みインスタンスにはオブジェクト識別子がないため、埋込みインスタンスへのREFは取得できません。また、オブジェクト・ナビゲーションの基本としても機能できません。ただし、アプリケーションで埋込みインスタンスをフェッチする必要がある状況は多数存在します。

たとえば、address型が作成されたとします。

CREATE TYPE address AS OBJECT
( street1             varchar2(50),
street2             varchar2(50),
city                varchar2(30),
state               char(2),
zip                 number(5));

これで、その型を他の表で列のデータ型として使用することができます。

CREATE TABLE clients
( name          varchar2(40),
addr          address);

OCIアプリケーションで次のSQL文を発行します。

SELECT addr FROM clients
WHERE name='BEAR BYTE DATA MANAGEMENT'

この文は、clients表の埋込みオブジェクトaddressを戻します。アプリケーションでは、このオブジェクトの属性値を別の処理で使用できます。

アプリケーションでは、第2章で説明したリレーショナルSQL文の操作と同じ方法で、この文を準備し処理します。

- OCIStmtPrepare2()を使用してアプリケーション要求を準備します。

- 1つ以上の適切なバインド・コールを使用して、入力変数をバインドします。

- addressインスタンスを受け取る出力変数を定義します。「Cアプリケーションでのオブジェクトの表現」で説明するとおり、OTTで生成されたオブジェクト型のC構造体表現を使用します。

addr1      *address; /* variable of the address struct type */

出力変数の定義時に、定義コールのdtyデータ型パラメータを、名前付きデータ型のデータ型定数、SQLT_NTYに設定します。

- OCIStmtExecute()で文を実行します。

- OCIStmtFetch2()を使用して、結果のインスタンスをaddr1にフェッチします。

次に、「オブジェクト属性の操作」で説明しているように、インスタンスの属性にアクセスするか、あるいはインスタンスを別のSQL文の入力パラメータとして渡すことができます。

注意:
埋込みインスタンスに対する変更内容は、SQLのUPDATE文の実行によってのみ永続的にできます。

関連項目:
SQL文の準備と実行の詳細は、「OCIプログラミング・ステップ」を参照してください。

オブジェクトのメタ属性

オブジェクトのメタ属性には、オブジェクトの状態に関する情報を、アプリケーションまたはオブジェクト・キャッシュに提供できるフラグの役割があります。たとえば、オブジェクトのメタ属性の1つとして、オブジェクトがサーバーにフラッシュ済かどうかを示す属性があります。オブジェクトのメタ属性は、アプリケーションでインスタンスの動作を制御するのに役立ちます。

永続オブジェクトのインスタンスと一時オブジェクトのインスタンスには、それぞれ異なるメタ属性があります。永続オブジェクトのメタ属性は、さらに永続メタ属性と一時メタ属性に分かれます。一時メタ属性は、インスタンスがメモリー内にあるときにのみ存在します。永続メタ属性は、サーバーに格納されているオブジェクトにも適用されます。

永続オブジェクトのメタ属性

表11-1に、スタンドアロン永続オブジェクトのメタ属性を示します。

表11-1 永続オブジェクトのメタ属性

メタ属性

意味

既存

オブジェクトが存在しているか

NULL

インスタンスのNULL情報

ロック

オブジェクトはロックされているか

使用済

オブジェクトに使用済のマークが設定されているか

確保済

オブジェクトは確保済か

割当て時間

「オブジェクト継続時間」を参照してください。

確保継続時間

「オブジェクト継続時間」を参照してください。

注意:
埋込み永続オブジェクトは、NULLおよび割当て期間属性のみを持つことができ、これらは一時的です。

OCIには、アプリケーションでオブジェクトの様々な属性のステータスをチェックできるOCIObjectGetProperty()関数があります。この関数の構文は次のとおりです。

sword OCIObjectGetProperty ( OCIEnv              *envh,
OCIError            *errh,
const void          *obj,
OCIObjectPropId     propertyId,
void                *property,
ub4                 *size );

propertyIdおよびpropertyパラメータは、どんな種類のプロパティまたは属性に関する情報の取出しにも使用されます。

この後、異なるプロパティIDとそれに対応するproperty引数の型が続きます。

関連項目:
「OCIObjectGetProperty()」

OCI_OBJECTPROP_LIFETIME

このプロパティによって、指定されたオブジェクトが永続オブジェクト、一時オブジェクト、または値のインスタンスかのいずれであるかが識別されます。property引数はOCIObjectLifetime型の変数へのポインタにしてください。可能な値は、次のとおりです。

- OCI_OBJECT_PERSISTENT

- OCI_OBJECT_TRANSIENT

- OCI_OBJECT_VALUE

OCI_OBJECTPROP_SCHEMA

このプロパティによって、オブジェクトが存在する表のスキーマ名が戻されます。指定されたオブジェクトが一時インスタンスまたは値を指し示している場合は、エラーが戻されます。スキーマ名の保持に入力バッファのサイズが足りない場合は、エラーが戻され、エラー・メッセージで必要なサイズが表示されます。成功した場合は、sizeによって、戻されたスキーマ名のサイズがバイト単位で戻されます。property引数は、text型の配列にし、コール元は、sizeをバイト単位で配列のサイズに設定する必要があります。

OCI_OBJECTPROP_TABLE

このプロパティによってそのオブジェクトが存在する表名が戻されます。指定されたオブジェクトが一時インスタンスまたは値を指し示している場合は、エラーが戻されます。表名の保持に入力バッファのサイズが足りない場合は、エラーが戻され、エラー・メッセージで必要なサイズが表示されます。成功した場合は、sizeによって、戻された表名のサイズがバイト単位で戻されます。property引数は、text型の配列にし、コール元は、sizeをバイト単位で配列のサイズに設定する必要があります。

OCI_OBJECTPROP_PIN_DURATION

このプロパティによってオブジェクトの確保継続時間が戻されます。指定されたオブジェクトが値のインスタンスを指し示している場合は、エラーが戻されます。property引数はOCIDuration型の変数へのポインタにしてください。次の値が有効です。

- OCI_DURATION_SESSION

- OCI_DURATION_TRANS

OCI_OBJECTPROP_ALLOC_DURATION

このプロパティによって、オブジェクトの割当て時間が戻されます。property引数はOCIDuration型の変数へのポインタにしてください。次の値が有効です。

- OCI_DURATION_SESSION

- OCI_DURATION_TRANS

関連項目:
継続期間の詳細は、「オブジェクト継続時間」を参照してください。

OCI_OBJECTPROP_LOCK

このプロパティによってオブジェクトのロック状況が戻されます。可能なロック状況は、OCILockOptで示されます。指定されたオブジェクトが一時インスタンスまたは値インスタンスを指し示している場合は、エラーが戻されます。property引数はOCILockOpt型の変数へのポインタにしてください。オブジェクトのロック状況は、OCIObjectIsLocked()関数をコールしても取り出せます。

OCI_OBJECTPROP_MARKSTATUS

これによって使用済ステータスが戻され、オブジェクトが新規のオブジェクトであるか、更新されたオブジェクトであるか、削除されたオブジェクトであるかが示されます。指定されたオブジェクトが一時インスタンスまたは値インスタンスを指し示している場合は、エラーが戻されます。property引数はOCIObjectMarkStatus型にしてください。次の値が有効です。

- OCI_OBJECT_NEW

- OCI_OBJECT_DELETED

- OCI_OBJECT_UPDATED

次のマクロを使用してマーク状態をテストすることが可能です。

- OCI_OBJECT_IS_UPDATED (flag)

- OCI_OBJECT_IS_DELETED (flag)

- OCI_OBJECT_IS_NEW (flag)

- OCI_OBJECT_IS_DIRTY (flag)

OCI_OBJECTPROP_VIEW

このプロパティによって指定されたオブジェクトがオブジェクト・ビューであるかどうかが識別されます。戻されたプロパティ値がTRUEの場合、そのオブジェクトはビューであり、そうでない場合はビューではありません。指定されたオブジェクトが一時インスタンスまたは値インスタンスを指し示している場合は、エラーが戻されます。property引数はboolean型にしてください。

ビューが仮想表であるのと同様に、オブジェクト・ビューは仮想オブジェクト表です。ビューの各行はオブジェクトであるため、メソッドのコール、ドット表記法を使用したオブジェクト属性へのアクセスおよびオブジェクトを指すREFの作成が可能です。

その他の属性関数

表11-2に示すように、OCIには、アプリケーションでこれらの属性を直接的または間接的に設定あるいはチェックできる関数が提供あります。

表11-2 設定およびチェック関数

メタ属性

設定に使用する関数

チェックに使用する関数

NULL

<なし>

OCIObjectGetInd()

存在

<なし>

OCIObjectExists()

ロック

OCIObjectLock()

OCIObjectIsLocked()

使用済

OCIObjectMarkUpdate()

OCIObjectIsDirty()

一時オブジェクトのメタ属性

一時オブジェクトには、永続的属性はありません。表11-3では、一時属性を示しています。

表11-3 一時メタ属性

一時メタ属性

意味

既存

オブジェクトが存在しているか

確保済

オブジェクトはアプリケーションによってアクセスされるか

使用済

オブジェクトに使用済のマークが設定されているか

NULL

インスタンスのNULL情報。

割当て時間

「オブジェクト継続時間」を参照してください。

確保継続時間

「オブジェクト継続時間」を参照してください。

複合オブジェクト検索

例11-3と例11-4では、一度に1つのインスタンスのみがフェッチまたは確保されました。これらの場合、オブジェクトを取り出すためのサーバー・ラウンドとリップが、確保操作ごとに必要でした。

オブジェクト指向のアプリケーションでは、その問題点を、オブジェクト・グラフを形成する相互関連オブジェクトの集合としてモデル化する場合があります。アプリケーションは、いくつかのイニシャル・オブジェクトの集合から始めて、これらのイニシャル・オブジェクトの参照を使用して残りのオブジェクトを横断することにより、オブジェクトを処理します。クライアント/サーバー設定では、各トラバースがオブジェクトをフェッチするために、ネットワーク・ラウンドトリップを引き起こします。

オブジェクトに対するアプリケーションのパフォーマンスは、複合オブジェクト検索(COR)で向上します。これはプリフェッチ・メカニズムであり、アプリケーションでは、このメカニズムを使用して、リンクされた一連のオブジェクトを1回の操作で取り出すための基準を指定します。

注意:
後述するように、プリフェッチ・オブジェクトがすべて確保されているとはかぎりません。それらはオブジェクト・キャッシュ内にフェッチされるため、後続の確保コールはローカル操作で行われます。

複合オブジェクトは、論理的に関連した複数のオブジェクトの集合で、1つのルート・オブジェクトと、指定したネスト・レベルに基づいてそれぞれプリフェッチされた一連のオブジェクトで構成されています。ルート・オブジェクトは、明示的にフェッチされるか、または確保されます。ネスト・レベルは、複合オブジェクトのルート・オブジェクトから指定のプリフェッチ・オブジェクトまで最短で横断した場合の参照の数です。

アプリケーションで複合オブジェクトを指定するときは、複合オブジェクトの内容と境界を記述します。複合オブジェクトのフェッチは、環境のプリフェッチ制限、およびオブジェクトのプリフェッチに使用可能な、オブジェクト・キャッシュ内のメモリーの量によって制約されます。

注意:
CORの使用で機能は加わりませんが、パフォーマンスは向上します。その使用はオプションです。

次の型宣言を考えてみます。

CREATE TYPE customer(...);
CREATE TYPE line_item(...);
CREATE TYPE line_item_varray as VARRAY(100) of REF line_item;
CREATE TYPE purchase_order AS OBJECT
( po_number         NUMBER,
cust              REF customer,
related_orders    REF purchase_order,
line_items        line_item_varray);

purchase_order型には、スカラー値po_number、VARRAYのline_itemsおよび2つの参照が含まれています。1つはcustomer型への参照、もう1つはpurchase_order型への参照であり、この型がリンク済リストとして実装されることを示しています。

複合オブジェクトをフェッチする場合は、アプリケーションで次の指定をする必要があります。

- 目的のルート・オブジェクトへのREF。

- 複合オブジェクトの境界を指定するための1組以上の型およびネストの情報。型情報は、CORでたどるREF属性を示し、ネスト・レベルはリンクをたどるレベル数を示します。

前述の発注情報オブジェクトの場合は、アプリケーションで次の指定をする必要があります。

- ルート発注情報オブジェクトへのREF。

- cust、related_ordersまたはline_itemsについての1組以上の型およびネストの情報。

発注情報をフェッチするアプリケーションでは、その注文の顧客情報へのアクセスが必要になることも十分考えられます。単純なナビゲーションでは、2つのオブジェクトをフェッチするためにサーバーに2回アクセスすることが必要です。複合オブジェクト検索によって、発注情報を確保するときに顧客をプリフェッチできます。この場合、複合オブジェクトは、発注情報オブジェクトと参照する顧客のオブジェクトで構成されます。

前の例では、アプリケーションはREFにpurchase_orderを指定し、cust REF属性を、次のように、ネスト・レベル1までたどるように指示します。

- REF(PO object)

- {(customer, 1)}

アプリケーションで、purchase_orderオブジェクトと、オブジェクト・グラフに含まれるすべてのオブジェクトをプリフェッチする必要がある場合、custおよびrelated_ordersは両方とも、最大のネスト・レベルまでたどるようにアプリケーションで指示します。

- REF(PO object)

- {(customer, UB4MAXVAL), (purchase_order, UB4MAXVAL)}

(この例では、UB4MAXVALは、ルート・オブジェクトから参照を通して到達できる指定の型のオブジェクトすべてのプリフェッチを指定します。)

アプリケーションで、POおよび関連する明細項目すべてをフェッチする場合は、次の指定をします。

- REF(PO object)

- {(line_item, 1)}

アプリケーションでは、目的の深さまでのレベル・パラメータを設定することにより、REFを通してルート・オブジェクトから到達可能な(推移閉包)すべてのオブジェクトをフェッチすることもできます。前の2つの例では、それぞれアプリケーションで(PO object REF, UB4MAXVAL)と(PO object REF, 1)を指定して、必要なオブジェクトをプリフェッチすることもできます。この場合は多数のフェッチが余計に発生しますが、指定が非常に簡単であり、サーバー・ラウンドトリップが1回のみですみます。

オブジェクトのプリフェッチ

複合オブジェクトを指定してフェッチした後に行う、複合オブジェクトに含まれるオブジェクトのフェッチでは、これらのオブジェクトがすでにプリフェッチ済であり、オブジェクト・キャッシュ内にあるため、ネットワーク・ラウンドトリップは発生しません。プリフェッチするオブジェクトが多すぎると、オブジェクト・キャッシュがあふれる可能性があることを考慮します。あふれると、アプリケーションですでに確保している他のオブジェクトがキャッシュから押し出され、パフォーマンスの向上ではなく逆にパフォーマンスの低下につながることがあります。

注意:
プリフェッチ・オブジェクトすべてを保持するためのメモリーがキャッシュにない場合は、オブジェクトの一部がプリフェッチされない場合があります。アプリケーションでは、後でそれらのオブジェクトにアクセスするとき、ネットワーク・ラウンドトリップが発生します。

プリフェッチ・オブジェクトすべてに、SELECT権限が必要です。複合オブジェクト内のオブジェクトに対するSELECT権限がアプリケーションにない場合、そのオブジェクトはプリフェッチできません。

OCIでの複合オブジェクト検索の実装

複合オブジェクト検索(COR)によって、アプリケーションは、ルート・オブジェクトをフェッチするときに複合オブジェクトのプリフェッチができます。単純オブジェクトに対して使用するのと同じOCIObjectPin()関数に、複合オブジェクト指定を渡します。

アプリケーションは、複合オブジェクト検索ハンドルを使用して、複合オブジェクト検索用のパラメータを指定します。このハンドルは、OCIComplexObject型であり、その他のOCIハンドルと同じ方法で割り当てます。

複合オブジェクト検索ハンドルには、複合オブジェクト検索記述子のリストが含まれています。記述子はOCIComplexObjectComp型であり、その他のOCI記述子と同じ方法で割り当てます。

各COR記述子には、REF型とネスト・レベルが含まれています。REF型では、複合オブジェクトを組み立てるときにたどる参照の型を指定します。ネスト・レベルで、特定の型の参照をどこまでたどるかを指定します。ネスト・レベルの最大値には、整数値または定数UB4MAXVALを指定します。

また、アプリケーションは、型および深さのパラメータに対してCOR記述子を作成せずに、CORハンドル内で深さレベルも指定できます。この場合、すべてのREFは、CORハンドルで指定した深さまでたどられます。また、CORハンドルを使用して、包含するオブジェクトとともにコレクション属性をフェッチする(表内)デフォルトのケースとは反対に、オンデマンドで別個にフェッチする(表外)必要があるかどうかも指定できます。

アプリケーションでCORハンドルの属性を設定するには、OCIAttrSet()を使用します。次の属性があります。

OCI_ATTR_COMPLEXOBJECT_LEVEL－ ネスト・レベル

OCI_ATTR_COMPLEXOBJECT_COLL_OUTOFLINE－ オブジェクト型のコレクション属性をアウト・ラインでフェッチ

アプリケーションで、OCIDescriptorAlloc()を使用してCOR記述子を割り当て、次の属性を設定できます。

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE－REF型

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE_LEVEL－ 前述の型の参照に使用するネスト・レベル

これらの属性を設定すると、アプリケーションではOCIParamSet()をコールして記述子を複合オブジェクト検索ハンドルに設定します。ハンドルにはハンドルの記述子の数を指定するOCI_ATTR_PARAM_COUNT属性があります。この属性はOCIAttrGet()で読み取ることができます。

ハンドルに記述子を挿入した後、ハンドルをOCIObjectPin()コールに渡してルート・オブジェクトを確保し、複合オブジェクトの残りのオブジェクトのプリフェッチを行います。

複合オブジェクト検索ハンドルと記述子は、必要がなくなったとき、明示的に解放する必要があります。

関連項目:

- 「ハンドル」

- 「OCI記述子」

CORプリフェッチ

アプリケーションでは、ルート・オブジェクトのフェッチ時に複合オブジェクトを指定します。プリフェッチ・オブジェクトは、指定のルート・オブジェクトを基点とするオブジェクトのグラフに対して、幅優先横断を実行することによって取得されます。トラバースは、すべての必須オブジェクトがプリフェッチされたか、またはプリフェッチされたすべてのオブジェクトの合計サイズがプリフェッチ制限を超えたときに停止します。

CORインタフェース

複合オブジェクトをフェッチするためのインタフェースは、OCI確保インタフェースです。アプリケーションは、初期化済のCORハンドルをOCIObjectPin()に(またはハンドルの配列をOCIObjectArrayPin()に)渡して、ルート・オブジェクト、およびCORハンドルで指定したプリフェッチ・オブジェクトをフェッチすることができます。

sword OCIObjectPin ( OCIEnv              *env,
OCIError            *err,
OCIRef              *object_ref,
OCIComplexObject    *corhdl,
OCIPinOpt           pin_option,
OCIDuration         pin_duration,
OCILockOpt          lock_option,
void                **object );

sword OCIObjectArrayPin ( OCIEnv            *env,
OCIError          *err,
OCIRef            **ref_array,
ub4               array_size,
OCIComplexObject  **cor_array,
ub4               cor_array_size,
OCIPinOpt         pin_option,
OCIDuration       pin_duration,
OCILockOpt        lock,
void              **obj_array,
ub4               *pos );

CORの使用時には、次の点について留意してください。

- NULLのCORハンドル引数は、デフォルトでルート・オブジェクトのみを確保します。

- ルート・オブジェクト型でネスト・レベル0のCORハンドルは、ルート・オブジェクトのみをフェッチし、NULLのCORハンドルに相当します。

- ロック・オプションは、ルート・オブジェクトのみに適用されます。

注意:
プリフェッチ・オブジェクトにロック・オプションを指定するために、アプリケーションでは配列インタフェース(OCIObjectArrayPin())を使用して、複合オブジェクト内のオブジェクトすべてにアクセスし、REFの配列を作成し、別のラウンドトリップで複合オブジェクト全体をロックできます。

CORの例

例11-5では、複合オブジェクト検索を行うためにアプリケーション・プログラムを修正する方法を説明します。

発注情報とそれに関連した明細項目を表示するアプリケーションを考えてみます。太字のコードでこの処理を実行します。残りのコードでは、プリフェッチの複合オブジェクト検索を使用するため、アプリケーションのパフォーマンスが向上します。

例11-5 OCIでの複合オブジェクト検索の使用

OCIEnv *envhp;
OCIError *errhp;
OCIRef **liref;
OCIRef *poref;
OCIIter *itr;
boolean  eoc;
purchase_order *po = (purchase_order *)0;
line_item *li = (line_item *)0;
OCISvcCtx *svchp;
OCIComplexObject *corhp;
OCIComplexObjectComp *cordp;
OCIType *litdo;
ub4 level = 0;

/* get COR Handle */
OCIHandleAlloc((void  *) envhp, (void  **) &corhp, (ub4)
OCI_HTYPE_COMPLEXOBJECT, 0, (void  **)0);

/* get COR descriptor for type line_item */
OCIDescriptorAlloc((void  *) envhp, (void  **) &cordp, (ub4)
OCI_DTYPE_COMPLEXOBJECTCOMP, 0, (void  **) 0);

/* get type of line_item to set in COR descriptor */
OCITypeByName(envhp, errhp, svchp, (const text *) 0, (ub4) 0,
(const text *) "LINE_ITEM",
(ub4) strlen((const char *) "LINE_ITEM"), (text *) 0,
(ub4) 0, OCI_DURATION_SESSION,
OCI_TYPEGET_HEADER, &litdo);

/* set line_item type in COR descriptor */
OCIAttrSet( (void  *) cordp, (ub4) OCI_DTYPE_COMPLEXOBJECTCOMP,
(void  *) litdo, (ub4) sizeof(void  *), (ub4)
OCI_ATTR_COMPLEXOBJECTCOMP_TYPE, (OCIError *) errhp);
level = 1;

/* set depth level for line_item_varray in COR descriptor */
OCIAttrSet( (void  *) cordp, (ub4) OCI_DTYPE_COMPLEXOBJECTCOMP,
(void  *) &level, (ub4) sizeof(ub4), (ub4)
OCI_ATTR_COMPLEXOBJECTCOMP_TYPE_LEVEL, (OCIError *) errhp);

/* put COR descriptor in COR handle */
OCIParamSet(corhp, OCI_HTYPE_COMPLEXOBJECT, errhp, cordp,
OCI_DTYPE_COMPLEXOBJECTCOMP, 1);

/* pin the purchase order */
OCIObjectPin(envhp, errhp, poref, corhp, OCI_PIN_LATEST,
OCI_DURATION_SESSION, OCI_LOCK_NONE, (void  **)&po);

/* free COR descriptor and COR handle */
OCIDescriptorFree((void  *) cordp, (ub4) OCI_DTYPE_COMPLEXOBJECTCOMP);
OCIHandleFree((void  *) corhp, (ub4) OCI_HTYPE_COMPLEXOBJECT);

/* iterate and print line items for this purchase order */
OCIIterCreate(envhp, errhp, po->line_items, &itr);

/* get first line item */
OCIIterNext(envhp, errhp, itr, (void  **)&liref, (void  **)0, &eoc);
while (!eoc)        /* not end of collection */
{
/* pin line item */
OCIObjectPin(envhp, errhp, *liref, (void  *)0, OCI_PIN_RECENT,
OCI_DURATION_SESSION,
OCI_LOCK_NONE, (void  **)&li));
display_line_item(li);

/* get next line item */
OCIIterNext(envhp, errhp, itr, (void  **)&liref, (void  **)0, &eoc);
}

OCIとSQLのオブジェクトへのアクセス

アプリケーションで複数オブジェクト(オブジェクト参照によって相互に関連)のグラフを操作する必要がある場合は、オブジェクトへのアクセスに、SQLインタフェースよりもOCIインタフェースを使用する方が効率的です。SQLインタフェースを使用してオブジェクトのグラフを取り出すには、複数のSELECT文の実行、つまり、複数のネットワーク・ラウンドトリップが必要になる場合があります。OCIによって提供される複合オブジェクト検索機能を使用すると、アプリケーションは1つのOCIObjectPin()コール内で複数のオブジェクトのグラフを取り出せます。

アプリケーションでオブジェクトのグラフを取り出し、それをユーザーとの対話を基に変更して、その変更をデータベース内に持続させる場合の更新について考えてみます。SQLインタフェースを使用する場合、アプリケーションではオブジェクトのグラフの更新に複数のUPDATE文を実行する必要があります。新しいオブジェクトの作成と既存のオブジェクトの削除が変更に含まれている場合は、対応するINSERT文およびDELETE文も実行する必要があります。さらに、アプリケーションでは、表名の変更状況など、INSERT文、UPDATE文またはDELETE文の実行に必要な、さらに多くの情報を記録する必要があります。

OCIのOCICacheFlush()関数を使用すると、アプリケーションですべての変更(オブジェクトの挿入、削除および更新)を単一の操作でフラッシュできます。OCIではすべてが記録されるので、アプリケーションでのコーディングは少なくてすみます。オブジェクトのグラフの操作にOCIを使用すると、効率的なだけでなく使用しやすいインタフェースが提供されます。

たとえば、アプリケーションでREFを使用してオブジェクトをフェッチする必要がある場合を考えてみます。OCIの場合、このフェッチは、OCIObjectPin()コールを使用してそのオブジェクトを確保することで、実行されます。SQLインタフェースの場合、これは、SELECT文(たとえば、SELECT DEREF(ref) from tbl;)のREFを参照解除することで実行されます。同じREF (同じオブジェクトへの参照)が1つのトランザクション内で複数回参照解除されるような状況について考えてみます。OCI_PIN_RECENTオプションとともにOCIObjectPin()をコールすると、トランザクションに対してオブジェクトがサーバーから1度のみフェッチされ、同じREFで確保が繰り返し行われる結果、すでにキャッシュ内に確保されているオブジェクトへのポインタが戻されます。SQLインタフェースでは、SELECT DEREF...文を実行するたびに、サーバーからオブジェクトをフェッチすることになります。その結果、サーバーへのラウンドトリップは複数回になり、同じオブジェクトのコピーが複数になります。

最後に、アプリケーションで参照不可能なオブジェクトを次の例のようにフェッチする必要がある場合を考えてみます。

CREATE TABLE department
(
deptno number,
deptname varchar2(30),
manager employee_t
);

manager列に格納されているemployee_tインスタンスは参照不可能です。SQLインタフェースを使用できるのは、manager列インスタンスをフェッチする場合にかぎります。ただし、employee_tにREF属性がある場合は、OCIコールを使用してREFをナビゲートできます。

確保カウントおよび確保解除

オブジェクト・キャッシュ内の各オブジェクトには、関連する確保カウントがあります。確保カウントは、オブジェクトに並行アクセスするコード・モジュールの数を表します。オブジェクトを初めてキャッシュに確保したときに、確保カウントが1に設定されます。複合オブジェクト検索でプリフェッチ・オブジェクトをオブジェクト・キャッシュに入れた時点では、オブジェクトの確保カウントは0 (ゼロ)です。

確保済のオブジェクトを確保することができます。そうすると、確保カウントが1増えます。プロセスでオブジェクトの使用が終了したときは、 OCIObjectUnpin()を使用して確保解除を行う必要があります。このコールによって確保カウントが1減ります。

オブジェクトの確保カウントが0 (ゼロ)になった場合、必要があればオブジェクトをキャッシュから出し、オブジェクトが占めているメモリー領域を解放できます。

オブジェクトの確保カウントは、OCIObjectPinCountReset()をコールして、明示的に0 (ゼロ)に設定できます。

アプリケーションではOCICacheUnpin()をコールして、キャッシュ内にある特定の接続に関連した全オブジェクトを確保解除できます。

関連項目:

- 確保カウントが0 (ゼロ)のオブジェクトがキャッシュから削除される場合の条件と、キャッシュからエージ・アウトされるオブジェクトの詳細は、「オブジェクト・コピーの解放」を参照してください。

- オブジェクトまたはキャッシュ全体の明示的なフラッシュの詳細は、「オブジェクトのマークおよび変更のフラッシュ」を参照してください。

NULLインジケータ構造体

データベース表で、行の中に値のない列がある場合、その列はNULLまたはNULLを含むと呼ばれます。オブジェクトには、次の2種類のNULLを適用できます。

- オブジェクトの属性はすべて、NULL値を持つことができます。これはオブジェクトの属性の値が不明であることを意味します。

- オブジェクトのインスタンスがアトミックNULLである場合、オブジェクト全体の値が不明であることを意味します。

アトミックNULLとは、オブジェクトが存在しないということではありません。アトミックNULLのインスタンスは、値が不明なだけで、存在しています。つまり、データを持たないオブジェクトとみなすことができます。

OCIでオブジェクトを操作する場合は、アプリケーションで使用する各オブジェクト型のNULLインジケータ構造体を定義できます。そのために必要な作業は、通常、OTTで生成したNULLインジケータ構造体を構造体宣言とともに組み込むことのみです。OTTの出力ヘッダー・ファイルを組み込むと、アプリケーションでNULLインジケータ構造体を使用できるようになります。

各型に対するNULLインジケータ構造体の内容は、アトミックNULLインジケータ (OCIInd型)とインスタンスの各属性のNULLインジケータです。型にオブジェクト属性がある場合、NULLインジケータ構造体には、その属性のNULLインジケータ構造体が含まれます。例11-6では、対応するNULLインジケータ構造体とともに型のC表現を示しています。

例11-6 型のC表現とそれらに対応するNULLインジケータ構造体

struct address
{
OCINumber    no;
OCIString    *street;
OCIString    *state;
OCIString    *zip;
};
typedef struct address address;

struct address_ind
{
OCIInd    _atomic;
OCIInd    no;
OCIInd    street;
OCIInd    state;
OCIInd    zip;
};
typedef struct address_ind address_ind;

struct person
{
OCIString      *fname;
OCIString      *lname;
OCINumber      age;
OCIDate        birthday;
OCIArray       *dependentsAge;
OCITable       *prevAddr;
OCIRaw         *comment1;
OCILobLocator  *comment2;
address        addr;
OCIRef         *spouse;
};
typedef struct person person;

struct person_ind
{
OCIInd        _atomic;
OCIInd        fname;
OCIInd        lname;
OCIInd        age;
OCIInd        birthday;
OCIInd        dependentsAge;
OCIInd        prevAddr;
OCIInd        comment1;
OCIInd        comment2;
address_ind   addr;
OCIInd        spouse;
};
typedef struct person_ind person_ind;

注意:
person_indのdependentsAgeフィールドは、VARRAY (personの配列dependentsAgeフィールド)全体がアトミックNULLかどうかを示します。dependentsAgeフィールドの個々の要素のNULL情報は、OCICollGetElem()のコールのelemindパラメータを通して取り出せます。同様に、person_indのprevAddrフィールドは、NESTED TABLE (personのprevAddrフィールド)全体がアトミックNULLかどうかを示します。prevAddrフィールドの個々の要素のNULL情報は、OCICollGetElem()のコールのelemindパラメータを通して取り出せます。

オブジェクト型インスタンスの場合は、NULLインジケータ構造体の最初のフィールドがアトミックNULLインジケータで、残りのフィールドはレイアウトがオブジェクト型インスタンスの属性に似ている属性NULLインジケータです。

アプリケーションでは、アトミックNULLインジケータの値をチェックすることで、インスタンスがアトミックNULLかどうかをテストできます。また、他のインスタンスをチェックすることで、次のコード例で示すように、アプリケーションでその属性のNULL状態をテストできます。

person_ind *my_person_ind
if( my_person_ind -> _atomic == OCI_IND_NULL)
printf ("instance is atomically NULL\n");
else
if( my_person_ind -> fname == OCI_IND_NULL)
printf ("fname attribute is NULL\n");

前述の例では、アトミックNULLインジケータまたは属性NULLインジケータの値が事前定義の値OCI_IND_NULLと比較され、NULLかどうかがテストされます。この比較では、事前定義済の次の値が使用可能です。

- OCI_IND_NOTNULL－ 値がNULLでないことを示します。

- OCI_IND_NULL－ 値がNULLであることを示します。

- OCI_IND_BADNULL－ 囲みオブジェクト(親オブジェクト)がNULLであることを示します。この値はPL/SQLで使用され、INVALID_NULLとしても参照されます。たとえば、型インスタンスがNULLの場合、その属性はINVALID_NULLです。

OCIObjectGetInd()関数を使用して、オブジェクトのNULLインジケータ構造体を取り出します。

C構造体内の属性を更新する場合、その属性のNULLインジケータも設定する必要があります。

obj->attr1 = string1;
OCIObjectGetInd(envhp, errhp, obj, &ind);
ind->attr1 = OCI_IND_NOTNULL;

関連項目:
OTT生成のNULLインジケータ構造体の詳細は、第15章を参照してください。

オブジェクトの作成

OCIアプリケーションでは、OCIObjectNew()を使用してあらゆるオブジェクトを作成できます。アプリケーションで永続オブジェクトを作成するには、新規オブジェクトを挿入するオブジェクト表を指定してください。この値は、OCIObjectPinTable()をコールして取り出し、tableパラメータで渡します。一時オブジェクトを作成するには、作成するオブジェクトの型に対する型記述子オブジェクト(OCIDescribeAny()をコールして取出し)のみを渡す必要があります。

また、typecodeパラメータに適切な値を渡し、OCIObjectNew()を使用して、スカラーのインスタンス(REF、LOB、文字列、ロー、数値、日付など)およびコレクション(VARRAYやNESTED TABLEなど)を作成できます。

新規オブジェクトの属性値

デフォルトでは、新規作成されたオブジェクトのすべての属性に NULL値があります。属性データを初期化した後で、対応する各属性のNULLステータスをNULL以外に変更する必要があります。

オブジェクトの作成時に、属性をNULL以外の値に設定できます。これは、OCIAttrSet()を使用して環境ハンドルのOCI_ATTR_OBJECT_NEWNOTNULL属性をTRUEに設定することによって実行できます。その後、この属性をFALSEに設定すると、このモードを無効にできます。

OCI_ATTR_OBJECT_NEWNOTNULLがTRUEに設定されている場合は、OCIObjectNew()によってNULL以外のオブジェクトが作成されます。オブジェクトの属性には、表11-4に示したデフォルト値があり、対応するNULLインジケータは、NOT NULLに設定されています。

表11-4 新しいオブジェクトの属性値

属性の型

デフォルト値

REF

オブジェクトにREF属性がある場合は、オブジェクトをフラッシュする前にこの属性を有効なREFに設定する必要があり、そうしないとエラーが戻されます。

DATE

Oracle Databaseで扱える最古の日付で、01-JAN-4712 BCE (ユリウス日の第1日)の午前0時。

ANSI DATE

Oracle Databaseで扱える最古の日付で、01-JAN-4712 BCE (ユリウス日の第1日)。

TIMESTAMP

Oracle Databaseで扱える最古の日時で、01-JAN-4712 BCE (ユリウス日の第1日)の午前0時。

TIMESTAMP WITH TIME ZONE

Oracle Databaseで扱える最古の日時で、UTC (0:0)タイム・ゾーンで、01-JAN-4712 BCE (ユリウス日の第1日)の午前0時。

TIMESTAMP WITH LOCAL TIME ZONE

Oracle Databaseで扱える最古の日時で、UTC (0:0)タイム・ゾーンで、01-JAN-4712 BCE (ユリウス日の第1日)の午前0時。

INTERVAL YEAR TO MONTH

INTERVAL '0-0' YEAR TO MONTH

INTERVAL DAY TO SECOND

INTERVAL '0 0:0:0' DAY TO SECOND

FLOAT

0

NUMBER

0

DECIMAL

0

RAW

長さが0に設定されたロー・データ。注意: RAW属性のデフォルト値は、NULL RAW属性のデフォルト値と同じです。

VARCHAR2, NVARCHAR2

長さが0で最初の文字がNULLに設定されたOCIString。デフォルト値は、NULL文字列属性のデフォルト値と同じです。

CHAR, NCHAR

長さが0で最初の文字がNULLに設定されたOCIString。デフォルト値は、NULL文字列属性のデフォルト値と同じです。

VARCHAR

長さが0で最初の文字がNULLに設定されたOCIString。デフォルト値は、NULL文字列属性のデフォルト値と同じです。

VARRAY

要素が0のコレクション

NESTED TABLE

要素が0の表

CLOB, NCLOB

空のCLOB

BLOB

空のBLOB

BFILE

ディレクトリ・オブジェクトおよびファイル名を設定することによって、BFILEを有効な値に初期化する必要があります。

オブジェクトの解放およびコピー

OCIObjectFree()を使用して、OCIObjectNew()で割り当てたメモリーを解放できます。オブジェクト・インスタンスには、追加メモリー(2次メモリー・チャンク)へのポインタである属性を設定できます。

関連項目:
「インスタンスのメモリー・レイアウト」

オブジェクトの解放とは、関連するNULLインジケータ構造体や2次メモリー・チャンクなど、オブジェクトに割り当てたすべてのメモリーの割当てを解除することです。2次メモリー・チャンクを明示的に解放したり、ポインタの再割当てをすることはできません。これは、メモリー・リークやメモリーの破損が発生する可能性があるためです。このプロシージャによって、一時オブジェクトが、存続期間内に削除されます(永続オブジェクトは削除されません)。アプリケーションでは、永続オブジェクトを削除するには、OCIObjectMarkDelete()を使用します。

アプリケーションでは、OCIObjectCopy()を使用して、1つのインスタンスを同じ型の別のインスタンスにコピーできます。

関連項目:
第18章「OCIのナビゲーショナル関数と型関数」

オブジェクト参照と型参照

アプリケーションでは、OCIのオブジェクト拡張機能を利用して、オブジェクトの内容に対してポインタや参照による柔軟なアクセスができます。OCIでは、オブジェクトのポインタを指定したとき、オブジェクトに対する参照を戻すOCIObjectGetObjectRef()関数を提供しています。

また、アプリケーションで、オブジェクトの型情報へのアクセスを行う場合は、OCIには、オブジェクトに対するポインタを指定すると、オブジェクトの型記述子オブジェクト(TDO)に対する参照を戻すOCIObjectGetProperty()関数があります。

システム生成オブジェクト識別子(OID)を備えたオブジェクト表に基づいて永続オブジェクトが生成されると、OCIObjectGetObjectRef()を使用してただちにこのオブジェクトへの参照を取得できます。ただし、永続オブジェクトがオブジェクト・ビューまたは主キー・ベースのOIDを備えたオブジェクト表に基づいている場合、主キーに属するすべての属性を設定してからでなければ参照は取得できません。

オブジェクト・ビューおよび主キー・ベースのOIDを備えたオブジェクト表に基づくオブジェクトの作成

アプリケーションで、OCIObjectNew()コールを使用して、オブジェクト・ビュー、または主キー・ベースのオブジェクト識別子(OID)を備えたオブジェクト表に基づいたオブジェクトを作成できます。このようなビューおよび表のオブジェクト識別子は属性値に基づいているため、アプリケーションでOCIObjectSetAttr()を使用して、主キーに属するすべての属性を設定する必要があります。属性値を設定すると、アプリケーションで、OCIObjectGetObjectRef()をコールすることによって、属性値に基づいたオブジェクト参照を取得できます。

この処理には、次のステップが必要です。

1. 新しいオブジェクトの基になるオブジェクト・ビューまたはオブジェクト表を確保します。

2. ステップ1の確保操作で取得した表またはビューに対するハンドルを渡し、OCIObjectNew()を使用して新しいオブジェクトを作成します。

3. OCIObjectSetAttr()を使用して、オブジェクト属性の必要な値を入力します。これらには、オブジェクト表またはオブジェクト・ビューのユーザー定義オブジェクト識別子を構成する属性を含める必要があります。

4. ステップ1の確保操作で取得した表またはビューに対するハンドルを渡し、OCIObjectNew()を使用してオブジェク参照を割り当てます。

5. 必要に応じて、OCIObjectGetObjectRef()を使用して主キーを基にしたオブジェクトへの参照を取得します。必要ならば、ステップ2に戻ってさらにオブジェクトを作成します。

6. 新しく作成されたオブジェクトをサーバーにフラッシュします。

例11-7では、このプロセスを実装して、HRスキーマ内のemp_viewオブジェクト・ビューに対して新しいオブジェクトを作成する方法を示します。

例11-7 オブジェクト・ビューに対する新規オブジェクトの作成

void object_view_new ()
{
void     *table;
OCIRef   *pkref;
void     *object;
OCIType  *emptdo;
...
/* Set up the service context, error handle and so on.. */
...
/* Pin the object view */
OCIObjectPinTable(envp,errorp,svctx, "HR", strlen("HR"), "EMP_VIEW",
strlen("EMP_VIEW"),(void  *) 0, OCI_DURATION_SESSION, (void  **) &table);

/* Create a new object instance  */
OCIObjectNew(envp, errorp, svctx, OCI_TYPECODE_OBJECT,(OCIType *)emptdo, table,
OCI_DURATION_SESSION,FALSE,&object);

/* Populate the attributes of "object" */
OCIObjectSetAttr(...);
...
/* Allocate an object reference */
OCIObjectNew(envp, errorp, svctx, OCI_TYPECODE_REF, (OCIType *)0, (void  *)0,
OCI_DURATION_SESSION,TRUE,&pkref);

/* Get the reference using OCIObjectGetObjectRef */
OCIObjectGetObjectRef(envp,errorp,object,pkref);
...
/* Flush new objects to server */
...
} /* end function */

オブジェクト・アプリケーションでのエラー処理

アプリケーションでオブジェクトを使用するかどうかにかかわらず、OCIアプリケーションでのエラー処理は同じです。関数のリターン・コードとエラー・メッセージの詳細は、「OCIでのエラー処理」を参照してください。

型の継承

オブジェクトの型継承には、C++およびJavaでの継承と類似した点が多くあります。オブジェクト型は、既存のオブジェクト型のサブタイプとして作成できます。サブタイプは、元の型であるスーパータイプのすべての属性とメソッド(メンバー関数とプロシージャ)を継承します。サポートされているのは1回の継承のみで、オブジェクトは複数のスーパータイプを持つことはできません。スーパータイプは、新規属性とメソッドを継承する属性とメソッドに追加します。また、継承されたメソッドのいずれかをオーバーライド(実装の再定義)することもできます。サブタイプは、そのスーパータイプを拡張(つまり、元から継承)します。

関連項目:
詳細は、『Oracle Databaseオブジェクト・リレーショナル開発者ガイド』を参照してください。

たとえば、Person_t型は、サブタイプStudent_tとサブタイプEmployee_tを所有できます。さらに、Student_tも独自のサブタイプPartTimeStudent_tを所有できます。サブタイプを所有するには、型宣言にフラグNOT FINALが必要です。デフォルトのフラグはFINALで、この型はサブタイプを所有できないことを意味します。

この章でこれまで説明した型は、すべてFINALです。Oracle Databaseリリース9.0より前に開発されたアプリケーションの型は、すべてFINALです。FINALの型は、NOT FINALに変更できます。サブタイプを所有しないNOT FINAL型は、FINALに変更できます。次の例では、Person_tがNOT FINALとして宣言されています。

CREATE TYPE Person_t AS OBJECT
( ssn NUMBER,
name VARCHAR2(30),
address VARCHAR2(100)) NOT FINAL;

サブタイプは、そのスーパータイプに宣言されたすべての属性およびメソッドを継承します。また、新規属性とメソッドを宣言することもできますが、これらの名前はスーパータイプの名前とは別のものにする必要があります。キーワードUNDERにより、次のようにスーパータイプを識別します。

CREATE TYPE Student_t UNDER Person_t
( deptid NUMBER,
major  VARCHAR2(30)) NOT FINAL;

新しく宣言した属性deptidおよびmajorは、サブタイプStudent_tに所属しています。たとえば、サブタイプEmployee_tを次のように宣言します。

CREATE TYPE Employee_t UNDER Person_t
( empid NUMBER,
mgr   VARCHAR2(30));

この例の結果としてOTTにより生成される構造体については、「OTTでの型の継承のサポート」を参照してください。

このサブタイプStudent_tは、PartTimeStudent_tなどの独自のサブタイプを所有できます。

CREATE TYPE PartTimeStudent_t UNDER Student_t
( numhours NUMBER) ;

代入性

ポリモフィズムのメリットは、一部代入性プロパティから引き出されます。代入性により、必要になるサブタイプに関する特別な知識がなくても、元々スーパータイプに対して記述されたコードにサブタイプの値を使用させることができます。サブタイプの値は、スーパータイプの値と同様に、メソッドの特殊化の範囲内で別のメカニズムを使用する可能性がある場合でも、前後のコードに対して作用します。

インスタンスの代入性とは、サブタイプのオブジェクト値を、スーパータイプで宣言されたコンテキスト内で使用できるようにする機能を指します。REFの代入性とは、サブタイプへのREFを、スーパータイプへのREFで宣言されたコンテキスト内で使用できるようにする機能を指します。

REF型の属性は置換可能です。つまり、REF Tとして定義された属性は、Tまたはその任意のサブタイプのインスタンスへのREFを保持できます。

オブジェクト型の属性は置換可能です。つまり、(オブジェクト)型Tとして定義された属性は、Tまたはその任意のサブタイプのインスタンスを保持できます。

コレクションの要素の型は置換可能です。つまり、T型の要素を持つコレクションを定義した場合、そのコレクションは、T型およびその任意のサブタイプのインスタンスを保持できます。オブジェクト属性の代入性の例を次に示します。

CREATE TYPE Book_t AS OBJECT
( title VARCHAR2(30),
author Person_t     /* substitutable */);

したがって、Book_tインスタンスは、次のように、タイトル文字列とPerson_t(または、Person_tの任意のサブタイプ)インスタンスを指定することによって作成できます。

Book_t('My Oracle Experience',
Employee_t(12345, 'Joe', 'SF', 1111, NULL))

NOT INSTANTIABLEの型とメソッド

型はNOT INSTANTIABLEとして宣言でき、これは、その型に(デフォルトまたはユーザー定義の)コンストラクタがないことを意味します。したがって、この型のインスタンスは構成できません。通常は、このような型にインスタンス化可能なサブタイプを定義するのに使用されます。このプロパティの使用方法を次に示します。

CREATE TYPE Address_t AS OBJECT(...) NOT INSTANTIABLE NOT FINAL;
CREATE TYPE USAddress_t UNDER Address_t(...);
CREATE TYPE IntlAddress_t UNDER Address_t(...);

型のメソッドは、NOT INSTANTIABLEとして宣言できます。メソッドをNOT INSTANTIABLEとして宣言することは、型がそのメソッドを実装しないことを意味します。また、NOT INSTANTIABLEメソッドが含まれている型は、必ずNOT INSTANTIABLEとして宣言する必要があります。たとえば、次のようにします。

CREATE TYPE T AS OBJECT
(
x NUMBER,
NOT INSTANTIABLE MEMBER FUNCTION func1() RETURN NUMBER
) NOT INSTANTIABLE NOT FINAL;

NOT INSTANTIABLE型のサブタイプは、スーパータイプの任意のNOT INSTANTIABLEメソッドをオーバーライドして、具体的な実装を行うことができます。NOT INSTANTIABLEメソッドが残っている場合、サブタイプも必ずNOT INSTANTIABLEとして宣言する必要があります。

NOT INSTANTIABLEサブタイプは、インスタンス化可能なスーパータイプの下に定義できます。NOT INSTANTIABLE型をFINALとして宣言することは無効なため、使用できません。

OCIでの型の継承のサポート

次のコールは、型の継承をサポートしています。

OCIDescribeAny()

OCIDescribeAny()関数は、継承された型固有の情報を提供します。継承された型のプロパティにはその他の属性が追加されています。たとえば、型のスーパータイプを取得できます。

関連項目:
既存のスキーマおよびサブスキーマ・オブジェクトの記述にOCIDescribeAny()を使用できる属性については、表6-7および表6-9を参照してください。

バインド関数および定義関数

OCIのバインド関数は、REF、インスタンスおよびコレクション要素の代入性をサポートしています(スーパータイプがある場合は、サブタイプのインスタンスを渡すことができます)。すべての型のチェックと変換は、サーバー側で実行されるため、OCIのバインド・インタフェースに対する変更はありません。

OCIの定義関数も、代入性をサポートしています(サブタイプのインスタンスをスーパータイプの保持を宣言した定義変数にフェッチできます)。ただし、この場合、サブタイプのインスタンスを保持するために、システムによるメモリーのサイズ変更が必要になることがあります。

注意:
この場合、クライアント・プログラムでは、オブジェクト・キャッシュから割り当てられた(したがって、サイズ変更が可能な)オブジェクトを使用する必要があります。

値が多相になる可能性がある場合、クライアントでは、(スタック上に割り当てられた)構造体を定義変数として使用しないでください。

関連項目:
バインドおよび定義のプロセスの詳細は、第12章を参照してください。

OCIObjectGetTypeRef()

OCIObjectGetTypeRef()関数は、入力オブジェクトに最も特有の型のTDOのREFを戻します。この操作では、ユーザーに最も特有な型に対する権限がない場合、エラーが戻されます。

OCIObjectCopy()

OCIObjectCopy()関数は、ソース・インスタンスの内容をターゲット・インスタンスにコピーします。ソース・インスタンスとターゲット・インスタンスは、同じ型にしてください。スーパータイプとサブタイプ間でコピーすることはできません。

同様に、tdo引数は、ソースおよびターゲット・オブジェクトと同じオブジェクト・タイプを記述する必要があり、ソースおよびターゲット・オブジェクトのスーパータイプまたはサブタイプを参照しないようにする必要があります。

OCICollAssignElem()

入力要素として、宣言された型のサブタイプのインスタンスを使用できます。コレクションの型がPerson_tの場合は、OCICollAssignElem()関数を使用して、Employee_tインスタンスをコレクションの要素として割り当てることができます。

OCICollAppend()

入力要素として、宣言された型のサブタイプのインスタンスを使用できます。コレクションの型がPerson_tの場合は、OCICollAppend()関数を使用して、コレクションにEmployee_tインスタンスを追加できます。

OCICollGetElem()

戻されるコレクション要素は、宣言された型のサブタイプのインスタンスの場合があります。コレクションの型がPerson_tの場合は、OCICollGetElem()関数を使用して、コレクションにEmployee_tインスタンスなどの要素へのポインタを取得します。

OTTでの型の継承のサポート

Object Type Translator (OTT)では、継承される属性を'_super'というカプセル化された構造体内で最初に宣言し、その後に新しい属性を宣言することで、オブジェクトの型の継承をサポートします。これを実行する理由は、Cでは型の継承がサポートされていないためです。

関連項目:
例および説明は、「OTTによる型の継承のサポート」を参照してください。

型の変更

型属性の追加、削除および変更がサポートされています。この概念は、型進化と呼ばれます。これについては、Oracle Databaseオブジェクト・リレーショナル開発者ガイドを参照してください。

OCIDescribeAny()は、入力オブジェクトの型がOCI_OTYPE_NAMEで、記述済のオブジェクトの型がOCI_PTYPE_TYPEの場合、つまり、OCIDescribeAny()に入力する名前が型名である場合、要求された型の最新バージョンの情報を戻します。

関連項目:

- 「OCITypeArrayByName()」および「OCITypeByName()」。型情報にアクセスするには、これらの関数以外に、OCIDescribeAny()を使用します。

- 型の変更のオブジェクト・キャッシュへの影響は、「型の変更とオブジェクト・キャッシュ」を参照してください。

12 OCIのオブジェクト・リレーショナル・データ型

この章では、OCIデータ型のマッピング関数および操作関数で操作できる各データ型の用途と構造について説明します。また、関数をグループ別にまとめ、使用可能な関数とその目的のリストを示します。さらに、OCIアプリケーションのバインド操作と定義操作でこれらのデータ型を使用する方法も説明します。

この章は、次の項目で構成されています。

- オブジェクトに対するOCI関数の概要

- Oracleデータ型のCへのマッピング

- OCIでのCデータ型の操作

- 日付(OCIDate)

- 日時および時間隔(OCIDateTime、OCIInterval)

- 数値(OCINumber)

- 固定長または可変長文字列(OCIString)

- ロー(OCIRaw)

- コレクション(OCITable、OCIArray、OCIColl、OCIIter)

- マルチレベル・コレクション型

- REF(OCIRef)

- オブジェクト型情報の格納およびアクセス

- AnyTypeインタフェース、AnyDataインタフェースおよびAnyDataSetインタフェース

- 名前付きデータ型のバインド

- 名前付きデータ型の定義

- Oracle Cデータ型のバインドおよび定義

- SQLT_NTYのバインドおよび定義の例

オブジェクトに対するOCI関数の概要

OCIデータ型のマッピング関数および操作関数を使用すると、事前定義済のOracle Cデータ型のインスタンスを操作できます。これらのデータ型は、Oracle Databaseのオブジェクト型など、ユーザー定義のデータ型の属性を表現するために使用します。

OCIの各関数グループは、特定のネーミング規則によって区別されます。たとえば、データ型のマッピング関数および操作関数は、関数名が接頭辞OCIで始まり、その後にデータ型が続くため、簡単に認識できます(例: OCIDateFromText()およびOCIRawSize())。後述するように、名前はさらに特定の型のデータを操作する関数グループに分類できます。

これらの関数を操作する事前定義済のOracle C型は、接頭辞OCIで始まる名前でも区別できます(例: OCIDateやOCIString)。

データ型のマッピング関数および操作関数は、アプリケーションで、Oracle Databaseに格納されたオブジェクト、またはSQL問合せで取り出されたオブジェクトの属性を操作、バインドまたは定義する必要がある場合に使用します。第14章でも説明していますが、取り出したオブジェクトはクライアント側のオブジェクト・キャッシュに格納されます。

OCIクライアントは、バインドまたは定義操作を実行する前に記述子を割り当てる必要があります。OCIStmtExecute()およびOCIStmtFetch2()は、記述子が OCIDescriptorAlloc()によって割り当てられていない場合、これらの記述子にはメモリーを割り当てることはできません。

これらの関数は、OCIアプリケーションをオブジェクト・モードで実行している間にのみ有効です。OCIのオブジェクト・モードでの初期化、およびオブジェクトにアクセスして操作するOCIアプリケーションの作成の詳細は、「環境およびオブジェクト・キャッシュの初期化」を参照してください。

関連項目:
オブジェクト型、属性およびコレクション・データ型の詳細は、『Oracle Database概要』を参照してください。

注意:
OCIDateなどのオブジェクト型に対する操作では、結果のアドレスを演算子のアドレスと同じにできます。

Oracleデータ型のCへのマッピング

Oracleには、表を作成し、ユーザー定義のデータ型(オブジェクト型を含む)を指定できる、一連の事前定義済のデータ型があります。オブジェクト型はOracle Databaseの機能を拡張するものであり、オブジェクト型を使用すると、処理対象のデータの型を正確にモデル化したデータ型を作成できます。そのため、プログラマは、より効率的で簡単なデータ・アクセスができます。

NCHARおよびNVARCHAR2はオブジェクトの属性として使用でき、CではOCIString *にマップされます。

データベースの表およびオブジェクト型は、Oracleが供給するデータ型に基づいています。データベースの表およびオブジェクト型は、SQL文で作成し、VARCHAR2やNUMBERなどの特定のOracle内部データ型を使用して格納します。たとえば、次のSQL文では、ユーザー定義のaddressデータ型と、そのデータ型のインスタンスを格納するオブジェクト表を作成します。

CREATE TYPE address AS OBJECT
(street1    varchar2(50),
street2     varchar2(50),
city        varchar2(30),
state       char(2),
zip         number(5));
CREATE TABLE address_table OF address;

この新しいaddress型を使用して、次のようなオブジェクト列を持つ標準表を作成したとします。

CREATE TABLE employees
(name         varchar2(30),
birthday      date,
home_addr     address);

OCIアプリケーションでは、SQL文に対応付けられた、簡単なバインドおよび定義操作を使用して、情報をemployees表のnameおよびbirthdayの列で操作できます。オブジェクトの属性として格納されている情報にアクセスするには、いくつかの追加ステップが必要です。

OCIアプリケーションでは、まずオブジェクトをC言語書式で表現する手段が必要です。そのためには、Object Type Translator (OTT)を使用して、ユーザー定義型のC構造体表現を生成します。生成した構造体の要素には、Oracleのデータ型をC言語にマッピングしたデータ型が含まれます。

関連項目:
オブジェクト属性の型として使用できるOracleの型と、対応するCマッピングについては、表15-1を参照してください。

その他のC型としてOCIIndがあります。これは、オブジェクト型の属性に対応するNULLインジケータ情報を表現するために使用します。

関連項目:
OTTの使用方法の詳細および例は、第15章を参照してください。

OCI型マッピングの方法論

事前定義済のOracle型についてマッピングを指定する場合、Oracleでは独特の設計方針に従ってきました。カレント・システムには、次のメリットがあります。

- OCINumberのようなデータ型の実際の表現は、クライアントのアプリケーションでは不透明で、データ型は事前に定義済の一連の関数によって操作されます。これによって、将来改善する際にも、ユーザー・コードを中断せずに内部表現を変更できます。

- オブジェクト指向パラダイムに従った実装がなされています。このパラダイムではクラスの実装の詳細は隠されており、見えるのは必要な操作のみです。

- この実装方法はプログラマにとって有利です。Oracleの数値で提供されるOracle数値変数を、精度を落とすことなく操作するCプログラムを記述する場合について考えてみます。Oracle Databaseリリース7でこの操作を実行するには、SELECT ... FROM DUAL文を発行する必要があります。以降のリリースでは、OCINumber*()関数をコールするのみです。

OCIでのCデータ型の操作

OCIアプリケーションで、2つの整変数を合計して結果を第3の変数に格納するという非常に簡単なデータ操作を行うとします。

int    int_1, int_2, sum;
...
/* some initialization occurs */
...
sum = int_1 + int_2;

C言語は、integerのような単純な型に対する一連の事前定義済操作を提供します。ただし、表15-1に示されているCデータ型は、C言語の単純な基本形ではありません。OCIStringおよびOCINumberのような型は、実際は特定のOracle定義の内部構造を持つ構造体です。単に、2つのOCINumberを合計して、その値を第3の変数に格納することはできません。

次の内容は、有効ではありません。

OCINumber    num_1, num_2, sum;
...
/* some initialization occurs */
...
sum = num_1 + num_2;           /* NOT A VALID OPERATION */

このような新しいデータ型を操作するための関数が、OCIデータ型のマッピング関数および操作関数です。たとえば、この例でOCINumberを加算するには、OCINumberAdd()関数を使用します。

OCINumber    num_1, num_2, sum;
...
/* some initialization occurs */
...
OCINumberAdd(errhp, &num_1, &num_2, &sum): /* errhp is error handle */

OCIには、新規データ型をそれぞれ操作する関数があります。関数の名前から、その関数で操作するデータ型がわかります。最初の3文字OCIは、関数がOCIの一部であることを示します。関数名の次の部分は、関数で操作するデータ型を示します。表12-1は、各種の関数の接頭辞、関数名の例および関数の操作対象のデータ型を示しています。

図12-1 関数の接頭辞の例

関数の接頭辞

例

操作対象

OCIColl

OCICollGetElem()

OCIColl, OCIIter, OCITable, OCIArray

OCIDate

OCIDateDaysBetween()

OCIDate

OCIDateTime

OCIDateTimeSubtract()

OCIDate, OCIDateTime

OCIInterval

OCIIntervalToText()

OCIInterval

OCIIter

OCIIterInit()

OCIIter

OCINumber

OCINumberAdd()

OCINumber

OCIRaw

OCIRawResize()

OCIRaw *

OCIRef

OCIRefAssign()

OCIRef *

OCIString

OCIStringSize()

OCIString *

OCITable

OCITableLast()

OCITable *

各データ型の構造については、そのデータ型を操作対象にする関数のリストとともに、この章で後述します。

Oracle数値操作の精度

Oracleの数値の精度は、10進数で38桁です。Oracleの数値操作は、次の例外を除いて、全桁で行います。

- 逆三角関数の精度は、10進数で28桁です。

- 三角関数を含むその他の超越関数の精度は、およそ10進数で37桁です。

- システム固有の浮動小数点型との間の変換では、適切な浮動小数点型の精度になり、10進数で38桁を超えることはありません。

日付(OCIDate)

Oracleの日付書式は、不透明なC構造体であるOCIDate型でCにマップされます。構造体の要素は日付の年、月、日、時間、分および秒を表します。適切なOCI関数を使用すると、特定の要素を設定および取出しできます。

OCIDateデータ型は、バインド・コールまたは定義コールで、外部型コードSQLT_ODTを使用して直接バインドまたは定義できます。

特に明記されていないかぎり、これらの関数コールでのdateという用語は、型OCIDateの値を示します。

関連項目:
すべての関数のプロトタイプと説明は、第19章を参照してください。

日付の例

例12-1は、OCIコールを使用して、OCIDate型の属性を操作する方法の例を示しています。この例では、OCIEnvおよびOCIErrorは、「OCI環境の初期化」の説明に従って初期化されているとします。確保については、「オブジェクト・キャッシュ操作」を参照してください。

例12-1 OCIDate型の属性の操作

#define FMT "DAY, MONTH DD, YYYY"
#define LANG "American"
struct person
{
OCIDate start_date;
};
typedef struct person person;

OCIError *err;
person *tim;
sword status;                      /* error status */
uword invalid;
OCIDate last_day, next_day;
text buf[100], last_day_buf[100], next_day_buf[100];
ub4 buflen = sizeof(buf);

/* Pin tim person object in the object cache. */
/*  For this example, assume that
/* tim is pointing to the pinned object. */
/* set the start date of tim */

OCIDateSetTime(&tim->start_date,8,0,0);
OCIDateSetDate(&tim->start_date,1990,10,5);

/* check if the date is valid */
if (OCIDateCheck(err, &tim->start_date, &invalid) != OCI_SUCCESS)
/* error handling code */

if (invalid)
/* error handling code */

/* get the last day of start_date's month */
if (OCIDateLastDay(err, &tim->start_date, &last_day) != OCI_SUCCESS)
/* error handling code */

/* get date of next named day */
if (OCIDateNextDay(err, &tim->start_date, "Wednesday",    strlen("Wednesday"),
&next_day) != OCI_SUCCESS)
/* error handling code */
/* convert dates to strings and print the information */
/* first convert the date itself*/
buflen = sizeof(buf);
if (OCIDateToText(err, &tim->start_date, FMT, sizeof(FMT)-1, LANG,
sizeof(LANG)-1,             &buflen, buf) != OCI_SUCCESS)
/* error handling code */

/* now the last day of the month */
buflen = sizeof(last_day_buf);
if (OCIDateToText(err, &last_day, FMT, sizeof(FMT)-1, LANG,    sizeof(LANG)-1,
&buflen, last_day_buf) != OCI_SUCCESS)
/* error handling code */

/* now the first Wednesday after this date */
buflen = sizeof(next_day_buf);
if (OCIDateToText(err, &next_day, FMT, sizeof(FMT)-1, LANG,
sizeof(LANG)-1, &buflen, next_day_buf) != OCI_SUCCESS)
/* error handling code */

/* print the information */
printf("For: %s\n", buf);
printf("The last day of the month is: %s\n", last_day_buf);
printf("The next Wednesday is: %s\n", next_day_buf);

出力は次のとおりです。

For: FRIDAY   , OCTOBER   05, 1990
The last day of the month is: WEDNESDAY, OCTOBER   31, 1990
The next Wednesday is: WEDNESDAY, OCTOBER   10, 1990

日時および時間隔(OCIDateTime、OCIInterval)

OCIDateTimeデータ型は、Oracleのタイムスタンプのデータ型(TIMESTAMP、TIMESTAMP WITH TIME ZONE、TIMESTAMP WITH LOCAL TIME ZONE)およびANSI DATEデータ型の表現に使用する不透明な構造体です。適切なOCI関数を使用すると、これらの型(つまり、年、日、小数秒)でのデータの設定または取出しを実行できます。

OCIIntervalデータ型も不透明な構造体で、Oracleの時間隔データ型(INTERVAL YEAR TO MONTH、INTERVAL DAY TO SECOND)の表現に使用されます。

バインドまたは定義のコールで、表12-2に示す外部型コードを使用すると、OCIDateTimeとOCIIntervalのデータをバインドおよび定義できます。

表12-2 日時および時間隔データ型のバインドと定義

OCIデータ型

データの型

バンド/定義の外部型コード

OCIDateTime

ANSI DATE

SQLT_DATE

OCIDateTime

TIMESTAMP

SQLT_TIMESTAMP

OCIDateTime

TIMESTAMPWITHTIMEZONE

SQLT_TIMESTAMP_TZ

OCIDateTime

TIMESTAMPWITHLOCALTIMEZONE

SQLT_TIMESTAMP_LTZ

OCIInterval

INTERVALYEARTOMONTH

SQLT_INTERVAL_YM

OCIInterval

INTERVALDAYTOSECOND

SQLT_INTERVAL_DS

日時と時間隔のデータを操作するOCI関数を表12-3および表12-4にリストします。これらの関数の詳細は、「OCIの日付関数、日時関数および時間隔関数」を参照してください。

通常、OCIDateTimeデータを操作する関数は、OCIDateデータにも有効です。

日時関数

次の関数は、OCIDateTimeの値を操作します。この関数の中には、日時と時間隔の値に関する算術演算を行う関数もあります。また、特定の日時型に対してのみ動作する関数もあります。可能な型は、次のとおりです。

- SQLT_DATE: DATE

- SQLT_TIMESTAMP: TIMESTAMP

- SQLT_TIMESTAMP_TZ: TIMESTAMP WITH TIME ZONE

- SQLT_TIMESTAMP_LTZ: TIMESTAMP WITH LOCAL TIME ZONE

特定の関数に有効な入力型の詳細は、表12-3に示す各関数の説明を参照してください。

表12-3 日時関数

関数

用途

「OCIDateTimeAssign()」

日時の割当てを実行します。

「OCIDateTimeCheck()」

指定の日付が有効かどうかをチェックします。

「OCIDateTimeCompare()」

2つの日時値を比較します。

「OCIDateTimeConstruct()」

日時記述子を作成します。

「OCIDateTimeConvert()」

ある日時型を別の日時型に変換します。

「OCIDateTimeFromArray()」

日付が含まれている配列をOCIDateTime記述子に変換します。

「OCIDateTimeFromText()」

指定された書式に従って、指定の文字列をOCIDateTime記述子のOracle日時型に変換します。

「OCIDateTimeGetDate()」

日時値の日付部分(年、月、日)を取得します。

「OCIDateTimeGetTime()」

日時値の時刻部分(時間、分、秒、小数秒)を取得します。

「OCIDateTimeGetTimeZoneName()」

日時値のタイム・ゾーン名部分を取得します。

「OCIDateTimeGetTimeZoneOffset()」

日時値のタイム・ゾーン(時間、分)部分を取得します。

「OCIDateTimeIntervalAdd()」

日時に時間隔を加算して、結果の日時を生成します。

「OCIDateTimeIntervalSub()」

日時から時間隔を減算して、その結果を日時に格納します。

「OCIDateTimeSubtract()」

2つの日時を入力値にして、その差異を時間隔に格納します。

「OCIDateTimeSysTimeStamp()」

現行のシステム日付および時刻を、タイム・ゾーン付きタイムスタンプとして取得します。

「OCIDateTimeToArray()」

OCIDateTime記述子を配列に変換します。

「OCIDateTimeToText()」

指定された日付を指定の書式の文字列に変換します。

「OCIDateZoneToZone()」

あるタイム・ゾーンの日付を別のタイム・ゾーンの日付に変換します。

日時の例

例12-2のコード・フラグメントは、OCIDateTimeデータ型を使用してTIMESTAMP WITH LOCAL TIME ZONE列からデータを選択する方法を示しています。

例12-2 OCIDateTime型の属性の操作

...

/* allocate the program variable for storing the data */
OCIDateTime *tstmpltz = (OCIDateTime *)NULL;

/* Col1 is a time stamp with local time zone column */
OraText *sqlstmt = (OraText *)"SELECT col1 FROM foo";

/* Allocate the descriptor (storage) for the data type */
status = OCIDescriptorAlloc(envhp,(void  **)&tstmpltz, OCI_DTYPE_TIMESTAMP_LTZ,
0, (void  **)0);
....

status = OCIStmtPrepare (stmthp, errhp, sqlstmt, (ub4)strlen ((char *)sqlstmt),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);

/* specify the define buffer for col1 */
status = OCIDefineByPos(stmthp, &defnp, errhp, 1, &tstmpltz, sizeof(tstmpltz),
SQLT_TIMESTAMP_LTZ, 0, 0, 0, OCI_DEFAULT);

/* Execute and Fetch */
OCIStmtExecute(svchp, stmthp, errhp, 1, 0,(OCISnapshot *) NULL,
(OCISnapshot *)NULL, OCI_DEFAULT)

At this point tstmpltz contains a valid time stamp with local time zone data. You
can get the time zone name of the datetime data using:

status = OCIDateTimeGetTimeZoneName(envhp, errhp, tstmpltz, (ub1 *)buf,
(ub4 *)&buflen);
...

時間隔関数

例12-4に示す関数は、時間隔データのみを操作します。対象となる時間隔の型の指定が必要な場合があります。可能な型は、次のとおりです。

- SQLT_INTERVAL_YM: 年から月までの時間隔

- SQLT_INTERVAL_DS: 日から秒までの時間隔

詳細は、各関数の説明を参照してください。

関連項目:
各関数の名前と用途のリストおよび詳細は、「OCIの日付関数、日時関数および時間隔関数」 を参照してください。

表12-4 時間隔関数

関数

用途

「OCIIntervalAdd()」

2つの時間隔を加算して、その結果の時間隔を生成します。

「OCIIntervalAssign()」

ある時間隔を別の時間隔にコピーします。

「OCIIntervalCheck()」

時間隔の妥当性をチェックします。

「OCIIntervalCompare()」

2つの時間隔を比較します。

「OCIIntervalDivide()」

時間隔をOracle NUMBERで除算して、時間隔を生成します。

「OCIIntervalFromNumber()」

Oracle NUMBERを時間隔に変換します。

「OCIIntervalFromText()」

時間隔文字列が指定されている場合、その文字列で表現される時間隔を変換します。

「OCIIntervalFromTZ()」

タイム・ゾーン形式の入力文字列が指定されている場合、時間隔を戻します。

「OCIIntervalGetDaySecond()」

時間隔から日、時、分、秒の値を取得します。

「OCIIntervalGetYearMonth()」

時間隔から年と月を取得します。

「OCIIntervalMultiply()」

時間隔をOracle NUMBERで乗算して、時間隔を生成します。

「OCIIntervalSetDaySecond()」

時間隔に日、時、分、秒を設定します。

「OCIIntervalSetYearMonth()」

時間隔に年と月を設定します。

「OCIIntervalSubtract()」

2つの時間隔を減算し、その結果を時間隔に格納します。

「OCIIntervalToNumber()」

時間隔をOracle NUMBERに変換します。

「OCIIntervalToText()」

時間隔が指定されている場合、その時間隔を表現する文字列を生成します。

数値(OCINumber)

OCINumberデータ型は、Oracleの数値データ型(NUMBER、FLOAT、DECIMALなど)の表現に使用する不透明な構造体です。この型は、バインド・コールまたは定義コールで外部型コードSQLT_VNUを使用して、バインドまたは定義できます。

特に明記されていないかぎり、これらの関数コールでのnumberという用語は、型OCINumberの値を示します。

関連項目:
すべてのOCI NUMBER関数のプロトタイプと説明は、表19-11を参照してください。

OCINumberの例

例12-3のコード・フラグメントは、OCINumber型の属性を操作する方法の例を示しています。例12-4のコード・フラグメントは、OCIDescribeAny()コールから戻されたOCINumber形式の値を符号なし整数に変換する方法を示します。

例12-3 OCINumber型の属性の操作

/* Example 1  */
struct person
{
OCINumber sal;
};
typedef struct person person;
OCIError *err;
person* steve;
person* scott;
person* jason;
OCINumber  *stevesal;
OCINumber  *scottsal;
OCINumber *debsal;
sword   status;
int     inum;
double  dnum;
OCINumber ornum;
text   buffer[21];
ub4     buflen;
sword   result;

/* For this example, assume OCIEnv and OCIError are initialized. */
/* For this example, assume that steve, scott, and jason are pointing to
person objects that have been pinned in the object cache. */
stevesal = &steve->sal;
scottsal = &scott->sal;
debsal = &jason->sal;

/* initialize steve's salary to be $12,000 */
inum = 12000;
status = OCINumberFromInt(err, &inum, sizeof(inum), OCI_NUMBER_SIGNED,
stevesal);
if (status != OCI_SUCCESS)  /* handle error from OCINumberFromInt */;

/* initialize scott's salary to be the same as steve's */
OCINumberAssign(err, stevesal, scottsal);

/* initialize jason's salary to be 20% more than steve's */
dnum = 1.2;
status = OCINumberFromReal(err, &dnum, sizeof(dnum), &ornum);
if (status != OCI_SUCCESS)  /* handle error from OCINumberFromReal */;
status = OCINumberMul(err, stevesal, &ornum, debsal);
if (status != OCI_SUCCESS)  /* handle error from OCINumberMul */;

/* give scott a 50% raise */
dnum = 1.5;
status = OCINumberFromReal(err, &dnum, sizeof(dnum), &ornum);
if (status != OCI_SUCCESS)  /* handle error from OCINumberFromReal */;
status = OCINumberMul(err, scottsal, &ornum, scottsal);
if (status != OCI_SUCCESS)  /* handle error from OCINumberMul */;

/* double steve's salary */
status = OCINumberAdd(err, stevesal, stevesal, stevesal);
if (status != OCI_SUCCESS)  /* handle error from OCINumberAdd */;

/* get steve's salary in integer */
status = OCINumberToInt(err, stevesal, sizeof(inum), OCI_NUMBER_SIGNED, &inum);
if (status != OCI_SUCCESS)  /* handle error from OCINumberToInt */;

/* inum is set to 24000 */
/* get jason's salary in double */
status = OCINumberToReal(err, debsal, sizeof(dnum), &dnum);
if (status != OCI_SUCCESS)  /* handle error from OCINumberToReal */;

/* dnum is set to 14400 */
/* print scott's salary as DEM0001'8000.00 */
buflen = sizeof(buffer);
status = OCINumberToText(err, scottsal, (text *)"C0999G9999D99", 13,
(text *)"NLS_NUMERIC_CHARACTERS='.'' NLS_ISO_CURRENCY='Germany'",
54, &buflen, (text *)buffer);
if (status != OCI_SUCCESS)  /* handle error from OCINumberToText */;
printf("scott's salary = %s\n", buffer);

/* compare steve and scott's salaries */
status = OCINumberCmp(err, stevesal, scottsal, &result);
if (status != OCI_SUCCESS)  /* handle error from OCINumberCmp */;

/* result is positive */
/* read jason's new salary from string */
status = OCINumberFromText(err, (text *)"48'000.00", 9, (text
*)"99G999D99", 9,
(text *)"NLS_NUMERIC_CHARACTERS='.''", 27, debsal);
if (status != OCI_SUCCESS)  /* handle error from OCINumberFromText */;
/* jason's salary is now 48000.00 */

例12-4は、OCINumber形式でOCIDescribeAny()コールから戻された数値型(OCI_ATTR_MAXやOCI_ATTR_MINなど)を符号なしC整数に変換する方法を示します。

例12-4 OCIDescribeAny()コールから戻されたOCINumber形式の値の符号なし整数への変換

/* Example 2 */
ub4  max_seq_val  = 0;
ub1 *max_valp     = NULL;
ub4  max_val_size;
OCINumber max_val;
OCINumberSetZero(_errhp, &max_val);
OCIParam* parmdp = 0;
status = OCIAttrGet ((void *)_dschp, (ub4)OCI_HTYPE_DESCRIBE, &parmdp, 0,
(ub4)OCI_ATTR_PARAM, _errhp);
if (isError (status, _errhp))
{
return 0;
}
status = OCIAttrGet ((void *)parmdp, (ub4)OCI_DTYPE_PARAM, &max_valp,
&max_val_size, (ub4)OCI_ATTR_MAX, _errhp);
//create an OCINumber object from the ORACLE NUMBER FORMAT
max_val.OCINumberPart[0] = max_val_size; //set the length byte
memcpy(&max_val.OCINumberPart[1], max_valp, max_val_size); //copy the actual bytes
//now convert max_val to an unsigned C integer, max_seq_val
status = OCINumberToInt(_errhp, &max_val, sizeof(max_seq_val),
OCI_NUMBER_UNSIGNED, &max_seq_val);

固定長または可変長文字列(OCIString)

固定長または可変長の文字列データは、Cプログラムに対してOCIString *として表現されます。

文字列の長さには、NULL文字は含まれていません。

OCIString *型の変数のバインドと定義には、外部型コードSQLT_VSTを使用します。

関連項目:
すべての文字列関数のプロトタイプと説明は、表19-16を参照してください。

文字列関数

表12-5は、Cのプログラマが文字列のインスタンスを操作できる関数を示しています。

表12-5 文字列関数

関数

用途

「OCIStringAllocSize()」

文字列の割当てメモリー・サイズをコード・ポイント(Unicode)またはバイト単位で取得します。

「OCIStringAssign()」

文字列を別の文字列に割り当てます。

「OCIStringAssignText()」

ソース・テキスト文字列をターゲット文字列に割り当てます。

「OCIStringPtr()」

指定の文字列のテキストへのポインタを取得します。

「OCIStringResize()」

指定の文字列のメモリー・サイズを変更します。

「OCIStringSize()」

指定の文字列のサイズを取得します。

文字列の例

例12-5では、テキスト文字列を文字列に代入し、文字列の文字列部分へのポインタと文字列サイズを取得して、出力します。

OCIStringAssignText()で、vstring1パラメータを渡すために二重間接演算が使用されていることに注意してください。

例12-5 OCIString型の属性の操作

OCIEnv       *envhp;
OCIError     *errhp;
OCIString     *vstring1 = (OCIString *)0;
OCIString     *vstring2 = (OCIString *)0;
text          c_string[20];
text         *text_ptr;
sword        status;

strcpy((char *)c_string, "hello world");
/* Assign a text string to an OCIString */
status = OCIStringAssignText(envhp, errhp, c_string,
(ub4)strlen((char *)c_string),&vstring1);
/* Memory for vstring1 is allocated as part of string assignment */

status = OCIStringAssignText(envhp, errhp, (text *)"hello again",
(ub4)strlen("This is a longer string."),&vstring1);
/* vstring1 is automatically resized to store the longer string */

/* Get a pointer to the string part of vstring1 */
text_ptr = OCIStringPtr(envhp, vstring1);
/* text_ptr now points to "hello world" */
printf("%s\n", text_ptr);

ロー(OCIRaw)

可変長ロー・データは、OCIRaw *データ型を使用してCで表現されます。

OCIRaw *型の変数のバインドと定義には、外部型コードSQLT_LVBを使用します。

関連項目:
すべてのロー関数のプロトタイプと説明は、表19-14を参照してください。

ロー関数

表12-6は、OCIRawの操作を実行する関数を示しています。

表12-6 ロー関数

関数

用途

「OCIRawAllocSize()」

ロー・メモリーの割り当てられたサイズ(バイト単位)を取得します。

「OCIRawAssignBytes()」

ロー・データ(ub1 *)をOCIRaw *に代入します。

「OCIRawAssignRaw()」

1つのOCIRaw *を別のOCIRaw *に代入します。

「OCIRawPtr()」

ロー・データへのポインタを取得します。

「OCIRawResize()」

可変長ロー・データのメモリーのサイズ変更を行います。

「OCIRawSize()」

ロー・データのサイズを取得します。

ローの例

例12-6は、ロー・データのブロックを設定し、そのデータへのポインタを取得する方法を示しています。

OCIRawAssignBytes()のコールで二重間接演算を使用していることに注意してください。

例12-6 OCIRaw型の属性の操作

OCIEnv      *envhp;
OCIError    *errhp;
sword       status;
ub1         data_block[10000];
ub4         data_block_len = 10000;
OCIRaw      *raw1 = (OCIRaw *) 0;
ub1 *raw1_pointer;

/* Set up the RAW */
/* assume 'data_block' has been initialized */
status = OCIRawAssignBytes(envhp, errhp, data_block, data_block_len,
&raw1);

/* Get a pointer to the data part of the RAW */
raw1_pointer = OCIRawPtr(envhp, raw1);

コレクション(OCITable、OCIArray、OCIColl、OCIIter)

Oracle Databaseには、可変長配列(VARRAY)とネストした表の2種類のコレクションがあります。Cアプリケーションでは、VARRAYはOCIArray *と表現され、ネストした表は、OCITable *と表現されます。これらの両方のデータ型は(後述するOCICollとOCIIterと同様に)、不透明な構造体です。

様々な汎用コレクション関数により、コレクション・データを操作できます。汎用コレクション関数は、VARRAYとネストした表の両方に使用できます。また、ネストした表固有の一連の関数もあります。

関連項目:
「ネストした表の操作関数」

VARRAYまたはネストした表のインスタンスは、OCIObjectNew()を使用して割り当て、OCIObjectFree()を使用して解放できます。

関連項目:
これらの関数のプロトタイプと説明は、「OCIコレクションおよびイテレータ関数」を参照してください。

汎用コレクション関数

Oracle Databaseには、可変長配列(VARRAY)とネストした表の2種類のコレクションがあります。VARRAYとネストした表は、どちらも汎用コレクション型のサブタイプとみなすことができます。

Cでは、汎用コレクションをOCIColl *、VARRAYをOCIArray *、ネストした表をOCITable *と表現します。Oracleには、汎用コレクションを操作するための一連の関数群(OCIColl *など)があります。これらの関数は、OCICollGetElem()のように接頭辞OCICollで始まります。OCIColl*()関数をコールして、VARRAYとネストした表を操作することもできます。

汎用コレクション関数は、2つの主なカテゴリにグループ化できます。

- VARRAYまたはネストした表のデータを操作するグループ

- コレクション・イテレータを使用してコレクションをスキャンするグループ

汎用コレクション関数は、VARRAYを操作する関数の完全な集合です。その他の関数は、特にネストした表で操作するための関数です。これらの関数は、OCITableExists()のように接頭辞OCITableで識別できます。

関連項目:
「ネストした表の操作関数」

注意:
コレクション関数に渡された索引は、0 (ゼロ)が基数です。

コレクション・データ操作関数

表12-7は、コレクション・データを操作する汎用関数を示しています。

表12-7 コレクション関数

関数

用途

「OCICollAppend()」

コレクションの最後に要素を追加します。

「OCICollAssign()」

1つのコレクションを別のコレクションに割り当てます。

「OCICollAssignElem()」

指定の索引位置に要素を割り当てます。

「OCICollGetElem()」

索引位置の指定時に要素へのポインタを取得します。

「OCICollGetElemArray()」

コレクションから要素の配列を取得します。

「OCICollIsLocator()」

コレクションがロケータベースであるかどうかを示します。

「OCICollMax()」

コレクションの上限を取得します。

「OCICollSize()」

コレクションのカレント・サイズを取得します。

「OCICollTrim()」

コレクションの終わりからn個の要素を切り捨てます。

コレクション・スキャン関数

表12-8は、コレクション・イテレータを使用してコレクションをスキャンできる汎用関数を示しています。イテレータは、OCIIter型であり、最初にOCIIterCreate()をコールして作成します。

表12-8 コレクション・スキャン関数

関数

用途

「OCIIterCreate()」

コレクションの要素をスキャンするためのイテレータを作成します。

「OCIIterDelete()」

コレクション・イテレータを削除します。

「OCIIterGetCurrent()」

イテレータが指し示すカレント要素へのポインタを取得します。

「OCIIterInit()」

イテレータを初期化して指定のコレクションをスキャンします。

「OCIIterNext()」

次のイテレータ・コレクション要素へのポインタを取得します。

「OCIIterPrev()」

直前のイテレータ・コレクション要素へのポインタを取得します。

VARRAY/コレクション・イテレータの例

例12-7では、コレクション・イテレータを作成し、それを使用してVARRAY (可変長配列)をスキャンします。

例12-7 コレクション・データ操作関数の使用

OCIEnv       *envhp;
OCIError     *errhp;
text         *text_ptr;
sword        status;
OCIArray     *clients;
OCIString    *client_elem;
OCIIter      *iterator;
boolean      eoc;
void         *elem;
OCIInd       *elemind;

/* Assume envhp, errhp have been initialized */
/* Assume clients points to a varray */

/* Print the elements of clients */
/* To do this, create an iterator to scan the varray */
status = OCIIterCreate(envhp, errhp, clients, &iterator);

/* Get the first element of the clients varray */
printf("Clients' list:\n");
status = OCIIterNext(envhp, errhp, iterator, &elem,
(void  **) &elemind, &eoc);

while (!eoc && (status == OCI_SUCCESS))
{
client_elem = *((OCIString **)elem);
/* client_elem points to the string */

/*
the element pointer type returned by OCIIterNext() through 'elem' is

the same as that of OCICollGetElem(). See OCICollGetElem() for
details.  */

/*
client_elem points to an OCIString descriptor, so to print it out,
get a pointer to where the text begins
*/
text_ptr = OCIStringPtr(envhp, client_elem);

/*
text_ptr now points to the text part of the client OCIString, which
is a
NULL-terminated string
*/
printf("  %s\n", text_ptr);
status = OCIIterNext(envhp, errhp, iterator, &elem,
(void  **)&elemind, &eoc);
}

if (status != OCI_SUCCESS)
{
/* handle error */
}

/* destroy the iterator */
status = OCIIterDelete(envhp, errhp, &iterator);

ネストした表の操作関数

その名前が示すように、1つの表はネストしている、つまり変数、属性、パラメータまたは列として別の表の中に含まれている場合があります。ネストした表には、OCITableDelete()関数で削除された要素が含まれている場合があります。

たとえば、10個の要素を指定して作成した表があり、0から4と9の索引を持つ要素をOCITableDelete()で削除したとします。既存の最初の要素は要素5になり、既存の最後の要素は要素8になります。

前述のように、汎用コレクション関数を使用しても、ネストした表へのマッピングやネストした表の操作ができます。さらに、表12-9は、ネストした表専用の関数を示しています。ネストした表専用の関数は、VARRAYでは使用できません。

表12-9 ネストした表の関数

関数

用途

「OCITableDelete()」

指定の索引位置にある要素を削除します。

「OCITableExists()」

指定の索引位置に要素が存在するかどうかをテストします。

「OCITableFirst()」

表の最初の既存要素の索引を戻します。

「OCITableLast()」

表の最後の既存要素の索引を戻します。

「OCITableNext()」

表の次の既存要素の索引を戻します。

「OCITablePrev()」

表の直前の既存要素の索引を戻します。

「OCITableSize()」

削除した要素を除いた表のサイズを戻します。

ネストした表の要素への順序付け

ネストした表がオブジェクト・キャッシュにフェッチされた場合、その要素には、0 (ゼロ)から始まり要素数から1を引いた数で終わる順序が一時的に付けられます。たとえば、40個の要素を持つ表では、0から39まで順序付けが行われます。

これらの位置序数を使用して、要素の値のフェッチと代入が行われます(たとえば、要素iへのフェッチや、要素jへの代入など。iとjは、指定の表の有効な位置序数です)。

表をデータベースにコピーすると、一時的な順序付けは失われます。表の要素に対して削除の操作を行うことがあります。削除操作により、一時的な穴が作成されます。つまり、削除操作では、残りの表要素の位置序数は変更されません。

ネストした表のロケータ

ネストした表のロケータを取り出すことができます。ロケータはコレクション値へのハンドルのようなもので、検索時に存在するデータベース・スナップショットについての情報を含みます。このスナップショット情報は、後にロケータを使用してコレクション要素がフェッチされるときに、データベースでコレクション値の正しいインスタンス化を取り出すために役立ちます。

LOBロケータとは異なり、コレクション・ロケータはコレクション・インスタンスの変更には使用できず、正しいデータを特定するだけです。ロケータを使用すると、アプリケーションは、非常に大規模な場合もある全コレクションを検索しなくても、ハンドルをネストした表に戻すことができます。

コレクション列または属性をフェッチするときにロケータが戻される必要がある場合、ユーザーは、RETURN AS LOCATOR指定を使用して、表がいつ作成されるかを指定します。

関連項目:
『Oracle Database SQL言語リファレンス』

コレクションがロケータベースであるかどうかを判断するには、OCICollIsLocator()関数を使用します。

マルチレベル・コレクション型

コレクション要素自体が直接的または間接的に別のコレクション型である場合があります。マルチレベル・コレクション型とは、このようなトップレベルのコレクション型に付けられた名前です。

マルチレベル・コレクションには、次のような特性があります。

- 他のコレクション型の集まりである場合があります。

- コレクション属性を持つオブジェクトの集まりである場合があります。

- ネスト・レベルの数に制限がありません。

- VARRAYとネストした表の組合せを含めることができます。

- 表の列として使用できます。

OCIルーチンは、マルチレベル・コレクションを処理します。次のルーチンは、パラメータ*elemのOCIColl*を戻すことができるため、このパラメータは任意のコレクションのルーチンで使用できます。

- OCICollGetElem()

- OCIIterGetCurrent()

- OCIIterNext()

- OCIIterPrev()

次の関数は、コレクション要素を取得し、それを既存のコレクションに追加します。要素型が別のコレクションの場合、パラメータelemは、OCIColl*となることがあります。

- OCICollAssignElem()

- OCICollAppend()

マルチレベル・コレクション型の例

次の型および表は、例12-8で使用します。

type_1 (a NUMBER, b NUMBER)
NT1 TABLE OF type_1
NT2 TABLE OF NT1

例12-8のコード・フラグメントは、マルチレベル・コレクション全体で反復します。

例12-8 マルチレベル・コレクション・データ操作関数の使用

...
OCIColl *outer_coll;
OCIColl *inner_coll;
OCIIter *itr1, *itr2;
Type_1 *type_1_instance;
..
/* assume that outer_coll points to a valid coll of type NT2 */
checkerr(errhp, OCIIterCreate(envhp, errhp, outer_coll, &itr1));
for(eoc = FALSE;!OCIIterNext(envhp, errhp, itr1, (void  **) &elem,
(void  **) &elem_null, &eoc) && !eoc;)
{
inner_coll = (OCIColl *)elem;
/* iterate over inner collection.. */
checkerr(errhp, OCIIterCreate(envhp, errhp, inner_coll, &itr2));
for(eoc2 = FALSE;!OCIIterNext(envhp, errhp, itr2, (void  **)&elem2,
(void  **) &elem2_null, &eoc2) && !eoc2;)
{
type_1_instance = (Type_1 *)elem2;
/* use the fields of type_1_instance */
}
/* close iterator over inner collection */
checkerr(errhp, OCIIterDelete(envhp, errhp, &itr2));
}
/* close iterator over outer collection */
checkerr(errhp, OCIIterDelete(envhp, errhp, &itr1));
...

REF(OCIRef)

REF(参照)とは、オブジェクトを識別する識別子です。これは、一意にオブジェクトを検索する不透明な構造体です。REFによって、オブジェクトは別のオブジェクトを指し示すことができます。

Cアプリケーションでは、OCIRef *でREFを表現します。

関連項目:
すべてのREF操作関数のプロトタイプと説明は、表19-15を参照してください。

REF操作関数

表12-10は、REFの操作を実行する関数を示しています。

表12-10 REF操作関数

関数

用途

「OCIRefAssign()」

1つのREFを別のREFに代入します。

「OCIRefClear()」

REFを消去またはNULL化します。

「OCIRefFromHex()」

16進文字列をREFに変換します。

「OCIRefHexSize()」

REFの16進文字列表現のサイズを戻します。

「OCIRefIsEqual()」

2つのREFが等しいかどうかを比較します。

「OCIRefIsNull()」

REFがNULLかどうかをテストします。

「OCIRefToHex()」

REFを16進文字列に変換します。

REFの例

例12-9では、2つのREFがNULLかどうかをテストし、両者が等しいかどうかを比較し、一方のREFをもう一方のREFに代入します。OCIRefAssign()のコールで二重間接演算を使用していることに注意してください。

例12-9 REF操作関数の使用

OCIEnv       *envhp;
OCIError     *errhp;
sword        status;
boolean      refs_equal;
OCIRef       *ref1, *ref2;

/* assume REFs have been initialized to point to valid objects */
/*Compare two REFs for equality */
refs_equal = OCIRefIsEqual(envhp, ref1, ref2);
printf("After first OCIRefIsEqual:\n");
if(refs_equal)
printf("REFs equal\n");
else
printf("REFs not equal\n");

/*Assign ref1 to ref2 */
status = OCIRefAssign (envhp, errhp, ref1, &ref2);
if(status != OCI_SUCCESS)
/*error handling*/

/*Compare the two REFs again for equality */
refs_equal = OCIRefIsEqual(envhp, ref1, ref2);
printf("After second OCIRefIsEqual:\n");
if(refs_equal)
printf("REFs equal\n");
else
printf("REFs not equal\n");

オブジェクト型情報の格納およびアクセス

この項では、OCIデータ型と型記述子について説明します。

記述子オブジェクト

ある型をCREATE TYPE文で作成すると、その型はサーバーに格納され、型記述子オブジェクト(TDO)に関連付けられます。さらに、型の各データ属性、型の各メソッド、各メソッドの各パラメータ、およびメソッドが戻す結果について、記述子オブジェクトがデータベースに格納されます。表12-11は、記述子オブジェクトの種類別に、関連付けられているOCIデータ型を示しています。

表12-11 記述子オブジェクト

情報の種類

OCIデータ型

型

OCIType

型属性、コレクション要素、メソッド・パラメータ、メソッドの結果

OCITypeElem

メソッド

OCITypeMethod

OCI関数の中には(OCIBindObject()およびOCIObjectNew()を含む)、TDOを入力パラメータとして必要とする関数があります。アプリケーションで、その型のTDOをOCIType変数で取得できるOCITypeByName()をコールしてTDOを取得できます。TDOを取得すると、必要に応じて、そのTDOをその他のコールに渡すことができます。

AnyTypeインタフェース、AnyDataインタフェースおよびAnyDataSetインタフェース

AnyTypeインタフェース、AnyDataインタフェースおよびAnyDataSetインタフェースによって、自己記述データをモデル化できます。異機種間データ型を同じ列に格納し、アプリケーションでそのデータの型を問い合せることができます。

後続の項の説明では、これらの定義が使用されています。

- 永続型。SQL文CREATE TYPEを使用して作成される型。データベースに永続的に格納されます。

- 一時型。データベースに永続的には格納されない無名型の記述。必要に応じてプログラムで作成されます。また、必要な場合は、動的方式でアプリケーションの様々なコンポーネント間で型情報をやりとりするのに便利です。

- 自己記述データ。型情報をその実際の内容とともにカプセル化したデータ。OCIでは、OCIAnyDataデータ型によって、このようなデータがモデル化されます。ほとんどのSQL型のデータ値は、元のデータ値に変換しなおすことができるOCIAnyDataに変換できます。SQLやPL/SQLでは、SYS.ANYDATA型によって、このデータセットがモデル化されます。

- 自己記述データセット。一連のデータ・インスタンス(すべて同じ型)を型記述とともにカプセル化したもの。すべての型記述が同じである必要があります。OCIでは、OCIDataAnySetデータ型によって、このようなデータがモデル化されます。SQLやPL/SQLでは、SYS.ANYDATASETによって、このようなデータがモデル化されます。

これらの型記述および自己記述データの作成と操作に必要なインタフェースは、OCI (C言語)およびSQLとPL/SQLの両方で使用可能です。次の各項では、関連するOCIインタフェースを説明します。

関連項目:

- 「永続オブジェクト、一時オブジェクトおよび値」

- この項に示したOracleが供給する型の概要は、『Oracle Database SQL言語リファレンス』を参照してください。

型インタフェース

型インタフェースを使用して、名前付きおよび匿名の一時オブジェクト型(属性付きで構造化されたもの)とコレクション型を作成できます。OCITypeBeginCreate()コールを使用して、一時オブジェクト型とコレクション型の作成を開始します(作成する型は、型コード・パラメータによって決定されます)。

OCIDescriptorAlloc()を使用して、パラメータ・ハンドルを割り当てる必要があります。次に、OCIAttrSet()を使用して、型情報(オブジェクト型の属性とコレクション要素の型に関する情報)を設定する必要があります。オブジェクト型の場合は、例12-10に示すように、OCITypeAddAttr()を使用して属性情報をその型に追加します。最新の属性情報が追加された後で、OCITypeEndCreate()をコールする必要があります。

例12-10 型インタフェースを使用したオブジェクト型の作成

OCITypeBeginCreate( ...)        /* Begin Type Creation */
OCIDescriptorAlloc(...)
OCIAttrSet(...)
OCITypeAddAttr(...)             /* Add attribute 1 */
OCIAttrSet(...)
OCITypeAddAttr(...)             /* Add attribute 2 */
...
OCITypeEndCreate(...)           /* End Type Creation */

コレクション型の場合は、例12-11に示すように、OCITypeSetCollection()を使用して情報をコレクション要素型に設定します。次に、OCITypeEndCreate()をコールして、作成を終了します。

例12-11 型インタフェースを使用したコレクション型の作成

OCITypeBeginCreate( ...)        /* Begin Type Creation */
OCIDescriptorAlloc(...)
OCIAttrSet(...)
OCITypeSetCollection(...)       /* Set information on collection element */
OCITypeEndCreate(...)           /* End Type Creation */

OCIDescribeAny()コールを使用すると、永続型に対応するOCITypeを取得できます。

OCITypeコールのパラメータ記述子の作成

OCIDescriptorAlloc()コールを使用すると、OCIParam (親ハンドルが環境ハンドルの場合)を割り当てることができます。その後、次の使用可能な属性の型を使用して、OCIAttrSet()をコールし、関連する型情報を設定できます。

- OCI_ATTR_PRECISION

数値精度を設定します。(ub1 *)属性値を、精度値を保持しているバッファに渡します。

- OCI_ATTR_SCALE

数値のスケールを設定します。(sb1 *)属性値を、スケール値を保持しているバッファに渡します。

- OCI_ATTR_CHARSET_ID

キャラクタ・タイプのキャラクタ・セットIDを設定します。(ub2 *)属性値を、キャラクタ・セットIDを保持しているバッファに渡します。

- OCI_ATTR_CHARSET_FORM

キャラクタ・タイプのキャラクタ・セット・フォームを設定します。(ub1 *)属性値を、キャラクタ・セット・フォーム値を保持しているバッファに渡します。

- OCI_ATTR_DATA_SIZE

VARCHAR2、RAWなどの長さ。(ub2 *)属性値を、長さを保持しているバッファに渡します。

- OCI_ATTR_TYPECODE

型コードを設定します。(ub2 *)属性値を、型コードを保持しているバッファに渡します。この属性は、最初に設定する必要があります。

- OCI_ATTR_TDO

オブジェクトまたはコレクション属性のOCITypeを設定します。(OCIType *)属性値を、その属性に対応するOCITypeに渡します。AnyTypeの構成中に、このOCIParamを使用する場合、OCITypeが確保されていることを確認します。一時型属性の場合の割当て時間は、少なくともトップレベルのOCITypeが作成されている時間内である必要があります。それ以外の場合は例外が戻されます。

- 組込み型の場合、SQL型属性にアクセス可能な型コード(OCI_ATTR_TYPECODEに対する許容値)は、次のとおりです。
OCI_TYPECODE_DATE、OCI_TYPECODE_NUMBER、

OCI_TYPECODE_VARCHAR、OCI_TYPECODE_RAW、

OCI_TYPECODE_CHAR、OCI_TYPECODE_VARCHAR2、

OCI_TYPECODE_VARCHAR、OCI_TYPECODE_BLOB、

OCI_TYPECODE_BFILE、OCI_TYPECODE_CLOB、

OCI_TYPECODE_TIMESTAMP、OCI_TYPECODE_TIMESTAMP_TZ、

OCI_TYPECODE_TIMESTAMP_LTZ、

OCI_TYPECODE_INTERVAL_YMおよびOCI_TYPECODE_INTERVAL_DS。

- 属性またはコレクション要素の型自体が別の一時型である場合は、OCI_ATTR_TYPECODEをOCI_TYPECODE_OBJECT、OCI_TYPECODE_REF (REF用)、OCI_TYPECODE_VARRAYまたはOCI_TYPECODE_TABLEに設定し、OCI_ATTR_TDOを一時型に対応するOCITypeに設定します。

- ユーザー定義の型属性の場合、OCI_ATTR_TYPECODEに対する許容値は、次のとおりです。

- OCI_TYPECODE_OBJECT (オブジェクト型用)

- OCI_TYPECODE_REF (REF型用)

- OCI_TYPECODE_VARRAYまたはOCI_TYPECODE_TABLE (コレクション用)

ユーザー定義の場合は、OCI_ATTR_TDOを適切なユーザー定義型のOCITypeに設定する必要があります。

永続型のOCITypeの取得

次の例のように、OCIDescribeAny()コールを使用すると、永続型に対応するOCITypeを取得できます。

OCIDescribeAny(svchp, errhp. (void  *)"HR.EMPLOYEES",
(ub4)strlen("HR.EMPLOYEES"),
(ub1)OCI_OTYPE_NAME, (ub1)OCI_DEFAULT, OCI_PTYPE_TYPE, dschp);

記述ハンドル(dschp)から、OCIAttrGet()コールを使用して、OCITypeを取得できます。

型のアクセス・コール

一時型の記述を使用してOCIDescribeAny()をコールし、その型の動的記述にアクセスできます。OCITypeのポインタはobjtypeがOCI_OTYPE_PTRに設定されている場合、OCIDescribeAny()に直接渡すことができます。これによって、属性情報を名前および位置で取得できます。

OCIDescribeAny()への拡張

一時型が組込み型である(組込みの型コードで作成されている)場合、この一時型(OCI_PTYPE_TYPE型に相当)を記述するパラメータ・ハンドルでは、次の追加の属性がサポートされます。

- OCI_ATTR_DATA_SIZE

- OCI_ATTR_TYPECODE

- OCI_ATTR_DATA_TYPE

- OCI_ATTR_PRECISION

- OCI_ATTR_SCALE

- OCI_ATTR_CHARSET_ID

- OCI_ATTR_CHARSET_FORM

- OCI_ATTR_LFPRECISION

- OCI_ATTR_FSPRECISION

これらの属性には、型属性の記述時に通常付与される内容が含まれています。

注意:
これらの属性は、一時的な組込み型に対してのみサポートされます。属性OCI_ATTR_IS_TRANSIENT_TYPEとOCI_ATTR_IS_PREDEFINED_TYPEは、これらの型に該当します。永続型の場合、これらの属性は、その型の属性(OCI_PTYPE_TYPE_ATTR型に相当)のパラメータ・ハンドルでのみサポートされます。

OCIAnyDataインタフェース

OCIAnyDataは、型情報とその型のデータ・インスタンス(つまり、自己記述データ)をカプセル化します。OCIAnyDataは、OCIAnyDataConvert()コールを使用して、組込み型またはユーザー定義型のインスタンスから作成できます。このコールがOCIAnyDataへの変換(キャスト)を実行します。

また、オブジェクト型およびコレクション型は、型情報(OCIType)を指定してOCIAnyDataBeginCreate()をコールすることにより、ピースごと(オブジェクト型に対して一度に1つの属性または一度に1つのコレクション要素)に構成できます。その後、オブジェクト型に対してOCIAnyDataAttrSet()、コレクション型に対してOCIAnyDataCollAddElem()を使用できます。最後に、OCIAnyDataEndCreate()コールを使用して、作成プロセスを終了します。

その後で、アクセス・ルーチンを起動できます。OCIAnyDataを対応する型のインスタンスに変換(キャスト)するには、OCIAnyDataAccess()を使用します。

オブジェクト型またはコレクション型に基づいたOCIAnyDataも個別にアクセスできます。

パフォーマンス改善のために、特別なコレクション構成とアクセス・コールが用意されています。例12-12に示すように、これらのコールを使用すると、メモリー内での不要なコレクションの作成やコレクション全体のコピーなどが回避できます。

例12-12 パフォーマンス改善のための特別な構成とアクセス・コールの使用

OCIAnyDataConvert(...)        /* Cast a built-in or user-defined type instance
to an OCIAnyData in 1 call. */

OCIAnyDataBeginCreate(...)    /* Begin AnyData Creation */

OCIAnyDataAttrSet(...)        /* Attribute-wise construction for object types */

または

OCIAnyDataCollAddElem(...)    /* Element-wise construction for collections */

OCIAnyDataEndCreate(...)      /* End OCIAnyData Creation */

OCIAnyData関数のNCHAR型コード

OCIAnyDataTypeCodeToSqlt()関数は、OCIAnyData値のOCITypeCodeを、OCIAnyData APIが戻す値の表現に対応するSQLTコードに変換します。

次の型コードは、OCIAnyData関数でのみ使用されます。

- OCI_TYPECODE_NCHAR

- OCI_TYPECODE_NVARCHAR2

- OCI_TYPECODE_NCLOB

OCIDescribeAny()などその他の関数のコールでは、これらの型コードは戻されず、キャラクタ・セット・フォームを使用してデータがNCHARかどうか(キャラクタ・セット・フォームがSQLCS_NCHARかどうか)を判断する必要があります。

OCIAnyDataTypeCodeToSqlt()は、OCI_TYPECODE_CHARおよびOCI_TYPECODE_VARCHAR2を、キャラクタ・セット・フォームがSQLCS_IMPLICITの出力値SQLT_VST (OCIStringマッピングに対応)に変換します。また、OCI_TYPECODE_NVARCHAR2は、キャラクタ・セット・フォームがSQLCS_NCHARのSQLT_VST (OCIStringマッピングはOCIAnyData APIで使用されます)を戻します。

関連項目:
「OCIAnyDataTypeCodeToSqlt()」

OCIAnyDataSetインタフェース

OCIAnyDataSetは、型情報とその型のインスタンスの集合をカプセル化します。構成処理を開始するには、OCIAnyDataSetBeginCreate()をコールします。OCIAnyDataSetAddInstance()をコールして新規インスタンスを追加すると、このコールは、そのインスタンスに対応するOCIAnyDataを戻します。

次に、このインスタンスを作成するためのOCIAnyData関数を呼び出すことができます。すべてのインスタンスが追加されたら、OCIAnyDataSetEndCreate()をコールします。

アクセスする場合は、OCIAnyDataSetGetInstance()をコールして、そのインスタンスに対応するOCIAnyDataを取得します。順次アクセスのみがサポートされます。その後で、次の例に示すように、OCIAnyDataアクセス関数を起動できます。

OCIAnyDataSetBeginCreate(...)   /* Begin AnyDataSet Creation */
OCIAnyDataSetAddInstance(...)   /* Add a new instance to the AnyDataSet */
/* Use the OCIAnyData*() functions to create
the instance */
OCIAnyDataSetEndCreate(...)     /* End OCIAnyDataSet Creation */

関連項目:
これらのインタフェースでの各コールの詳細は、第21章を参照してください。

名前付きデータ型のバインド

この項では、オブジェクトやコレクションなどの名前付きデータ型とREFのバインドについて説明します。

名前付きデータ型のバインド

名前付きデータ型(オブジェクト型やコレクション)のバインドでは、OCIBindByName()またはOCIBindByPos()の後にもう1つのバインド・コールが必要です。OCIBindObject()コールで、オブジェクト型のバインド固有の追加属性を設定します。OCIアプリケーションでは、このコールを使用して、オブジェクト・データ型の列を持つ表からデータをフェッチします。

OCIBindObject()コールでパラメータの1つとして、名前付きデータ型の型記述子オブジェクト(TDO)を受け取ります。データ型OCITypeのTDOは、名前付きデータ型が作成されるときに作成され、データベースに格納されます。これには、型とその属性についての情報が入っています。アプリケーションでは、OCITypeByName()をコールしてTDOを取得できます。

OCIBindObject()コールでは、名前付きデータ型バインド用の標識変数または構造体も設定します。

名前付きデータ型をバインドするときは、SQLT_NTYデータ型定数を使用して、バインドするプログラム変数のデータ型を指定します。SQLT_NTYは、名前付きデータ型を表現するC構造体をバインドすることを示します。この構造体へのポインタをバインド・コールに渡します。

スーパータイプがある場合は、継承とインスタンスの代入性を使用して、サブタイプのインスタンスをバインドできます。

場合によっては、名前付きデータ型の操作に3つのバインド・コールが必要になることがあります。たとえば、名前付きデータ型の静的配列をPL/SQL表にバインドするには、OCIBindByName()、OCIBindArrayOfStruct()およびOCIBindObject()という3つのコールを呼び出します。

関連項目:

- これらのデータ型を使用してデータベースから埋込みオブジェクトをフェッチする方法の詳細は、「埋込みオブジェクトのフェッチ」を参照してください。

- 「名前付きデータ型およびREFバインドの情報」

- 「記述子オブジェクト」

REFのバインド

名前付きデータ型と同様に、REFのバインドも2ステップで処理します。最初にOCIBindByName()またはOCIBindByPos()をコールし、次にOCIBindObject()をコールします。

REFは、SQLT_REFデータ型を使用してバインドします。SQLT_REFを使用する場合、バインドするプログラム変数は、OCIRef *型の変数にする必要があります。

スーパータイプへのREFがある場合は、継承とREFの代入性を使用して、REFの値をサブタイプのインスタンスにバインドできます。

関連項目:

- REFのオブジェクトへのバインドと確保の詳細は、「サーバーからのオブジェクト参照の取出し」を参照してください。

- 他の重要な情報は、「名前付きデータ型およびREFバインドの情報」を参照してください。

名前付きデータ型およびREFバインドの情報

名前付きデータ型およびREFバインドを取り扱う場合は、次に示す重要な情報について注意してください。メモリー割当てと標識変数の使用方法についての参照先も示します。

- バインド対象のデータ型がSQLT_NTYである場合は、OCIBindObject()コールのインジケータ構造体パラメータ(void ** indpp)が使用され、スカラー・インジケータは完全に無視されます。

- データ型がSQLT_REFの場合は、スカラー・インジケータが使用され、OCIBindObject()のインジケータ構造体のパラメータは完全に無視されます。

- インジケータ構造体の使用はオプションです。ユーザーは、indppパラメータのNULLポインタをOCIBindObject()コールに渡すことができます。そのため、バインド時に、オブジェクトがアトミックNULLではなく、そのオブジェクトのどの属性もNULLではありません。

- OCIBindObject()コールのインジケータ構造体サイズ・ポインタindspおよびプログラム変数サイズ・ポインタpgvspは、オプションです。これらのパラメータが不要な場合、ユーザーはNULLを渡すことができます。

配列バインドに関する情報

配列挿入または配列フェッチ用に、名前付きデータ型またはREFの配列バインドを行うには、ユーザーはポインタの配列を適切な型のバッファ(事前割当て済またはそれ以外)に渡す必要があります。同様に、スカラー・インジケータの配列(SQLT_REF型)またはポインタ配列を、インジケータ構造体(SQLT_NTY型)に渡す必要があります。

関連項目:
SQLT_NTYの詳細は、「名前付きデータ型: オブジェクト、VARRAY、NESTED TABLE」を参照してください。

名前付きデータ型の定義

この項では、名前付きデータ型(オブジェクト、コレクションなど)とREFの定義について説明します。

名前付きデータ型出力変数の定義

名前付きデータ型(オブジェクト型、NESTED TABLE、VARRAY)の定義には、2つの定義コールが必要です。最初にdtyパラメータにSQLT_NTYを指定して、OCIDefineByPos()をコールします。アプリケーションでは、OCIDefineByPos()に続いて、OCIDefineObject()をコールして、名前付きデータ型定義に関係するその他の属性を設定する必要があります。この場合、OCIDefineByPos()内のデータ・バッファ・ポインタは無視されます。

名前付きデータ型定義のSQLT_NTYデータ型定数を指定します。この場合、結果のデータが名前付きデータ型のホスト言語表現の中にフェッチされます。通常、これはObject Type Translatorによって生成されるC構造体になります。

OCIDefineObject()コールを行うときは、C構造体のアドレスへのポインタ(事前割当て済またはそれ以外)を定義する必要があります。オブジェクトは、OCIObjectNew()を使用して作成され、キャッシュまたはユーザー定義のメモリーに割り当てられます。

ただし、継承が行われる場合は、オブジェクト・キャッシュ内のオブジェクトを使用し、ユーザー・メモリーから割り当てられたオブジェクトをスタックから渡さないことを強くお薦めします。そうしない場合、インスタンスの代入性により、クライアントがスーパータイプ・インスタンスを予期しているにもかかわらず、サーバーがサブタイプ・インスタンスを戻してしまうことがあります。サーバーは、オブジェクトを動的にサイズ変更する必要があります。この操作は、キャッシュ内のオブジェクトに対してのみ可能です。

関連項目:
名前付きデータ型の定義に関するその他の詳細は、「名前付きデータ型、REF定義およびPL/SQL OUTバインドの情報」を参照してください。

REF出力変数の定義

名前付きデータ型と同様に、REF出力変数の定義も2ステップで処理します。第1ステップでOCIDefineByPos()をコールし、第2ステップでOCIDefineObject()をコールします。また、名前付きデータ型の場合と同様に、OCIDefineByPos()のdtyパラメータにSQLT_REFデータ型定数を渡します。

SQLT_REFでは、アプリケーションで結果として得るデータをOCIRef *型変数にフェッチすることを示します。「OCIでのオブジェクトの操作」で説明するとおり、このREFをオブジェクトの確保とナビゲーションの一部として使用します。

関連項目:
REFの定義に関するその他の詳細は、「名前付きデータ型、REF定義およびPL/SQL OUTバインドの情報」を参照してください。

名前付きデータ型、REF定義およびPL/SQL OUTバインドの情報

名前付きデータ型およびREF定義を取り扱う場合は、次に示す重要な情報について注意してください。メモリー割当てと標識変数の使用方法についての参照先も示します。

PL/SQL OUTバインドとは、プレースホルダをPL/SQLブロックの出力変数にバインドすることです。SQL文では出力バッファを定義コールで設定しますが、PL/SQLブロックでは出力バッファをバインド・コールで設定します。詳細は、「PL/SQLのプレースホルダのバインド」を参照してください。

- 定義対象のデータ型がSQLT_NTYの場合は、OCIDefineObject()コールのインジケータ構造体パラメータ(void ** indpp)が使用され、スカラー・インジケータは完全に無視されます。

- データ型がSQLT_REFの場合は、スカラー・インジケータが使用され、OCIDefineObject()のインジケータ構造体のパラメータは完全に無視されます。

- インジケータ構造体の使用はオプションです。ユーザーは、indppパラメータのNULLポインタをOCIDefineObject()コールに渡すことができます。そのため、フェッチまたはPL/SQL OUTバインド時に、NULLであるかどうかの情報はユーザーには認識されません。

- SQL定義またはPL/SQL OUTバインドの場合、プログラマは出力変数またはインジケータのいずれかに対して事前割当済メモリーを渡すことができます。渡されると、その事前割当て済メモリーが結果データの格納に使用され、2次メモリー(アウト・ライン・メモリー)がある場合は、その内容がすべて割当て解除されます。事前割当て済メモリーは、キャッシュ(OCIObjectNew()コールの結果)から取得する必要があります。

注意:
キャッシュからではなく、クライアント・アプリケーションで所有するメモリー領域からメモリーを割り当てる場合は、オブジェクトにアウト・ライン2次メモリーがないことを確認する必要があります。

SQLT_NTY型を使用したオブジェクト定義に対してオブジェクト・メモリーを事前割当てするには、クライアント・アプリケーションでOCIObjectNew()関数を使用する必要があります。クライアント・アプリケーションでは、malloc()を使用する割当てや、スタックへの割当てなど、独自のプライベート・メモリー領域へのオブジェクトの割当ては行わないでください。OCIObjectNew()関数によって、オブジェクト・キャッシュにオブジェクトが割り当てられます。割り当てられたオブジェクトは、OCIObjectFree()を使用すると解放できます。OCIObjectNew()およびOCIObjectFree()の詳細は、第18章を参照してください。

注意:
ユーザーがオブジェクト・メモリーを事前割当てせずに、出力変数をNULLポインタ値に初期化した場合でも、OCIDefineObject()の動作に変化はありません。この場合、オブジェクトはOCIライブラリによって暗黙的にオブジェクト・キャッシュ内に割り当てられます。

- SQL定義またはPL/SQL OUTバインドの場合、ユーザーが出力変数またはインジケータに対してNULLアドレスを渡すと、その変数またはインジケータ用のメモリーは、OCIによって暗黙的に割り当てられます。

- SQLT_NTY型の出力オブジェクトが(SQL定義またはPL/SQL OUTバインドで)アトミックNULLの場合は、NULLインジケータ構造体のみが(必要であれば暗黙的に)割り当てられてデータが挿入され、オブジェクトがアトミックNULLであることが明示されます。トップレベルのオブジェクトは、暗黙的に割り当てられません。

- アプリケーションでは、OCIObjectFree()をコールしてインジケータを解放できます。トップレベルのオブジェクトがある場合は(アトミックNULLでないオブジェクトの場合など)、そのトップレベルのオブジェクトをOCIObjectFree()で解放すると、インジケータも解放されます。オブジェクトがアトミックNULLである場合は、トップレベルのオブジェクトがないので、インジケータを個別に解放する必要があります。

- OCIDefineObject()コールのインジケータ構造体サイズ・ポインタindszpおよびプログラム変数サイズ・ポインタpvszspは、オプションです。これらのパラメータが不要な場合、ユーザーはNULLを渡すことができます。

配列定義に関する情報

名前付きデータ型またはREFの配列定義を行うには、ユーザーはポインタ配列を適切な型のバッファ(事前割当て済またはそれ以外)に渡す必要があります。同様に、スカラー・インジケータの配列(SQLT_REF型)またはポインタ配列を、インジケータ構造体(SQLT_NTY型)に渡す必要があります。

Oracle Cデータ型のバインドおよび定義

これまでの章では、OCIのバインド操作と定義操作について説明しました。「OCIのプレースホルダのバインド」では、OCIバインド操作の基本について、「OCIでの出力変数の定義」では、OCI定義操作の基本について説明しています。名前付きデータ型およびREFのバインドと定義の詳細は、第5章を参照してください。

バインドと定義の基本的な機能に関する章では、アプリケーションでSQL文の入力(バインド)値として、または問合せに対する出力(定義)バッファとしてスカラー変数またはスカラーの配列を使用する方法を示しています。

名前付きデータ型とREFに関する項では、オブジェクトや参照をバインドまたは定義する方法を説明しています。「オブジェクトの確保」では、さらにオブジェクト参照の確保について、「埋込みオブジェクトのフェッチ」では、埋込みインスタンスのフェッチについて、「オブジェクト・ナビゲーション」では、オブジェクト・ナビゲーションについて説明しています。

この項では、この章で説明するデータ型マッピングに従って、個々の属性値のバインドと定義の方法を説明します。

この章で定義する型の1つであるOCINumber、OCIStringなどの変数は、一般にアプリケーションで宣言でき、適切なデータ型コードが指定されているため、OCIバインドまたは定義操作で直接使用できます。表12-12は、Cマッピングとともにバインドおよび定義で使用できるデータ型と、バインドまたは定義コールのdty (データ型コード)パラメータで指定する必要のある、OCI外部データ型のリストです。

表12-12 バインドおよび定義用のデータ型マッピング

データ型

Cマッピング

OCIの外部データ型とコード

Oracle NUMBER

OCINumber

VARNUM(SQLT_VNU)

Oracle DATE

OCIDate

SQLT_ODT

BLOB

OCILobLocator *

SQLT_BLOB

CLOBおよびNCLOB

CILobLocator *

SQLTY_LOB

VARCHAR2、NVARCHAR2

OCIString *

SQLT_VST 脚注 1

RAW

OCIRaw *

SQLT_LVB 脚注 1

CHAR、NCHAR

OCIString *

SQLT_VST

オブジェクト

struct *

名前付きデータ型(SQLT_NTY)

REF

OCIRef *

REF(SQLT_REF)

VARRAY

OCIArray *

名前付きデータ型(SQLT_NTY)

NESTED TABLE

OCITable *

名前付きデータ型(SQLT_NTY)

DATETIME

OCIDateTime *

詳細は、「日時および時間隔(OCIDateTime、OCIInterval)」を参照してください。

INTERVAL

OCIInterval *

詳細は、「日時および時間隔(OCIDateTime、OCIInterval)」を参照してください。

脚注 1 OCIString *型の定義変数にデータをフェッチするには、最初にOCIStringResize()ルーチンを使用して文字列のサイズを設定する必要があります。そのためには、記述操作によって選択リスト・データの長さを取得することが必要な場合があります。同様に、OCIRaw *も最初にOCIStringResize()でサイズを決定する必要があります。

次の項では、Cにマッピングしたデータ型のOCIアプリケーションでの使用例を示します。

関連項目:
OCI外部データ型の説明とデータ型コードのリストは、第3章を参照してください。

バインドおよび定義の例

この項では、OCIのバインド操作と定義操作でOCINumber型の変数を使用する例を示します。

この例では、次のようなpersonというオブジェクト型が作成されていると仮定します。

CREATE TYPE person AS OBJECT
(name     varchar2(30),
salary     number);

この型を使用して、person型の列を持つemployees (従業員)表を作成します。

CREATE TABLE employees
(emp_id    number,
job_title  varchar2(30),
emp        person);

Object Type Translator (OTT)では、personに対して次のC構造体とNULLインジケータ構造体が生成されます。

struct person
{   OCIString * name;
OCINumber salary;};
typedef struct person person;

struct person_ind
{   OCIInd  _atomic;
OCIInd  name;
OCIInd  salary;}
typedef struct person_ind person_ind;

関連項目:
OTTの詳細は、第15章を参照してください。

employees表は値が入り、OCIアプリケーションはpersonの変数を宣言するとします。

person *my_person;

また、アプリケーションでは、次のように、SELECT文によってオブジェクトがその変数にフェッチされたとします。

text *mystmt = (text *) "SELECT person FROM employees
WHERE emp.name='Andrea'";

この場合、「OCIでの拡張定義操作」の説明に従って、名前付きデータ型の適切なOCI定義コールを使用し、my_personをこの文の出力変数として定義する必要があります。文を実行すると、Andreaという名前のpersonオブジェクトがmy_person変数に取り出されます。

オブジェクトがmy_personに取り出されると、OCIアプリケーションでmy_personの名前や給与などの属性にアクセスできるようになります。

アプリケーションでは、別の従業員の給与を、次の例ようにAndreaと同様に更新します。

text *updstmt = (text *) "UPDATE employees SET emp.salary = :newsal
WHERE emp.name = 'MONGO'";

my_person->salaryに格納されているAndreaの給与は、プレースホルダ:newsalにバインドされ、VARNUMの外部データ型(データ型コード=6)をバインド操作に指定します。

OCIBindByName(...,":newsal",...,&my_person->salary,...,6,...);
OCIStmtExecute(...,updstmt,...);

文を実行すると、データベースにあるMongoの給与が、my_personに格納されているように、Andreaの給与と等しくなります。

その反対に、Mongoの給与をデータベースに問い合せてから給与に必要な割当てを行うことにより、アプリケーションでAndreaの給与をMongoの給与と同額になるよう更新できます。

text *selstmt = (text *) "SELECT emp.salary FROM employees
WHERE emp.name = 'MONGO'";
OCINumber mongo_sal;
...
OCIDefineByPos(...,1,...,&mongo_sal,...,6,...);
OCIStmtExecute(...,selstmt,...);
OCINumberAssign(...,&mongo_sal, &my_person->salary);

この場合には、アプリケーションでOCINumberの型の出力変数を宣言し、それを定義のステップで使用します。アプリケーションでは、位置1の出力変数も定義し、適切なデータ型コード(VARNUMの場合は6)を使用します。

mongo_salというOCINumberに給与の値をフェッチし、適切なOCI関数OCINumberAssign()を使用して、現在キャッシュ内にあるAndreaオブジェクトのコピーに新しい給与を割り当てます。データベース内にあるデータを変更するには、変更内容をサーバーにフラッシュする必要があります。

給与更新の例

前の項の例では、Oracleデータ型がバインド操作と定義操作に与える柔軟性に関して説明しました。この項では、同じ操作を異なる方法でどのように実行するかを説明します。これらのデータ型は、OCIアプリケーション内で様々な方法で使用できます。

この項の例は、特定のOCI作業を実行するのに使用されるコールのフローを説明します。これらの例では拡張擬似コードを使用しています。実際の関数名を使用していますが、簡素化のためにパラメータとタイプキャストは一部のみ示します。ハンドルの割当てなど、その他の必要なOCIコールも省略しています。

シナリオ

これから示す例のシナリオは、次のとおりです。

- ある病院のemployees表に、BRUCEという従業員が存在します。前の項のperson型およびemployees表の作成文を参照してください。

- Bruceの現在の職種は、RADIOLOGISTです。

- Bruceは、RADIOLOGY_CHIEFに昇進したため、それに伴った昇給があります。

- 次に示すように、病院の給与はドル単位の整数値とし、職種に応じて設定し、salariesという表に格納します。

CREATE TABLE salaries
(job_title   varchar2(20),
salary       integer));

- Bruceの給与を昇進にあわせて更新します。

Bruceの給与を更新して昇進を反映するには、アプリケーションでは、salaries表からRADIOLOGY_CHIEFに該当する給与を取りだして、Bruceの給与を更新する必要があります。別のステップで、彼の新しい職種と変更済オブジェクトをデータベースに書き込みます。

次のようにperson型の変数を宣言したとします。

person * my_person;

Bruceに対応するオブジェクトはpersonにフェッチされます。給与更新を実行するには、次の各項に示す3通りの方法があります。

方法1 - フェッチ、変換、割当て

例12-13では次の方法をとります。

1. 整変数を使用して従来のOCI定義を行い、データベースから新しい給与を取り出します。

2. 整数をOCINumberに変換します。

3. 新しい給与をBruceに割り当てます。

例12-13 給与更新の方法1: フェッチ、変換、割当て

#define INT_TYPE 3        /* data type code for sword integer define */

text *getsal = (text *) "SELECT salary FROM salaries
WHERE job_title='RADIOLOGY_CHIEF'";
sword    new_sal;
OCINumber   orl_new_sal;
...
OCIDefineByPos(...,1,...,new_sal,...,INT_TYPE,...);
/* define int output */
OCIStmtExecute(...,getsal,...);
/* get new salary as int */
OCINumberFromInt(...,new_sal,...,&orl_new_sal);
/* convert salary to OCINumber */
OCINumberAssign(...,&orl_new_sal, &my_person->salary);
/* assign new salary */

方法2 - フェッチ、割当て

この方法(例12-14)では、方法1で説明したステップを1つ省略します。

1. OCINumber型の出力変数を定義します。そのため値を取り出した後の変換は必要ありません。

2. 新しい給与をBruceに割り当てます。

例12-14 給与更新の方法2: フェッチ、割当て、変換なし

#define VARNUM_TYPE 6         /* data type code for defining VARNUM */

text *getsal = (text *) "SELECT salary FROM salaries
WHERE job_title='RADIOLOGY_CHIEF'";
OCINumber   orl_new_sal;
...
OCIDefineByPos(...,1,...,orl_new_sal,...,VARNUM_TYPE,...);
/* define OCINumber output */
OCIStmtExecute(...,getsal,...);      /* get new salary as OCINumber */
OCINumberAssign(...,&orl_new_sal, &my_person->salary);
/* assign new salary */

方法3 - 直接フェッチ

この方法(例12-15)では、操作全体を1回の定義とフェッチで実行します。出力変数を介在させる必要はなく、データベースから取り出した値を、キャッシュに格納されているオブジェクトの給与属性に直接フェッチします。

Bruceに対応するオブジェクトはオブジェクト・キャッシュ内に確保されているため、その給与属性の位置を定義変数として使用し、その変数に直接実行し、フェッチを行います。

例12-15 給与更新の方法3: 直接フェッチ

#define VARNUM_TYPE 6         /* data type code for defining VARNUM */

text *getsal = (text *) "SELECT salary FROM salaries
WHERE job_title='RADIOLOGY_CHIEF'";
...
OCIDefineByPos(...,1,...,&my_person->salary,...,VARNUM_TYPE,...);
/* define bruce's salary in cache as output variable */
OCIStmtExecute(...,getsal,...);
/* execute and fetch directly */

まとめと注意

この3つの例に示したように、Cデータ型を使用すると柔軟性のあるバインドと定義を実行できます。たとえば、整数をフェッチし、OCINumberに変換して操作できます。この方法では、OCINumberを中間的な変数として使用し、問合せの結果を格納できます。あるいは、目的のオブジェクトのOCINumber属性にデータを直接フェッチすることもできます。

注意:
OCIのこれらの例では、問合せの実行前に出力変数が定義されている場合、結果として得られるデータは、出力バッファに直接プリフェッチされることを覚えておいてください。

これらの例では、アプリケーションで変更がデータベースに確実に永続的に書き込まれるためには、追加ステップが必要です。この追加ステップには、SQLのUPDATEコールとOCIトランザクションのコミット・コールを含めることができます。

これらの例ではすべて定義操作を処理していますが、同じような状況がバインドにも当てはまります。

同様に、これらの例ではOCINumber型のみを扱いましたが、この章でこれから説明する他のOracleのC型についても、同じような種々の操作を実行できます。

SQLT_NTYのバインドおよび定義の例

次のコード・フラグメントは、OCIBindObject()などのバインド・コールでのSQLT_NTY名前付きデータ型、およびOCIDefineObject()などの定義コールでのSQLT_NTY名前付きデータ型の使用方法を示しています。それぞれの例で、前に定義したSQL文を処理します。

SQLT_NTYのバインドの例

例12-16は、OCIBindObject()などのバインド・コールでのSQLT_NTY名前付きデータ型の使用方法を示しています。

例12-16 OCIBindObject()などのSQLT_NTYバインド・コールの使用

/*
** This example performs a SQL insert statement
*/
void insert(envhp, svchp, stmthp, errhp, insstmt, nrows)
OCIEnv *envhp;
OCISvcCtx *svchp;
OCIStmt *stmthp;
OCIError *errhp;
text *insstmt;
ub2   nrows;
{
OCIType *addr_tdo = (OCIType *)0 ;
address  addrs;
null_address naddrs;
address *addr = &addrs;
null_address *naddr = &naddrs;
sword custno =300;
OCIBind *bnd1p, *bnd2p;
ub2 i;

/* define the application request  */
checkerr(errhp, OCIStmtPrepare(stmthp, errhp, (text *) insstmt,
(ub4) strlen((char *)insstmt),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));

/* bind the input variable */
checkerr(errhp, OCIBindByName(stmthp, &bnd1p, errhp, (text *) ":custno",
(sb4) -1, (void  *) &custno,
(sb4) sizeof(sword), SQLT_INT,
(void  *) 0, (ub2 *)0, (ub2 *)0, (ub4) 0, (ub4 *) 0,
(ub4) OCI_DEFAULT));

checkerr(errhp, OCIBindByName(stmthp, &bnd2p, errhp, (text *) ":addr",
(sb4) -1, (void  *) 0,
(sb4) 0, SQLT_NTY, (void  *) 0, (ub2 *)0, (ub2 *)0,
(ub4) 0, (ub4 *) 0, (ub4) OCI_DEFAULT));

checkerr(errhp,
OCITypeByName(envhp, errhp, svchp, (const text *)
SCHEMA, (ub4) strlen((char *)SCHEMA),
(const text *)"ADDRESS_VALUE",
(ub4) strlen((char *)"ADDRESS_VALUE"),
(text *)0, 0, OCI_DURATION_SESSION,
OCI_TYPEGET_HEADER, &addr_tdo));

if(!addr_tdo)
{
printf("Null tdo returned\n");
return;
}

checkerr(errhp, OCIBindObject(bnd2p, errhp, addr_tdo, (void  **) &addr,
(ub4 *) 0, (void  **) &naddr, (ub4 *) 0));

SQLT_NTYの定義の例

例12-17は、OCIDefineObject()などの定義コールでのSQLT_NTY名前付きデータ型の使用方法を示しています。

例12-17 OCIDefineObject()などのSQLT_NTY定義コールの使用

/*
** This example executes a SELECT statement from a table that includes
** an object.
*/

void selectval(envhp, svchp, stmthp, errhp)
OCIEnv *envhp;
OCISvcCtx *svchp;
OCIStmt *stmthp;
OCIError *errhp;
{
OCIType *addr_tdo = (OCIType *)0;
OCIDefine *defn1p, *defn2p;
address *addr = (address *)NULL;
sword custno =0;
sb4 status;

/* define the application request  */
checkerr(errhp, OCIStmtPrepare(stmthp, errhp, (text *) selvalstmt,
(ub4) strlen((char *)selvalstmt),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));

/* define the output variable */
checkerr(errhp, OCIDefineByPos(stmthp, &defn1p, errhp, (ub4) 1, (void  *)
&custno, (sb4) sizeof(sword), SQLT_INT, (void  *) 0, (ub2 *)0,
(ub2 *)0, (ub4) OCI_DEFAULT));

checkerr(errhp, OCIDefineByPos(stmthp, &defn2p, errhp, (ub4) 2, (void  *)
0, (sb4) 0, SQLT_NTY, (void  *) 0, (ub2 *)0,
(ub2 *)0, (ub4) OCI_DEFAULT));

checkerr(errhp,
OCITypeByName(envhp, errhp, svchp, (const text *)
SCHEMA, (ub4) strlen((char *)SCHEMA),
(const text *) "ADDRESS_VALUE",
(ub4) strlen((char *)"ADDRESS_VALUE"),
(text *)0, 0, OCI_DURATION_SESSION,
OCI_TYPEGET_HEADER, &addr_tdo));

if(!addr_tdo)
{
printf("NULL tdo returned\n");
return;
}

checkerr(errhp, OCIDefineObject(defn2p, errhp, addr_tdo, (void  **)
&addr, (ub4 *) 0, (void  **) 0, (ub4 *) 0));

checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4) 0,
(OCISnapshot *) NULL, (OCISnapshot *) NULL, (ub4) OCI_DEFAULT));

13 ダイレクト・パス・ロード

ダイレクト・パス・ロード関数は、データを外部ファイルから表とパーティションにロードするために使用します。

この章は、次の項目で構成されています。

- ダイレクト・パス・ロードの概要

- オブジェクト型のダイレクト・パス・ロード

- ピース単位のダイレクト・パス・ロード

- ダイレクト・パス・コンテキスト・ハンドルとオブジェクト型の属性

ダイレクト・パス・ロードの概要

ダイレクト・パス・ロード・インタフェースを使用すると、OCIアプリケーションからOracle Databaseのダイレクト・パス・ロード・エンジンにアクセスし、SQL*Loaderユーティリティの関数を実行できます。この機能によって、データを外部ファイルから表またはパーティション表のパーティションのいずれかにロードできます。

図13-1では、この章のテーマを紹介しています。この図のクライアント側では、データは入力バッファを通して列配列に入力されます。OCIDirPathColArrayToStream()コールにより、データがストリーム形式でサーバー側に移動します。これによりデータが列配列に渡され、この列配列はブロック・フォーマッタを使用して、データをデータベース表に送信します。

図13-1 ダイレクト・パス・ロード

OCIダイレクト・パス・ロード・インタフェースには、複数行のデータが含まれたダイレクト・パス・ストリームをロードすることによって複数の行をロードできます。

ダイレクト・パスAPIを使用するには、クライアント・アプリケーションで次のステップを実行します。

1. OCIを初期化します。

2. ダイレクト・パス・コンテキスト・ハンドルを割り当てて、属性を設定します。

3. ロードするオブジェクト(表、パーティションまたはサブパーティション)の名前を指定します。

4. オブジェクトの列の外部データ型を記述します。

5. ダイレクト・パス・インタフェースを準備します。

6. 1列以上の列配列を割り当てます。

7. 1つ以上のダイレクト・パス・ストリームを割り当てます。

8. 列配列内のエントリを、各列に対する入力データ値を指し示すように設定します。

9. 列配列をダイレクト・パス・ストリーム形式に変換します。

10. ダイレクト・パス・ストリームをロードします。

11. 発生したエラーをすべて取り出します。

12. ダイレクト・パス終了関数をコールします。

13. ハンドルおよびデータ構造を解放します。

14. サーバーから切断します。

ステップ8から11は、ロード対象のデータに従って繰り返すことができます。

ダイレクト・ロード操作では、オブジェクトでDML操作が行われないように、ロード対象のオブジェクトをロックする必要があります。オブジェクトがロードされる間、問合せはロック解除されており、使用可能です。DMLロックのモードおよび取得されるDMLロックは、OCI_ATTR_DIRPATH_PARALLELオプションの仕様、および表全体のロードではなくパーティションまたはサブパーティションのロードが実行されているかどうかに応じて異なります。

- 表のロードの場合、OCI_ATTR_DIRPATH_PARALLELオプションの設定とその結果は、次のとおりです。

- FALSEの場合、表DML X-Lockが取得されます。

- TRUEの場合、表DML S-Lockが取得されます。

- パーティションのロードの場合、OCI_ATTR_DIRPATH_PARALLELオプションの設定とその結果は、次のとおりです。

- FALSEの場合、表DML SX-LockとパーティションDML X-Lockが取得されます。

- TRUEの場合、表DML SS-LockとパーティションDML S-Lockが取得されます。

関連項目:
「ダイレクト・パス・コンテキスト・ハンドル(OCIDirPathCtx)の属性」

ダイレクト・パス・ロードでサポートされるデータ型

ダイレクト・パス・ロード操作では、スカラー列に対して有効な外部データ型は次のとおりです。

- SQLT_CHR

- SQLT_DAT

- SQLT_INT

- SQLT_UIN

- SQLT_FLT

- SQLT_BIN

- SQLT_NUM

- SQLT_PDN

- SQLT_CLOB

- SQLT_BLOB

- SQLT_DATE

- SQLT_TIMESTAMP

- SQLT_TIMESTAMP_TZ

- SQLT_TIMESTAMP_LTZ

- SQLT_INTERVAL_YM

- SQLT_INTERVAL_DS

次の外部オブジェクトのデータ型がサポートされています。

- SQLT_NTY - 列オブジェクト(FINALとNOT FINAL)およびSQL文字列の列

- SQLT_REF - REF列(FINALとNOT FINAL)

次の表の型がサポートされています。

- ネストした表

- オブジェクト表(FINALとNOT FINAL)

関連項目:

- 列のデータ型の設定または取出しの詳細は、「列パラメータ属性へのアクセス」を参照してください。

- データ型の詳細は、表3-2を参照してください。

ダイレクト・パス・ハンドル

ダイレクト・パス・ロードは、ダイレクト・パス配列の挿入操作に対応しています。ダイレクト・パス・ロード・インタフェースでは、次のハンドルを使用してロードされるオブジェクトおよび操作するデータの指定が記録されます。

- ダイレクト・パス・コンテキスト

- OCIダイレクト・パス関数コンテキスト

- ダイレクト・パス列配列およびダイレクト・パス関数列配列

- ダイレクト・パス・ストリーム

関連項目:
「ダイレクト・パス・ロード・ハンドル属性」およびこの後述のダイレクト・パス属性に関する説明を参照してください。

ダイレクト・パス・コンテキスト

ダイレクト・パス・コンテキスト・ハンドルは、ロード対象の各オブジェクト(表またはパーティション表のパーティションのいずれか)に対して割り当てる必要があります。OCIDirPathCtxハンドルは、OCIDirPathFuncCtx、OCIDirPathColArrayおよびOCIDirPathStreamハンドルの親ハンドルであるため、OCIDirPathCtxハンドルを解放すると、その子ハンドルも解放されます(ただし、親ハンドルの解放前に、子ハンドルを個別に解放するコーディングをお薦めします)。

ダイレクト・パス・コンテキストは、OCIHandleAlloc()を使用して割り当てます。ダイレクト・パス・コンテキストの親ハンドルは、常に環境ハンドルです。ダイレクト・パス・コンテキストは、OCIHandleFree()を使用して解放します。例13-1に示すように、すべてのダイレクト・パス・プログラムの最初の2行にヘッダー・ファイルを組み込みます。

例13-1 ヘッダー・ファイルを組み込む必要があるダイレクト・パス・プログラム

...
#include <cdemodp0.h>
#include <cdemodp.h>

OCIEnv *envp;
OCIDirPathCtx *dpctx;
sword error;
error = OCIHandleAlloc((void  *)envp, (void  **)&dpctx,
OCI_HTYPE_DIRPATH_CTX, (size_t)0,(void  **)0);
...
error = OCIHandleFree(dpctx, OCI_HTYPE_DIRPATH_CTX);

OCIダイレクト・パス関数コンテキスト

関連項目:
サポートされているデータ型の詳細は、『Oracle Databaseオブジェクト・リレーショナル開発者ガイド』を参照してください。

OCIDirPathFuncCtx型のダイレクト・パス関数コンテキスト・ハンドルは、次の名前付き型とREF列の記述に使用します。

- 列オブジェクト。このオブジェクト内の関数コンテキストでは、オブジェクト型が記述され、デフォルト・コンストラクタとして使用されて、オブジェクトとそのコンストラクタのオブジェクト属性を作成します。

- REF列。この列内の関数コンテキストでは、行オブジェクトの参照元である単一のオブジェクト表(オプション)および各行オブジェクトを識別するREF引数が記述されます。

- SQL文字列の列。この列内の関数コンテキストでは、列にロードする値を計算するためのSQL文字列とその引数が記述されます。

例13-2に示すように、関数コンテキストの割当てを示すには、OCI_HTYPE_DIRPATH_FN_CTXハンドル型をOCIHandleAlloc()に渡します。

例13-2 関数コンテキストを割り当てるためにハンドル型を渡す例

OCIDirPathCtx *dpctx;       /* direct path context */
OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
sword error;

error = OCIHandleAlloc((void  *)dpctx, (void  **)&dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(size_t)0, (void  **)0);

ダイレクト・パス関数コンテキストの親ハンドルは、常にダイレクト・パス・コンテキスト・ハンドルであることに注意してください。次のOCIHandleFree()を使用して、ダイレクト・パス関数コンテキスト・ハンドルを解放します。

error = OCIHandleFree(dpfnctx, OCI_HTYPE_DIRPATH_FN_CTX);

ダイレクト・パス列配列およびダイレクト・パス関数列配列

ダイレクト・パス・インタフェースに行配列を表示するには、ダイレクト・パス列配列ハンドルおよびダイレクト・パス関数列配列ハンドルを使用します。行は、列の値、列の長さおよび列フラグの3つの配列によって表します。列配列で使用するメソッドには、配列ハンドルの割当て、および配列のエントリに対応する値の設定や取得があります。

これらのハンドルは同じデータ構造体OCIDirPathColArrayを共有しますが、この2つの列配列ハンドルは、親ハンドルとハンドル型が異なります。

ダイレクト・パス列配列ハンドルは、OCIHandleAlloc()を使用して割り当てます。例13-3のコード・フラグメントは、ダイレクト・パス列配列ハンドルの明示的な割当てを示します。

例13-3 ダイレクト・パス列配列ハンドルの明示的な割当て

OCIDirPathCtx *dpctx;      /* direct path context */
OCIDirPathColArray *dpca;  /* direct path column array */
sword error;
error = OCIHandleAlloc((void  *)dpctx, (void  **)&dpca,
OCI_HTYPE_DIRPATH_COLUMN_ARRAY,
(size_t)0, (void  **)0);

ダイレクト・パス列配列ハンドルは、OCIHandleFree()を使用して解放します。

error = OCIHandleFree(dpca, OCI_HTYPE_DIRPATH_COLUMN_ARRAY);

例13-4は、ダイレクト・パス関数列配列ハンドルをほとんど同じ方法で割り当てることを示しています。

例13-4 ダイレクト・パス関数列配列ハンドルの明示的な割当て

OCIDirPathFuncCtx *dpfnctx;   /* direct path function context */
OCIDirPathColArray *dpfnca;   /* direct path function column array */
sword error;
error = OCIHandleAlloc((void  *)dpfnctx, (void  **)&dpfnca,
(ub4)OCI_HTYPE_DIRPATH_FN_COL_ARRAY,
(size_t)0, (void  **)0);

ダイレクト・パス関数列配列ハンドルは、OCIHandleFree()を使用して解放します。

error = OCIHandleFree(dpfnca, OCI_HTYPE_DIRPATH_FN_COL_ARRAY);

OCIDirPathColArrayハンドルの解放により、そのハンドルに関連付けられた列配列も解放されます。

ダイレクト・パス・ストリーム

変換操作OCIDirPathColArrayToStream()およびロード操作OCIDirPathLoadStream()には、ダイレクト・パス・ストリーム・ハンドルを使用します。

ダイレクト・パス・ストリーム・ハンドルは、クライアントがOCIHandleAlloc()を使用して割り当てます。OCIDirPathStreamハンドルの構造体は、フォーム(バッファ、バッファ長)内のペアとみなすことができます。

ダイレクト・パス・ストリームは、Oracle表データの線形表現です。変換操作は、常にストリームの最後に追加されます。ロード操作は、常にストリームの最初に起動します。ストリームのロードが正常終了した後、OCIDirPathStreamReset()をコールしてストリームをリセットする必要があります。

例13-5は、OCIHandleAlloc()を使用して割り当てられるダイレクト・パス・ストリーム・ハンドルを示しています。親ハンドルは、常にOCIDirPathCtxハンドルです。

例13-5 ダイレクト・パス・ストリーム・ハンドルの割当て

OCIDirPathCtx *dpctx;    /* direct path context */
OCIDirPathStream *dpstr; /* direct path stream */
sword error;
error = OCIHandleAlloc((void  *)dpctx, (void  **)&dpstr,
OCI_HTYPE_DIRPATH_STREAM, (size_t)0,(void  **)0);

ダイレクト・パス・ストリーム・ハンドルは、OCIHandleFree()を使用して解放します。

error = OCIHandleFree(dpstr, OCI_HTYPE_DIRPATH_STREAM);

OCIDirPathStreamハンドルの解放によって、そのハンドルに関連付けられているストリーム・バッファも解放されます。

ダイレクト・パス・インタフェースの関数

この項にリストされた関数は、ダイレクト・パス・ロード・インタフェースとともに使用します。

関連項目:
各関数の詳細は、「ダイレクト・パス・ロード関数」を参照してください。

ダイレクト・パス・コンテキストの操作は、表13-1の関数で実行します。

表13-1 ダイレクト・パス・コンテキストの関数

関数

用途

OCIDirPathAbort()

ダイレクト・パス処理を終了します。

OCIDirPathDataSave()

データのセーブポイントを実行します。

OCIDirPathFinish()

ロードされたデータをコミットします。

OCIDirPathFlushRow()

サーバーから部分的にロードされた行をフラッシュします。この関数は非推奨です。

OCIDirPathLoadStream()

ダイレクト・パス・ストリーム形式に変換されたデータをロードします。

OCIDirPathPrepare()

行の変換またはロードを行うために、ダイレクト・パス・インタフェースを準備します。

ダイレクト・パス列配列の操作は、表13-2の関数で実行します。

表13-2 ダイレクト・パス列配列の関数

関数

用途

OCIDirPathColArrayEntryGet()

列配列内の特定のエントリを取得します。

OCIDirPathColArrayEntrySet()

列配列内の特定のエントリを特定の値に設定します。

OCIDirPathColArrayRowGet()

特定の行番号の基本行ポインタを取得します。

OCIDirPathColArrayReset()

行配列の状態をリセットします。

OCIDirPathColArrayToStream()

列配列形式からダイレクト・パス・ストリーム形式に変換します。

ダイレクト・パス・ストリームの操作は、ダイレクト・ストリームの状態をリセットするOCIDirPathStreamReset()関数で実行します。

ダイレクト・パス・ロード・インタフェースに関する制限と制約

ダイレクト・パス・ロード・インタフェースには、SQL*Loaderと同じ次の制限があります。

- トリガーがサポートされていません。

- 参照整合性制約がサポートされていません。

- クラスタ化表がサポートされていません。

- リモート・オブジェクトのロードがサポートされていません。

- LONGは最後に指定してください。

- LOB、オブジェクトまたはコレクションを戻すSQL文字列がサポートされていません。

- VARRAY列のロードがサポートされていません。

- すべてのパーティション列は、LOBの前に指定する必要があります。これは、LOBをパーティションに書き込む前に、書込み先のパーティションを確認する必要があるためです。

スカラー列に対するダイレクト・パス・ロードの例

この項では、スカラー列に対するダイレクト・パス・ロードの例を説明します。

ダイレクト・パス・ロードの例で使用されているデータ構造

例13-6は、例13-7で例13-17を介して使用されるデータ構造を示しています。

例13-6 ダイレクト・パス・ロードの例で使用されているデータ構造

/* load control structure */
struct loadctl
{
ub4                 nrow_ctl;            /* number of rows in column array */
ub2                 ncol_ctl;         /* number of columns in column array */
OCIEnv             *envhp_ctl;                       /* environment handle */
OCIServer          *srvhp_ctl;                            /* server handle */
OCIError           *errhp_ctl;                             /* error handle */
OCIError           *errhp2_ctl;                /* yet another error handle */
OCISvcCtx          *svchp_ctl;                          /* service context */
OCISession         *authp_ctl;                   /* authentication context */
OCIParam           *colLstDesc_ctl;        /* column list parameter handle */
OCIDirPathCtx      *dpctx_ctl;                      /* direct path context */
OCIDirPathColArray *dpca_ctl;           /* direct path column array handle */
OCIDirPathColArray *dpobjca_ctl;          /* dp column array handle for obj*/
OCIDirPathColArray *dpnestedobjca_ctl;  /* dp col array hndl for nested obj*/
OCIDirPathStream   *dpstr_ctl;                /* direct path stream handle */
ub1                *buf_ctl;    /* pre-alloc'd buffer for out-of-line data */
ub4                 bufsz_ctl;                 /* size of buf_ctl in bytes */
ub4                 bufoff_ctl;                     /* offset into buf_ctl */
ub4                *otor_ctl;                  /* Offset to Recnum mapping */
ub1                *inbuf_ctl;                 /* buffer for input records */
struct pctx         pctx_ctl;                     /* partial field context */
boolean             loadobjcol_ctl;             /* load to obj col(s)? T/F */
};

例13-7は、複数の構造体を定義するdemoディレクトリのヘッダー・ファイルcdemodp.hを示しています。

例13-7 ヘッダー・ファイルcdemodp.hの内容

#ifndef cdemodp_ORACLE
# define cdemodp_ORACLE

# include <oratypes.h>

# ifndef externdef
#  define externdef
# endif

/* External column attributes */
struct col
{
text *name_col;                                             /* column name */
ub2   id_col;                                            /* column load ID */
ub2   exttyp_col;                                         /* external type */
text *datemask_col;                             /* datemask, if applicable */
ub1   prec_col;                                /* precision, if applicable */
sb1   scale_col;                                   /* scale, if applicable */
ub2   csid_col;                                        /* character set ID */
ub1   date_col;            /* is column a chrdate or date? 1=TRUE. 0=FALSE */
struct obj * obj_col;          /* description of object, if applicable */
#define COL_OID 0x1                                         /* col is an OID */
ub4   flag_col;
};

/* Input field descriptor
* For this example (and simplicity),
* fields are strictly positional.
*/
struct fld
{
ub4  begpos_fld;                             /* 1-based beginning position */
ub4  endpos_fld;                             /* 1-based ending    position */
ub4  maxlen_fld;                       /* max length for out-of-line field */
ub4    flag_fld;
#define FLD_INLINE            0x1
#define FLD_OUTOFLINE         0x2
#define FLD_STRIP_LEAD_BLANK  0x4
#define FLD_STRIP_TRAIL_BLANK 0x8
};

struct obj
{
text               *name_obj;                                /* type  name*/
ub2                 ncol_obj;              /* number of columns in col_obj*/
struct col         *col_obj;                          /* column attributes*/
struct fld         *fld_obj;                           /* field descriptor*/
ub4                 rowoff_obj;  /* current row offset in the column array*/
ub4                 nrows_obj;              /* number of rows in col array*/
OCIDirPathFuncCtx  *ctx_obj;       /* Function context for this obj column*/
OCIDirPathColArray *ca_obj;           /* column array  for this obj column*/
ub4                 flag_obj;                              /* type of obj */
#define OBJ_OBJ  0x1                                             /* obj col */
#define OBJ_OPQ  0x2                                  /* opaque/sql str col */
#define OBJ_REF  0x4                                             /* ref col */
};

struct tbl
{
text        *owner_tbl;                                     /* table owner */
text        *name_tbl;                                       /* table name */
text        *subname_tbl;                        /* subname, if applicable */
ub2          ncol_tbl;                     /* number of columns in col_tbl */
text        *dfltdatemask_tbl;            /* table level default date mask */
struct col  *col_tbl;                                 /* column attributes */
struct fld  *fld_tbl;                                  /* field descriptor */
ub1          parallel_tbl;                         /* parallel: 1 for true */
ub1          nolog_tbl;                          /* no logging: 1 for true */
ub4          xfrsz_tbl;                   /* transfer buffer size in bytes */
text         *objconstr_tbl;   /* obj constr/type if loading a derived obj */
};

struct sess                        /* options for a direct path load session */
{
text        *username_sess;                                        /* user */
text        *password_sess;                                    /* password */
text        *inst_sess;                            /* remote instance name */
text        *outfn_sess;                                /* output filename */
ub4          maxreclen_sess;          /* max size of input record in bytes */
};
#endif                                              /* cdemodp_ORACLE */

スカラー列に対するダイレクト・パス・ロードの例の概略

例13-8は、OCIダイレクト・パス・インタフェースの使用方法の例を示すサンプル・コードです。これは一部省略されたコード例です。

init_load関数は、tblpで記述された表上で、ダイレクト・パスAPIを使用してダイレクト・パス・ロードを実行します。ctlpによって指定されたloadctl構造体の環境およびサービス・コンテキストは、適切に初期化されています。サーバーへの接続は確立されています。

例13-8 OCIダイレクト・パス・インタフェースの使用方法

STATICF void
init_load(ctlp, tblp)
struct loadctl *ctlp;
struct tbl     *tblp;
{
struct  col   *colp;
struct  fld   *fldp;
sword          ociret;                       /* return code from OCI calls */
OCIDirPathCtx *dpctx;                               /* direct path context */
OCIParam      *colDesc;                     /* column parameter descriptor */
ub1            parmtyp;
ub1           *timestamp = (ub1 *)0;
ub4            size;
ub4            i;
ub4            pos;

/* allocate and initialize a direct path context */
/* See cdemodp.c for the definition of OCI_CHECK */
OCI_CHECK(ctlp->envhp_ctl, OCI_HTYPE_ENV, ociret, ctlp,
OCIHandleAlloc((void  *)ctlp->envhp_ctl,
(void  **)&ctlp->dpctx_ctl,
(ub4)OCI_HTYPE_DIRPATH_CTX,
(size_t)0, (void  **)0));

dpctx = ctlp->dpctx_ctl;                                      /* shorthand */

OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((void  *)dpctx, (ub4)OCI_HTYPE_DIRPATH_CTX,
(void  *)tblp->name_tbl,
(ub4)strlen((const char *)tblp->name_tbl),
(ub4)OCI_ATTR_NAME, ctlp->errhp_ctl));

OCI_ATTR_SUB_NAME、OCI_ATTR_SCHEMA_NAMEなど、その他の属性も設定します。属性を設定した後、ロードの準備をします。

OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIDirPathPrepare(dpctx, ctlp->svchp_ctl, ctlp->errhp_ctl));

列配列とストリーム・ハンドルの割当て

例13-9に示すように、ダイレクト・パス・コンテキスト・ハンドルは、列配列ハンドルおよびストリーム・ハンドルの親ハンドルです。また、エラーは、ダイレクト・パス・コンテキストに関連付けられている環境ハンドルとともに戻されます。

例13-9 列配列とストリーム・ハンドルの割当て

OCI_CHECK(ctlp->envhp_ctl, OCI_HTYPE_ENV, ociret, ctlp,
OCIHandleAlloc((void  *)ctlp->dpctx_ctl, (void  **)&ctlp->dpca_ctl,
(ub4)OCI_HTYPE_DIRPATH_COLUMN_ARRAY,
(size_t)0, (void  **)0));

OCI_CHECK(ctlp->envhp_ctl, OCI_HTYPE_ENV, ociret, ctlp,
OCIHandleAlloc((void  *)ctlp->dpctx_ctl,(void  **)&ctlp->dpstr_ctl,
(ub4)OCI_HTYPE_DIRPATH_STREAM,
(size_t)0, (void  **)0));

行数と列数の取得

例13-10に示すように、割り当てた列配列から行数および列数を取得します。

例13-10 行数と列数の取得

OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrGet(ctlp->dpca_ctl, (ub4)OCI_HTYPE_DIRPATH_COLUMN_ARRAY,
&ctlp->nrow_ctl, 0, OCI_ATTR_NUM_ROWS,
ctlp->errhp_ctl));

OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrGet(ctlp->dpca_ctl, (ub4)OCI_HTYPE_DIRPATH_COLUMN_ARRAY,
&ctlp->ncol_ctl, 0, OCI_ATTR_NUM_COLS,
ctlp->errhp_ctl));

入力データ・フィールドの設定

例13-11に示すように、入力データ・フィールドを対応するデータ列に設定します。

例13-11 入力データ・フィールドの設定

ub4            rowoff;                          /* column array row offset */
ub4            clen;                                      /* column length */
ub1            cflg;                                  /* column state flag */
ub1           *cval;                             /* column character value */

OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIDirPathColArrayEntrySet(ctlp->dpca_ctl, ctlp->errhp_ctl,
rowoff, colp->id_col,
cval, clen, cflg));

列配列の状態のリセット

例13-12に示すように、前の変換を続ける必要がある場合、または行にデータを追加する場合は、列配列の状態をリセットします。

例13-12 列配列の状態のリセット

(void) OCIDirPathColArrayReset(ctlp->dpca_ctl, ctlp->errhp_ctl);

ストリームの状態のリセット

例13-13に示すように、ストリームの状態をリセットして、新しいストリームを開始します。リセットしなかった場合は、ストリーム内のデータが既存のデータの末尾に追加されます。

例13-13 ストリームの状態のリセット

(void) OCIDirPathStreamReset(ctlp->dpstr_ctl, ctlp->errhp_ctl);

列配列内のデータのストリーム形式への変換

例13-14に示すように、データの入力後、列配列内のデータをストリーム形式に変換し、不正なレコードを削除します。

例13-14 データのストリーム形式への変換

ub4            rowcnt;                   /* number of rows in column array */
ub4            startoff;         /* starting row offset into column array  */

/* convert array to stream, filter out bad records */
ocierr = OCIDirPathColArrayToStream(ctlp->dpca_ctl, ctlp->dpctx_ctl,
ctlp->dpstr_ctl, ctlp->errhp_ctl,
rowcnt, startoff);

ストリームのロード

ストリーム内での位置は、ストリームを作成した列配列のオフセット情報とともに、ストリーム・ハンドルに内部的に保持されます。例13-15に示すように、ストリーム形式への変換が実行されると、ストリームにデータが追加されます。適切な場合にストリームをリセットすることはコール元の責任です。エラーが発生すると、位置は次の行に移動します。エラーが最後の行で発生した場合は、ストリームの最後に移動します。次のOCIDirPathLoadStream()コールがある場合は、次の行で開始されます。OCIDirPathLoadStream()コールが実行され、ストリームの最後に達した場合は、OCI_NO_DATAが戻されます。

例13-15 ストリームのロード

/* load the stream */
ociret = OCIDirPathLoadStream(ctlp->dpctx_ctl, ctlp->dpstr_ctl,
ctlp->errhp_ctl);

ダイレクト・パス・ロードの終了

例13-16に示すように、ダイレクト・パス・ロードを終了します。

例13-16 ダイレクト・パス・ロード操作の終了

/* finish the direct path load operation */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIDirPathFinish(ctlp->dpctx_ctl, ctlp->errhp_ctl));

ダイレクト・パス・ハンドルの解放

例13-17に示すように、割り当てられているすべてのダイレクト・パス・ハンドルを解放します。親のダイレクト・パス・コンテキスト・ハンドルの解放前に、ダイレクト・パス列配列ハンドルとストリーム・ハンドルが解放されます。

例13-17 ダイレクト・パス・ハンドルの解放

/* free up server data structures for the load */
ociret = OCIHandleFree((void  *)ctlp->dpca_ctl,
OCI_HTYPE_DIRPATH_COLUMN_ARRAY);
ociret = OCIHandleFree((void  *)ctlp->dpstr_ctl,
OCI_HTYPE_DIRPATH_STREAM);
ociret = OCIHandleFree((void  *)ctlp->dpctx_ctl,
OCI_HTYPE_DIRPATH_CTX);

OCIのダイレクト・パス・ロードでの日付キャッシュの使用

表に格納するためにデータ型変換が必要なOracle日付およびタイムスタンプの値をロードする場合は、日付キャッシュ機能を使用するとパフォーマンスが向上します。ダイレクト・パス・ロードでのこの機能の使用方法の詳細は、『Oracle Databaseユーティリティ』を参照してください。

この機能は、同じ日付またはタイムスタンプの値が入力値として繰返しロードされるダイレクト・パス・ロードを特に対象としています。日付変換は(特に複数の日付列がロードされる場合)、非常に時間がかかり、ロード時間の中で大きな割合を占める場合があります。入力データに多数の同じ日付値がある場合は、日付キャッシュ機能を使用すると実際に変換される日付の数が減少するため、パフォーマンスが向上します。ただし、日付キャッシュ機能によってパフォーマンスが向上するのは、多数の同じ日付が入力値として日付列にロードされる場合のみです(この章で使用する「日付」という用語は、日付およびタイムスタンプのすべてのデータ型を指します)。

日付キャッシュはデフォルトで有効です。日付キャッシュ・サイズを明示的に指定した場合、デフォルトでは日付キャッシュ機能は使用禁止になりません。この動作をオーバーライドするには、OCI_ATTR_DIRPATH_DCACHE_DISABLEを1に設定します。この設定以外の場合は、データ変換を回避するためにキャッシュが検索されます。ただし、キャッシュ・ミス(重複した値がないエントリ)は、日付キャッシュ機能の使用による効果がなく、時間がかかる日付変換関数を使用した通常の方法で変換されます。

OCI_ATTR_DIRPATH_DCACHE_NUM属性、OCI_ATTR_DIRPATH_DCACHE_MISSES属性およびOCI_ATTR_DIRPATH_DCACHE_HITS属性を問い合せて、ロードに必要なキャッシュ・サイズを調整します。

キャッシュ・ミスがなく、キャッシュ内の要素数がキャッシュ・サイズより小さい場合は、キャッシュ・サイズを小さくします。多数のキャッシュ・ミスが発生し、相対的にヒット数(重複した値があるエントリ)が少ない場合は、キャッシュ・サイズを大きくすることができます。ただし、多数の日付キャッシュ・ミスが発生すると、アプリケーションの処理速度は日付キャッシュを使用しない場合よりも遅くなる場合があります。キャッシュ・サイズを大きくしすぎると、ページングやメモリー消費量の増加など、別の問題が発生する可能性があります。キャッシュ・サイズを大きくしてもパフォーマンスが向上しない場合、この機能は使用しないでください。

日付キャッシュ機能を明示的かつ全体的に使用禁止にするには、日付キャッシュ・サイズを0 (ゼロ)に設定します。

この機能では、次のOCIダイレクト・パス・コンテキスト属性を設定できます。

OCI_ATTR_DIRPATH_DCACHE_SIZE

この属性を0 (ゼロ)以外に設定する場合は、表に対する日付キャッシュ・サイズを要素数で設定します。たとえば、日付キャッシュ・サイズを200に設定すると、最大200個の一意の日付またはタイムスタンプ値をキャッシュに格納できます。OCIDirPathPrepare()をコールした後は、日付キャッシュ・サイズを変更できません。デフォルト値は0 (ゼロ)で、これは表に対する日付キャッシュが作成されないことを意味します。日付キャッシュは、データ型変換が必要な1つ以上の日付またはタイムスタンプ値がロードされ、この属性値が0 (ゼロ)以外の場合のみ、表に対して作成されます。

OCI_ATTR_DIRPATH_DCACHE_NUM

この属性を使用して、日付キャッシュ内の現在のエントリ数を問い合せます。

OCI_ATTR_DIRPATH_DCACHE_MISSES

この属性を使用して、現在の日付キャッシュ・ミス数を問い合せます。ミスの数が多い場合は、より大きい日付キャッシュ・サイズを使用することを検討してください。日付キャッシュ・サイズを大きくしてもこの数が大幅に減少しない場合は、日付キャッシュ機能を使用しないでください。日付キャッシュ・ミスが発生すると、ハッシングや参照のために時間を費やします。

OCI_ATTR_DIRPATH_DCACHE_HITS

この属性を使用して、日付キャッシュ・ヒット数を問い合せます。日付キャッシュ機能の使用による効果があることを確認するには、この数が相対的に多くなる必要があります。

OCI_ATTR_DIRPATH_DCACHE_DISABLE

この属性を1に設定すると、サイズを超えた場合に日付キャッシュが使用禁止になります。OCIDirPathPrepare()をコールした後は、この属性を変更または設定できません。

デフォルト(= 0)では、オーバーフロー時にキャッシュが使用禁止になりません。キャッシュが使用禁止でない場合は、変換を回避するためにキャッシュが検索されますが、入力された日付値のエントリがオーバーフローすると日付キャッシュには追加されず、時間がかかる日付変換関数を使用して変換されます。多数の日付キャッシュ・ミスが発生すると、アプリケーションの処理速度は日付キャッシュを使用しない場合よりも遅くなる場合があります。

この属性を問い合せると、オーバーフローが原因で日付キャッシュが使用禁止になっているかどうかも確認できます。

関連項目:
「ダイレクト・パス・コンテキスト・ハンドル(OCIDirPathCtx)の属性」

オブジェクト型のダイレクト・パス・ロード

この項では、ダイレクト・パス関数コンテキストによる多様な非スカラー型のロードについて説明します。

非スカラー型は、次のとおりです。

- ネストした表

- オブジェクト表(FINALとNOT FINAL)

- 列オブジェクト(FINALとNOT FINAL)

- REF列(FINALとNOT FINAL)

- SQL文字列の列

関連項目:
Oracle Databaseのインストールで使用可能なダイレクト・パス・ロードのデモ・プログラムのリストは、表B-1を参照してください。

ネストした表のダイレクト・パス・ロード

ネストした表は、別の表に格納されます。ダイレクト・パス・ロードAPIを使用して、ネストした表をSETIDという外部キーで、その親の表とは別にロードし、2つの表をリンクします。

注意:

- 現在、SETIDはシステムで生成されないため、ユーザーによる指定が必要です。

- 親と子の表を別々にロードするときに、子の表に行は挿入されているが、対応する親の行が親の表に挿入されていない場合、孤立した子が作成される可能性があります。また、親の表には親の行が挿入されているが、子の表には子の行が挿入されていない場合、親の行において子が欠落します。

ネストした表の列とそのネストした表の記述

注意:
スカラー・データのロードと異なるステップは、イタリック表記になっています。

ネストした表の列を持つ親表のロードと、子であるネストした表のロードは、別のアクションです。

- ネストした表の列を持つ親表をロードする手順は、次のとおりです。

1. 親表とその列を通常どおり記述しますが、このとき、次の手順を行います。

2. ネストした表の列を記述するときに、この列にSETIDを格納します。外部データ型は、データ・ファイルのSETIDが文字の場合はSQLT_CHRで、バイナリの場合はSQLT_BINです。

- ネストした表(子)をロードする手順は、次のとおりです。

1. ネストした表とその列を通常どおり記述します。

2. SETID 列は必須です。

- ダミーの名前(setidなど)を使用して、そのOCI_ATTR_NAMEを設定します。これは、APIでは、プログラマがそのシステム名を認識しているとはみなしていないためです。

- これがSETID列であることを示すように、OCI_ATTR_DIRPATH_SIDで列属性を設定します。

ub1 flg = 1;
sword error;

error = OCIAttrSet((void  *)colDesc,
OCI_DTYPE_PARAM,
(void  *)&flg, (ub4)0,
OCI_ATTR_DIRPATH_SID, ctlp->errhp_ctl);

列オブジェクトのダイレクト・パス・ロード

列オブジェクトとは、オブジェクトとして定義される表の列のことです。現在は、すべての構成属性で構成されるデフォルト・コンストラクタのみがサポートされています。

列オブジェクトの記述

列オブジェクトとそのオブジェクト属性を記述するには、ダイレクト・パス関数コンテキストを使用します。列オブジェクトの記述には、そのオブジェクトのコンストラクタの設定が必要です。オブジェクト属性の記述は、スカラー列のリストの記述に類似しています。

列オブジェクトを記述する手順は、次のとおりです。

注意:

- ネストした列のオブジェクトがサポートされています。

- 次に説明する手順は、表にロードするスカラー列のリストを記述する手順に類似しています。スカラー・データのロードと異なるステップは、イタリック表記になっています。

1. パラメータ・ハンドルをOCI_DTYPE_PARAMで列オブジェクトに割り当てます。このパラメータ・ハンドルを使用して、列の外部属性を設定します。

2. 列名とその他の外部列の属性(最大データ・サイズ、精度、スケールなど)を設定します。

3. OCI_ATTR_DATA_TYPEで、外部型をSQLT_NTY (名前付き型)として設定します。

4. ダイレクト・パス関数コンテキスト・ハンドルを割り当てます。このコンテキストを使用して、列のオブジェクト型と属性を記述します。

OCIDirPathFuncCtx *dpfnctx  /* direct path function context */;
sword error;
error = OCIHandleAlloc((void  *)dpctx, (void  **)&dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(size_t)0, (void  **)0);

5. 関数コンテキストのOCI_ATTR_NAMEで列のオブジェクト型の名前(Employeeなど)を設定します。

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
text *obj_type;   /* column object's object type */
sword error;

error = OCIAttrSet((void  *)dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(void  *)obj_type, (ub4)strlen((const char *)obj_type),
OCI_ATTR_NAME, ctlp->errhp_ctl);

6. 式の型OCI_ATTR_DIRPATH_EXPR_TYPEをOCI_DIRPATH_EXPR_OBJ_CONSTRに設定します。これは、OCI_ATTR_NAMEを持つ式セットが、デフォルトのオブジェクト・コンストラクタとして使用されることを意味します。

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
ub1 expr_type = OCI_DIRPATH_EXPR_OBJ_CONSTR;
sword error;

error = OCIAttrSet((void  *)dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(void  *)&expr_type, (ub4)0,
OCI_ATTR_DIRPATH_EXPR_TYPE,
ctlp->errhp_ctl);

7. OCI_ATTR_NUM_COLSを使用して、この列オブジェクトにロードする列またはオブジェクト属性の数を設定します。

8. 関数コンテキストOCIDirPathFuncCtxの列または属性のパラメータ・リストを取得します。

9. 各オブジェクト属性の場合:

1. OCI_DTYPE_PARAMで、オブジェクト属性の列記述子を取得します。

2. OCI_ATTR_NAMEで属性の列名を設定します。

3. OCI_ATTR_DATA_TYPEで外部列の型(ダイレクト・パスAPIに渡されるデータの型)を設定します。

4. その他の外部列の属性(最大データ・サイズ、精度、スケールなど)を設定します。

5. この属性の列が列オブジェクトの場合は、そのオブジェクト属性に対して手順3から10を実行します。

6. 列記述子へのハンドルを解放します。

10. 手順4で作成した関数コンテキストOCIDirPathFuncCtxを、親の列オブジェクトのパラメータ・ハンドルにOCI_ATTR_DIRPATH_FN_CTXを使用して設定します。

列配列の列オブジェクトへの割当て

列オブジェクトをダイレクト・パス・ロードすると、そのオブジェクトの属性データは、そのオブジェクト専用に作成された個別の列配列にロードされます。子の列配列は、ネストされているかどうかに関係なく、各列オブジェクトに割り当てられます。子の列配列にあるオブジェクト属性の各行は、その親列配列内の親の列オブジェクトにある対応するNULL以外の行にマップされます。

列オブジェクトのダイレクト・パス関数コンテキスト・ハンドルとOCI_HTYPE_DIRPATH_FN_COL_ARRAY関数列配列値を使用します。

例13-18は、列オブジェクトに子の列配列を割り当てる方法を示しています。

例13-18 列オブジェクトへの子の列配列の割当て

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
OCIDirPathColArray *dpfnca;   /* direct path function column array */
sword error;

error = OCIHandleAlloc((void  *)dpfnctx, (void  **)&dpfnca,
OCI_HTYPE_DIRPATH_FN_COL_ARRAY,
(size_t)0, (void  **)0);

列オブジェクト・データの列配列へのロード

列がスカラー列の場合は、その値のアドレスをOCIDirPathColArrayEntrySet()に渡して、その値を列配列に設定します。列がオブジェクトの場合は、かわりに、子の列配列ハンドルのアドレスを渡します。子の列配列にはオブジェクトの属性データが格納されます。

データを列オブジェクトにロードする手順は、次のとおりです。

注意:
スカラー・データのロードと異なるステップは、イタリック表記になっています。

(開始します。)各列オブジェクトに対して、次の手順を実行します。

1. 列がNULL以外の場合:

1. オブジェクト属性の列ごとに、次の操作を行います。
オブジェクト属性がネストされた列オブジェクトの場合は、(開始)に移動し、この全手順を繰り返し実行します。

OCIDirPathColArrayEntrySet()を使用して、子列配列にデータを設定します。

2. 子列配列ハンドルのアドレスをOCIDirPathColArrayEntrySet()に渡すことにより、列配列で列オブジェクトのデータを設定します。

2. 列がNULLの場合:
データのNULLアドレス、長さ0 (ゼロ)およびOCI_DIRPATH_COL_NULLフラグをOCIDirPathColArrayEntrySet()に渡して、列オブジェクトのデータを列配列に設定します。

OCI_DIRPATH_COL_ERROR

OCI_DIRPATH_COL_ERRORの値をOCIDirPathColArrayEntry()に渡すことにより、現在の列配列行を無視する必要があることを示します。一部の列にデータを追加するときにエラーが発生した場合(前のOCIDirPathColArrayToStream()コールからOCI_NEED_DATAが戻された場合)は、通常、この値を使用して前のすべての行変換を取り消します。現在の行の出力ストリーム・バッファに格納されている、前に変換されたデータは削除されます。これにより、変換は列配列内の次の行から続行されます。削除された行は、変換された行としてカウントされます。

OCI_DIRPATH_COL_ERRORを指定すると、現在の行の他、参照される子列配列で対応する任意の行(最上位レベルの列配列行までの行)が無視されます。参照されるすべての子列配列を次の行に移動すると、NULL子列配列参照は無視されます。

SQL文字列の列のダイレクト・パス・ロード

列の値は、SQL文字列で計算できます。SQL文字列は、スカラー列の型に使用できます。SQL文字列は、オブジェクト型には使用できませんが、スカラー列の型のオブジェクト属性には使用できます。NESTED TABLE、SEQUENCEおよびLONGには使用できません。

SQL式は、OCIDirPathFuncCtxを使用してダイレクト・パスAPIで表現します。式のOCI_ATTR_NAMEの値が、その式の名前付きバインド変数のパラメータ・リストを含むSQL文字列になります。

バインド変数のネームスペースは、列のSQL文字列に限定されています。複数の列に対して同じバインド変数名を使用できますが、同じ名前の引数はその列のSQL文字列に対してのみ適用されます。

列のSQL文字列に1つのバインド変数への複数の参照が含まれており、その名前で複数の引数が指定されている場合は、すべての値を同じにする必要があります。同じにしない場合、結果が未定義になります。この場合、特定のSQL式内の同じバインド変数名への参照がすべて1つの引数にバインドされているため、実際に必要なのは1つの引数のみです。

SQL文字列の例を、次に示します。

substr(substr(:string, :offset, :length), :offset, :length)

この例では、次の点に注意してください。

- SQL式はネストできます。

- バインド変数名は、その式内で繰り返し指定できます。

SQL文字列の列の記述

注意:
スカラー・データのロードと異なるステップは、イタリック表記になっています。

1. パラメータ・ハンドルをOCI_DTYPE_PARAMでSQL文字列の列に割り当てます。このパラメータ・ハンドルを使用して、列の外部属性を設定します。

2. 列名とその他の外部列の属性(最大データ・サイズ、精度、スケールなど)を設定します。

3. OCI_ATTR_DATA_TYPEを使用して、SQL文字列の列の外部型をSQLT_NTYとして設定します。

4. ダイレクト・パス関数コンテキスト・ハンドルを割り当てます。このコンテキストを使用して、SQL文字列の引数を記述します。

OCIDirPathFuncCtx *dpfnctx  /* direct path function context */;
sword error;
error = OCIHandleAlloc((void  *)dpctx, (void  **)&dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(size_t)0, (void  **)0);

5. 列のSQL文字列を関数コンテキストのOCI_ATTR_NAMEに設定します。

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
text *sql_str;   /* column's SQL string expression */
sword error;

error = OCIAttrSet((void  *)dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(void  *)sql_str, (ub4)strlen((const char *)sql_str),
OCI_ATTR_NAME, ctlp->errhp_ctl);

6. 式の型OCI_ATTR_DIRPATH_EXPR_TYPEをOCI_DIRPATH_EXPR_SQLとして設定します。これは、OCI_ATTR_NAMEを持つ式セットが、値を導出するためのSQL文字列として使用されることを意味します。

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
ub1 expr_type = OCI_DIRPATH_EXPR_SQL;
sword error;

error = OCIAttrSet((void  *)dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(void  *)&expr_type, (ub4)0,
OCI_ATTR_DIRPATH_EXPR_TYPE, ctlp->errhp_ctl);

7. SQL文字列に渡す引数の数をOCI_ATTR_NUM_COLSを使用して設定します。

8. 関数コンテキストの列または属性のパラメータ・リストを取得します。

9. SQL文字列の引数ごとに、次の操作を行います。

1. OCI_DTYPE_PARAMで、オブジェクト属性の列記述子を取得します。

2. SQL文字列の引数の定義順序は重要ではありません。SQL文字列で使用されている順序と一致させる必要はありません。

3. OCI_ATTR_NAMEで属性の列名を設定します。

4. SQL文字列の引数には、ネーミング規則が適用されます。

5. 引数名は、SQL文字列で使用されているバインド変数名と内容が一致している必要がありますが、大/小文字区別を一致させる必要はありません。たとえば、SQL文字列がsubstr(:INPUT_STRING, 3, 5)の場合は、引数名をinput_stringにしてもかまいません。

6. 1つの引数をSQL文字列内で繰り返し使用する場合は、宣言は1回のみ実施し、1つの引数としてのみカウントしてください。

7. OCI_ATTR_DATA_TYPEで外部列の型(ダイレクト・パスAPIに渡されるデータの型)を設定します。

8. その他の外部列の属性(最大データ・サイズ、精度、スケールなど)を設定します。

9. 列記述子へのハンドルを解放します。

10. 手順4で作成した関数コンテキストOCIDirPathFuncCtxを、親の列オブジェクトのパラメータ・ハンドルにOCI_ATTR_DIRPATH_FN_CTXを使用して設定します。

列配列のSQL文字列の列への割当て

SQL文字列の列をダイレクト・パス・ロードすると、その引数のデータは、そのSQL文字列の列専用に作成された個別の列配列にロードされます。子の列配列は、SQL文字列の列ごとに割り当てられます。子の列配列にある引数の各行は、その親列配列内の親のSQL文字列の列にある対応するNULL以外の行にマップされます。

例13-19は、SQL文字列の列に子の列配列を割り当てる方法を示しています。

例13-19 SQL文字列の列への子の列配列の割当て

OCIDirPathFuncCtx *dpfnctx;        /* direct path function context */
OCIDirPathColArray *dpfnca;   /* direct path function column array */
sword error;

error = OCIHandleAlloc((void  *)dpfnctx, (void  **)&dpfnca,
OCI_HTYPE_DIRPATH_FN_COL_ARRAY,
(size_t)0, (void  **)0);

SQL文字列データの列配列へのロード

列がスカラー列の場合は、その値のアドレスをOCIDirPathColArrayEntrySet()に渡して、その値を列配列に設定します。列がSQL文字列型の場合は、かわりに、子の列配列ハンドルのアドレスを渡します。子の列配列には、SQL文字列の引数データが格納されます。

データをSQL文字列の列にロードする手順は、次のとおりです。

注意:
スカラー・データのロードと異なるステップは、イタリック表記になっています。

SQL文字列の列ごとに、次の操作を行います。

1. 列がNULL以外の場合:

1. 関数の引数の列ごとに、次の操作を行います。
OCIDirPathColArrayEntrySet()を使用して、子列配列にデータを設定します。

2. 子列配列ハンドルのアドレスをOCIDirPathColArrayEntrySet()に渡すことにより、SQL文字列の列データを列配列に設定します。

2. 列がNULLの場合:
データのNULLアドレス、長さ0 (ゼロ)およびOCI_DIRPATH_COL_NULLフラグをOCIDirPathColArrayEntrySet()に渡して、SQL文字列の列データを列配列に設定します。

この処理は、列オブジェクトの処理に類似しています。

関連項目:
OCI_DIRPATH_COL_ERRORの値をOCIDirPathColArrayEntry()に渡して、エラー発生時に現在の列配列行を無視する必要があることを示す方法の詳細は、「OCI_DIRPATH_COL_ERROR」を参照してください。

REF列のダイレクト・パス・ロード

REF型とは、オブジェクト表の行オブジェクトへのポインタ、つまり参照です。

REF列の記述

REF列への引数の記述は、表にロードする列リストの記述に類似しています。

注意:
REF列は、表のトップレベル列に設定したり、オブジェクト属性として列オブジェクトにネストできます。
スカラー・データのロードと異なるステップは、イタリック表記になっています。

1. OCI_DTYPE_PARAMで、REF列のパラメータ・ハンドルを取得します。このパラメータ・ハンドルを使用して、列の外部属性を設定します。

2. 列名とその他の外部列の属性(最大データ・サイズ、精度、スケールなど)を設定します。

3. OCI_ATTR_DATA_TYPEを使用して、REF列の外部型をSQLT_REFとして設定します。

4. ダイレクト・パス関数コンテキスト・ハンドルを割り当てます。このコンテキストを使用して、REF列の引数を記述します。

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
sword error;

error = OCIHandleAlloc((void  *)dpctx, (void  **)&dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(size_t)0, (void  **)0);

5. オプション: REF列の表名を関数コンテキストのOCI_ATTR_NAMEに設定します。詳細は、次の手順を参照してください。

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
text *ref_tbl;     /* column's reference table */
sword error;

error = OCIAttrSet((void  *)dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(void  *)ref_tbl, (ub4)strlen((const char *)ref_tbl),
OCI_ATTR_NAME, ctlp->errhp_ctl);

6. オプション: 式の型OCI_ATTR_DIRPATH_EXPR_TYPEをOCI_DIRPATH_EXPR_REF_TBLNAMEに設定します。この設定は、手順5が完了している場合にのみ実行します。これは、OCI_ATTR_NAMEを持つ式セットが、行オブジェクトを参照するためのオブジェクト表として使用されることを意味します。このパラメータはオプションです。このパラメータの動作は、REFの型によって異なります。

- 有効範囲なしのREF列(有効範囲なし、システムOIDベース)
このパラメータが設定されていない場合、このREF列には、有効範囲なしのREF列の定義により、参照表の名前が引数としてデータ行ごとに含まれている必要があります。

パラメータが設定されている場合、このREF列がロードの継続時間中に参照できるのは、指定されたオブジェクト表の行オブジェクトのみです。このREF列に、参照表の名前を引数として含めることはできません。(ダイレクト・パスAPIは、このパラメータをショート・カットとしてユーザーに提供しています。ユーザーは、このパラメータをロードの継続時間中に同じ参照オブジェクト表を参照する有効範囲なしのREF列にロードします)。

- 有効範囲付REF列(有効範囲付、システムOIDベースおよび主キー・ベース)
このパラメータが設定されていない場合、ダイレクト・パスAPIは、スキーマで指定されている参照表を使用します。

設定されている場合、参照表の名前は、この有効範囲付REF列のスキーマに指定されているオブジェクト表と一致している必要があります。表名が一致していない場合は、エラーが発生します。

このパラメータが設定されているかどうかに関係なく、この参照表の名前がデータ行に存在しているかどうかはAPIにとって問題ではありません。名前がデータ行にある場合、その名前はスキーマに指定されている表名と一致している必要があります。名前がデータ行にない場合、APIはスキーマに指定されている参照表を使用します。

7. 行オブジェクトの参照に使用するREF引数の数を、OCI_ATTR_NUM_COLSで設定します。必要な引数の数は、REF列の型によって異なります。この数は、前述の手順6で導出されます。

- 有効範囲なしのREF列(有効範囲なし、システムOIDベースのREF列)
OCI_DIRPATH_EXPR_REF_TBLNAMEが使用されている場合は、1つの引数が導出されます。参照表の名前の引数はなく、OID値の引数が1つです。

OCI_DIRPATH_EXPR_REF_TBLNAMEが使用されていない場合は、2つです。参照表の名前の引数が1つとOID値の引数が1つです。

- 有効範囲付REF列(有効範囲付、システムOIDベースおよび主キー・ベース)
OCI_DIRPATH_EXPR_REF_TBLNAMEを使用しているかどうかにかかわらず、オブジェクトIDを構成している列数がNの場合、受入れ可能な数はNまたはN+1です。参照表の名前がデータ行にない場合、最小値はNです。参照表の名前がデータ行にある場合、その最小値はN+1です。注意: REFがシステムOIDベースの場合、Nは1になります。REFが主キー・ベースの場合、Nは主キーを構成するコンポーネント列の数になります。参照表の名前がデータ行にある場合は、Nに1を加算します。

注意:
NまたはN+1以外のある数のREF引数で渡された場合のエラー・メッセージを簡単化するには、Nを予期している際に何らかの数の引数が検出されたことだけを示すエラー・メッセージにします。メッセージではN+1について記述されていませんが、N+1は受入れ可能である(参照表名が必要ない場合でも)ため、エラー・メッセージは表示されません。

8. 関数コンテキストの列または属性のパラメータ・リストを取得します。

9. REFの引数または属性ごとに、次の操作を行います。

1. OCI_DTYPE_PARAMで、REF引数の列記述子を取得します。

2. OCI_ATTR_NAMEで属性の列名を設定します。
REF引数の順序は重要です。参照表の名前が指定されている場合は、その名前を最初のREF引数に指定します。オブジェクトIDは、システム生成または主キー・ベースに関係なく、次のREF引数に指定します。

REF引数には次のネーミング規則が適用されます。参照表の名前は表の列ではないため、列名にref-tblなどのダミーの名前を使用できます。システム生成のOID列に対しては、列名にsys-OIDなどのダミーの名前を使用できます。主キー・ベースのオブジェクトIDに対しては、ロード対象のすべての主キー列をリストします。OIDに対してダミーの名前を作成する必要はありません。コンポーネント列名は、指定されている場合(次のショートカットの注意を参照)、任意の順序で指定できます。

ショートカットを使用する場合は、オブジェクトIDに属性列名を設定しないでください。

ショートカット。 － システムOIDベースのREF列をロードする場合は、列名に名前を設定しないでください。名前はAPIによって判断されます。ただし、外部データ型などの他の列属性は、プログラマが設定する必要があります。

主キーREF列をロードしており、その主キーが複数の列で構成されている場合、ショートカットはそれぞれの列名に設定されません。ただし、外部データ型などの他の列属性は、プログラマが設定する必要があります。

注意:
コンポーネント列名がNULLの場合は、APIコードによって、主キーに定義された位置または順序で列名が決定されます。したがって、名前以外の列属性を設定する場合は、その属性がコンポーネントの列に適切な順序で設定されていることを確認してください。

3. OCI_ATTR_DATA_TYPEを使用して外部列の型(ダイレクト・パスAPIに渡されるデータの型)を設定します。

4. その他の外部列の属性(最大データ・サイズ、精度、スケールなど)を設定します。

5. 列記述子へのハンドルを解放します。

6. 手順4で作成された関数コンテキストOCIDirPathFuncCtxを、OCI_ATTR_DIRPATH_FN_CTXを使用して親の列オブジェクトのパラメータ・ハンドルに設定します。

列配列のREF列への割当て

例13-20は、REF列に子の列配列を割り当てる方法を示しています。

例13-20 REF列への子の列配列の割当て

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
OCIDirPathColArray *dpfnca; /* direct path function column array */
sword error;

error = OCIHandleAlloc((void  *)dpfnctx, (void  **)&dpfnca,
OCI_HTYPE_DIRPATH_FN_COL_ARRAY,
(size_t)0, (void  **)0);

REFデータの列配列へのロード

列がスカラー列の場合は、その値のアドレスをOCIDirPathColArrayEntrySet()に渡して、その値を列配列に設定します。列がREFの場合は、かわりに、子の列配列ハンドルのアドレスを渡します。子の列配列には、REFの引数のデータが格納されます。

データをREF列にロードする手順は、次のとおりです。

注意:
スカラー・データのロードと異なるステップは、イタリック表記になっています。

REF列ごとに、次の操作を行います。

1. 列がNULL以外の場合:

1. REF引数の列ごとに、次の操作を行います。
OCIDirPathColArrayEntrySet()を使用して、子列配列にデータを設定します。

2. 子列配列ハンドルのアドレスをOCIDirPathColArrayEntrySet()に渡すことにより、REF列のデータを列配列に設定します。

2. 列がNULLの場合:
データのNULLアドレス、長さ0 (ゼロ)およびOCI_DIRPATH_COL_NULLフラグをOCIDirPathColArrayEntrySet()に渡して、REF列のデータを列配列に設定します。

関連項目:
「OCI_DIRPATH_COL_ERROR」

NOT FINALオブジェクトおよびREF列のダイレクト・パス・ロード

SQLオブジェクトの継承は型の階層を形成するオブジェクト型のファミリ・ツリーに基づいていることに注意してください。型の階層は、スーパータイプという親オブジェクト型と、親から導出された、サブタイプという1つ以上のレベルの子オブジェクト型で構成されます。

継承階層

図13-2は、Person型の列の継承階層を示しています。Personスーパータイプは、NameとAddressの2つの属性を持ち、階層の最上位にあります。Personには、EmployeeとStudentの2つのサブタイプがあります。Employeeサブタイプには、ManagerとDeptidの2つの属性があります。Studentサブタイプには、UnitsとGPAの2つの属性があります。ParttimeEmployeeは、Employeeのサブタイプで、これの下に表示されます。サブタイプParttimeEmployeeには、1つの属性Hoursがあります。これらは、Person列に格納できる型です。

図13-2 Person型の列の継承階層

継承可能にするオブジェクト型に対して、オブジェクト型定義では、それが継承可能であることを指定する必要があることに注意してください。指定すると、そこからサブタイプを導出できます。継承可能にするオブジェクトを指定するには、型定義にキーワードNOT FINALを指定する必要があります。継承可能にしないオブジェクトを指定するには、型定義にキーワードFINALを指定する必要があります。FINAL型およびNOT FINAL型の定義の詳細は、『Oracle Databaseオブジェクト・リレーショナル開発者ガイド』を参照してください。

Person型の列を含む表をダイレクト・パス・ロードする場合、実際の型セットには、NOT FINAL型Personとその3つのサブタイプであるStudent、EmployeeおよびParttimeEmployeeを含めることができます。このロードの継続時間中、ダイレクト・パス・ロードAPIがサポートするのは、このNOT FINAL列の固定的な派生型のロードのみであるため、ダイレクト・パス・ロードAPIでは、ロード対象となる型、その型に対してロードする属性およびその型の作成に使用する関数などを認識する必要があります。

そのため、派生型を記述およびロードするときは、ロード対象となるその型の全属性を指定する必要があります。サブタイプは、この型とその親の全属性に固有なすべてのオブジェクト属性のフラット表現とみなしてください。したがって、ロード対象の属性列すべてを記述してカウントする必要があります。

たとえば、ParttimeEmployeeのすべての列をロードするには、ロード対象となるName、Address、Manager、DeptidおよびHoursの5つのオブジェクト属性を記述してカウントする必要があります。

ロード対象の固定的な派生型の記述

NOT FINALまたは置換可能オブジェクト列と固定的な派生型のREF列を記述する手順は、同じ型のFINAL列を記述する手順と類似していることに注意してください。

X型(XはオブジェクトまたはREF)のNOT FINAL列を記述するには、「列オブジェクトのダイレクト・パス・ロード」または「REF列のダイレクト・パス・ロード」を参照してください。次の各項で、この型のFINAL列について説明します。派生型(スーパータイプまたはサブタイプの場合があります)は、ロードの継続時間中固定されているため、NOT FINAL列を記述するためのクライアント側インタフェースは、FINAL列を記述する場合と同じです。

サブタイプは、この型とその親の全属性に固有なすべてのオブジェクト属性のフラット表現とみなすことができます。したがって、ロード対象の属性列すべてを記述してカウントする必要があります。

列配列の割当て

列配列の割当ては、同じ型のFINAL列の場合と同じです。

データの列配列へのロード

列配列へのデータのロードは、同じ型のFINAL列の場合と同じです。

オブジェクト表のダイレクト・パス・ロード

オブジェクト表とは、すべての行がオブジェクト(つまり、行オブジェクト)である表です。表の各列は、オブジェクト属性です。

オブジェクト表の記述

オブジェクト表の記述は、非オブジェクト表の記述と非常に類似しています。各オブジェクト属性が表の列です。唯一の相違点は、OIDがシステム生成、ユーザー生成または主キー・ベースの場合に、そのOIDの記述が必要になることです。

オブジェクト表を記述する手順は、次のとおりです。

注意:
非オブジェクト表のロードと異なるステップは、イタリック表記になっています。

オブジェクト属性列ごとに、次の操作を行います。

それぞれの型(NUMBER、REFなど)に基づいて、各オブジェクト属性の列を必要に応じて記述します。

オブジェクト表がOID (Oracle Internet Directory)の場合は、次の操作を行います。

1. オブジェクトIDがシステム生成の場合。
何もする必要はありません。システムがすべての行オブジェクトのOIDを生成します。

2. オブジェクトIDがユーザー生成の場合。

1. 仮の名前(cust_oidなど)を使用してOIDの列名を表現します。

2. OCI_ATTR_DIRPATH_OIDでOIDの列属性を設定します。

3. オブジェクトIDが主キー・ベースの場合。

1. OIDを構成しているすべての主キー列をロードします。

2. OCI_ATTR_DIRPATH_OIDを設定しないでください。ダミーの名前を持つOID列は作成されていません。

列配列のオブジェクト表への割当て

例13-21は、列配列のオブジェクト表への割当ては、非オブジェクト表に列配列を割り当てる方法と同じであることを示しています。

例13-21 列配列のオブジェクト表への割当て

OCIDirPathColArray *dpca;  /* direct path column array */
sword error;

error = OCIHandleAlloc((void  *)dpctx, (void  **)&dpca,
OCI_HTYPE_DIRPATH_COLUMN_ARRAY,
(size_t)0, (void  **)0);

データの列配列へのロード

列配列へのデータのロードは、非オブジェクト表にデータをロードする方法と同じです。

NOT FINALオブジェクト表のダイレクト・パス・ロード

NOT FINALオブジェクト表は継承をサポートしますが、FINALオブジェクト表は継承をサポートできません。

NOT FINALオブジェクト表の記述

固定的な派生型のNOT FINALオブジェクト表の記述は、FINALオブジェクト表の記述と非常に類似しています。

固定的な派生型のNOT FINALオブジェクト表を記述する手順は、次のとおりです。

注意:
FINALオブジェクト表の記述と異なるステップは、イタリック表記になっています。

1. OCI_ATTR_DIRPATH_OBJ_CONSTRを使用して、ダイレクト・パス・コンテキストにオブジェクト表のオブジェクト型を設定します。これは、スーパータイプまたは派生型に関係なく、ロードの継続時間中、この表へのロードにはオブジェクト型がデフォルトのオブジェクト・コンストラクタとして使用されることを意味します。

text *obj_type;            /* the object type to load into this NOT FINAL */
/* object table */
sword error;

error = OCIAttrSet((void  *)dpctx,
OCI_HTYPE_DIRPATH_CTX,
(void  *) obj_type,
(ub4)strlen((const char *) obj_type),
OCI_ATTR_DIRPATH_OBJ_CONSTR, ctlp->errhp_ctl);

2. ロードする各オブジェクト属性列のデータ型に従って記述します。必要に応じて、オブジェクトIDを記述します。これは、FINALオブジェクト表を記述する方法と同じです。

列配列のNOT FINALオブジェクト表への割当て

NOT FINALオブジェクト表の列配列の割当ては、FINALオブジェクト表の場合と同じです。

ピース単位のダイレクト・パス・ロード

一度にメモリー内に格納できないデータのロードをサポートするために、ピース単位のロードを使用します。

ダイレクト・パスAPIでは、LONGとLOBの段階的なロードがサポートされています。これには、次の手順を順に実行します。

1. 最初のピースをOCIDirPathColArrayEntrySet()を使用して列配列に設定し、OCI_DIRPATH_COL_PARTIALフラグに渡して、この列の全データのロードが完了していないことを示します。

2. 列配列をストリームに変換します。

3. ストリームをロードします。

4. そのデータの次のピースを列配列に設定します。このピースが未完了の場合は、パーシャル・フラグを設定して手順2に戻ります。完了している場合は、OCI_DIRPATH_COL_COMPLETEフラグを設定して次の列へ続行します。

このアプローチは、本質的には列オブジェクトの大規模な属性やSQL文字列型の大規模な引数を扱う方法と同じです。

関連項目:
OCI_DIRPATH_COL_ERRORの値をOCIDirPathColArrayEntry()に渡して、エラー発生時に現在の列配列行を無視する必要があることを示す方法の詳細は、「OCI_DIRPATH_COL_ERROR」を参照してください。

注意:
コレクションは、このようにピース単位でロードしません。NESTED TABLEは、トップレベル表と同じように、個別にロードします。NESTED TABLEは段階的にロードでき、またピース単位でロードされた列を含めることができます。したがって、コレクションを格納している列には、OCI_DIRPATH_COL_PARTIALフラグを設定しないでください。

オブジェクト型のピース単位のロード

オブジェクトは、そのオブジェクトが格納されている親の表から個別の列配列にロードします。したがって、オブジェクトをピース単位でロードする必要がある場合は、子の列配列に要素を設定して、ピース化された要素を含める必要があります。

通常の手順は、次のとおりです。

1. ピース化された要素に、OCI_DIRPATH_COL_PARTIALフラグを設定します。

2. 子の列配列ハンドルを親の列配列に設定し、そのエントリもOCI_DIRPATH_COL_PARTIALフラグでマークします。

3. 親の列配列をストリームに変換します。この結果、子の列配列もストリームに変換されます。

4. ストリームをロードします。

5. 手順1に戻り、その要素に対する残りのデータのロードを、完了するまで続行します。

ピース単位のロードには、いくつかのルールがあります。

- パーシャル要素は、任意のレベルで一度に1つしか存在できません。1つのパーシャル要素が完了とマークされた後は、そのレベルの別の要素をパーシャル要素に設定できます。

- 要素がパーシャルで、かつトップレベルでない場合は、制御階層上のその要素のすべての親にもパーシャルのマークを付ける必要があります。

- ネスト・レベルが複数の場合は、対象データをストリームに変換できるレベルまで移動する必要があります。これがトップレベル表になります。

関連項目:
OCI_DIRPATH_COL_ERRORの値をOCIDirPathColArrayEntry()に渡して、エラー発生時に現在の列配列行を無視する必要があることを示す方法の詳細は、「OCI_DIRPATH_COL_ERROR」を参照してください。

ダイレクト・パス・コンテキスト・ハンドルとオブジェクト型の属性

次の説明では、付録Aにリストされているハンドルと属性の詳細を補足します。

ダイレクト・パス・コンテキストの属性

1つのダイレクト・パス・コンテキストの属性があります。

OCI_ATTR_DIRPATH_OBJ_CONSTR

オブジェクト型がNOT FINALオブジェクト表にロードされることを示します。

ttext *obj_type;            /* the object type to load into this NOT FINAL */
/* object table */
sword error;

error = OCIAttrSet((void  *)dpctx,
OCI_HTYPE_DIRPATH_CTX,
(void  *) obj_type,
(ub4)strlen((const char *) obj_type),
OCI_ATTR_DIRPATH_OBJ_CONSTR, ctlp->errhp_ctl);

ダイレクト・パス関数コンテキストと属性

関数コンテキスト・ハンドルの属性の概要を、次に示します。

関連項目:
「ダイレクト・パス・コンテキスト・ハンドル(OCIDirPathCtx)の属性」

OCI_ATTR_DIRPATH_OBJ_CONSTR

オブジェクト型が置換可能なオブジェクト表にロードされることを示します。

text *obj_type; /* stores an object type name */
sword error;

error = OCIAttrSet((void  *)dpctx,
OCI_HTYPE_DIRPATH_CTX,
(void  *) obj_type,
(ub4)strlen((const char *) obj_type),
OCI_ATTR_DIRPATH_OBJ_CONSTR, ctlp->errhp_ctl);

OCI_ATTR_NAME

関数コンテキストの作成時に、非スカラー列を記述する式に相当するOCI_ATTR_NAMEを設定します。次に、式の型を示すOCI属性を設定します。式の型は、それが列オブジェクト、REF列またはSQL文字列の列であるかに応じて異なります。

列オブジェクト

必要な式は、オブジェクト型名です。オブジェクト型はデフォルトのオブジェクト・コンストラクタとして使用されます。

式の型OCI_ATTR_DIRPATH_EXPR_TYPEをOCI_DIRPATH_EXPR_OBJ_CONSTRに設定し、この式がオブジェクト型名であることを示します。

REF列

このオプションの式は、参照表名です。この表は、REF列が行オブジェクトを参照する参照元のオブジェクト表です。

式の型OCI_ATTR_DIRPATH_EXPR_TYPEをOCI_DIRPATH_EXPR_REF_TBLNAMEに設定し、この式が参照オブジェクト表であることを示します。

このパラメータの動作は、設定の有無に関係なく、REFの型によって異なります。

- 有効範囲なしのREF列(有効範囲なし、システムOIDベース)

- このパラメータが設定されていない場合、このREF列には、有効範囲なしのREF列の定義により、参照表の名前が引数としてデータ行ごとに含まれている必要があります。

- パラメータが設定されている場合、このREF列がロードの継続時間中に参照できるのは、指定されたオブジェクト表の行オブジェクトのみです。このREF列に、参照表の名前を引数として含めることはできません。(ダイレクト・パスAPIは、このパラメータをショートカットとしてユーザーに提供しています。ユーザーは、このパラメータをロードの継続時間中に同じ参照オブジェクト表を参照する有効範囲なしのREF列にロードします)。

- 有効範囲付REF列(有効範囲付、システムOIDベースおよび主キー・ベース)

- このパラメータが設定されていない場合、ダイレクト・パスAPIは、スキーマで指定されている参照表を使用します。

- このパラメータが設定されている場合、参照表の名前は、この有効範囲付REF列のスキーマに指定されているオブジェクト表と一致している必要があります。表名が一致していない場合は、エラーが発生します。

- このパラメータが設定されているかどうかに関係なく、この参照表の名前がデータ行に存在しているかどうかはAPIにとって問題ではありません。名前がデータ行にある場合、その名前はスキーマに指定されている表名と一致している必要があります。名前がデータ行にない場合、APIはスキーマに定義されている参照表を使用します。

SQL文字列の列

この必須式には、列に格納される値を導出するSQL文字列が含まれています。

式の型OCI_ATTR_DIRPATH_EXPR_TYPEをOCI_DIRPATH_EXPR_SQLに設定し、この式がSQL文字列であることを示します。

OCI_ATTR_DIRPATH_EXPR_TYPE

この属性を使用して、非スカラー列の関数コンテキストに対して、OCI_ATTR_NAMEで指定した式の型を示します。

OCI_ATTR_NAMEが設定されている場合、OCI_ATTR_DIRPATH_EXPR_TYPEは必須です。

OCI_ATTR_DIRPATH_EXPR_TYPEに使用可能な値は、次のとおりです。

- OCI_DIRPATH_EXPR_OBJ_CONSTR

- 式がオブジェクト型名であること、この式が列オブジェクトに対するデフォルトのオブジェクト・コンストラクタとして使用されることを示します。

- 列オブジェクトには必須です。

- OCI_DIRPATH_EXPR_REF_TBLNAME

- 式が参照オブジェクト表の名前であることを示します。この表は、REF列が行オブジェクトを参照する参照元のオブジェクト表です。

- REF列の場合は、オプションです。

- OCI_DIRPATH_EXPR_SQL

- 式は列に格納されている値を導出するために実行されるSQL文字列であることを示します。

- SQL文字列の列の場合は、必須です。

例13-22は、前述のルールおよび値を例示した疑似コードを示しています。

例13-22 OCI_ATTR_DIRPATH_EXPR_TYPE属性への値の指定

OCIDirPathFuncCtx  *dpfnctx; /* function context for this nonscalar column */
ub1 expr_type; /* expression type */
sword error;

if (...) /* (column type is an object) */
expr_type = OCI_DIRPATH_EXPR_OBJ_CONSTR;
...
if (...) /* (column type is a REF && function context name exists) */
expr_type = OCI_DIRPATH_EXPR_REF_TBLNAME;
...
if (...) /* (column type is a SQL string) */
expr_type = OCI_DIRPATH_EXPR_SQL;
...
error = OCIAttrSet((void  *)(dpfnctx),
OCI_HTYPE_DIRPATH_FN_CTX,
(void  *)&expr_type, (ub4)0,
OCI_ATTR_DIRPATH_EXPR_TYPE, ctlp->errhp_ctl);

OCI_ATTR_DIRPATH_NO_INDEX_ERRORS

OCI_ATTR_DIRPATH_NO_INDEX_ERRORSが1である場合、索引はロード中のどの時点でも使用不可に設定されません。索引エラーが検出された場合、ロードは終了します。つまり、行はロードされず、索引はそのままとなります。デフォルトは0 (ゼロ)です。

関連項目:
「OCI_ATTR_DIRPATH_NO_INDEX_ERRORS」

OCI_ATTR_NUM_COLS

この属性は、非スカラー列用にロードまたは処理する属性や引数の数を記述します。このパラメータは、列リストが取り出される前に設定する必要があります。式の型は、それが列オブジェクト、SQL文字列の列またはREF列であるかに応じて異なります。

列オブジェクト

この列オブジェクト用にロードするオブジェクト属性列の数。

SQL文字列の列

SQL文字列に渡す引数の数。

引数が関数内で繰り返して使用される場合も、1つとしてカウントしてください。

REF列

REF列が指し示す必要のある行オブジェクトを識別するREF引数の数。

必要な引数の数は、REF列の型によって異なります。

- 有効範囲なしのREF列(有効範囲なし、システムOIDベースのREF列)

- OCI_DIRPATH_EXPR_REF_TBLNAMEを使用している場合。参照表の名前の引数はなく、OID値の引数が1つです。(OID値のみがデータ行にある。)

- OCI_DIRPATH_EXPR_REF_TBLNAMEを使用していない場合。参照表の名前の引数が1つとOID値の引数が1つです。(参照表名とOID値の両方がデータ行にある。)

- 有効範囲付REF列(有効範囲付、システムOIDベースおよび主キー・ベース)

- OCI_DIRPATH_EXPR_REF_TBLNAMEを使用しているかどうかにかかわらず、オブジェクトIDを構成している列数がNの場合、受入れ可能な数はNまたはN+1です。参照表の名前がデータ行にない場合、最小値はNです。参照表の名前がデータ行にある場合は、N+1を使用します。

- REFがシステムOIDベースの場合、Nは1になります。REFが主キー・ベースの場合、Nは主キーを構成するコンポーネント列の数になります。参照表の名前がデータ行にある場合は、Nに1を加算します。

注意:
NまたはN+1以外のある数のREF引数で渡された場合のエラー・メッセージを簡単化するには、Nを予期している際に何らかの数の引数が検出されたことだけを示すエラー・メッセージにします。メッセージではN+1について記述されていませんが、N+1は受入れ可能である(参照表名が必要ない場合でも)ため、エラー・メッセージは表示されません。

OCI_ATTR_NUM_ROWS

OCI_HTYPE_DIRPATH_FN_CTX (関数コンテキスト)に対して使用される場合、この属性は、取出し専用のため、ユーザーによる設定はできません。この属性は、OCIAttrGet()にのみ使用でき、OCIAttrSet()には使用できません。OCIAttrGet()をOCI_ATTR_NUM_ROWS使用してコールすると、それまでにロードされた行数が戻されます。

ただし、属性OCI_ATTR_NUM_ROWSは、OCI_HTYPE_DIRPATH_CTX (表レベルのコンテキスト)に対して使用する場合は、設定およびユーザーによる取出しの両方が可能です。

OCIAttrSet()をOCI_ATTR_NUM_ROWSとOCI_HTYPE_DIRPATH_CTXを使用してコールすると、表レベルの列配列に割り当てる行数が設定されます。設定されない場合、ダイレクト・パスAPIコードは、レコード最大サイズと転送バッファのサイズに基づいて適切な数を導出します。割り当てた行数を確認するには、表レベルの列配列については、OCI_ATTR_NUM_ROWSをOCI_HTYPE_DIRPATH_COLUMN_ARRAYで使用し、関数列配列については、OCI_HTYPE_DIRPATH_FN_COL_ARRAYを使用して、OCIAttrGet()をコールします。

OCIAttrGet()をOCI_ATTR_NUM_ROWSとOCI_HTYPE_DIRPATH_CTXでコールすると、それまでにロードされた行数が戻されます。

この属性は、関数コンテキストではユーザーは設定できません。OCI_ATTR_NUM_ROWSとOCIAttrSet()により、関数列配列内で必要な行数を指定することはできません。これは、すべての関数列配列が、表レベルの列配列と同じ行数を持っているためです。この属性は、表レベルのコンテキストでのみ設定することができ、関数コンテキストでは設定できません。

ダイレクト・パス列パラメータ属性

オブジェクト、SQL文字列またはREF列を記述すると、その列属性の1つが関数コンテキストになります。

列がオブジェクトの場合、その関数コンテキストには、そのオブジェクト型とオブジェクト属性が記述されます。列がSQL文字列の場合、関数コンテキストは、コール対象の式を記述します。列がREFの場合、関数コンテキストは、参照表の名前と行オブジェクトの識別子を記述します。

例13-23は、関数コンテキストを列属性として設定し、OCI_ATTR_DIRPATH_FN_CTXをOCIAttrSet()コールで使用することを示しています。

例13-23 列属性としての関数コンテキストの設定

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
sword error;

error = OCIAttrSet((void  *)colDesc,
OCI_DTYPE_PARAM,
(void  *)(dpfnctx), (ub4)0,
OCI_ATTR_DIRPATH_FN_CTX, ctlp->errhp_ctl);

列パラメータ・コンテキスト・ハンドルの属性について次に説明します。

関連項目:
「ダイレクト・パス列パラメータ属性」

OCI_ATTR_NAME

次に、ネストした表、オブジェクト表、SQL文字列の列およびREF列をロードするためのネーミング規則について説明します。

通常、オブジェクト表のシステム生成オブジェクトID (OID)列やネストした表のSETID (SID)列など、プログラマにとって不明なシステム名を持つシステム列にデータをロードする場合、あるいは列がデータベース表の列を持たない引数(SQL文字列やREF引数など)である場合は、ダミーの名前を使用します。

列はデータベース表の列であっても、ダミーの名前を使用した場合は、その列がデータベースで識別されない名前の場合でも関数が識別できるように、列属性を設定する必要があります。

ネーミング規則は、次のとおりです。

- 子のネストした表のSETID (SID)列
SETID列は必須です。ダミーの名前を使用して、そのOCI_ATTR_NAMEを設定します。これは、APIでは、ユーザーがそのシステム名を認識しているとはみなしていないためです。これがSID列であることを示すように、OCI_ATTR_DIRPATH_SIDで列属性を設定します。

- オブジェクト表のオブジェクトID (OID)列
次の場合、オブジェクトIDは必須です。

1. オブジェクトIDがシステム生成の場合。
列名にダミーの名前(たとえば、cust_oid)を使用します。

OCI_ATTR_DIRPATH_OIDで列属性を設定します。その結果、ダミーの名前を持つ列が複数ある場合にも、システム生成のOIDを表す列を識別できます。

2. オブジェクトIDが主キー・ベースの場合。
列名にはダミーの名前を使用できません。したがって、OCI_ATTR_DIRPATH_OIDを使用してその列属性を設定する必要はありません。

- SQL文字列の引数

1. OCI_ATTR_NAMEで属性の列名を設定します。

2. SQL文字列の引数の順序は、重要ではありません。SQL文字列で使用されている順序と一致させる必要はありません。

3. SQL文字列の引数には、ネーミング規則が適用されます。

- 引数名は、SQL文字列で使用されているバインド変数名と内容が一致している必要がありますが、大/小文字区別を一致させる必要はありません。たとえば、SQL文字列がsubstr(:INPUT_STRING, 3, 5)の場合は、引数名をinput_stringにできます。

- 1つの引数がSQL文字列で繰り返し使用される場合、それを一度宣言した後は、1つの引数としてカウントできます。

- REF引数

1. OCI_ATTR_NAMEで属性の列名を設定します。
REF引数の順序は重要です。

- 参照表の名前が指定されている場合は、その名前を最初のREF引数に指定します。

- オブジェクトIDは、システム生成または主キー・ベースに関係なく、次のREF引数に指定します。

2. REFの引数には、ネーミング規則が適用されます。

- 参照表名の引数に対しては、列名にref-tblなどのダミーの名前を使用します。

- システム生成OIDの引数に対しては、列名にsys-OIDなどのダミーの名前を使用します。注意: この列は、引数として使用され、ロード対象の列としては使用されないため、OCI_ATTR_DIRPATH_OIDで設定しないでください。

- 主キー・ベースのオブジェクトIDに対しては、ロード対象のすべての主キー列をリストします。OIDに対してダミーの名前を作成する必要はありません。コンポーネント列名は、指定されている場合(次のショートカットのステップを参照)、任意の順序で指定できます。

3. ショートカットを使用する場合は、オブジェクトIDに属性列名を設定しないでください。

- ショートカット。- システムOIDベースのREF列をロードする場合は、列名に名前を設定しないでください。名前はAPIによって判断されます。ただし、外部データ型などの他の列属性は、プログラマが設定する必要があります。

- 主キーREF列をロードしており、その主キーが複数の列で構成されている場合、ショートカットはそれぞれの列名に設定されません。ただし、外部データ型などの他の列属性は、プログラマが設定する必要があります。

注意:
コンポーネント列名がNULLの場合は、APIコードによって、主キーに定義された位置または順序で列名が決定されます。したがって、名前以外の列属性を設定する場合は、その属性がコンポーネントの列に適切な順序で設定されていることを確認してください。

OCI_ATTR_DIRPATH_SID

列がネストした表のSETID列であることを示します。ネストした表にロードする場合は必須です。

ub1 flg = 1;
sword error;

error = OCIAttrSet((void  *)colDesc,
OCI_DTYPE_PARAM,
(void  *)&flg, (ub4)0,
OCI_ATTR_DIRPATH_SID, ctlp->errhp_ctl);

OCI_ATTR_DIRPATH_OID

列がオブジェクト表のオブジェクトID列であることを示します。

ub1 flg = 1;
sword error;

error = OCIAttrSet((void  *)colDesc,
OCI_DTYPE_PARAM,
(void  *)&flg, (ub4)0,
OCI_ATTR_DIRPATH_OID, ctlp->errhp_ctl);

非スカラー列のダイレクト・パス関数列配列ハンドル

関連項目:
「ダイレクト・パス関数の列配列ハンドル(OCIDirPathColArray)属性」

列がオブジェクト、SQL文字列またはREFの場合は、OCI_HTYPE_DIRPATH_FN_COL_ARRAYハンドル型を使用します。構造体OCIDirPathColArrayは、スカラー列と非スカラー列の両方の場合で同じです。

例13-24は、関数コンテキストに子の列配列を割り当てる方法を示しています。

例13-24 関数コンテキストへの子の列配列の割当て

OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
OCIDirPathColArray *dpfnca; /* direct path function column array */
sword error;

error = OCIHandleAlloc((void  *)dpfnctx, (void  **)&dpfnca,
OCI_HTYPE_DIRPATH_FN_COL_ARRAY,
(size_t)0, (void  **)0);

OCI_ATTR_NUM_ROWS属性

OCI_HTYPE_DIRPATH_FN_COL_ARRAY (関数列配列)に対して使用される場合、この属性は、取出し専用のため、ユーザーによる設定はできません。OCI_ATTR_NUM_ROWS属性を関数OCIAttrGet()でコールすると、関数列配列に割り当てられた行数が戻されます。

14 OCIのオブジェクトに関する高度なトピック

この章では、オブジェクトをOracle Databaseで操作するためのOCIの機能を紹介します。また、OCIのオブジェクト・ナビゲーショナル関数コール、型進化およびXMLのサポートについても説明します。

この章は、次の項目で構成されています。

- オブジェクト・キャッシュおよびメモリー管理

- オブジェクト・ナビゲーション

- OCIナビゲーショナル関数

- 型の変更とオブジェクト・キャッシュ

- OCIでのXMLのサポート

オブジェクト・キャッシュおよびメモリー管理

オブジェクト・キャッシュは、オブジェクトの参照とメモリー管理をサポートするクライアント側のメモリー・バッファです。これはOCIアプリケーションでフェッチしたオブジェクト・インスタンスを格納し、追跡するためのものです。オブジェクト・キャッシュには、メモリー管理が用意されています。

アプリケーションでSQLのSELECT文またはOCIのPINオペレーションによってオブジェクトをフェッチすると、オブジェクトのコピーがオブジェクト・キャッシュに格納されます。SELECT文で直接フェッチされたオブジェクトは、値によってフェッチされる、確保できない参照不可能なオブジェクトです。確保できるのは参照可能オブジェクトのみです。

オブジェクトを確保するとき、適切なバージョンのオブジェクトがキャッシュ内に存在していれば、サーバーからオブジェクトをフェッチする必要はありません。

OCIを使用してREFを参照解除し、オブジェクトを取り出す各クライアント・プログラムでは、オブジェクト・キャッシュが使用されます。クライアント側のオブジェクト・キャッシュは、オブジェクト・モードで初期化されたすべてのOCI環境ハンドルで割り当てられます。1つのプロセスの複数のスレッドで、同一のOCI環境ハンドルを共有することによって同一のクライアント側キャッシュを共有できます。

オブジェクト・キャッシュ内には接続ごとに、各参照可能オブジェクトのコピーがそれぞれ1つあります。オブジェクト・キャッシュは、接続によって論理的にパーティション化されます。

1つのREFを複数回参照解除するか、同じ接続における等価な複数のREFを参照解除した場合は、オブジェクトの同一コピーが戻されます。

キャッシュ内のオブジェクトのコピーを変更する場合は、変更内容を他のプロセスに表示する前にサーバーにフラッシュする必要があります。不要になったオブジェクトは確保解除するか、または解放できます。このオブジェクトをキャッシュからスワップすることにより、占有しているメモリー領域を解放できます。

キャッシュにロードされたデータベース・オブジェクトは、C言語構造体に透過的にマップされます。オブジェクト・キャッシュでは、キャッシュ内のすべてのオブジェクト・コピーと、それぞれに対応するデータベース内のオブジェクトとの間の関連付けが、メンテナンスされます。トランザクションをコミットすると、キャッシュ内のオブジェクト・コピーに対して行った変更がデータベースに自動的に伝播されます。

オブジェクト・キャッシュではオブジェクト・コピーの内容は管理されず、オブジェクト・コピーが自動的にリフレッシュされることもありません。アプリケーションでは、オブジェクト・コピーの内容の正確さと一貫性を確保する必要があります。たとえば、アプリケーションが挿入、更新または削除を行うためにオブジェクト・コピーにマークを付け、トランザクションを終了した場合、キャッシュはオブジェクト・コピーのマークを解除するだけであり、コピーを消去したり無効化したりしません。アプリケーションは、recentまたはlatestのオブジェクト・コピーを確保するか、または次のトランザクションでオブジェクト・コピーをリフレッシュする必要があります。アプリケーションがいずれかのオブジェクト・コピーを確保した場合、以前終了したトランザクションから変更内容がコミットされていない同じオブジェクト・コピーを取得することがあります。

関連項目:
「オブジェクト・コピーの確保」

オブジェクト・キャッシュは、modeがOCI_OBJECTのOCIEnvCreate()によってOCI環境が初期化されると作成されます。

オブジェクト・キャッシュでは、REFをオブジェクトにマッピングするための高速参照表がメンテナンスされています。アプリケーションがREFを参照解除するときに、対応するオブジェクトがオブジェクト・キャッシュにキャッシュされていない場合、オブジェクト・キャッシュは、サーバーに対して、オブジェクトをデータベースからフェッチしてオブジェクト・キャッシュにロードする要求を自動的に送信します。

同一のREFに対するその後の参照解除は、ローカル・キャッシュ・アクセスになり、ネットワークのラウンドトリップが発生しないため、より高速になります。キャッシュ内のオブジェクトにアクセス中であることをオブジェクト・キャッシュに通知するために、アプリケーションはオブジェクトを確保し、オブジェクトの処理が終了した時点で確保解除します。オブジェクト・キャッシュでは、キャッシュ内の各オブジェクトに対する確保カウントが保持されますが、このカウントは確保コールにより増加し、確保解除コールにより減少します。確保カウントが0 (ゼロ)になると、アプリケーションがそのオブジェクトを必要としなくなります。

オブジェクト・キャッシュでは、最低使用頻度(LRU)アルゴリズムを使用して、キャッシュのサイズが管理されます。LRUアルゴリズムは、キャッシュが最大サイズに達すると、候補オブジェクトを解放します。候補オブジェクトとは、確保カウントが0 (ゼロ)のオブジェクトのことです。

同じサーバーに対して稼働中の各アプリケーション・プロセスには、図14-1で示すような専用のオブジェクト・キャッシュがあります。

図14-1 オブジェクト・キャッシュ

オブジェクト・キャッシュは、メモリーに現在あるオブジェクトの追跡、そのオブジェクトへの参照のメンテナンス、自動オブジェクト・スワッピングの管理、オブジェクトのメタ属性の追跡を行います。

キャッシュの一貫性

オブジェクト・キャッシュ内のオブジェクト・コピーと、データベース内で対応するオブジェクトとの間における値の一貫性は、自動的にはメンテナンスされません。つまり、アプリケーションでオブジェクト・コピーを変更すると、その変更内容はデータベース内の対応するオブジェクトに自動的に適用されず、その逆も同様です。オブジェクト・キャッシュでは、変更されたオブジェクト・コピーをデータベースにフラッシュする操作や、古いオブジェクト・コピーをデータベースの最新値にリフレッシュする操作が可能であり、プログラムである程度の一貫性をメンテナンスできます。

注意:
Oracle Databaseは、サーバーのバッファ・キャッシュまたはデータベースとの自動キャッシュ一貫性をサポートしていません。自動キャッシュ一貫性とは、対応するオブジェクトがサーバーのバッファ・キャッシュで変更されると、ローカル・オブジェクト・コピーがオブジェクト・キャッシュによってリフレッシュされるメカニズムを指します。このメカニズムは、オブジェクト・キャッシュが、サーバー内の対応するオブジェクトに直接アクセスする前に、ローカル・オブジェクト・コピーに行われた変更をバッファ・キャッシュにフラッシュしたとき実行されます。直接的なアクセスには、SQL、トリガーまたはストアド・プロシージャを使用した、サーバーのオブジェクトの読取りや変更が含まれます。

オブジェクト・キャッシュ・パラメータ

オブジェクト・キャッシュには、環境ハンドルの属性である、2つの重要なパラメータが関連付けられています。

- OCI_ATTR_CACHE_MAX_SIZE – キャッシュの最大サイズ

- OCI_ATTR_CACHE_OPT_SIZE – キャッシュの最適サイズ

これらのパラメータは、キャッシュのメモリー使用量レベルを示し、削除してもよいオブジェクトをいつ自動的にキャッシュから削除してメモリーを解放するかを判断するのに役立ちます。

現在キャッシュにあるオブジェクトのメモリー使用量が最大キャッシュ・サイズに達するかそれを超えると、キャッシュでは、確保カウントが0 (ゼロ)の、マークされていないオブジェクトの自動的な解放(またはエージ・アウト)が始まります。キャッシュのメモリー使用量が最適サイズに達するか、解放対象オブジェクトがなくなるまで、オブジェクトの解放が続きます。キャッシュが指定した最大キャッシュ・サイズを超えることがあります。

OCI_ATTR_CACHE_MAX_SIZEは、OCI_ATTR_CACHE_OPT_SIZEのパーセントで指定します。オブジェクト・キャッシュの最大サイズ(バイト単位)は、次のアルゴリズムを使用して、OCI_ATTR_CACHE_OPT_SIZEをOCI_ATTR_CACHE_MAX_SIZEのパーセントで増分して計算します。

maximum_cache_size = optimal_size + optimal_size * max_size_percentage / 100

次に、環境ハンドル属性でアルゴリズムを表します。

maximum_cache_size = OCI_ATTR_CACHE_OPT_SIZE + OCI_ATTR_CACHE_OPT_SIZE *
OCI_ATTR_CACHE_MAX_SIZE / 100

OCI_ATTR_CACHE_MAX_SIZEの値は、OCI_ATTR_CACHE_OPT_SIZEの10% (デフォルト)に設定できます。OCI_ATTR_CACHE_OPT_SIZEのデフォルト値は8MBです。

環境ハンドルのキャッシュ・サイズ属性の設定にはOCIAttrSet()コールを、取出しにはOCIAttrGet()関数を使用します。

関連項目:
詳細は、「環境ハンドル属性」を参照してください。

オブジェクト・キャッシュ操作

この項では、オブジェクト・キャッシュで使用されるオブジェクト・コピーを操作する重要な関数について説明します。

関連項目:
すべてのOCIのナビゲーショナル関数、キャッシュ関数およびオブジェクトの管理関数のリストは、「OCIナビゲーショナル関数」を参照してください。

確保と確保解除

オブジェクト・コピーの確保によって、アプリケーションは、そのコピーへのREFを参照解除して、キャッシュ内のオブジェクト・コピーにアクセスできるようになります。

オブジェクトを確保解除すると、オブジェクトが現在使用中でないことがキャッシュに対して示されます。不要になったオブジェクトは確保解除してキャッシュからの暗黙的な解放の対象にし、メモリーを解放してください。

解放

オブジェクト・コピーを解放すると、オブジェクト・コピーはキャッシュから削除され、使用されていたメモリーが解放されます。

マークとマーク解除

オブジェクトをマークすることで、キャッシュ内のオブジェクト・コピーが更新されており、オブジェクト・コピーをフラッシュするときにサーバー内の対応するオブジェクトを更新する必要があることが、キャッシュに通知されます。

オブジェクトをマーク解除すると、オブジェクトが更新されたという指示が削除されます。

フラッシュ

オブジェクトをフラッシュすると、キャッシュ内のマークされたオブジェクト・コピーに対して行ったローカルな変更が、サーバー内の対応するオブジェクトに書き込まれます。それによって、オブジェクト・キャッシュ内のコピーのマークが解除されます。

リフレッシュ

キャッシュ内のオブジェクト・コピーをリフレッシュすると、そのコピーは、サーバー内の対応するオブジェクトの最新値に置き換わります。

トップレベルのオブジェクト・メモリーへのポインタは、リフレッシュ後も有効です。2次レベル・メモリーへのポインタ(文字列テキスト・ポインタ、コレクションなど)は、リフレッシュ後に無効になる場合があります。

たとえば、オブジェクトの型がpersonで、salary (NUMBER)とname (VARCHAR2(20))の2つの属性を持っているとします。この型は、次のとおりです。

struct Person {
OCINumber salary;
OCIString *name;
}

クライアントがPersonインスタンスへのポインタscott_pを持っており、そのインスタンスに対してOCIObjectRefresh()をコールする場合、ポインタscott_pはリフレッシュ後も同じままですが、scott_p->nameなどの第2レベルのメモリーへのポインタは異なることがあります。

オブジェクト・コピーのロードと削除

この項では、確保、確保解除および解放の各関数を説明します。

オブジェクト・コピーの確保

オブジェクト・キャッシュ内のREFをアプリケーションで参照解除する必要がある場合は、OCIObjectPin()をコールします。このコールによってREFが参照解除され、キャッシュ内のオブジェクト・コピーが確保されます。オブジェクト・コピーは、確保されているかぎり、アプリケーションからアクセス可能であることが保証されます。OCIObjectPin()で、PINオプションであるany、recentまたはlatestを受け付けます。PINオプションのデータ型はOCIPinOptです。

- any (OCI_PIN_ANY)オプションが指定される場合で、キャッシュ内にオブジェクト・コピーがある場合は、それをオブジェクト・キャッシュでただちに戻します。キャッシュ内にオブジェクト・コピーがない場合、オブジェクト・キャッシュでは最新のオブジェクト・コピーをデータベースからロードして、そのオブジェクト・コピーが戻されます。anyオプションは、製品、営業担当者、ベンダー、販売領域、部品、事務所などの、読取り専用、情報、事実またはメタのオブジェクトに適しています。これらのオブジェクトは、通常は頻繁に変更されることはなく、変更されてもその変更内容はアプリケーションに影響しません。
オブジェクト・キャッシュでは、指定された接続のキャッシュの論理パーティション内にあるオブジェクト・コピーのみが検索される点に注意してください。パーティション内にコピーがない場合、オブジェクトの最新コピーがサーバーからロードされます。

- latest (OCI_PIN_LATEST)オプションを指定すると、オブジェクト・キャッシュは、最新のオブジェクト・コピーをデータベースからキャッシュにロードします。また、オブジェクト・コピーがキャッシュ内でロックされないかぎり、そのコピーを戻します。この場合、マークを付けられたオブジェクト・コピーが即座に戻されます。オブジェクトがキャッシュ内にあり、ロックされていない場合、最新のオブジェクト・コピーがロードされ、既存のオブジェクト・コピーを上書きします。latestオプションは、発注書、不具合、明細項目、銀行口座、株価情報などの操作オブジェクトに適しています。通常、これらのオブジェクトは頻繁に変更されるため、プログラムが、これらのオブジェクトが最新の状態のときにアクセスすることが重要になります。

- recent (OCI_PIN_RECENT)オプションが指定される場合、2つの可能性が考えられます。

- 同じトランザクションにおいて、latestまたはrecentオプションを使用して、オブジェクト・コピーが以前に確保されている場合は、recentオプションはanyオプションと同等になります。

- 前述の条件が当てはまらない場合は、recentオプションはlatestオプションと同等になります。

プログラムでオブジェクトが確保される場合、プログラムではsessionまたはtransactionという2つの可能な値の内の1つが確保継続時間に指定されます。継続時間のデータ型はOCIDurationです。

- 確保継続時間がsession (OCI_DURATION_SESSION)の場合、セッションを終了するまで(つまり接続の終了まで)、またはプログラムで(OCIObjectUnpin()をコールして)明示的に確保解除されるまで、オブジェクト・コピーは確保されたままとなります。

- 確保継続時間がtransaction (OCI_DURATION_TRANS)の場合、トランザクションの終了まで、または明示的に確保解除されるまで、オブジェクト・コピーは確保されたままとなります。

オブジェクト・コピーをデータベースからキャッシュにロードするとき、実際にはキャッシュで次の文が実行されます。

SELECT VALUE(t) FROM t WHERE REF(t) = :r

この文では、tはオブジェクトが格納されているオブジェクト表であり、rはREFです。フェッチされた値はキャッシュ内のオブジェクト・コピーの値になります。

オブジェクト・キャッシュでは、個々のSELECT文が効率的に実行され、各オブジェクト・コピーがキャッシュにロードされるため、コミット読取りトランザクションでは、オブジェクト・コピー相互の読取り一貫性は保証されません。

シリアライズ可能トランザクションでは、recentまたはlatestで確保されたオブジェクト・コピーは相互の読取り一貫性があります。これは、これらのオブジェクト・コピーをロードするSELECT文は、同じデータベース・スナップショットに基づいて実行されるためです。

コミット読取りトランザクションとシリアライズ・トランザクションは、データベースがサポート可能な異なる分離レベルを示します。これ以外にも、非コミット読取りや反復可能読取りなど様々な分離レベルがあります。各分離レベルでは、同時トランザクション間でのある程度の干渉は許容されます。通常、分離レベルでより多くの干渉が許容される場合、同時トランザクションの同時実行性が向上します。コミット読取りトランザクションでは、問合せが複数回実行された場合、コミットされた他のトランザクションによる変更が表示されるため、このタイプのランザクションでは一貫性のないデータ・セットが生成されることがあります。シリアライズ・トランザクションの場合は、このようなことはありません。

オブジェクト・キャッシュのモデルは、Oracle Databaseトランザクション・モデルに対して直交状態であるか、または独立しています。オブジェクト・キャッシュの動作は、トランザクション・モデルによって変わることはありません。ただし、同じプログラムを異なる複数のトランザクション・モデル(コミット読取りとシリアライズ可能など)のもとで実行した場合、オブジェクト・キャッシュを介してサーバーから取り出したオブジェクトは、異なることがあります。

注意:
OCIObjectArrayPin()の場合、オブジェクトは常にデータベースから取り出されるため、PINオプションは無効です。REFがキャッシュ内のオブジェクトに対するものである場合、OCIObjectArrayPin()は次のエラーで失敗します。

ORA-22881: dangling REF

オブジェクト・コピーの確保解除

プログラムで使用しないオブジェクト・コピーは、確保解除できます。その後、解放できるようになります。キャッシュのメモリーが残り少なくなった場合は、オブジェクト・コピーを完全に確保解除すると同時にマーク解除し、キャッシュ内のそのコピーを暗黙的解放の対象にする必要があります。オブジェクト・コピーを完全に確保解除するには、n回確保した場合はn回確保解除する必要があります。

確保解除済でマーク未解除のオブジェクト・コピーは、フラッシュするか、ユーザーが明示的にマーク解除しないと暗黙的解放の対象になりません。ただし、オブジェクト・キャッシュのメモリーが残り少なくなると、オブジェクト・キャッシュのオブジェクト・コピーは暗黙的に解放されるので、確保解除したオブジェクト・コピーを必ずしも解放する必要はありません。暗黙的に解放されていないオブジェクト・コピーをプログラムで(anyまたはrecentオプションを指定して)再度確保した場合、同一のオブジェクト・コピーを入手することになります。

アプリケーションでオブジェクト・コピーを確保解除するには、OCIObjectUnpin()またはOCIObjectPinCountReset()をコールします。さらに、プログラムでは、特定の接続に対してキャッシュ内のすべてのオブジェクト・コピーを完全に確保解除するために、OCICacheUnpin()をコールできます。

オブジェクト・コピーの解放

オブジェクト・コピーの解放とは、オブジェクト・キャッシュからオブジェクト・コピーを削除し、そのコピーが使用していたメモリーを解放することです。キャッシュのメモリーを解放するには、次の2つの方法があります。

- 明示的解放 – プログラムでOCIObjectFree()をコールして、キャッシュからオブジェクト・コピーを明示的に解放または削除します。この関数には、マークまたは確保されたオブジェクト・コピーのいずれかを(強制的に)解放するオプションがあります。OCICacheFree()をコールしてキャッシュ内のすべてのオブジェクト・コピーを解放することもできます。

- 暗黙的解放 – キャッシュのメモリーが残り少なくなった場合は、確保解除済のオブジェクト・コピーとマーク解除済のオブジェクト・コピーの両方が、暗黙的に解放されます。マークされた、確保解除済のオブジェクトは、オブジェクト・コピーをフラッシュまたはマーク解除した場合にのみ、暗黙的解放の対象になります。

関連項目:
詳細は、「オブジェクト・キャッシュ・パラメータ」を参照してください。

メモリー管理を目的とする場合は、不要になったオブジェクトをアプリケーションで確保解除することが重要です。確保解除したオブジェクトはキャッシュから削除される対象になるので、必要なときにキャッシュのメモリーをスムーズに解放できます。

OCIでは、クライアント側キャッシュにある参照されていないオブジェクトを解放する関数は提供していません。

オブジェクト・コピーの変更

この項では、オブジェクト・コピーをマークする関数とマークを解除する関数を説明します。

オブジェクト・コピーのマーク

オブジェクト・コピーは、キャッシュ内でローカルに作成、更新および削除できます。(OCIObjectNew()をコールすることによって)キャッシュ内にオブジェクト・コピーを作成すると、オブジェクト・キャッシュでオブジェクト・コピーに挿入のマークが付けられます。そのため、このオブジェクト・コピーをフラッシュすると、オブジェクトがサーバーに挿入されます。

オブジェクト・コピーがキャッシュ内で更新された場合、ユーザーは、オブジェクト・コピーに更新のマークを付ける(OCIObjectMarkUpdate()をコールする)ことによって、オブジェクト・キャッシュに通知する必要があります。オブジェクト・コピーをフラッシュすると、サーバー内の対応するオブジェクトが、オブジェクト・コピーの値に更新されます。

オブジェクト・コピーが削除された場合、そのオブジェクト・コピーは(OCIObjectMarkDelete()をコールすることにより)オブジェクト・キャッシュ内で削除のマークが付けられます。オブジェクト・コピーをフラッシュすると、サーバー内の対応するオブジェクトが削除されます。マークされたオブジェクト・コピーのメモリーは、そのコピーをフラッシュして確保解除しないかぎり解放されません。プログラムで削除マーク付きのオブジェクトを確保すると、参照先のない参照を参照解除した場合と同様のエラーになります。

1つのオブジェクト・コピーを複数回変更した場合、そのコピーをフラッシュしたときにサーバーのオブジェクトに適用されるのは、最後の変更結果です。たとえば、オブジェクト・コピーを更新した後で削除した場合、オブジェクト・コピーをフラッシュすると、サーバーのオブジェクトは削除されます。同様に、オブジェクト・コピーの属性を複数回更新した場合、オブジェクト・コピーをフラッシュしたときにサーバーで更新されるのは、属性の最終的な値です。

プログラムでは、オブジェクト・コピーがオブジェクト・キャッシュにロードされている場合のみ、オブジェクト・コピーを更新済または削除済としてマークすることができます。

オブジェクト・コピーのマーク解除

オブジェクト・キャッシュ内のマークされたオブジェクト・コピーは、マーク解除できます。マークされたオブジェクト・コピーをマーク解除すると、オブジェクト・コピーに対して行った変更内容はサーバーにフラッシュされないことが保証されます。オブジェクト・キャッシュのオブジェクト・コピーに対して行ったローカルな変更内容は、取り消されません。

プログラムでオブジェクトをマーク解除するには、OCIObjectUnmark()をコールします。さらに、OCICacheUnmark()をコールして、特定の接続に対して、キャッシュ内のすべてのオブジェクト・コピーをマーク解除することもできます。

オブジェクト・コピーとサーバーとの同期化

この項では、キャッシュとサーバーの同期化操作(フラッシュ、リフレッシュ)を説明します。

変更をサーバーにフラッシュ

オブジェクト・コピーをフラッシュすると、キャッシュ内のマークされたオブジェクト・コピーに対して行ったローカルな変更が、サーバーに書き込まれます。OCIObjectFlush()をコールして、単一のオブジェクト・コピーをフラッシュできます。OCICacheFlush()をコールして、キャッシュ内のすべてのマークされたオブジェクト・コピーをフラッシュするか、リストに選択されているマークされたオブジェクト・コピーをフラッシュできます。OCICacheFlush()は、特定のサービス・コンテキストに関連付けられたオブジェクトをフラッシュします。「OCICacheFlush()」を参照してください。

オブジェクト・コピーをフラッシュしたら、マークを解除します。(フラッシュ後にオブジェクトはサーバーでロックされます。そのため、キャッシュ内のオブジェクト・コピーはロック状態とマークされます。)

注意:
OCIObjectFlush()操作では、複数のオブジェクトがフラッシュされる場合でも、サーバー・ラウンドトリップは1回のみです。

コールバック関数(OCICacheFlush()コールのオプションの引数)によって、ある型の使用済オブジェクトのみをフラッシュできます。目的のオブジェクトのみを戻すコールバックを定義します。この場合でも、フラッシュに対し、サーバー・ラウンドトリップが1回のみ発生します。

OCICacheFlush()のデフォルト・モードでは、オブジェクトは使用済とマークされるようにフラッシュされます。このフラッシュ操作のパフォーマンスは、環境ハンドル内でOCI_ATTR_CACHE_ARRAYFLUSH属性を設定すると、非常に向上します。

関連項目:
「環境ハンドル属性」

ただし、OCI_ATTR_CACHE_ARRAYFLUSH属性は、オブジェクトがフラッシュされる順序が重要でない場合にのみ使用することができます。この属性が有効なときは、使用済オブジェクトはまとめてグループ化され、サーバーによる表の更新が効率的に行われるような方法でサーバーに送信されます。この属性が有効なときは、オブジェクトが使用済としてマークされる順序の維持は保証されません。

オブジェクト・コピーのリフレッシュ

オブジェクト・コピーをリフレッシュすると、サーバー内の対応するオブジェクトの最新値が、オブジェクト・コピーに再ロードされます。最新値は、その他のコミット済トランザクションでの変更や、同じトランザクションで(オブジェクト・キャッシュを介さずに)直接サーバー内で行った変更を含む場合があります。プログラムでは、SQL DMLまたはトリガー、ストアド・プロシージャを使用して、サーバー内のオブジェクトを直接変更できます。

プログラムで、マークされたオブジェクト・コピーをリフレッシュするには、まずオブジェクト・コピーをマーク解除する必要があります。確保解除したオブジェクト・コピーは、リフレッシュすると(つまりキャッシュ全体をリフレッシュすると)、解放されます。

プログラムで単一のオブジェクト・コピーをリフレッシュするには、OCIObjectRefresh()をコールします。または、OCICacheRefresh()をコールして、キャッシュ内のすべてのオブジェクト・コピー、トランザクションでロードしたすべてのオブジェクト・コピー(つまり、recentまたはlatestオプションを指定して確保したオブジェクト・コピー)、またはリストに選択されたオブジェクト・コピーのいずれかをリフレッシュできます。

オブジェクトをサーバーにフラッシュすると、トリガーを起動してサーバー内のさらに多くのオブジェクトを変更できます。その場合、オブジェクト・キャッシュ内にある(トリガーによって変更したオブジェクトと)同一のオブジェクトは最新の状態ではなくなり、リフレッシュしないとロックまたはフラッシュできません。

各種のメタ属性フラグおよびオブジェクト継続時間は、表14-1で説明するとおり、リフレッシュされた後で変更されます。

表14-1 リフレッシュ操作後のオブジェクト属性

オブジェクト属性

リフレッシュ後の状態

既存

適切な値に設定

確保済

変更なし

フラッシュ済

リセット

割当て時間

変更なし

確保継続時間

変更なし

リフレッシュ操作の間、オブジェクト・キャッシュは新しいデータをオブジェクト・コピーのトップレベルのメモリーにロードし、トップレベルのメモリーを再利用します。オブジェクト・コピーのトップレベルのメモリーには、オブジェクトの表内格納属性が含まれています。ただし、オブジェクト・コピーの表外格納属性用のメモリーは、解放して再配置できます。これは、表外格納属性のサイズが可変であるためです。

関連項目:
オブジェクト・メモリーの詳細は、「インスタンスのメモリー・レイアウト」を参照してください。

オブジェクトのロック

この項では、オブジェクトのロックに関連するOCI関数について説明します。

ロック・オプション

オブジェクトを確保すると、オブジェクトをロックするか、またはロック・オプションを使用しないかを指定できます。オブジェクトをロックすると、サーバー側のロックが取得されるため、他のユーザーはオブジェクトを変更できなくなります。ロックが解除されるのは、トランザクションがコミットまたはロールバックする場合です。次に、各種のロック・オプションを示します。

- ロック・オプションOCI_LOCK_NONEは、ロックなしでオブジェクトを確保するようにキャッシュに指示します。

- ロック・オプションOCI_LOCK_Xは、ロックを取得した後でのみオブジェクトを確保するようにキャッシュに指示します。オブジェクトが現在別のユーザーによってロックされている場合、このオプションによる確保コールは、ロックが取得できるまで待機してから、コール元に戻ります。これは、SELECT FOR UPDATE文の実行に相当します。

- ロック・オプションOCI_LOCK_X_NOWAITは、ロックを取得した後でのみオブジェクトを確保するようにキャッシュに指示します。OCI_LOCK_Xオプションとは異なり、OCI_LOCK_X_NOWAITオプションによる確保コールは、オブジェクトが現在別のユーザーによってロックされている場合、待機しません。これは、SELECT FOR UPDATE WITH NOWAIT文の実行に相当します。

更新するためのオブジェクトのロック

プログラムでは、オプションでOCIObjectLock()をコールして、更新するオブジェクトをロックできます。このコールは、データベースのオブジェクトに対する行ロックの実行をオブジェクト・キャッシュに指示します。これは、次の文の実行と類似しています。

SELECT NULL FROM t WHERE REF(t) = :r FOR UPDATE

この文では、tは、ロックするオブジェクトを格納しているオブジェクト表であり、rはオブジェクトを識別するREFです。OCIObjectLock()をコールすると、オブジェクト・キャッシュ内のオブジェクト・コピーがロック状態とマークされます。

オブジェクトのグラフまたはオブジェクトの集合をロックするには、オブジェクトごとにOCIObjectLock()のコールが必要なため、数回のコールが必要です。配列確保のOCIObjectArrayPin()コールを使用すると、パフォーマンスが向上します。

オブジェクトをロックすることにより、キャッシュのオブジェクトが最新のものであることをアプリケーションで保証します。オブジェクトがアプリケーションでロックされている間は、その他のトランザクションはそのオブジェクトを変更できません。

トランザクションの最後には、すべてのロックがサーバーによって自動的に解放されます。オブジェクト・コピーのロック状態インジケータはリセットされます。

NOWAITオプションを使用したロック

ロックしようとしているオブジェクトが、現在別のユーザーによってロックされている場合があります。この場合、アプリケーションはブロックされます。

オブジェクトをロックする際にブロッキングを避けるためには、アプリケーションでOCIObjectLock()コールのかわりにOCIObjectLockNoWait()コールを使用できます。この関数では、別のユーザーによるロックのためオブジェクトをロックできない場合は、すぐにエラーが戻されます。

NOWAITオプションは、OCI_LOCK_X_NOWAITの値をロック・オプション・パラメータとして渡すことで、コールを確保するためにも利用できます。

コミット時ロックの実装

OCIアプリケーションにコミット時ロックを実装するには、2つのオプションを使用します。コミット時ロックでは、トランザクションによって、オブジェクト・キャッシュ内のオブジェクトの変更とフラッシュ、および変更のコミットが正常に行われることを想定しています。

コミット時ロックのオプション1

第1のコミット時ロック・オプションは、シリアライズ可能なレベルでトランザクションを実行するOCIアプリケーションのためのオプションです。

OCIでは、オブジェクト・キャッシュ内のオブジェクトをロックせずに参照解除して確保し、キャッシュ内でそのオブジェクトを(ロックせずに)変更し、使用済のオブジェクトをデータベースにフラッシュするコールをサポートしています。

トランザクションの開始以降、使用済オブジェクトが、別のコミット済トランザクションによって変更された場合、フラッシュ操作の間に、シリアライズ不能トランザクションのエラーが戻されます。トランザクションの開始以降、別のトランザクションで変更された使用済オブジェクトがない場合は、トランザクションによって変更内容はデータベースに正常に書き込まれます。

注意:
OCITransCommit()は、使用済オブジェクトをデータベースにフラッシュしてから、トランザクションをコミットします。

この機能により、コミット時ロック・モデルが効果的に実装されます。

コミット時ロックのオプション2

アプリケーションでは、オブジェクトの変更検出モードを使用可能に切り替えられます。この操作を行うには、環境ハンドルのOCI_ATTR_OBJECT_DETECTCHANGE属性の値にTRUEを設定します。

このモードがアクティブのときは、別のオブジェクトがコミットしたトランザクションによってサーバー内で変更されているオブジェクトをフラッシュしようとすると、アプリケーションにORA-08179エラー「並行性チェックに失敗しました」が戻されます。この後、アプリケーションではこのエラーを適切な方法で処理できます。

オブジェクト・アプリケーションでのコミットおよびロールバック

トランザクションをコミットすると(OCITransCommit())、すべてのマークされたオブジェクトがサーバーにフラッシュされます。トランザクション継続時間を指定して確保したオブジェクト・コピーは、確保解除されます。

トランザクションをロールバックすると、すべてのマークされたオブジェクトがマーク解除されます。トランザクション継続時間を指定して確保したオブジェクト・コピーは、確保解除されます。

オブジェクト継続時間

メモリー内に空き領域を確保するために、オブジェクト・キャッシュは、可能なときにはいつでもオブジェクトのメモリーの再利用を試みます。オブジェクト・キャッシュは、オブジェクトの存続期間(割当て時間)の期限が切れるか、またはオブジェクトの確保継続時間の期限が切れたときに、オブジェクトのメモリーを再利用します。割当て時間は、オブジェクトがOCIObjectNew()で作成されたときに設定され、確保継続時間は、オブジェクトがOCIObjectPin()で確保されたときに設定されます。期間値のデータ型はOCIDurationです。

注意:
オブジェクトの確保継続時間は、オブジェクトの割当て時間より長くは設定できません。

オブジェクトの割当て時間が終わりに達すると、オブジェクトは自動的に削除され、メモリーが再使用可能になります。確保継続時間はオブジェクトのメモリーを再利用できる時期を示し、キャッシュが一杯になるとメモリーは再利用されます。

OCIでは、次の2つの事前定義済の継続時間をサポートします。

- トランザクション(OCI_DURATION_TRANS)

- セッション(OCI_DURATION_SESSION)

トランザクション継続時間は、包含するトランザクションが終了(コミットまたは終了)したときに期限が切れます。セッション継続時間は、セッションまたは接続が終了した時点で期限切れになります。

アプリケーションでは、OCIObjectUnpin()を使用してオブジェクトを明示的に確保解除できます。個々のオブジェクトの明示的な確保解除を最小限にするには、関数OCICacheUnpin()を使用して、オブジェクト・キャッシュ内で現在確保済のすべてのオブジェクトを確保解除します。デフォルトでは、すべてのオブジェクトは、確保継続時間終了時に確保を解除されます。

継続時間例

表14-2は、アプリケーションで、異なる継続時間を使用する方法を示しています。このアプリケーションでは、1つの接続と3つのトランザクションで、4つのオブジェクトを作成または確保しています。最初の列は、相対的な時間インジケータです。2番目の列はデータベースで実行されるアクションを示し、3番目の列はそのアクションを実行する関数を示しています。残りの列はアプリケーションの各ポイントでの各種オブジェクトの状態を示しています。

たとえば、オブジェクト1は、T2で期間を接続継続時間として作成されてから、接続が終了するT19まで存在します。オブジェクト2は、T6でフェッチされた後、期間をトランザクション継続時間としてT7で確保され、トランザクションがコミットされるT9まで確保されたままとなります。

表14-2 割当て時間および確保継続時間の例

時間

アプリケーションのアクション

関数

オブジェクト1

オブジェクト2

オブジェクト3

オブジェクト4

T_1

接続を確立する

-

-

-

-

-

T_2

オブジェクト1を作成する - 割当て時間 = 接続

OCIObjectNew()

既存

-

-

-

T_5

トランザクション1を開始する

OCITransStart()

既存

-

-

-

T_6

SQL - REFをオブジェクト2にフェッチする

-

既存

-

-

-

T_7

オブジェクト2を確保する - 確保継続時間 = トランザクション

OCIObjectPin()

既存

確保済

-

-

T_8

アプリケーション・データを処理する

-

既存

確保済

-

-

T_9

トランザクション1をコミットする

OCITransCommit()

既存

確保解除

-

-

T_10

トランザクション2を開始する

OCITransStart()

既存

-

-

-

T_11

オブジェクト3を作成する - 割当て時間 = トランザクション

OCIObjectNew()

既存

-

既存

-

T_12

SQL - REFをオブジェクト4にフェッチする

-

既存

-

既存

-

T_13

オブジェクト4を確保する - 確保継続時間 = 接続

OCIObjectPin()

既存

-

既存

確保済

T_14

トランザクション2をコミットする

OCITransCommit()

既存

-

削除済

確保済

T_15

セッション1を終了する

OCIDurationEnd()

既存

-

-

確保済

T_16

トランザクション3を開始する

OCITransStart()

既存

-

-

確保済

T_17

アプリケーション・データを処理する

-

既存

-

-

確保済

T_18

トランザクション3をコミットする

OCITransCommit()

既存

-

-

確保済

T_19

接続を終了する

-

削除済

-

-

確保解除

関連項目:

- これらの関数に渡すことができるパラメータ値の詳細は、第18章のOCIObjectNew()およびOCIObjectPin()の説明を参照してください。

- 割当て時間が期限切れになる前にオブジェクト・メモリーを解放する場合の詳細は、「オブジェクトの作成」を参照してください。

インスタンスのメモリー・レイアウト

メモリーのインスタンスは、インスタンスのトップレベル・メモリー・チャンク、NULLインジケータ構造体のトップレベル・メモリー、およびオプションとしていくつかの2次メモリー・チャンクで構成されています。たとえば、例14-1に定義されたDEPARTMENTという行の型を想定します。

例14-1 Department行のオブジェクト型の表現

CREATE TYPE department AS OBJECT
( dep_name      varchar2(20),
budget        number,
manager       person,            /* person is an object type */
employees     person_array );   /* varray of person objects */

例14-2に、DEPARTMENTのC表現を示します。

例14-2 Department行のC表現

struct department
{
OCIString * dep_name;
OCINumber budget;
struct person manager;
OCIArray * employees;
);
typedef struct department department;

DEPARTMENTの各インスタンスには、dep_name、budget、manager、employeesなどのトップレベル属性が含まれたトップレベル・メモリー・チャンクがあります。dep_name属性とemployees属性は、追加メモリー(2次メモリー・チャンク)へのポインタです。2次メモリーは、埋込みインスタンスのデータを入れるために使用されます(employeesのVARRAYやdep_nameの文字列など)。

NULLインジケータ構造体のトップレベル・メモリーには、インスタンスのトップレベル・メモリー・チャンクにある属性のNULL状態が入っています。例14-2では、NULL構造体のトップレベル・メモリーに、属性dep_name、budgetおよびmanagerのNULL状態と属性employeesのアトミックNULL状態が含まれています。

オブジェクト・ナビゲーション

この項では、OCIアプリケーションでオブジェクト・キャッシュ内のオブジェクトのグラフをナビゲートする方法を説明します。

単純なオブジェクト・ナビゲーション

例14-1および例14-2では、アプリケーションで取り出したオブジェクトは単純なオブジェクトであり、その属性はすべてスカラー値でした。アプリケーションで、別のオブジェクトへのREFである属性を持つオブジェクトを取り出す場合は、OCIコールを使用してオブジェクト・グラフを横断し、参照対象のインスタンスにアクセスできます。

たとえば、次の宣言でデータベースに新しい型を定義したとします。

CREATE TYPE person_t AS OBJECT
(  name          VARCHAR2(30),
mother          REF person_t,
father          REF person_t);

person_tオブジェクトのオブジェクト表は、次の文を使用して作成します。

CREATE TABLE person_table OF person_t;

これでperson_t型のインスタンスをこの型指定表に格納できます。person_tの各インスタンスには、同じ表に格納される他の2つのオブジェクトへの参照が含まれています。NULL参照は、親に関する情報がないことを表します。

オブジェクト・グラフは、オブジェクト・インスタンス間のREFリンクを視覚的に表現したものです。たとえば、図14-2に、1オブジェクトから別のオブジェクトへのリンクを示すperson_tインスタンスのオブジェクト・グラフを示します。円はオブジェクトを表し、矢印は他のオブジェクトへの参照を表しています。矢印の隣のMとFは、それぞれ母と父を示しています。

図14-2 person_tインスタンスのオブジェクト・グラフ

この場合、各オブジェクトには、同じオブジェクトに関する2つの別のインスタンス(MおよびF)へのリンクがあります。これは、必ずしも当てはまるわけではありません。オブジェクトには、他のオブジェクト型へのリンクがある場合があります。他の型のグラフも使用可能です。たとえば、一連のオブジェクトをリンクしたリストとして実装した場合、オブジェクト・グラフは単純な連鎖として表示され、各オブジェクトは、リンクしたリスト内の前または次のオブジェクト、あるいはその両方を参照します。

この章の前半で説明した方法を使用して、person_tインスタンスへの参照を取り出し、次にそのインスタンスを確保できます。OCIには、1つのオブジェクトから別のオブジェクトへ参照をたどることでオブジェクト・グラフを横断できる機能があります。

たとえば、アプリケーションで前述のグラフのperson1インスタンスをフェッチし、pers_1として確保するとします。確保されると、アプリケーションでは、person1のmotherインスタンスにアクセスし、2回目のPINオペレーションでpers_2に確保することができます。

OCIObjectPin(env, err, pers_1->mother, OCI_PIN_ANY, OCI_DURATION_TRANS,
OCI_LOCK_X, (OCIComplexObject *) 0, &pers_2);

この場合、2つ目のインスタンスを取り出すためのOCIのフェッチ操作は必要ありません。

アプリケーションでは、次に、person1のfatherインスタンスを確保するか、person2の参照リンクで操作できます。

注意:
NULLまたは参照先がないREFを確保しようとすると、OCIObjectPin()コールがエラーになります。

OCIナビゲーショナル関数

この項では、OCIナビゲーショナル関数をまとめて簡単に説明します。関数は一般的な機能別にグループ化してあります。

関連項目:
これらの各関数の詳細は、第18章を参照してください。

これらの関数の使用方法については、この章の初めの項で説明しています。

ナビゲーショナル関数は、機能の種類によって異なる接頭辞を付けるネーミング計画に従っています。

OCICache*() - キャッシュ操作の関数。

OCIObject*() - 個々のオブジェクトを操作する関数。

確保/確保解除/解放関数

オブジェクトの確保、確保解除または解放を行うには、表14-3に示す関数を使用します。

表14-3 確保関数、解放関数および確保解除関数

関数

用途

OCICacheFree()

キャッシュの全インスタンスを解放します。

OCICacheUnpin()

キャッシュまたは接続で永続オブジェクトの確保を解除します。

OCIObjectArrayPin()

参照の配列を確保します。

OCIObjectFree()

スタンドアロン・インスタンスを解放し、確保解除します。

OCIObjectPin()

オブジェクトを確保します。

OCIObjectPinCountReset()

オブジェクトの確保を解除して確保カウントを0 (ゼロ)にします。

OCIObjectPinTable()

継続時間を指定して表オブジェクトを確保します。

OCIObjectUnpin()

オブジェクトの確保を解除します。

フラッシュおよびリフレッシュ関数

変更したオブジェクトをサーバーにフラッシュするには、表14-4に示す関数を使用します。

表14-4 フラッシュおよびリフレッシュ関数

関数

用途

OCICacheFlush()

キャッシュ内の変更済永続オブジェクトをサーバーにフラッシュします。

OCIObjectFlush()

単一の変更済永続オブジェクトをサーバーにフラッシュします。

OCICacheRefresh()

キャッシュ内の確保済永続オブジェクトをリフレッシュします。

OCIObjectRefresh()

単一の永続オブジェクトをリフレッシュします。

マークおよびマーク解除関数

アプリケーションでメタ属性の1つを変更してオブジェクトのマークまたはマーク解除を行うには、表14-5 に示す関数を使用します。

表14-5 マークおよびマーク解除関数

関数

用途

OCIObjectMarkDeleteByRef()

REFの指定時にオブジェクトを削除済にマークします。

OCIObjectMarkUpdate()

オブジェクトに更新済(使用済)のマークを付けます。

OCIObjectMarkDelete()

オブジェクトに削除済のマークを付けるか、または、値インスタンスを削除します。

OCICacheUnmark()

キャッシュ内の全オブジェクトをマーク解除します。

OCIObjectUnmark()

指定のオブジェクトを更新済にマークします。

OCIObjectUnmarkByRef()

REFの指定時にオブジェクトを更新済にマークします。

オブジェクトのメタ属性アクセッサ関数

アプリケーションでオブジェクトのメタ属性にアクセスするには、表14-6に示す関数を使用します。

表14-6オブジェクトのメタ属性関数

関数

用途

OCIObjectExists()

インスタンスの存在状況を取得します。

OCIObjectFlushStatus()

インスタンスのフラッシュ状態を取得します。

OCIObjectGetInd()

インスタンスのNULLインジケータ構造体を取得します。

OCIObjectIsDirty()

オブジェクトに更新済のマークが付いているかどうか調べます。

OCIObjectIsLocked()

オブジェクトはロック状態かどうか調べます。

その他の関数

表14-7に示す関数は、OCIアプリケーションにその他のオブジェクト機能を提供します。

表14-7その他のオブジェクト関数

関数

用途

OCIObjectCopy()

1つのインスタンスを別のインスタンスにコピーします。

OCIObjectGetObjectRef()

指定のオブジェクトへの参照を戻します。

OCIObjectGetTypeRef()

インスタンスのTDOへの参照を取得します。

OCIObjectLock()

永続オブジェクトをロックします。

OCIObjectLockNoWait()

NOWAITモードでオブジェクトをロックします。

OCIObjectNew()

新規インスタンスを作成します。

型の変更とオブジェクト・キャッシュ

型名に基づいて型情報がリクエストされると、OCIは最新バージョンの型に対応する型記述子オブジェクト(TDO)を戻します。サーバーとオブジェクト・キャッシュは同期していないため、オブジェクト・キャッシュ内のTDOは最新ではない場合があります。

オブジェクトの確保時に、イメージのバージョンがTDOのバージョンと異なっている可能性があります。この場合、エラーが発生します。アプリケーションを停止するか、またはTDOをリフレッシュしてオブジェクトを再確保するかを判断するのはユーザーです。アプリケーションを続行すると、アプリケーションが失敗する可能性があります。これは、イメージとTDOのバージョンが同じ場合でも、アプリケーションで定義されたオブジェクト構造(つまり、C構造体)が型の新しいバージョンと互換性があるという保証がないためです。特に、サーバー内で型から属性が削除された場合にこれが当てはまります。

したがって、型の構造体を変更した場合は、変更された型のヘッダー・ファイルを再生成し、アプリケーションを変更し、再コンパイルおよび再リンクしてから、プログラムを再実行する必要があります。

関連項目:
「型の変更」

OCIでのXMLのサポート

Oracle XML DBでは、XMLTypeデータ型を使用したXMLインスタンスの格納および操作をサポートしています。これらのXMLインスタンスにアクセスするには、OCIをC DOM API for XMLと併用します。

アプリケーション・プログラムでは、サーバー・ハンドル、文ハンドルなどの通常のOCIハンドルを初期化し、その後XMLコンテキストを初期化する必要があります。アプリケーション・プログラムでは、バックエンドでXMLインスタンスを操作したり、クライアント側で新規インスタンスを作成できます。初期化されたXMLコンテキストは、すべてのC DOM関数で使用できます。

Oracle XML DBに格納されたXMLデータは、C DOM構造体xmldocnodeによってクライアント側でアクセスできます。この構造体は、OCI文のXML値のバインド、定義および操作に使用できます。

関連項目:

- CでのXMLのサポートの詳細は、第23章を参照してください。

- バイナリXMLの例を含む、XML用C APIの使用方法は、『Oracle XML DB開発者ガイド』を参照してください。

- C用のXMLパーサーの詳細は、『Oracle XML Developer's Kitプログラマーズ・ガイド』を参照してください。

- DOM C APIs for XMLの詳細は、Oracle XMLリファレンスを参照してください。

XMLコンテキスト

XMLコンテキストは、すべてのC DOM API関数における必須パラメータです。この不透明なコンテキストは、データ・エンコーディング、エラー・メッセージ言語などに関連する情報をカプセル化します。このコンテキストの内容は、XDKおよびOracle XML DBアプリケーションでは異なります。

Oracle XML DBの場合、XMLコンテキストを初期化および解放するための2つのOCI関数が提供されています。

xmlctx *OCIXmlDbInitXmlCtx (OCIEnv *envhp, OCISvcCtx *svchp, OCIError *errhp,
ocixmldbparam *params, ub4 num_params);

void OCIXmlDbFreeXmlCtx (xmlctx *xctx);

サーバー上のXMLデータ

サーバー上のXMLデータは、OCI文のコールによって操作できます。他のオブジェクト・インスタンスと同様に、xmldocnodeを使用してXMLTypeの値をバインドおよび定義できます。サーバーからXMLデータを選択するには、OCI文を使用します。このデータは直接C DOM関数で使用できます。同様に、値を直接SQL文にバインドしなおすことができます。

OCI XML DB関数の使用

XMLコンテキストを初期化および終了するには、それぞれOCIXmlDbInitXmlCtx()関数およびOCIXmlDbFreeXmlCtx()関数を使用します。ヘッダー・ファイルocixmldb.hは統合C APIとともに使用されます。

例14-3は、C APIによる操作の実行方法を示すテスト例のコード・フラグメントです。

例14-3 C APIによるXMLコンテキストの初期化および終了

#ifndef S_ORACLE
#include <s.h>
#endif
#ifndef ORATYPES_ORACLE
#include <oratypes.h>
#endif
#ifndef XML_ORACLE
#include <xml.h>
#endif
#ifndef OCIXML_ORACLE
#include <ocixmldb.h>
#endif
#ifndef OCI_ORACLE
#include <oci.h>
#endif
#include <string.h>

typedef struct test_ctx {
OCIEnv *envhp;
OCIError *errhp;
OCISvcCtx *svchp;
OCIStmt *stmthp;
OCIServer *srvhp;
OCIDuration dur;
OCISession *sesshp;
oratext *username;
oratext *password;
} test_ctx;

...
void main()
{
test_ctx temp_ctx;
test_ctx *ctx = &temp_ctx;
OCIType *xmltdo = (OCIType *) 0;
xmldocnode *doc = (xmldocnode *)0;
ocixmldbparam params[1];
xmlnode *quux, *foo, *foo_data, *top;
xmlerr err;
sword status = 0;
xmlctx *xctx;
...
/* Initialize envhp, svchp, errhp, dur, stmthp */
...

/* Get an xml context */
params[0].name_ocixmldbparam = XCTXINIT_OCIDUR;
params[0].value_ocixmldbparam = &ctx->dur;
xctx = OCIXmlDbInitXmlCtx(ctx->envhp, ctx->svchp, ctx->errhp, params, 1);

/* Do unified C API operations next */
...

/* Free the statement handle using OCIHandleFree() */
...
/* Free the allocations associated with the context */
OCIXmlDbFreeXmlCtx(xctx);
/* Free envhp, svchp, errhp, stmthp */
...
}

OCIクライアントからバイナリXMLへのアクセス

中間層とクライアント層では、バイナリのXML形式でXMLを生成、消費および処理できます。Cアプリケーションでは、XML DBリポジトリからデータをフェッチし、DOMを使用してXMLの更新を実行し、データベースに格納します。または、クライアント上で作成または入力されたXML文書に対して、XSLT、XQueryおよび他のユーティリティを使用できます。その後、出力XMLはXML DBに保存されます。

クライアント・アプリケーションは、バイナリのXML文書のエンコードまたはデコード中にトークン定義、XMLスキーマおよびDTDをフェッチするために、メタデータ・リポジトリ(通常はバックエンド・データベース)への接続(メタデータ接続)を必要とします。

リポジトリ・コンテキストは、専用接続または接続プールを使用して初期化されます。リポジトリ・コンテキストから取得した接続を使用して、トークン定義やXMLスキーマなどのメタデータがフェッチされます。これに対して、アプリケーションには、データベースとの間でデータ(XMLデータなど)の通常の転送に使用するデータ接続もあります。リポジトリ・コンテキストは、(1つ以上の)データ接続に明示的に関連付けられています。データ接続を使用してデータベースとの間でXMLデータが読書きされる場合、基礎となるエンコードまたはデコード操作中に、該当するリポジトリ・コンテキストがアクセスされます。必要に応じて、リポジトリからメタデータをフェッチするためにメタデータ接続が使用されます。

OCIアプリケーションからXMLデータへのアクセス

Cアプリケーションでは、OCIを使用してデータベースに存在する永続XMLにアクセスし、統合XML C APIを使用してフェッチしたXMLデータを操作できます。

クライアント・アプリケーションでは、次のステップを実行します。

1. 通常のOCIハンドル(OCIEnv、OCISvcCtxおよびOCIErrorなど)を作成します。

2. バイナリのXMLメタデータをフェッチするためにリポジトリ・コンテキストを1つ以上作成します。

3. リポジトリ・コンテキストをデータ接続に関連付けます。

4. 変数をSELECT、INSERTおよびUPDATE文にバインドまたは定義します(xmldocnode)。

5. SELECT、INSERTまたはUPDATE文を実行して、XML文書をフェッチまたは格納します。この時点で、クライアントOCIライブラリがデータベース・バックエンドと相互作用し、必要なXMLスキーマ、DTD、トークン定義などをフェッチします。

6. 統合C APIを使用してXMLデータ(DOM)を操作します。

リポジトリ・コンテキスト

OCIBinXmlReposCtxは、リポジトリ・コンテキストのデータ構造です。クライアント・アプリケーションでは、メタデータ・リポジトリに接続情報を提供することで、このコンテキストを作成します。アプリケーションでは、複数のリポジトリ・コンテキストを作成して複数のトークン・リポジトリに接続できます。リポジトリ・コンテキストは、データ接続(OCISvcCtx)に明示的に関連付けられます。システムがデータ接続との間でデータをエンコードまたはデコードするためにメタデータをフェッチする必要がある場合は、該当するメタデータにアクセスします。

アプリケーションでは、OCIEnvごとに1つリポジトリ・コンテキストを作成することをお薦めします。これにより、マルチスレッド・アプリケーションの同時実行性が向上します。

リポジトリ・コンテキストは、専用OCI接続またはOCI接続プールから作成できます。

専用OCI接続からのリポジトリ・コンテキストの作成

OCIBinXmlCreateReposCtxFromConn()は、指定した専用OCI接続を使用してリポジトリ・コンテキストを作成します。OCI接続はメタデータ・アクセスでのみ使用されるため、アプリケーションの別のシナリオでは使用しないでください。また、この接続へのアクセスはシリアライズされています。つまり、複数のスレッドが同じ接続を使用しようとしている場合、アクセスは一度に1つのスレッドに制限されます。次の項で説明するように、スケーラビリティの理由により、アプリケーションでは接続プールを使用してリポジトリ・コンテキストを作成することをお薦めします。

注意: データに使用するのと同じ接続を渡すことも可能です。ただし、この場合、クライアント・システムがSELECTやINSERTのような別の操作の一部を実行する間にメタデータ・リポジトリに接続すると、特定の状況でエラーになる可能性があります。

接続プールからのリポジトリ・コンテキストの作成

OCIBinXmlCreateReposCtxFromCPool()では、接続プールからリポジトリ・コンテキストが作成されます。アプリケーションからバックエンド・リポジトリにアクセスする間に、プール内の使用可能接続が使用されます。さらに、この接続はメタデータ操作の完了直後にプールに解放されます。マルチスレッド・アプリケーションのシナリオには、接続プールを使用することをお薦めします。様々なスレッドがプール内の異なる接続を使用し、完了直後に解放できます。このアプローチでは、少数の物理接続で高度な拡張性と同時実行性が実現できます。

リポジトリ・コンテキストとデータ接続の関連付け

OCIBinXmlSetReposCtxForConn()では、リポジトリ・コンテキストがOCISvcCtx *により記述されたデータ接続に関連付けられます。複数のデータ接続で同じリポジトリ・コンテキストを共有できますが、リポジトリへのアクセスがシリアル化される可能性があります(専用接続ベースの場合)。システムがエンコードまたはデコード操作のためにメタデータをフェッチする必要がある場合は、OCIEnv、OCISvcCtxのペアから該当するリポジトリ接続を参照し、それを使用して必要なメタデータをフェッチします。

XMLTypeエンコーディング形式のプリファレンス設定

デフォルトでは、データベースに送信されたXMLデータは、ソース形式(DBから読取り済の場合)などの特定の内部基準に基づいて、可能な形式(テキスト、オブジェクト・リレーショナルまたはバイナリのXML)のいずれかでエンコードされます。OCIBinXmlSetFormatPref()は、エンコーディング形式のプリファレンスを設定する明示的なメカニズムを提供します。将来は、デフォルト形式をバイナリのXMLにできるようになりますが、この関数を使用すると必要に応じてデフォルト形式を上書きできます。

接続プールの使用例

XML DBのマニュアルに示したこの例で、接続プールからリポジトリ・コンテキストを作成してデータ接続に関連付ける方法を示します。データベースはローカルで、テストは単一スレッド・モードで実行されます。

関連項目:
Oracle XML DBによるXML用OCIおよびC APIの使用方法は、『Oracle XML DB開発者ガイド』を参照してください。

15 OCIでのObject Type Translatorの使用

この章では、Object Type Translator (OTT)について説明します。OTTを使用すると、データベース・オブジェクト型や名前付きコレクション型をC構造体にマップして、OCIアプリケーションで使用できます。

この章は、次の項目で構成されています。

- OTTの概要

- Object Type Translatorの使用方法

- OTTのコマンドライン

- intypeファイル

- OTTデータ型マッピング

- outtypeファイル

- OCIアプリケーションでのOTTの使用方法

- OTTリファレンス

OTTの概要

Object Type Translator (OTT)は、Oracleサーバーでユーザー定義型を使用するC言語アプリケーションを開発するのに役立ちます。

SQLのCREATE TYPE文を使用すると、オブジェクト型を作成できます。これらの型の定義をデータベースに格納しておき、データベースの表を作成するときに使用できます。これらの表を作成すると、OCIのプログラマは、表に格納されたオブジェクトにアクセスできます。

オブジェクト・データにアクセスするアプリケーションでは、データをホスト言語形式で表現する必要があります。これは、オブジェクト型をC構造体として表現することによって実現できます。プログラマがデータベース・オブジェクト・タイプを表す構造体宣言を、手入力でコーディングすることは可能ですが、多くの型がある場合、この作業は時間がかかり、エラーを生む原因になることも少なくありません。OTTでは、適切な構造体宣言を自動的に生成することにより、このような手動のコーディングをしなくて済むようにします。OCIのアプリケーションでは、OTTで生成された初期化関数をコールします。

OTTは、格納済のデータ型を表す構造体を作成するのみでなく、オブジェクト型またはそのフィールドがNULLかどうかを示すパラレル・インジケータ構造体も生成します。

Object Type Translatorの使用方法

Object Type Translator (OTT)は、オブジェクト型と名前付きコレクション型のデータベース定義を、OCIアプリケーションに組み込むことができるC構造体宣言に変換します。

OTTを明示的に起動し、データベース型をC表現に変換する必要があります。

ほとんどのオペレーティング・システムでは、コマンドラインからOTTを起動します。これは、intypeファイルを入力として受け取り、outtypeファイル、1つ以上のC言語のヘッダー・ファイルおよびオプションの実装ファイルを生成します。OTTを起動するコマンドの例を次に示します。

ott userid=scott intype=demoin.typ outtype=demoout.typ code=c hfile=demo.h\
initfile=demov.c

このコマンドで、OTTをユーザー名scottでデータベースに接続します。ユーザーはパスワードの入力を求められます。

実装ファイル(demov.c)には、変換済のユーザー定義型の情報を含む型バージョン表を初期化する関数を格納します。

この章の後の項で、各パラメータについて詳しく説明します。

demoin.typファイルの例

CASE=LOWER
TYPE emptype

demoout.typファイルの例

CASE = LOWER
TYPE SCOTT.EMPTYPE AS emptype
VERSION = "$8.0"
HFILE = demo.h

この例のdemoin.typファイルには、TYPEが前に付く変換対象の型(TYPE emptypeなど)があります。outtypeファイルの構造体は、intypeファイルに似ており、OTTで取得した情報が追加されます。

OTTによる変換が終了すると、ヘッダー・ファイルには、intypeファイルで指定した各型のC構造体表現と、各型に対応したNULLインジケータ構造体が入っています。たとえば、例15-1に示すように、intypeファイルにリストされたemployee型が定義されたとします。

例15-1 intypeファイルにリストされたemployeeオブジェクト型の定義

CREATE TYPE emptype AS OBJECT
(
name       VARCHAR2(30),
empno      NUMBER,
deptno     NUMBER,
hiredate   DATE,
salary     NUMBER
);

OTTで生成されたヘッダー・ファイル(demo.h)には、その他の項目の中に、例15-2に示すような宣言が含まれます。

例15-2 生成されたヘッダー・ファイルdemo.hの内容

struct emptype
{
OCIString * name;
OCINumber empno;
OCINumber deptno;
OCIDate   hiredate;
OCINumber salary;
};
typedef struct emptype emptype;

struct emptype_ind
{
OCIInd _atomic;
OCIInd name;
OCIInd empno;
OCIInd deptno;
OCIInd hiredate;
OCIInd salary;
};
typedef struct employee_ind employee_ind;

例15-3は、このコマンドで生成されたサンプルの実装ファイル(demov.c)に含まれている内容を示しています。

例15-3 demov.cファイルの内容

#ifndef OCI_ORACLE
#include <oci.h>
#endif

sword demov(OCIEnv *env, OCIError *err)
{
sword status = OCITypeVTInit(env, err);
if (status == OCI_SUCCESS)
status = OCITypeVTInsert(env, err,
"HR", 2,
"EMPTYPE", 7,
"$8.0", 4);
return status;
}

このintypeファイルのパラメータにより、生成した構造体に名前を付ける方法を制御します。この例では、構造体名emptypeが、データベース型名emptypeに一致しています。intypeファイル内の行CASE=lowerに従って、構造体名は小文字にします。

構造体宣言(OCIStringやOCIIndなど)のデータ型は、特殊なデータ型です。

関連項目:
これらの型の詳細は、「OTTデータ型マッピング」を参照してください。

この章の残りの各項では、OCIでのOTTの使用方法を説明します。その後に続く参照の項では、コマンドライン構文、パラメータ、intypeファイルの構造、ネストした#includeファイルの生成、スキーマ名の使用方法、デフォルトの名前マッピングおよび制限事項を説明します。

データベースでの型の作成

OTTを使用するときの最初のステップは、オブジェクト型または名前付きコレクション型を作成してデータベースに格納することです。そのためには、SQLのCREATE TYPE文を使用します。

関連項目:
CREATE TYPE文の詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

OTTの起動

OTTを起動するステップは、次のとおりです。OTTパラメータは、コマンドラインで、または構成ファイルをコールしたファイルで指定できます。一部のパラメータは、intypeファイルでも指定できます。

1つのパラメータが複数箇所に指定されている場合は、コマンドラインのパラメータ値がintypeファイルの値より優先され、intypeファイルの値はユーザー定義の構成ファイルの値より優先され、ユーザー定義の構成ファイルの値は、デフォルトの構成ファイルの値より優先されます。

グローバル・オプション、つまり、コマンドラインのオプションまたはintypeファイルのTYPE文の前のオプションについては、intypeファイルの値がコマンドラインの値で上書きされます。(intypeファイルでグローバルとして指定できるオプションには、CASE、CODE、INITFILEおよびINITFUNCがあります。HFILEは含まれません。)TYPEを指定するintypeファイルのオプションは、特定の型にのみ適用されます。その型に適用される、コマンドラインで指定したそれ以外のオプションは上書きされます。TYPE person HFILE=p.hと入力した場合、オプションはpersonにのみ適用され、コマンドラインのHFILEは上書きされます。文はコマンドライン・パラメータとはみなされません。

コマンドライン

コマンドラインに設定されたパラメータ(オプションとも呼ばれます)は、他で設定されたパラメータを上書きします。

関連項目:
「OTTのコマンドライン」

構成ファイル

構成ファイルは、OTTパラメータが入っているテキスト・ファイルです。ファイル内の非空白行には、1つのパラメータと、それに対応付けられた1つ以上の値が入っています。1行に2つ以上のパラメータを指定した場合は、最初のパラメータのみが使用されます。構成ファイルの非空白行では、空白は使用できません。

構成ファイルは、コマンドラインで名前を付けることができます。さらに、デフォルトの構成ファイルは常に読み取られます。このデフォルトの構成ファイルは常に存在している必要がありますが、空でもかまいません。デフォルトの構成ファイルの名前はottcfg.cfgであり、構成ファイルの位置はシステム固有の設定です。たとえば、Solarisでのファイル指定は、$ORACLE_HOME/precomp/admin/ottcfg.cfgです。詳細は、使用しているオペレーティング・システムのマニュアルを参照してください。

INTYPEファイル

intypeファイルには、OTTが変換するユーザー定義型のリストが指定されています。

パラメータのCASE、HFILE、INITFUNCおよびINITFILEは、intypeファイルに含めることができます。

関連項目:
「intypeファイル」

OTTのコマンドライン

ほとんどのオペレーティング・システムでは、コマンドラインからOTTを起動します。入出力ファイルやデータベース接続情報などを指定できます。OTTの起動方法は、使用しているオペレーティング・システム固有のマニュアルを参照してください。

関連項目:
「Object Type Translator for Windowsの使用」

OTTコマンドライン起動の例

例15-4は、コマンドラインからのOTTの起動方法を示しています。

例15-4 コマンドラインからのOTTの起動

ott userid=bren intype=demoin.typ outtype=demoout.typ code=c \
hfile=demo.h initfile=demov.c

注意:
等号(=)の両側には空白を挿入しないでください。

次の各項では、この例で使用しているコマンドラインの要素を説明します。

関連項目:
様々なOTTコマンドライン・オプションの詳細は、「OTTリファレンス」を参照してください。

OTT

OTTを起動します。必ずコマンドラインの先頭に置きます。

USERID

OTTが使用するデータベース接続情報を指定します。

例15-4では、OTTはユーザー名brenで接続し、その後、そのパスワードの入力が求められます。

INTYPE

使用するintypeファイルの名前を指定します。

例15-4では、intypeファイルの名前がdemoin.typに指定されています。

OUTTYPE

outtypeファイルの名前を指定します。OTTでCヘッダー・ファイルを生成すると、変換された型の情報がouttypeファイルに書き込まれます。このファイルには、変換された各型のエントリが、バージョン文字列およびC表現を書き込んだヘッダー・ファイルとともに含まれています。

例15-4では、outtypeファイルの名前がdemoout.typに指定されています。

注意:
outtypeのキーワードで指定されたファイルが存在している場合、そのファイルは、OTTが実行されると上書きされます。outtypeファイル名とintypeファイル名が同じ場合は、outtypeファイル内の情報でintypeファイルが上書きされます。

CODE

変換の目標言語を指定します。次のオプションがあります。

- C (ANSI_Cと等価)

- ANSI_C (ANSI C対応)

- KR_C (Kernighan & Ritchie C対応)

現在はデフォルト・オプションがないため、このパラメータは必須です。

構造体の宣言は、両方のC言語において同一です。INITFILEファイルに定義されている初期化関数のスタイルは、KR_Cが使用されているかどうかによって異なります。INITFILE オプションが使用されていない場合、3つのオプションはすべて等価です。

HFILE

生成された構造体を書き込むCヘッダー・ファイルの名前を指定します。

例15-4では、生成される構造体はdemo.hと呼ばれるファイルに格納されます。

注意:
キーワードhfileで既存のファイルを指定した場合は、OTTの実行時に上書きされますが、次のように例外が1つあります。OTTで生成されたファイルの内容がそのファイルの前の内容と同一の場合、OTTはそのファイルに実際には書き込みません。これにより、ファイルの変更時間を節約でき、LinuxおよびUNIXのmakeおよび他のオペレーティング・システムでの類似機能で、不必要な再コンパイルが実行されません。

INITFILE

型の初期化関数が格納されるCソース・ファイルの名前を指定します。

注意:
キーワードinitfileで既存のファイルを指定した場合は、OTTの実行時に上書きされますが、次のように例外が1つあります。OTTで生成されたファイルの内容がそのファイルの前の内容と同一の場合、OTTはそのファイルに実際には書き込みません。これにより、ファイルの変更時間を節約でき、LinuxおよびUNIXのmakeおよび他のオペレーティング・システムでの類似機能で、不必要な再コンパイルが実行されません。

intypeファイル

OTTの実行時に、intypeファイルはどのデータベース型の変換が必要であるかをOTTに指示します。また、このファイルを使用して、生成される構造体の命名方法も指定できます。intypeファイルは、ユーザー作成ファイルでも、前回OTTを起動したときのouttypeファイルでもかまいません。intypeパラメータが使用されていない場合は、OTTの接続先のスキーマにあるすべての型が変換されます。

例15-5は、簡単なユーザー作成intypeファイルを示しています。

例15-5 ユーザー作成intypeファイルの内容

CASE=LOWER
TYPE employee
TRANSLATE SALARY$ AS salary
DEPTNO AS department
TYPE ADDRESS
TYPE item
TYPE "Person"
TYPE PURCHASE_ORDER AS p_o

例15-5の詳細な説明は次のようになります。

第1行のCASEキーワードは、生成されたC識別子を小文字にすることを指示しています。ただし、このCASEオプションは、intypeファイルに明示的に記述されていない識別子にのみ適用されます。そのため、常にemployeeはemployee、ADDRESSはADDRESSというC構造体になります。これらの構造体のメンバーは、小文字で名前が付けられます。

関連項目:
「CASE」

TYPEキーワードで始まる行で、データベース内の変換する型を指定します。この例では、employee、ADDRESS、item、PersonおよびPURCHASE_ORDERの各型が相当します。

TRANSLATE...ASキーワードは、オブジェクト型のC構造体への変換時に、オブジェクト属性の名前変更が必要なことを指定しています。この例では、employee型のSALARY$属性がsalaryに変換されます。

最終行のASキーワードは、オブジェクト型を構造体に変換するとき、名前を変更することを指定しています。この例では、PURCHASE_ORDERというデータベース型をp_oという構造体に変換します。

ASを使用して型や属性名を変換しなければ、その型や属性のデータベース名がC言語の識別子名として使用されます。ただし、CASEオプションを指定した場合、有効なC言語の識別子文字にマップできない文字は、アンダースコアに置換されます。型または属性名を変換する理由は、次のとおりです。

- 名前に、アルファベット、数字またはアンダースコア以外の文字が含まれている

- 名前がCキーワードと競合する。

- 型名が、同じ有効範囲内の別の識別子と競合する。たとえば、プログラムで、異なるスキーマにある同じ名前の2つの型を使用する場合に発生します。

- プログラマが別の名前に変更する。

OTTでは、intypeファイルにリストされていない他の型の変換が必要になる場合があります。これは、OTTでは変換前にintypeファイル内の型の依存性が分析され、必要に応じてその他の型が変換されるためです。たとえば、ADDRESS型がintypeファイルにリストされていなくても、Person型がADDRESS型の属性を所有している場合、Person型の定義は必須のため、OTTは、ADDRESSを変換します。

TRANSITIVEパラメータの値としてFALSEを指定すると、OTTは、intypeファイルに指定されていない型は生成しません。

通常の大/小文字の区別がないSQL識別子は、intypeファイルでは、大/小文字のどのような組合せのつづりでもかまいません。また、引用符で囲みません。

CREATE TYPE "Person"などの大/小文字を区別して作成したSQL識別子を参照するには、TYPE "Person"などの引用符を使用します。SQL識別子は、宣言の際に引用符で囲んだ場合は、大/小文字が区別されます。引用符は、TYPE "CASE"などのOTT予約語であるSQL識別子の参照にも使用できます。そのため、名前を引用符で囲むときは、そのSQL識別子がCREATE TYPE Caseのように大/小文字を区別せずに作成されている場合、引用符で囲む名前は大文字にする必要があります。OTT予約語がSQL識別子の名前参照用に使用されているが、引用符で囲まれていない場合、OTTはintypeファイルに構文エラーをレポートします。

関連項目:
intypeファイルの構造体の指定と使用可能なオプションの詳細は、「intypeファイルの構造体」を参照してください。

OTTデータ型マッピング

OTTでデータベース型から生成したC構造体には、オブジェクト型の属性ごとに1つずつ対応する要素が含まれています。属性のデータ型は、Oracleのオブジェクト・データ型で使用される型にマップされます。Oracle Databaseのデータ型には、事前定義済の基本型の集合が組み込まれています。これらのデータ型は、オブジェクト型やコレクションなどのユーザー定義型の作成をサポートします。

また、Oracle Databaseには、オブジェクト型属性をC構造体で表現するための事前定義済の型の集合も含まれています。たとえば、例15-6のようなオブジェクト型定義と、例15-7のようなOTTで生成した対応する構造体宣言があるとします。

例15-6 従業員用のオブジェクト型定義

CREATE TYPE employee AS OBJECT
(   name       VARCHAR2(30),
empno      NUMBER,
deptno     NUMBER,
hiredate   DATE,
salary$    NUMBER);

CASE=LOWERで、型または属性名の明示的なマッピングがないと仮定すると、OTT出力は例15-7のようになります。

例15-7 OTTで生成した構造体宣言

struct employee
{   OCIString * name;
OCINumber empno;
OCINumber deptno;
OCIDate   hiredate;
OCINumber salary_;
};
typedef struct emp_type emp_type;
struct employee_ind
{
OCIInd _atomic;
OCIInd name;
OCIInd empno;
OCIInd deptno;
OCIInd hiredate;
OCIInd salary_;
}
typedef struct employee_ind employee_ind;

関連項目:
インジケータの構造体(struct employee_ind)の説明は、「NULLインジケータ構造体」を参照してください。

ここでは、構造体宣言のデータ型、OCIString、OCINumber、OCIDateおよびOCIIndを使用してオブジェクト型の属性のデータ型をマップしています。たとえば、empno属性のNUMBERデータ型は、OCINumberデータ型にマップされます。また、これらのデータ型は、バインド変数および定義変数の型としても使用できます。

オブジェクト・データ型のCへのマッピング

この項では、Oracleのオブジェクト属性型とOTTで生成されるCの型とのマッピングを説明します。「OTT型マッピングの例」では、様々なマッピングの例を示します。表15-1は、属性として使用できる型から、OTTで生成されるオブジェクト・データ型へのマッピングをリストしています。

表15-1 オブジェクト型属性のオブジェクト・データ型マッピング

オブジェクト属性の型

Cマッピング

BFILE

OCIBFileLocator*

BLOB

OCILobLocator *またはOCIBlobLocator *

CHAR(N)、CHARACTER(N)、NCHAR(N)

OCIString *

CLOB、NCLOB

OCILobLocator *またはOCIClobLocator *

DATE

OCIDate

ANSI DATE

OCIDateTime *

TIMESTAMP、TIMESTAMP WITH TIME ZONE、TIMESTAMP WITH LOCAL TIME ZONE

OCIDateTime *

INTERVAL YEAR TO MONTH、INTERVAL DAY TO SECOND

OCIInterval *

DEC、DEC(N)、DEC(N,N)

OCINumber

DECIMAL、DECIMAL(N)、DECIMAL(N,N)

OCINumber

FLOAT、FLOAT(N)、DOUBLE PRECISION

OCINumber

BINARY_FLOAT

float

BINARY_DOUBLE

double

INT、INTEGER、SMALLINT

OCINumber

ネストしたオブジェクト型

ネストしたオブジェクト型のCの名前

NESTED TABLE

OCITable *

NUMBER、NUMBER(N)、NUMBER(N,N)

OCINumber

NUMERIC、NUMERIC(N)、NUMERIC(N,N)

OCINumber

RAW(N)

OCIRaw *

REAL

OCINumber

REF

OCIRef *

VARCHAR(N)

OCIString *

VARCHAR2(N)、NVARCHAR2(N)

OCIString *

VARRAY

OCIArray *

注意:
REF、VARRAYおよびNESTED TABLE型の場合、OTTでは、typedefが生成されます。このtypedefで宣言された型は、構造体宣言でデータ・メンバーの型として使用されます。例は、「OTT型マッピングの例」を参照してください。

オブジェクト型にREFまたはコレクション型の属性が含まれている場合は、最初にREFまたはコレクション型のtypedefが生成されます。次に、オブジェクト型に対応する構造体宣言が生成されます。構造体には、REFまたはコレクション型へのポインタを型に持つ要素が含まれます。

あるオブジェクト型に、別のオブジェクト型を持つ属性が含まれている場合、OTTではネストした型が最初に生成されます(TRANSITIVE=TRUEの場合)。次に、オブジェクト型属性が、ネストしたオブジェクト型である型のネストした構造体にマッピングされます。

OTTがオブジェクト以外のデータベース属性の型をマップするOracleのCデータ型は構造体で、OCIDate以外は不透明です。

OTT型マッピングの例

例15-9は、例15-8に示すデータベース型の指定時に、OTTで作成される各種の型のマッピングを示しています。

例15-8 OTT型マッピング用のオブジェクト型定義の例

CREATE TYPE my_varray AS VARRAY(5) of integer;

CREATE TYPE object_type AS OBJECT
(object_name    VARCHAR2(20));

CREATE TYPE my_table AS TABLE OF object_type;

CREATE TYPE other_type AS OBJECT (object_number NUMBER);

CREATE TYPE many_types AS OBJECT
( the_varchar    VARCHAR2(30),
the_char       CHAR(3),
the_blob       BLOB,
the_clob       CLOB,
the_object     object_type,
another_ref    REF other_type,
the_ref        REF many_types,
the_varray     my_varray,
the_table      my_table,
the_date       DATE,
the_num        NUMBER,
the_raw        RAW(255));

intypeファイルには次が含まれています。

CASE = LOWER
TYPE many_types

OTTでは、例15-9に示すようなC構造体が生成されます。

注意:
例15-9では、構造体についての補足説明として、コメントを付けています。これらのコメントは、実際のOTT出力の一部ではありません。

例15-9 オブジェクト型定義からOTTで作成される各種の型のマッピング

#ifndef MYFILENAME_ORACLE
#define MYFILENAME_ORACLE

#ifndef OCI_ORACLE
#include <oci.h>
#endif

typedef OCIRef many_types_ref;
typedef OCIRef object_type_ref;
typedef OCIArray my_varray;            /* used in many_types */
typedef OCITable my_table;             /* used in many_types*/
typedef OCIRef other_type_ref;
struct object_type                     /* used in many_types */
{
OCIString * object_name;
};
typedef struct object_type object_type;

struct object_type_ind               /*indicator struct for*/
{                                            /*object_types*/
OCIInd _atomic;
OCIInd object_name;
};
typedef struct object_type_ind object_type_ind;

struct many_types
{
OCIString *        the_varchar;
OCIString *        the_char;
OCIBlobLocator *   the_blob;
OCIClobLocator *   the_clob;
struct object_type the_object;
other_type_ref *   another_ref;
many_types_ref *   the_ref;
my_varray *        the_varray;
my_table *         the_table;
OCIDate            the_date;
OCINumber          the_num;
OCIRaw *           the_raw;
};
typedef struct many_types many_types;

struct many_types_ind                  /*indicator struct for*/
{                                               /*many_types*/
OCIInd _atomic;
OCIInd the_varchar;
OCIInd the_char;
OCIInd the_blob;
OCIInd the_clob;
struct object_type_ind the_object;              /*nested*/
OCIInd another_ref;
OCIInd the_ref;
OCIInd the_varray;
OCIInd the_table;
OCIInd the_date;
OCIInd the_num;
OCIInd the_raw;
};
typedef struct many_types_ind many_types_ind;

#endif

intypeファイルでは変換対象として1つの項目しか指定していませんが、2つのオブジェクト型と2つの名前付きコレクション型が変換されていることに注意してください。これは、OTTパラメータ「TRANSITIVE」のデフォルト値がTRUEのためです。前述の項で説明しているとおり、TRANSITIVE=TRUEの場合、OTTは、リストされている型の変換を完了するために、変換対象の型の属性に使用されている型をすべて自動的に変換します。

この自動変換は、オブジェクト型属性のポインタまたはREFによってのみアクセスされる型には適用されません。たとえば、many_types型には属性としてanother_ref REF other_typeがありますが、struct other_typeは生成されません。

この例では、VARRAY、NESTED TABLEおよびREFの各型を宣言するために、typedefがどのように使用されているかも示しています。

typedefは、始めに使用されます。

typedef OCIRef many_types_ref;
typedef OCIRef object_type_ref;
typedef OCIArray my_varray;
typedef OCITable my_table;
typedef OCIRef other_type_ref;

構造体many_typesでは、次のようにVARRAY、NESTED TABLEおよびREFの各属性が宣言されています。

struct many_types
{  ...
other_type_ref *   another_ref;
many_types_ref *   the_ref;
my_varray *        the_varray;
my_table *         the_table;
...
}

NULLインジケータ構造体

OTTでデータベース・オブジェクト・タイプを表現するC構造体が生成されるたびに、対応するNULLインジケータ構造体も生成されます。C構造体にオブジェクト型を選択するとき、パラレル構造体の中にNULLインジケータ情報を選択できます。

たとえば、例15-9では、次のNULLインジケータ構造体が生成されます。

struct many_types_ind
{
OCIInd _atomic;
OCIInd the_varchar;
OCIInd the_char;
OCIInd the_blob;
OCIInd the_clob;
struct object_type_ind the_object;
OCIInd another_ref;
OCIInd the_ref;
OCIInd the_varray;
OCIInd the_table;
OCIInd the_date;
OCIInd the_num;
OCIInd the_raw;
};
typedef struct many_types_ind many_types_ind;

NULLインジケータ構造体のレイアウトは重要です。構造体の第1要素(_atomic)は、アトミックNULLインジケータです。この値は、オブジェクト型全体のNULL状態を示します。このアトミックNULLインジケータの後に、OTTで生成した、オブジェクト型を表現する構造体の各要素に対応するインジケータ要素が続きます。

あるオブジェクト型の定義の一部として別のオブジェクト型が含まれている場合(この例ではobject_type属性)、その属性のインジケータ・エントリは、ネストしたオブジェクト型(TRANSITIVE=TRUEの場合)に対応しているNULLインジケータ構造体(object_type_ind)です。

VARRAYとNESTED TABLEには、各要素のNULL情報が含まれています。

NULLインジケータ構造体のその他の要素のデータ型は、すべてOCIIndです。

関連項目:
アトミックNULLの詳細は、「NULLインジケータ構造体」を参照してください。

OTTによる型の継承のサポート

オブジェクトの型の継承をサポートするために、OTTは、新しい属性を宣言する前に、継承される属性を、特別な名前_superを持つカプセル化された構造体内で宣言することで、オブジェクトのサブタイプを表すC構造体を生成します。これによって、スーパータイプを継承するオブジェクトのサブタイプについては、その構造体の第1要素が_superと命名され、サブタイプの各属性に対応する要素がその後に続きます。この_superと命名された要素の型がスーパータイプの名前です。

たとえば、例15-10に示すように、サブタイプStudent_tとEmployee_tを持つPerson_t型があるとします。

例15-10 オブジェクト型とサブタイプの定義

CREATE TYPE Person_t AS OBJECT
( ssn     NUMBER,
name    VARCHAR2(30),
address VARCHAR2(100)) NOT FINAL;

CREATE TYPE Student_t UNDER Person_t
( deptid NUMBER,
major  VARCHAR2(30)) NOT FINAL;

CREATE TYPE Employee_t UNDER Person_t
( empid NUMBER,
mgr   VARCHAR2(30));

また、例15-11に示す内容のintypeファイルもあるとします。

例15-11 intypeファイルの内容

CASE=SAME
TYPE EMPLOYEE_T
TYPE STUDENT_T
TYPE PERSON_T

例15-12に示すように、OTTでは、Person_t、Student_tおよびEmployee_tに対するC構造体とそれぞれのNULLインジケータ構造体が生成されます。

例15-12 OTTによる型に対するC構造体とNULLインジケータ構造体の生成

#ifndef MYFILENAME_ORACLE
#define MYFILENAME_ORACLE

#ifndef OCI_ORACLE
#include <oci.h>
#endif

typedef OCIRef EMPLOYEE_T_ref;
typedef OCIRef STUDENT_T_ref;
typedef OCIRef PERSON_T_ref;

struct PERSON_T
{
OCINumber SSN;
OCIString * NAME;
OCIString * ADDRESS;
};
typedef struct PERSON_T PERSON_T;

struct PERSON_T_ind
{
OCIInd _atomic;
OCIInd SSN;
OCIInd NAME;
OCIInd ADDRESS;
};
typedef struct PERSON_T_ind PERSON_T_ind;

struct EMPLOYEE_T
{
PERSON_T_ind;
OCINumber EMPID;
OCIString * MGR;
};
typedef struct EMPLOYEE_T EMPLOYEE_T;

struct EMPLOYEE_T_ind
{
PERSON_T _super;
OCIInd EMPID;
OCIInd MGR;
};
typedef struct EMPLOYEE_T_ind EMPLOYEE_T_ind;

struct STUDENT_T
{
PERSON_T _super;
OCINumber DEPTID;
OCIString * MAJOR;
};
typedef struct STUDENT_T STUDENT_T;

struct STUDENT_T_ind
{
PERSON_T _super;
OCIInd DEPTID;
OCIInd MAJOR;
};
typedef struct STUDENT_T_ind STUDENT_T_ind;

#endif

前述のCマッピング変換によって、サブタイプのインスタンスからCのスーパータイプのインスタンスへのアップキャストが簡単かつ適切に行われます。たとえば、次のようにします。

STUDENT_T *stu_ptr = some_ptr;               /* some STUDENT_T instance  */
PERSON_T  *pers_ptr = (PERSON_T *)stu_ptr;   /* upcasting */

同様に、NULLインジケータ構造体が生成されます。スーパータイプPerson_tのNULLインジケータ構造体の最初の要素は_atomicで、サブタイプEmployee_tおよびStudent_tのNULLインジケータ構造体の最初の要素は_superであることに注意してください(サブタイプの場合、アトミック要素は生成されません)。

置換可能なオブジェクト属性

NOT FINAL型の属性(置換可能な属性)の場合、埋込み属性は、ポインタとして表現されます。

次のBook_t型を想定します。

CREATE TYPE Book_t AS OBJECT
( title   VARCHAR2(30),
author  Person_t     /* substitutable */);

OTTで生成された対応するC構造体には、Person_tへのポインタが含まれています。

struct Book_t
{
OCIString  *title;
Person_t   *author;    /* pointer to Person_t struct */
}

この型に対応するNULLインジケータ構造体は、次のとおりです。

struct Book_t_ind
{
OCIInd  _atomic;
OCIInd  title;
OCIInd  author;
}

author属性に対応するNULLインジケータ構造体は、authorオブジェクト自体から取得できます。「OCIObjectGetInd()」を参照してください。

型がFINALに定義されている場合、サブタイプは使用できません。したがって、FINAL型の属性は置換できません。その場合、マッピングは前述のとおりになり、属性構造体はインラインです。型が変更され、NOT FINALに定義される場合は、マッピングを変更する必要があります。新しいマッピングは、OTTを再実行すると生成されます。

outtypeファイル

outtypeファイルは、OTTコマンドラインで名前が付けられます。OTTでCヘッダー・ファイルが生成されると、変換の結果がouttypeファイルに書き込まれます。このファイルには、変換された各型のエントリが、バージョン文字列およびC表現を書き込んだヘッダー・ファイルとともに含まれています。

OTTの1回の実行で生成されたouttypeファイルは、それ以降のOTTの起動ではintypeファイルとして使用できます。

たとえば、例15-13に示すように、例15-5で使用した簡単なintypeファイルがあるとします。

例15-13 intypeファイルの内容

CASE=LOWER
TYPE employee
TRANSLATE SALARY$ AS salary
DEPTNO AS department
TYPE ADDRESS
TYPE item
TYPE "Person"
TYPE PURCHASE_ORDER AS p_o

この例では、OTTで生成するC識別子の大/小文字の区別を指定し、変換する型をリストして指定しています。そのうち2つの型については、ネーミング規則が指定されています。

例15-14は、OTT実行後のouttypeファイルを示しています。

例15-14 OTT実行後のouttypeファイルの内容

CASE = LOWER
TYPE EMPLOYEE AS employee
VERSION = "$8.0"
HFILE = demo.h
TRANSLATE SALARY$ AS salary
DEPTNO AS department
TYPE ADDRESS AS ADDRESS
VERSION = "$8.0"
HFILE = demo.h
TYPE ITEM AS item
VERSION = "$8.0"
HFILE = demo.h
TYPE "Person" AS Person
VERSION = "$8.0"
HFILE = demo.h
TYPE PURCHASE_ORDER AS p_o
VERSION = "$8.0"
HFILE = demo.h

outtypeファイルの内容を調べると、intype指定に含まれていなかった型がリストされていることに気づきます。たとえば、person型が次のように変換されることのみ指定されたintypeファイルがあるとします。

CASE = LOWER
TYPE PERSON

ただし、このperson型の定義にaddress型の属性が含まれているため、outtypeファイルには、PERSONとADDRESSの両方のエントリが含まれます。person型を完全に変換するには、最初にaddressを変換する必要があります。

パラメータTRANSITIVEがTRUEに設定されている(デフォルトの)場合、OTTは、変換を実行する前にintypeファイル内の型の依存性を分析してから、必要に応じて他の型を変換します。

OCIアプリケーションでのOTTの使用方法

Oracleサーバー内のオブジェクトにアクセスするOCIアプリケーションでは、OTTで生成したCヘッダー・ファイルと実装ファイルを使用できます。ヘッダー・ファイルは、#include文でOCIコードに取り込みます。

OCIアプリケーションでは、ヘッダー・ファイルを組み込んだ後、ホスト言語形式のオブジェクト・データにアクセスし、操作できます。

図15-1は、最も単純なアプリケーションのOCIでOTTを使用する場合のステップを示しています。

1. SQLを使用してデータベースに型定義を作成します。

2. OTTで、オブジェクト型と名前付きコレクション型のC表現を含むヘッダー・ファイルを生成します。INITFILEオプションで命名された実装ファイルも生成します。

3. アプリケーションを記述します。OCIアプリケーションでユーザーが記述したコードで、INITFUNC関数を宣言してコールします。

4. ヘッダー・ファイルをOCIソース・コード・ファイルにインクルードします。

5. OTTで生成された実装ファイルを含めて、OCIアプリケーションがコンパイルされ、OCIライブラリにリンクされます。

6. OCI実行可能ファイルをOracle Databaseに対して実行します。

図15-1 OCIアプリケーションでのOTTの使用方法

OCIでのオブジェクトへのアクセスおよび操作

アプリケーション内部では、OCIプログラムでバインド操作と定義操作を実行できます。そのためには、OTTで生成したヘッダー・ファイルに示されている型で宣言したプログラム変数を使用します。

たとえば、アプリケーションでSQLのSELECT文を使用して、オブジェクトへのREFをフェッチし、適切なOCI関数を使用してそのオブジェクトを確保します。オブジェクトを確保した後、その他のOCI関数を使用してそのオブジェクトの属性データにアクセスし、操作できます。

OCIには、オブジェクト型の属性と名前付きコレクション型で操作するために特別に設計された、一連のデータ型マッピング関数および操作関数が組み込まれています。

使用可能な関数の例を次に示します。

- OCIStringSize()は、OCIString文字列のサイズを取得します。

- OCINumberAdd()は、2つのOCINumberの数値を加算します。

- OCILobIsEqual()は、2つのLOBロケータが等しいかどうかを比較します。

- OCIRawPtr()は、ロー・データ型OCIRawへのポインタを取得します。

- OCICollAppend()は、コレクション型(OCIArrayまたはOCITable)に要素を追加します。

- OCITableFirst()は、ネストした表(OCITable)の最初の既存要素の索引を戻します。

- OCIRefIsNull()は、REF(OCIRef)がNULLかどうかをテストします。

これらの関数の詳細は、このマニュアルの他の章を参照してください。

初期化関数のコール

OTTは、必要に応じてC初期化関数を生成します。初期化関数では、プログラムで使用されている各オブジェクト型について、どのバージョンの型が使用されているかを環境に通知します。INITFUNCオプションでOTTを起動する場合は、初期化関数の名前を指定するか、初期化関数が含まれている実装ファイル(INITFILE)の名前に基づいてデフォルト名を選択できます。

初期化関数には、環境ハンドル・ポインタとエラー・ハンドル・ポインタの2つの引数があります。一般的に、使用する初期化関数は1つですが、必ずしもそうである必要はありません。プログラムにコンパイル済の個別のピースがあり、異なる型を要求する場合は、各ピースに対して初期化関数が含まれた1つの初期化ファイルをそれぞれ要求して、OTTを個別に実行できます。

たとえば、OCIEnvCreate()をコールして、明示的なOCIオブジェクト・コールによって環境ハンドルを作成した後は、初期化関数も明示的にコールする必要があります。明示的に作成した環境ハンドルそれぞれに対して、必ずすべての初期化関数をコールする必要があります。これによって、各ハンドルは、プログラム全体で使用しているすべてのOracleデータ型にアクセスできます。

EXEC SQL CONTEXT USEやEXEC SQL CONNECTなどの埋込みSQL文を使用して環境ハンドルを暗黙的に作成する場合、ハンドルは暗黙的に初期化されるため、初期化関数をコールする必要はありません。これは、Pro*C/C++をOCIアプリケーションと結合している場合にのみ適用します。

次に、初期化関数の例を示します。

例15-15に示すような内容を含むintypeファイル、ex2c.typがあるとします。

例15-15 ex2c.typという名前のintypeファイルの内容

TYPE BREN.PERSON
TYPE BREN.ADDRESS

例15-16に示すように、コマンドラインからOTTを起動し、初期化関数を指定します。

例15-16 OTTの起動と初期化関数の指定

ott userid=bren intype=ex2c outtype=ex2co hfile=ex2ch.h initfile=ex2cv.c

OTTでは、例15-17に示すような内容のex2cv.cファイルが生成されます。

例15-17 ex2cv.cという名前のOTTで生成したファイルの内容

#ifndef OCI_ORACLE
#include <oci.h>
#endif

sword ex2cv(OCIEnv *env, OCIError *err)
{
sword status = OCITypeVTInit(env, err);
if (status == OCI_SUCCESS)
status = OCITypeVTInsert(env, err,
"BREN", 5,
"PERSON", 6,
"$8.0", 4);
if (status == OCI_SUCCESS)
status = OCITypeVTInsert(env, err,
"BREN", 5,
"ADDRESS", 7,
"$8.0", 4);
return status;
}

関数ex2cvによって、型バージョン表が作成され、BREN.PERSON型とBREN.ADDRESS型が挿入されます。

プログラムで明示的に環境ハンドルを作成する場合、明示的に作成するハンドルごとに初期化関数をコールする必要があるので、すべての初期化関数を生成し、コンパイルし、リンクしてください。プログラムが明示的に環境ハンドルを作成しない場合、初期化関数は必要ありません。

OTTで生成したヘッダー・ファイルを使用するプログラムでは、同時に生成された初期化関数も使用する必要があります。OTTでヘッダー・ファイルを生成し、プログラムで環境ハンドルを明示的に作成した場合は、実装ファイルもコンパイルして、実行可能ファイルにリンクする必要があります。

初期化関数の作業

C初期化関数は、OTTで処理する型のバージョン情報を提供します。C初期化関数は、OTTで処理する各オブジェクト・データ型の名前とバージョン識別子を型バージョン表に追加します。

型バージョン表は、Oracle Databaseの型マネージャが、特定のプログラムで使用する型のバージョンを特定するときに使用します。異なる時期にOTTで生成した異なる複数の初期化関数によって、型バージョン表に同じ型が複数回追加される可能性があります。型が複数回追加される場合、Oracle Databaseでは、毎回同じバージョンの型が確実に登録されるようにします。

初期化関数に対して関数プロトタイプを宣言し、その関数をコールするのは、OCIプログラマの役割です。

注意:
Oracle Databaseのカレント・リリースでは、型ごとにバージョンは1つのみです。型バージョン表の初期化は、Oracle Databaseの今後のリリースとの互換性を保つためにのみ必要です。

OTTリファレンス

OTTコマンドラインまたはCONFIGファイルで指定できるパラメータは、OTTの動作を制御します。また、一部のパラメータは、intypeファイルにも指定できます。

この項では、次の項目について詳しく説明します。

- OTTコマンドラインの構文

- OTTパラメータ

- OTTパラメータの指定可能な場所

- intypeファイルの構造体

- ネストされたインクルード・ファイルの生成

- SCHEMA_NAMESの使用方法

- デフォルトの名前のマッピング

- OTTでのファイル名比較の制限事項

この項では、次の規則を使用してOTTの構文を説明します。

- イタリックの文字列は、ユーザーが指定する変数またはパラメータです。

- 大文字の文字列は、そのとおりに入力する文字列です。ただし、大/小文字は区別されないため、小文字で入力しても有効です。

- OTTキーワードは、例やヘッダーでは小文字の固定幅フォントでリストされていますが、本文では、目立つように大文字で印刷されています。

- 大カッコ[...]で囲んだ項目は、オプション項目です。

- 1つの項目(あるいはカッコで囲まれた複数の項目)の直後の省略記号(...)は、その項目を何度も繰り返し指定できることを示します。

- これ以外の句読点記号は、示されているとおりに入力します。「.」や「@」などが含まれます。

OTTコマンドラインの構文

OTTコマンドライン・インタフェースは、OTTを明示的に起動してデータベース型をC構造体に変換するときに使用します。オブジェクトを使用するOCIアプリケーションを開発する場合は、必ずこのインタフェースが必要です。

OTTコマンドライン文は、キーワードOTTと、その後に続くOTTパラメータのリストによって構成されます。

OTTコマンドライン文に指定できるパラメータは、次のとおりです。

[userid=username/password[@db_name]]

[intype=filename]

outtype=filename

code=C|ANSI_C|KR_C

[hfile=filename]

[errtype=filename]

[config=filename]

[initfile=filename]

[initfunc=filename]

[case=SAME|LOWER|UPPER|OPPOSITE]

[schema_name=ALWAYS|IF_NEEDED|FROM_INTYPE]

[transitive=TRUE|FALSE]

[URL=url]

注意:
一般に、OTTコマンドの後に続くパラメータの順序は重要ではありません。OUTTYPEおよびCODEの各パラメータのみは常に必須です。

HFILEパラメータは、ほとんどの場合に使用されます。コマンドラインから省略すると、HFILEをintypeファイルの型ごとに個別に指定する必要があります。OTTでは、intypeファイルにリストされていない型を変換する必要があると判断すると、エラーをレポートします。したがって、HFILEパラメータを省略できるのは、intypeファイルが以前にOTT outtypeファイルとして生成された場合にかぎります。

intypeファイルを省略すると、スキーマ全体が変換されます。詳細は、「OTTパラメータ」 のパラメータの説明を参照してください。

OTTコマンドライン文の例を次に示します(パスワードの入力を求められます)。

OTT userid=marc intype=in.typ outtype=out.typ code=c hfile=demo.h\
errtype=demo.tls case=lower

次の各項では、OTTコマンドラインの各パラメータについて説明します。

OTTパラメータ

OTTコマンドラインにパラメータを入力するときの書式は、次のとおりです。

parameter=value

この書式で、parameterはリテラル・パラメータ文字列であり、valueは有効なパラメータ設定値です。リテラル・パラメータ文字列は大/小文字を区別しません。

コマンドラインのパラメータは、空白またはタブのいずれかを使用して区切ります。

また、パラメータは構成ファイル内でも指定できます。ただし、この場合、行の中に空白を入れることはできないため、各パラメータは独立した行に指定する必要があります。さらに、パラメータCASE、HFILE、INITFUNCおよびINITFILEは、intypeファイルに入れることができます。

USERID

USERIDパラメータでは、データベース・ユーザー名、パスワードおよびオプションのデータベース名(Oracle Net Servicesのデータベース指定文字列)を指定します。データベース名を省略すると、デフォルトのデータベースが使用されます。このパラメータの構文は、次のとおりです。

userid=username/password[@db_name]

USERIDパラメータはオプションです。省略した場合、OTTは自動的にユーザーOPS$usernameでデフォルトのデータベースへの接続を試みます。ここで、usernameは、ユーザーのオペレーティング・システムのユーザー名です。これが最初のパラメータである場合、次に示すように、USERID=、パスワードおよびデータベース名を省略できます。

OTT username ...

セキュリティ上の問題から、ユーザー名を入力するときのみ残りの項目を入力するよう求められます。

INTYPE

INTYPEパラメータでは、オブジェクト型指定のリストの読取り元ファイルの名前を指定します。読み取ったリストにある型が、OTTによって変換されます。

このパラメータの構文は、次のとおりです。

intype=filename

"USERIDが第1パラメータ、INTYPEが第2パラメータで、USERID=を省略した場合は、INTYPE=も省略できます。INTYPEパラメータが指定されていない場合は、ユーザーのスキーマの型すべてが変換されます。

OTT username filename...

intypeファイルは、型宣言のmakefileと考えることができます。C構造体宣言の必要な型をリストします。

関連項目:
intypeファイルの書式の説明は、「intypeファイルの構造体」を参照してください。

コマンドラインまたはintypeファイルのファイル名に拡張子がない場合は、「TYP」や「.typ」などのオペレーティング・システム固有の拡張子が追加されます。

OUTTYPE

OUTTYPEパラメータは、OTTが処理するすべてのオブジェクト・データ型の型情報を書き込むファイルの名前を指定します。これには、intypeファイルで明示的に指定したすべての型が含まれます。さらに、変換対象である他の型の宣言で使用しているために変換された型が含まれる場合もあります(TRANSITIVE=TRUEの場合)。このファイルは、それ以後にOTTを起動するときにintypeファイルとして使用できます。

outtype=filename

INTYPEパラメータとOUTTYPEパラメータが同一のファイルを参照している場合、intypeファイルの古い情報は、新しいINTYPEパラメータの情報に置き換えられます。これは、型の変更から開始し、型宣言の生成、ソースコードの編集、プリコンパイル、コンパイル、デバッグに至るサイクルで、同一のintypeファイルを繰り返し使用するときに便利です。

パラメータOUTTYPEは必ず指定してください。

コマンドラインまたはouttypeファイルのファイル名に拡張子がない場合は、「TYP」や「.typ」などのオペレーティング・システム固有の拡張子が追加されます。

CODE

CODE=C、CODE=KR_CまたはCODE=ANSI_Cとして指定されるOTT出力の目的ホスト言語です。「CODE=C」は、「CODE=ANSI_C」と等価です。

CODE=C|KR_C|ANSI_C

このパラメータは、デフォルト値がないので必ず指定する必要があります。

INITFILE

INITFILEパラメータでは、OTTで生成した初期化ファイルを書き込むファイルの名前を指定します。このパラメータを省略すると、初期化関数は生成されません。

Pro*C/C++プログラムの場合、必要な初期化はSQLLIBランタイム・ライブラリによって実行されるため、INITFILEは不要です。OCIプログラムのユーザーは、INITFILEファイルをコンパイルおよびリンクし、環境ハンドルの作成時に初期化ファイル関数をコールする必要があります。

コマンドラインまたはintypeファイルで指定したINITFILEファイル名に拡張子がない場合は、「C」や「.c」などのオペレーティング・システム固有の拡張子が追加されます。

initfile=filename

INITFUNC

INITFUNCパラメータは、OCIプログラムのみで使用します。OTTで生成する初期化関数の名前を指定します。このパラメータを省略すると、INITFILEの名前から初期化関数の名前が付けられます。

initfunc=filename

HFILE

HFILEパラメータは、intypeファイルに記述した型の宣言でインクルード(.h)ファイルを指定しなかった場合に、OTTによって生成されるインクルード・ファイルの名前を指定します。intypeファイルで各型のインクルード・ファイルを個々に指定していない場合は、このパラメータが必要です。また、intypeファイルに記述していない型を、2つ以上の異なるファイルで宣言されている他の型で使用し、TRANSITIVE=TRUEの場合は、intypeファイルに記述していない型も生成する必要があります。そのような場合もこのパラメータが必要です。

コマンドラインまたはintypeファイルで指定したHFILEファイル名に拡張子がない場合は、「H」や「.h」などのオペレーティング・システム固有の拡張子が追加されます。

hfile=filename

CONFIG

CONFIGパラメータでは、共通で使用するパラメータ指定をリストしたOTT構成ファイルの名前を指定します。また、パラメータ指定は、オペレーティング・システムによって異なる位置にあるシステム構成ファイルから読み取られます。残りのすべてのパラメータ指定は、コマンドラインまたはintypeファイルで指定する必要があります。

config=filename

注意:
CONFIGパラメータは、CONFIGファイルでは使用できません。

ERRTYPE

ERRTYPEパラメータを指定すると、OTTでは、intypeファイルのリストが、すべての情報メッセージおよびエラー・メッセージとともにERRTYPEファイルに書き込まれます。情報メッセージおよびエラー・メッセージは、ERRTYPEパラメータを指定したかどうかに関係なく、標準出力に送信されます。

実質的に、ERRTYPEファイルはエラー・メッセージが追加されたintypeファイルのコピーです。ほとんどの場合、エラー・メッセージにはエラーの原因となったテキストへのポインタが示されます。

コマンドラインまたはintypeファイルで指定したERRTYPEファイル名に拡張子がない場合は、「TLS」や「.tls」などのオペレーティング・システム固有の拡張子が追加されます。

errtype=filename

CASE

CASEパラメータは、OTTで生成する一部のC識別子の大/小文字の区別に影響を与えます。CASEの可能な値は、SAME、LOWER、UPPERおよびOPPOSITEです。CASE = SAMEの場合は、データベース型と属性名をC識別子に変換するときに、大/小文字は変更されません。CASE=LOWERの場合、大文字はすべて小文字に変換されます。CASE=UPPERの場合、小文字はすべて大文字に変換されます。CASE=OPPOSITEの場合、大文字はすべて小文字に変換され、小文字はすべて大文字に変換されます。

CASE=[SAME|LOWER|UPPER|OPPOSITE]

このオプションは、intypeファイルに記述されていない識別子(明示的にリストされていない属性または型)のみに影響を与えます。大/小文字の変換は、正当な識別子が生成された後で行われます。

INTYPEパラメータ・オプションで指定した型のC構造体識別子の大/小文字は、intypeファイルの大/小文字と同じです。たとえば、intypeファイルに次の行が含まれるとします。

TYPE Worker

OTTでは次の行が生成されます。

struct Worker {...};

ただし、intypeファイルは次のように書き込まれるとします。

TYPE wOrKeR

その場合、intypeファイルで指定された大/小文字に続いて、OTTでは次の行が生成されます。

struct wOrKeR {...};

intypeファイルに記述されていない、大/小文字の区別のないSQL識別子は、CASE=SAME,の場合は大文字で、CASE=OPPOSITEの場合は小文字で指定されます。宣言されるとき引用符で囲まれていないSQL識別子の場合、大/小文字の区別はありません。

SCHEMA_NAMES

SCHEMA_NAMESパラメータは、デフォルト・スキーマに基づいた型のデータベース名を、outtypeファイル内のスキーマ名で修飾する場合に、制御を行います。OTTで生成したouttypeファイルには、型名も含めて、OTTで処理された型の情報が含まれています。

関連項目:
「SCHEMA_NAMESの使用方法」

TRANSITIVE

TRANSITIVEパラメータの値は、TRUE (デフォルト)またはFALSEのいずれかです。intypeファイルで明示的にリストされていない型の依存性が変換対象かどうかを示します。

TRANSITIVE=TRUEが指定されている場合は、他の型で必要でintypeファイルで記述されていない型が生成されます。

TRANSITIVE=FALSEが指定されている場合は、intypeファイルに指定されていない型は生成されません。生成した他の型の属性型として使用されている場合でも生成されません。

URL

URLパラメータの場合、OTTでは、JavaインタフェースであるJDBC (Java Database Connectivity)を使用してデータベースに接続します。URLパラメータのデフォルト値は次のとおりです。

URL=jdbc:oracle:oci8:@

OCI8ドライバは、Oracle Databaseのインストールでクライアント側で使用します。

JDBCシン・ドライバ(Oracle Databaseをインストールしない場合にクライアント側で使用するJavaドライバ)を指定するには、次のURLパラメータの構文を使用します。

URL=jdbc:oracle:thin:@host:port:sid

hostはデータベースが実行されているホストの名前、portはポート番号、sidはOracle SIDです。

OTTパラメータの指定可能な場所

OTTパラメータは、コマンドラインまたはコマンドラインで名前が付けられたCONFIGファイル、あるいはその両方で指定できます。パラメータの一部は、intypeファイルでも指定できます。

OTTは、次のように起動します。

OTT username/password parameters

コマンドラインのパラメータの1つが次のパラメータである場合、構成ファイルfilenameからその他のパラメータが読み取られます。

config=filename

さらに、パラメータは、オペレーティング・システムによって異なる位置にあるデフォルトの構成ファイルから読み取られます。このファイルの存在は必要ですが、空でもかまいません。構成ファイルのパラメータは、スペースなしで、1行につき1つ表示してください。

引数を指定せずにOTTを実行すると、オンライン・パラメータ・リファレンスが表示されます。

変換されるOTTの型は、INTYPEパラメータで指定したファイルで命名されます。パラメータのCASE、INITFILE、INITFUNCおよびHFILEは、intypeファイルに含めることもできます。OTTで生成したouttypeファイルにはCASEパラメータが含まれ、初期化ファイルが生成されている場合は、INITFILEおよびINITFUNCの各パラメータが含まれます。outtype ファイルでは、型ごとにそれぞれHFILEを指定します。

OTTコマンドの大/小文字区別は、オペレーティング・システムによって異なります。

intypeファイルの構造体

intypeおよびouttypeファイルは、OTTで変換する型をリストし、型名や属性名を有効なC識別子に変換する方法を判断するのに必要な情報すべてを提供します。これらのファイルには、1つ以上の型指定を記述します。また、次のオプションを指定する場合もあります。

- CASE

- HFILE

- INITFILE

- INITFUNC

CASE、INITFILEまたはINITFUNCの各オプションを指定する場合は、すべての型指定よりも前に指定する必要があります。これらのオプションをコマンドラインとintypeファイルの両方に指定した場合は、コマンドラインの値が使用されます。

関連項目:
簡単なユーザー定義のintypeファイルの例、およびintypeファイルからOTTで生成される完全なouttypeファイルの例は、「outtypeファイル」を参照してください。

intypeファイルの型指定

intypeファイルでの型指定によって、変換対象のオブジェクト・データ型の名前が指定されます。また、outtypeでの型指定によって、変換済のオブジェクト・データ型の名前が指定されます。

TYPE employee
TRANSLATE SALARY$ AS salary
DEPTNO AS department
TYPE ADDRESS
TYPE PURCHASE_ORDER AS p_o

型指定の構造体は次のとおりです。[]内の値は、オプションの入力を示します。

TYPE type_name [AS type_identifier]
[VERSION [=] version_string]
[HFILE [=] hfile_name]
[TRANSLATE{member_name [AS identifier]}...]

type_nameの構文は次のとおりです。

[schema_name.]type_name

この場合、schema_nameは、指定されたオブジェクト・データ型を所有するスキーマの名前で、type_nameはその型の名前です。デフォルト・スキーマは、OTTを実行するユーザーのスキーマです。デフォルト・データベースは、ローカル・データベースです。

型指定の構成要素を次に説明します。

- type_name - Oracle Databaseオブジェクト・データ型の名前です。

- type_identifier－ 型を表すのに使用するC識別子です。type_identifierを省略すると、デフォルトの名前マッピング・アルゴリズムが使用されます。

- version_stringは、OTTの以前の起動によってコードが生成されたときに使用された型のバージョン文字列です。バージョン文字列はOTTによって生成され、outtypeファイルに書き込まれます。このファイルは、後でOTTを実行するときにintypeファイルとして使用できます。バージョン文字列はOTTの操作には影響しませんが、最終的にこれを使用して、起動中のプログラムで使用されるオブジェクト・データ型のバージョンが選択されます。

関連項目:
「デフォルトの名前のマッピング」

- hfile_name - 該当する構造体の宣言またはクラスが現れるヘッダー・ファイルの名前です。hfile_nameを省略すると、宣言の生成時には、コマンドラインのHFILEパラメータで指定したファイルが使用されます。

- member_name - identifierに変換される属性(データ番号)の名前です。

- identifier－ ユーザーのプログラムで属性を表現するC識別子です。識別子は、任意の数の属性に対してこの方法で指定できます。指定していない属性については、デフォルトの名前マッピング・アルゴリズムが使用されます。

オブジェクト・データ型は、次のいずれかの場合に変換する必要があります。

- intypeファイルに指定されています。

- 変換が必要な別の型を宣言する場合、およびTRANSITIVE=TRUEの場合は必須です。

明示的に記述していない型があり、その型が、正確に1つのファイルのみに宣言した型で必要だとします。この場合、OTTでは、明示的に記述していない型の変換結果は、それを必要とする明示的に宣言した型と同じファイルに書き込まれます。

明示的に記述していない型が、複数の異なるファイルの型の宣言に必要な場合、OTTでは、この必須の型の変換結果は、グローバルなHFILEファイルに書き込まれます。

ネストされたインクルード・ファイルの生成

OTTで生成した各HFILEでは、#includeディレクティブを使用して、他の必要なファイルをインクルードし、#defineディレクティブを使用して、ファイル名から構成された記号を定義します。これは、HFILEがインクルードされているかどうかを判断するために使用できます。たとえば、データベースに例15-18に示すような型があるとします。

例15-18 OTTによるインクルード・ファイルの生成方法を示すオブジェクト型定義

create type px1 AS OBJECT (col1 number, col2 integer);
create type px2 AS OBJECT (col1 px1);
create type px3 AS OBJECT (col1 px1);

intypeファイルの内容を例15-19に示します。

例15-19 intypeファイルの内容

CASE=lower
type pxl
hfile tott95a.h
type px3
hfile tott95b.h

例15-20に示すコマンドを含むOTTを起動する場合、例15-21および例15-22に示すヘッダー・ファイルが生成されます。

例15-20 コマンドラインからのOTTの起動

ott scott tott95i.typ outtype=tott95o.typ code=c

ヘッダー・ファイルtott95b.hの内容を例15-21に示します。

例15-21 ヘッダー・ファイルtott95b.hの内容

#ifndef TOTT95B_ORACLE
#define TOTT95B_ORACLE
#ifndef OCI_ORACLE
#include <oci.h>
#endif
#ifndef TOTT95A_ORACLE
#include "tott95a.h"
#endif
typedef OCIRef px3_ref;
struct px3
{
struct px1 col1;
};
typedef struct px3 px3;
struct px3_ind
{
OCIInd _atomic;
struct px1_ind col1
};
typedef struct px3_ind px3_ind;
#endif

ヘッダー・ファイルtott95a.hの内容を例15-22に示します。

例15-22 ヘッダー・ファイルtott95a.hの内容

#ifndef TOTT95A_ORACLE
#define TOTT95A_ORACLE
#ifndef OCI_ORACLE
#include <oci.h>
#endif
typedef OCIRef px1_ref;
struct px1
{
OCINumber col1;
OCINumber col2;
}
typedef struct px1 px1;
struct px1_ind
{
OCIInd _atomic;
OCIInd col1;
OCIInd col2;
}
typedef struct px1_ind px1_ind;
#endif

例15-21では、TOTT95B_ORACLEという記号を最初に定義しています。そのため、プログラマは、例15-23に示すように、構造体を使用してtott95b.hを条件付きで組み込むことができます。その場合、tott95b.hがインクルード・ファイルに依存しているかどうかを考慮する必要はありません。

例15-23 ヘッダー・ファイルtott95b.hを条件付きで組み込むために使用する構造体

#ifndef TOTT95B_ORACLE
#include "tott95b.h"
#endif

この方法によって、プログラマは、適当なファイル (たとえばfoo.h)からtott95b.hを組み込むことができます。その際、tott95b.hが、foo.hに組み込まれるその他のファイルにも組み込まれるかどうかは、わかっていなくてもかまいません。

記号TOTT95B_ORACLEの定義の後に、ファイルoci.hがインクルードされます。OTT生成のすべてのHFILEには、Pro*C/C++やOCIのプログラマに役立つ型と関数の宣言が含まれたoci.hがインクルードされます。OTTが#includeディレクティブに山カッコを使用するのは、この場合のみです。

次に、ファイルtott95a.hを組み込みます。このファイルを組み込む理由は、tott95b.hに必要な「struct px1」の宣言が入っているからです。ユーザーのintypeファイルで、1つ以上のファイルに型宣言を書き込むように要求すると、OTTでは、他のファイルのうちどれを各HFILEに組み込むかを判断し、必要な#includesディレクティブを生成します。

このOTTの#includeディレクティブで、引用符が使用されていることに注意してください。tott95b.hを組み込むプログラムをコンパイルするとき、tott95a.hの検索は、ソース・プログラムが検出された場所から始まり、それ以降は実装定義の検索規則に従います。この方法でtott95a.hを検索できない場合、intypeファイルでtott95a.hの位置を指定するには、完全なファイル名(/で始まるLinuxまたはUNIXの絶対パス名など)を使用する必要があります。

SCHEMA_NAMESの使用方法

このパラメータは、OTTが接続されたデフォルト・スキーマに基づいて付けた型の名前を、outtypeファイル内のスキーマ名で修飾するかどうかを決定します。

デフォルト・スキーマ以外のスキーマに基づいて付けた型の名前は、常にouttypeファイル内のスキーマ名で修飾されます。

スキーマ名で修飾するかしないかで、プログラム実行中に型がどのスキーマで検索されるかが決定します。

次の3通りの設定があります。

- schema_names=ALWAYS (デフォルト)
outtypeファイル内のすべての型名をスキーマ名で修飾します。

- schema_names=IF_NEEDED
デフォルト・スキーマに所属しているOUTTYPEファイル内の型名はスキーマ名で修飾しません。デフォルト・スキーマ以外のスキーマに属する型名は、スキーマ名で修飾します。

- schema_names=FROM_INTYPE
intypeファイルに記述されている型は、intypeファイル内のスキーマ名で修飾されている場合にのみ、outtypeファイル内のスキーマ名で修飾されます。デフォルト・スキーマ内の型は、intypeファイル内で記述されていなくても型の依存性によって生成する必要がある場合にはスキーマ名付きで記述されます。これは、その型に依存する型としてOTTで最初に検出された型がスキーマ名付きで記述されていた場合にのみ行われます。ただし、OTTが接続しているデフォルト・スキーマにない型は、常に、明示的に指定したスキーマ名付きで記述されます。

OTT生成のouttypeファイルは、Pro*C/C++に対する入力パラメータです。Pro*C/C++の側から見ると、このファイルはPro*C/C++のintypeファイルです。このファイルは、データベース型名をC言語の構造体名に対応付けます。この情報は、構造体に対して正しいデータベース型が選択されるように実行時に使用されます。outtypeファイル(Pro*C/C++のintypeファイル)内のスキーマ名で型が指定される場合、その型はプログラムの実行中に名前付きスキーマ内で検出されます。型がスキーマ名なしで指定される場合、その型はプログラムの接続先となるデフォルト・スキーマ内で検出されます。このデフォルト・スキーマは、OTTで使用されたデフォルト・スキーマとは異なる場合があります。

例: Schema_Namesの使用方法

SCHEMA_NAMESにFROM_INTYPEを設定し、次のようにintypeファイルで読み取るとします。

TYPE Person
TYPE david.Dept
TYPE sam.Company

OTTで生成した構造体を使用して、Pro*C/C++アプリケーションでsam.Company、david.DeptおよびPersonの各型を使用します。スキーマ名のないPersonを使用して、アプリケーションを接続するスキーマのPerson型を表します。

OTTとアプリケーションの両方がスキーマdavidに接続する場合、アプリケーションは、OTTが使用した型と同じ型(david.Person)を使用します。OTTがスキーマdavidに接続し、アプリケーションがスキーマjanaに接続している場合、アプリケーションでは、jana.Person型を使用します。この動作が有効なのは、スキーマdavidとスキーマjanaで同じCREATE TYPE Person文が実行された場合のみです。

一方、アプリケーションでは、どのスキーマに接続するかに関係なくdavid.Dept型を使用します。この場合、intypeファイルに型名とともにスキーマ名を記述する必要があります。

明示的に指定していない型が、OTTによって変換される場合があります。たとえば、次のSQL宣言があるとします。

CREATE TYPE Address AS OBJECT
( street    VARCHAR2(40),
city      VARCHAR(30),
state     CHAR(2),
zip_code  CHAR(10) );

CREATE TYPE Person AS OBJECT
( name      CHAR(20),
age       NUMBER,
addr      ADDRESS );

OTTがスキーマdavidに接続され、SCHEMA_NAMES=FROM_INTYPEが指定されて、ユーザーのintypeファイルにTYPE PersonまたはTYPE david.Personのいずれかが組み込まれているとします。

ただし、intypeファイルには、david.Person型でネストしたオブジェクト型として使用されているdavid.Address型は記述されていません。intypeファイルにTYPE david.Personが指定されている場合は、TYPE david.PersonとTYPE david.Addressがouttypeファイルに指定されます。intypeファイルにType Personが指定されている場合は、TYPE PersonとTYPE Addressがouttypeファイルに指定されます。

OTTで変換された複数の型にdavid.Address型が埋め込まれていても、intypeファイルに明示的に記述されていない場合、スキーマ名を使用するかどうかは、埋め込まれているdavid.Address型がOTTで最初に検出された時点で決まります。なんらかの理由で、david.Address型にはスキーマ名を付け、一方のPerson型には付けない場合、ユーザーはintypeファイルで明示的に次を指定する必要があります。

TYPE      david.Address

各型を単一のスキーマ内に宣言する通常の場合は、すべての型名をintypeファイル内のスキーマ名で修飾するのが最も安全です。

デフォルトの名前のマッピング

OTTでオブジェクト型または属性のC識別子名を作成する場合、OTTは、その名前をデータベース・キャラクタ・セットから有効なC識別子に変換します。最初に、名前はデータベース・キャラクタ・セットからOTTで使用するキャラクタ・セットに変換されます。次に、その変換された名前の変換内容がintypeファイルに指定されている場合は、intypeファイルで指定された変換内容が使用されます。それ以外の場合、OTTではCASEオプションを適用して、その名前を文字ごとにコンパイラのキャラクタ・セットに変換します。次にこのプロセスの詳細を示します。

OTTによってデータベース・エンティティ名が読み込まれると、データベース・キャラクタ・セットからOTTで使用するキャラクタ・セットに自動的に変換されます。OTTがデータベース・エンティティ名を正常に読み込むには、その名前のすべての文字がOTTのキャラクタ・セット内で検出される必要があります。しかし、文字によっては2つのキャラクタ・セット間でエンコーディングが異なる場合があります。

必要な文字がOTTで使用するキャラクタ・セットにすべて含まれていることを保証するには、データベース・キャラクタ・セットと同じものを使用するのが最も簡単な方法です。ただし、OTTのキャラクタ・セットは、コンパイラのキャラクタ・セットのスーパーセットである必要があります。つまり、コンパイラのキャラクタ・セットが7ビットASCIIの場合、OTTのキャラクタ・セットはサブセットとして7ビットASCIIを含む必要があります。コンパイラのキャラクタ・セットが7ビットEBCDICの場合は、OTTのキャラクタ・セットはサブセットとして7ビットEBCDICを含む必要があります。OTTが使用するキャラクタ・セットをユーザーが指定するには、環境変数NLS_LANGを設定するか、またはオペレーティング・システム固有の他のメカニズムを使用します。

OTTがデータベース・エンティティの名前を読み取ると、その名前は、OTTで使用するキャラクタ・セットからコンパイラのキャラクタ・セットに変換されます。その名前の変換内容がintypeファイルで指定されている場合、OTTはその変換内容を使用します。

それ以外の場合、OTTでは、次の手順で名前の変換を行います。

1. OTTのキャラクタ・セットがマルチバイト・キャラクタ・セットの場合で、名前の中のマルチバイト文字に等価のシングルバイト文字がある場合、そのマルチバイト文字をシングルバイト文字に変換します。

2. その名前を、OTTのキャラクタ・セットからコンパイラのキャラクタ・セットに変換します。コンパイラのキャラクタ・セットは、US7ASCIIなどのシングルバイト・キャラクタ・セットです。

3. 最後に、有効になっているCASEオプションに従って、文字の大/小文字が設定されます。そして、C言語の識別子で無効な文字、またはコンパイラのキャラクタ・セットに変換内容がない文字は、アンダースコアに置き換えられます。1文字でもアンダースコアに置き換えられると、OTTから警告メッセージが表示されます。名前に含まれる文字がすべてアンダースコアに置き換えられると、OTTによってエラー・メッセージが表示されます。

文字単位の名前の変換では、コンパイラのキャラクタ・セットにあるアンダースコア、数字またはシングルバイト文字は変更されません。したがって、有効なC識別子は変更されません。

名前の変換ではたとえば、ウムラウトの付いた「o」、アクセント符号の付いた「a」などのシングルバイト文字をそれぞれ「o」や「a」に変換したり、またマルチバイト文字をシングルバイトと等価に変換できます。名前に等価のシングルバイトがないマルチバイト文字がある場合、通常、その名前の変換はエラーとなります。この場合、ユーザーは、intypeファイルで名前の変換を指定する必要があります。

C言語の同一の名前に複数のデータベース識別子がマッピングされている場合に生じるネーミングの競合は、OTTでは検出されません。また、データベース識別子がCキーワードにマッピングされるときのネーミング問題も検出されません。

OTTでのファイル名比較の制限事項

現在、OTTは、コマンドラインまたはintypeファイルに指定したファイル名を比較することで、2つのファイルが同一かどうかを判断しています。OTTで2つのファイル名が同一のファイルを参照しているかどうかを判別する必要がある場合は、1つの潜在的な問題が生じます。たとえば、OTTで生成されたファイルfoo.hで、foo1.hに記述されている型宣言と、/private/elias/foo1.hに記述されている別の型宣言が必要な場合、OTTは、2つのファイルが同一の場合は1つの#includeディレクティブを、異なる場合は2つの#includeディレクティブを生成します。しかし、実際には2つのファイルは異なるという結論が出され、次のように2つの#includesディレクティブが生成されます。

#ifndef FOO1_ORACLE
#include "foo1.h"
#endif
#ifndef FOO1_ORACLE
#include "/private/elias/foo1.h"
#endif

foo1.hと/private/elias/foo1.hが別々のファイルである場合は、最初のファイルのみが組み込まれます。foo1.hと/private/elias/foo1.hが同一ファイルである場合は、#includeディレクティブが重複して記述されます。

そのため、コマンドラインまたはintypeファイルでファイルを複数回記述するときは、各記述で正確に同じファイル名を使用する必要があります。

16 OCIリレーショナル関数

この章では、最初にC言語対応のOCIリレーショナル関数について説明します。各関数コールの詳細を説明するとともに、使用しているアプリケーションでOCI関数をコールする方法についても説明します。

関連項目:
コード例は、Oracle Databaseのインストールに含まれているデモ・プログラムを参照してください。詳細は、付録Bを参照してください。

この章は、次の項目で構成されています。

- リレーショナル関数の概要

- 接続関数、認証関数および初期化関数

- ハンドル関数および記述子関数

- バインド関数、定義関数および記述関数

リレーショナル関数の概要

この章および第17章では、OCIリレーショナル関数コールと、基本OCIにおける関数について説明します。

関連項目:
リターン・コードおよびエラー処理の詳細は、「OCIでのエラー処理」を参照してください。

OCI関数の規則

各関数について、次の情報が記載されています。

用途

この関数によって実行されるアクションを簡単に説明します。

構文

関数の宣言。

パラメータ

この関数の各パラメータの説明。これにはパラメータのモードが含まれます。パラメータのモードには、表16-1に示す3つの値があります。

表16-1 パラメータのモード

モード

説明

IN

OCIにデータを渡すパラメータ

OUT

このコールでOCIからデータを受け取るパラメータ

IN/OUT

このコールでデータを渡し、このコールまたは後続のコールからの戻りでデータを受け取るパラメータ

コメント

この関数に関する詳細情報。関数の使用上の制約やアプリケーション内でこの関数を使用するときに役に立つ情報が記載されています。

戻り値

このオプションの項では、戻される可能性のある値について説明します。この項は、「コメント」の項の前または後にあります。

例

説明の対象となっている関数コールの使用方法を例示するコード(全体または一部)。すべての関数に例が記載されているわけではありません。

関連関数

関連する関数コールのリスト。

OCI関数のコール

OCIのこれまでのバージョンとは異なり、リリース8以上のOCIでは、NULL文字で終了する文字列の文字列長パラメータに-1を渡すことはできません。文字列長をパラメータとして渡すときは、NULL終了文字バイトを組み込まないでください。OCIでは、文字列はNULLで終了するとはみなされません。

OCIパラメータのバッファ長は、バイト単位です。ただし、次の場合は除きます。

- いくつかのLOBコール内のamountパラメータが文字単位である場合。

- 関数パラメータにUTF-16エンコーディングのテキストが使用されており、その長さが文字のポイント単位である場合。

LOB関数用のサーバー・ラウンドトリップ

個々のOCI LOB関数に必要なサーバー・ラウンドトリップ回数を示す表は、付録Cを参照してください。

接続関数、認証関数および初期化関数

表16-1は、この項で説明しているOCIの接続関数、認証関数および初期化関数を示しています。

表16-2 接続関数、認証関数および初期化関数

関数

用途

「OCIAppCtxClearAll()」

アプリケーション・コンテキストのネームスペース内のすべての属性値情報を消去します。

「OCIAppCtxSet()」

アプリケーション・コンテキストのネームスペース内の属性およびその関連値を設定します。

「OCIConnectionPoolCreate()」

接続プールを初期化します。

「OCIConnectionPoolDestroy()」

接続プールを破棄します。

「OCIDBShutdown()」

Oracle Databaseを停止します

「OCIDBStartup()」

Oracle Databaseのインスタンスを起動します。

「OCIEnvCreate()」

OCI環境ハンドルを作成および初期化します。

「OCIEnvNlsCreate()」

OCI関数が実行される環境ハンドルを作成および初期化します。この環境の作成時に、キャラクタ・セットIDおよび各国語キャラクタ・セットIDを設定できます。

「OCILogoff()」

OCILogon2()またはOCILogon()を使用して取得したセッションを解放します。

「OCILogon()」

シングルセッション・ログインを単純化します。

「OCILogon2()」

様々なモードでログイン・セッションを作成します。

「OCIServerAttach()」

サーバーに連結します。サーバー・コンテキスト・ハンドルを初期化します。

「OCIServerDetach()」

サーバーから連結解除します。サーバー・コンテキスト・ハンドルを未初期化します。

「OCISessionBegin()」

ユーザーを認証します。

「OCISessionEnd()」

ユーザー・セッションを終了します。

「OCISessionGet()」

セッション・プールからセッションを取得します。

「OCISessionPoolCreate()」

セッション・プールを初期化します。

「OCISessionPoolDestroy()」

セッション・プールを破棄します。

「OCISessionRelease()」

セッションを解放します。

「OCITerminate()」

共有メモリー・サブシステムから連結解除します。

OCIAppCtxClearAll()

用途

アプリケーション・コンテキストのネームスペース内のすべての属性値情報を消去します。

構文

sword OCIAppCtxClearAll ( void      *sesshndl,
void      *nsptr,
ub4       nsptrlen,
OCIError  *errhp,
ub4       mode ;

パラメータ

sesshndl (IN/OUT)

セッション・ハンドルのポインタです。

nsptr (IN)

ネームスペース文字列(現在はCLIENTCONTEXTのみ)へのポインタです。

nsptrlen (IN)

ネームスペース文字列の長さです。

errhp (OUT)

OCIErrorGet()に渡すことができるエラー・ハンドルです。

mode (IN)

モード(デフォルトはOCI_DEFAULT)です。

戻り値

エラー番号を戻します。

コメント

これは、サーバーへの次回のコール時にサーバー側のコンテキスト情報をクリーン・アップします。このネームスペース情報は、情報がサーバーに送信されるとセッション・ハンドルから消去され、必要に応じて再設定する必要があります。

関連関数

OCIAppCtxSet()

OCIAppCtxSet()

用途

アプリケーション・コンテキストのネームスペース内の属性およびその関連値を設定します。

構文

sword OCIAppCtxSet ( void      *sesshndl,
void      *nsptr,
ub4       nsptrlen,
void      *attrptr,
ub4       attrptrlen,
void      *valueptr,
ub4       valueptrlen,
OCIError  *errhp,
ub4       mode );

パラメータ

sesshndl (IN/OUT)

セッション・ハンドルのポインタです。

nsptr (IN)

ネームスペース文字列(現在はCLIENTCONTEXTのみ)へのポインタです。

nsptrlen (IN)

ネームスペース文字列の長さです。

attrptr (IN)

属性文字列へのポインタです。

attrptrlen (IN)

attrptrが指し示す文字列の長さです。

valueptr (IN)

値文字列へのポインタです。

valueptrlen (IN)

valueptrが指し示す文字列の長さです。

errhp (OUT)

OCIErrorGet()に渡すことができるエラー・ハンドルです。

mode (IN)

モード(デフォルトはOCI_DEFAULT)です。

戻り値

エラー番号を戻します。

コメント

セッション・ハンドルに設定された情報は、サーバーへの次回のコール時にサーバーに送信されます。

この情報は、情報がサーバーに送信されるとセッション・ハンドルから消去され、必要に応じて再設定する必要があります。

関連関数

OCIAppCtxClearAll()

OCIConnectionPoolCreate()

用途

接続プールを初期化します。

構文

sword OCIConnectionPoolCreate ( OCIEnv         *envhp,
OCIError       *errhp,
OCICPool       *poolhp,
OraText        **poolName,
sb4            *poolNameLen,
const OraText  *dblink,
sb4            dblinkLen,
ub4            connMin,
ub4            connMax,
ub4            connIncr,
const OraText  *poolUsername,
sb4            poolUserLen,
const OraText  *poolPassword,
sb4            poolPassLen,
ub4            mode );

パラメータ

envhp (IN)

接続プールを作成する環境へのポインタです。

errhp (IN/OUT)

OCIErrorGet()に渡すことができるエラー・ハンドルです。

poolhp (IN)

割当て済のプール・ハンドルです。

poolName (OUT)

接続先の接続プール名です。

poolNameLen (OUT)

poolNameが指し示す文字列の長さです。

dblink (IN)

接続先のデータベース(サーバー)を指定します。

dblinkLen (IN)

dblinkが指し示す文字列の長さです。

connMin (IN)

接続プールの最小接続数を指定します。有効な値は0 (ゼロ)以上です。

指定された数の接続がOCIConnectionPoolCreate()によってサーバーにオープンされます。接続プールを作成すると、必要なときのみ接続がオープンされます。通常、このパラメータは、アプリケーションで実行を予定している同時文の数に設定する必要があります。

connMax (IN)

データベースに対してオープンできる最大接続数を指定します。最大数に達すると、追加の接続はオープンしません。有効な値は1以上です。

connIncr (IN)

現行の接続数がconnMax未満の場合、アプリケーションでは、データベースに対してオープンする接続に次回の増分を設定できます。有効な値は0 (ゼロ)以上です。

poolUsername (IN)

接続プーリングでは、暗黙的な1次セッションが必要です。この属性はそのセッションのユーザー名を指定します。

poolUserLen (IN)

poolUsernameの長さです。

poolPassword (IN)

ユーザー名poolUsernameのパスワードです。

poolPassLen (IN)

poolPasswordの長さです。

mode (IN)

次のモードがサポートされています。

- OCI_DEFAULT

- OCI_CPOOL_REINITIALIZE

通常、OCIConnectionPoolCreate()は、modeをOCI_DEFAULTに設定してコールします。

プール属性を動的に変更する(たとえば、connMin、connMaxおよびconnIncrの各パラメータを変更する)には、modeをOCI_CPOOL_REINITIALIZEに設定して、OCIConnectionPoolCreate()をコールします。このコールの実行時、他のパラメータは無視されます。

コメント

OUTパラメータpoolNameとpoolNameLenには、データベース名とその長さの引数のかわりに、後続のOCIServerAttach()とOCILogon2()コールで使用する値が格納されます。

関連項目:
「接続プール・ハンドル属性」

関連関数

OCIConnectionPoolDestroy()、OCILogon2()、OCIServerAttach()

OCIConnectionPoolDestroy()

用途

接続プールを破棄します。

構文

sword OCIConnectionPoolDestroy ( OCICPool     *poolhp,
OCIError     *errhp,
ub4          mode );

パラメータ

poolhp (IN)

作成したプールのプール・ハンドルです。

errhp (IN/OUT)

OCIErrorGet()に渡すことができるエラー・ハンドルです。

mode (IN)

現在、この関数ではOCI_DEFAULTモードのみがサポートされています。

関連関数

OCIConnectionPoolCreate()

OCIDBShutdown()

用途

Oracle Databaseのインスタンスを停止します。

構文

sword OCIDBShutdown ( OCISvcCtx     *svchp,
OCIError      *errhp,
OCIAdmin      *admhp,
ub4           mode);

パラメータ

svchp (IN)

サービス・コンテキストへのハンドルです。svchpには、有効なサーバー・ハンドルおよび有効なユーザー・ハンドルを設定する必要があります。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

admhp (IN)－ オプション

インスタンス管理ハンドルです。現在は使用されていません。(OCIAdmin *)0を渡します。

mode (IN)

OCI_DEFAULT－ これ以上の接続は禁止されます。ユーザーがデータベースから切断されるまで待機します。

OCI_DBSHUTDOWN_TRANSACTIONAL－ これ以上の接続は禁止され、新しいトランザクションは許可されません。アクティブなトランザクションが完了するまで待機します。

OCI_DBSHUTDOWN_TRANSACTIONAL_LOCAL－ これ以上の接続は禁止され、新しいトランザクションは許可されません。ローカル・トランザクションが完了するまで待機します。

OCI_DBSHUTDOWN_IMMEDIATE－ 現在のコールが完了するまで待機しない、あるいはユーザーがデータベースから切断されるまで待機しません。コミットされていないトランザクションはすべて終了し、ロールバックされます。

OCI_DBSHUTDOWN_FINAL－ データベースを停止します。データベースがクローズされてマウントが解除された後、OCIDBShutdown()への2回目のコールでのみ使用する必要があります。

OCI_DBSHUTDOWN_ABORT－ 現在のコールが完了するまで待機しない、あるいはユーザーがデータベースから切断されるまで待機しません。コミットされていないトランザクションはすべて終了し、ロールバックはされません。データベースを停止する場合、これが最も速い処理方法ですが、次回のデータベースの起動時にインスタンスのリカバリが必要な場合があります。このため、このオプションは、バックグラウンド・プロセスが異常終了した場合など、通常とは異なる状況下で使用します。

コメント

停止するには、SYSOPERまたはSYSDBAとしてデータベースに接続している必要があります。ディスパッチャを介して共有サーバーには接続できません。OCI_DBSHUTDOWN_ABORT以外のモードで停止する場合、次の手順を使用します。

1. OCIDBShutdown()をOCI_DEFAULT、OCI_DBSHUTDOWN_TRANSACTIONAL、OCI_DBSHUTDOWN_TRANSACTIONAL_LOCALまたはOCI_DBSHUTDOWN_IMMEDIATEモードでコールし、これ以上の接続を禁止します。

2. 必要なALTER DATABASEコマンドを発行し、データベースをクローズしてマウントを解除します。

3. OCIDBShutdown()をOCI_DBSHUTDOWN_FINALモードでコールし、インスタンスを停止します。

関連項目:
「データベースの起動と停止」

関連関数

OCIAttrSet()、OCIDBStartup()

OCIDBStartup()

用途

Oracle Databaseのインスタンスを起動します。

構文

sword OCIDBStartup ( OCISvcCtx     *svchp,
OCIError      *errhp,
OCIAdmin      *admhp,
ub4           mode,
ub4           flags);

パラメータ

svchp (IN)

サービス・コンテキストへのハンドルです。svchpには、有効なサーバー・ハンドルおよび有効なユーザー・ハンドルが設定されている必要があります。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

admhp (IN)－ オプション

インスタンス管理ハンドルです。起動コールへの追加引数を渡すために使用します。OCI_ATTR_ADMIN_PFILEを設定していない場合は、(OCIAdmin *)0を渡します。

mode (IN)

OCI_DEFAULT - これが唯一サポートされているモードです。インスタンスを起動しますが、データベースをマウントまたはオープンすることはありません。STARTUP NOMOUNTと同じです。

flags (IN)

OCI_DEFAULT－ すべてのユーザーにデータベースへのアクセスを許可します。

OCI_DBSTARTUPFLAG_RESTRICT－ CREATE SESSION権限とRESTRICTED SESSION権限の両方を持つユーザー(通常はDBA)にのみデータベースへのアクセスを許可します。

OCI_DBSTARTUPFLAG_FORCE－ 新しいインスタンスを起動する前にABORTを使用して動作中のインスタンス(存在する場合)を停止します。この問題は、通常とは異なる状況下でのみ使用します。

コメント

SYSOPERまたはSYSDBAとしてOCI_PRELIM_AUTHモードでデータベースに接続する必要があります。ディスパッチャを介して共有サーバーには接続できません(つまり、OCI_DBSTARTUPFLAG_FORCEで実行中のインスタンスを再起動する場合)。クライアント側のパラメータ・ファイル(pfile)を使用するには、管理ハンドルでOCI_ATTR_ADMIN_PFILEを設定する必要があります。設定しない場合、サーバー側のパラメータ・ファイル(spfile)が使用されます。OCIDBStartup()のコールにより、サーバー上で1つのインスタンスが起動します。

関連項目:
「データベースの起動と停止」

関連関数

OCIAttrSet()、OCIDBShutdown()、OCIServerAttach()、OCISessionBegin()

OCIEnvCreate()

用途

OCI関数が実行される環境ハンドルを作成および初期化します。

構文

sword OCIEnvCreate   ( OCIEnv        **envhpp,
ub4           mode,
const void    *ctxp,
const void    *(*malocfp)
(void  *ctxp,
size_t size),
const void    *(*ralocfp)
(void  *ctxp,
void  *memptr,
size_t newsize),
const void    (*mfreefp)
(void  *ctxp,
void  *memptr))
size_t         xtramemsz,
void           **usrmempp );

パラメータ

envhpp (OUT)

エンコーディング設定がmodeで指定されている環境ハンドルへのポインタです。この設定は、envhppから導出された文ハンドルによって継承されます。

mode (IN)

モードの初期化を指定します。次のモードが有効です。

- OCI_DEFAULT - デフォルト値。非UTF-16エンコーディングです。

- OCI_THREADED - スレッド環境を使用します。ユーザーに公開されていない内部データ構造体がマルチ・スレッドによって同時にアクセスされないように保護します。

- OCI_OBJECT - オブジェクト機能を使用します。

- OCI_EVENTS - パブリッシュ/サブスクライブ通知を利用します。

- OCI_NO_UCB - 動的コールバック・ルーチンOCIEnvCallback()のコールを抑止します。デフォルトの動作では、環境の作成時にOCIEnvCallback()のコールが許可されます。

関連項目:
「動的なコールバック登録」

- OCI_ENV_NO_MUTEX - このモードでは、相互排他(mutex)ロックは発生しません。環境ハンドル、または環境ハンドルから導出されたハンドルで行われたすべてのOCIコールは、シリアライズする必要があります。OCI_THREADEDは、OCI_ENV_NO_MUTEXを指定する場合にも指定する必要があります。

- OCI_NEW_LENGTH_SEMANTICS - キャラクタ・セットに関係なく、すべてのハンドルに対して一貫してバイト長セマンティクスを使用します。

- OCI_SUPPRESS_NLS_VALIDATION - NLS文字検証を抑制します。NLS文字検証は、Oracle Database 11g リリース1 (11.1)以上ではデフォルトでオンです。OCI_ENABLE_NLS_VALIDATIONを使用して、NLS文字検証を有効にします。詳細は「コメント」を参照してください。

- OCI_NCHAR_LITERAL_REPLACE_ON - N置換をオンにします。

- OCI_NCHAR_LITERAL_REPLACE_OFF - N置換をオフにします。このモードおよびOCI_NCHAR_LITERAL_REPLACE_ONのどちらも使用しない場合、置換は環境変数ORA_NCHAR_LITERAL_REPLACEによって決定されます。この値はTRUEまたはFALSEに設定できます。TRUEに設定すると置換がオンになり、設定しない場合はオフになりますが、オフがOCIでのデフォルト設定です。

- OCI_ENABLE_NLS_VALIDATION - NLS文字検証を有効にします。詳細は「コメント」を参照してください。

ctxp (IN)

メモリー・コールバック・ルーチンのユーザー定義コンテキストを指定します。

malocfp (IN)

ユーザー定義のメモリー割当て関数を指定します。モードがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。

ctxp (IN)

ユーザー定義のメモリー割当て関数の、コンテキスト・ポインタを指定します。

size (IN)

ユーザー定義のメモリー割当て関数によって割り当てられるメモリーのサイズを指定します。

ralocfp (IN)

ユーザー定義のメモリー再割当て関数を指定します。モードがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。

ctxp (IN)

ユーザー定義のメモリー再割当て関数の、コンテキスト・ポインタを指定します。

memptr (IN)

メモリー・ブロックのポインタです。

newsize (IN)

新しく割り当てられるメモリーのサイズを指定します。

mfreefp (IN)

ユーザー定義のメモリー解放関数を指定します。モードがOCI_THREADEDの場合、このメモリー解放ルーチンは、スレッド・セーフにしてください。

ctxp (IN)

ユーザー定義のメモリー解放関数の、コンテキスト・ポインタを指定します。

memptr (IN)

解放されるメモリーへのポインタです。

xtramemsz (IN)

環境の継続時間中に割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

コールによりユーザーに割り当てられた、サイズxtramemszのユーザー・メモリーのポインタを戻します。

コメント

このコールにより、ユーザーによって指定されたモードを使用して、すべてのOCIコールの環境が作成されます。

注意:
このコールは、他のOCIコールより先に実行する必要があります。また、OCIInitialize()コールのかわりに使用してください。

このコールでは、残りのOCI関数で使用される環境ハンドルが戻されます。OCIには、それぞれ独自の環境モードを持つ複数の環境が存在する可能性があります。この関数では、どのモードで初期化を要求されても、プロセス・レベルの初期化を実行します。たとえば、環境をOCI_THREADEDで初期化した場合は、OCIで使用されるすべてのライブラリもそのスレッド・モードで初期化されます。

N置換をオンにすると、OCIStmtPrepare()またはOCIStmtPrepare2()関数では、SQLテキストに対してN置換が実行され、生成されたSQLテキストは文ハンドルに格納されます。このため、アプリケーションがOCI_ATTR_STATEMENTを使用してSQLテキストをOCI文ハンドルから取得する場合、元のSQLテキストではなく変更されたSQLテキストが戻されます。

kshシェルでN置換をオンにするには、次のように指定します。

export ORA_NCHAR_LITERAL_REPLACE=TRUE

cshシェルでN置換をオンにするには、次のように指定します。

setenv ORA_NCHAR_LITERAL_REPLACE TRUE

リモート・データベースのリリースが10.2より前である場合、N置換は実行されません。

OCIライブラリを使用してDLLまたは共有ライブラリを記述している場合は、非推奨のOCIInitialize()コールのかわりにこのコールを使用します。

関連項目:
xtramemszパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください。

OCI_SUPPRESS_NLS_VALIDATIONおよびOCI_ENABLE_NLS_VALIDATIONに関しては、デフォルトで、クライアントとサーバーのキャラクタ・セットが同一で、クライアントとサーバーが両方ともOracle Database 11gリリース1 (11.1)以上である場合は、パフォーマンス向上のために文字データはOCIで検証されません。したがって、アプリケーションで不完全なマルチバイト文字を持つ文字列が挿入される場合(バインド変数の末尾など)、このような文字列はデータベースでそのまま保持されることがあります。

クライアントまたはサーバーがOracle Database 11gリリース1 (11.1)より前のリリースである場合、OCIで不完全な文字は使用できません。

Oracle Database 10gリリース2 (10.2)までデフォルトであったOCI_ENABLE_NLS_VALIDATIONモードでは、不完全なマルチバイト文字がデータベースで保持されなくなります(クライアントおよびサーバーのキャラクタ・セットが同一である場合)。アプリケーションで不完全なマルチバイト文字が生成される可能性があり、クライアントおよびサーバーのキャラクタ・セットが同一である環境でアプリケーションが実行可能な場合は、そのような不完全な文字が除去されるように、OCI_ENABLE_NLS_VALIDATIONモードを明示的に使用することをお薦めします。

例

例16-1 N置換をオンにしたスレッド・セーフのOCI環境の作成

OCIEnv *envhp;
...
/* Create a thread-safe OCI environment with N' substitution turned on.  */
if(OCIEnvCreate((OCIEnv **)&envhp,
(ub4)OCI_THREADED | OCI_NCHAR_LITERAL_REPLACE_ON,
(void  *)0, (void  * (*)(void  *, size_t))0,
(void  * (*)(void  *, void  *, size_t))0,
(void (*)(void  *, void  *))0,
(size_t)0, (void  **)0))
{
printf("Failed: OCIEnvCreate()\n");
return 1;
}
...

関連関数

OCIHandleAlloc()、OCIHandleFree()、OCIEnvNlsCreate()、OCITerminate()

OCIEnvNlsCreate()

用途

OCI関数が実行される環境ハンドルを作成および初期化します。これは、OCIEnvCreate()関数を拡張した関数です。

構文

sword OCIEnvNlsCreate   ( OCIEnv        **envhpp,
ub4           mode,
void          *ctxp,
void          *(*malocfp)
(void  *ctxp,
size_t size),
void          *(*ralocfp)
(void  *ctxp,
void  *memptr,
size_t newsize),
void          (*mfreefp)
(void  *ctxp,
void  *memptr))
size_t        xtramemsz,
void          **usrmempp
ub2           charset,
ub2           ncharset );

パラメータ

envhpp (OUT)

エンコーディング設定がmodeで指定されている環境ハンドルへのポインタです。この設定は、envhppから導出された文ハンドルによって継承されます。

mode (IN)

モードの初期化を指定します。次のモードが有効です。

- OCI_DEFAULT - デフォルト値。非UTF-16エンコーディングです。

- OCI_THREADED - スレッド環境を使用します。ユーザーに公開されていない内部データ構造体がマルチ・スレッドによって同時にアクセスされないように保護します。

- OCI_OBJECT - オブジェクト機能を使用します。

- OCI_EVENTS - パブリッシュ/サブスクライブ通知を利用します。

- OCI_NO_UCB - 動的コールバック・ルーチンOCIEnvCallback()のコールを抑止します。デフォルトの動作では、環境の作成時にOCIEnvCallback()のコールが許可されます。

関連項目:
「動的なコールバック登録」

- OCI_ENV_NO_MUTEX - このモードでは、相互排他(mutex)ロックは発生しません。環境ハンドル、または環境ハンドルから導出されたハンドルで行われたすべてのOCIコールは、シリアライズする必要があります。OCI_THREADEDは、OCI_ENV_NO_MUTEXを指定する場合にも指定する必要があります。

- OCI_SUPPRESS_NLS_VALIDATION - NLS文字検証を抑制します。NLS文字検証は、Oracle Database 11g リリース1 (11.1)以上ではデフォルトでオンです。OCI_ENABLE_NLS_VALIDATIONを使用して、NLS文字検証を有効にします。詳細は「コメント」を参照してください。

- OCI_NCHAR_LITERAL_REPLACE_ON - N置換をオンにします。

- OCI_NCHAR_LITERAL_REPLACE_OFF - N置換をオフにします。このモードおよびOCI_NCHAR_LITERAL_REPLACE_ONのどちらも使用しない場合、置換は環境変数ORA_NCHAR_LITERAL_REPLACEによって決定されます。この値はTRUEまたはFALSEに設定できます。TRUEに設定すると置換がオンになり、設定しない場合はオフになりますが、オフがOCIでのデフォルト設定です。

- OCI_ENABLE_NLS_VALIDATION - NLS文字検証を有効にします。詳細は「コメント」を参照してください。

ctxp (IN)

メモリー・コールバック・ルーチンのユーザー定義コンテキストを指定します。

malocfp (IN)

ユーザー定義のメモリー割当て関数を指定します。modeがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。

ctxp (IN)

ユーザー定義のメモリー割当て関数の、コンテキスト・ポインタを指定します。

size (IN)

ユーザー定義のメモリー割当て関数によって割り当てられるメモリーのサイズを指定します。

ralocfp (IN)

ユーザー定義のメモリー再割当て関数を指定します。モードがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。

ctxp (IN)

ユーザー定義のメモリー再割当て関数の、コンテキスト・ポインタを指定します。

memptr (IN)

メモリー・ブロックのポインタです。

newsize (IN)

新しく割り当てられるメモリーのサイズを指定します。

mfreefp (IN)

ユーザー定義のメモリー解放関数を指定します。モードがOCI_THREADEDの場合、このメモリー解放ルーチンは、スレッド・セーフにしてください。

ctxp (IN)

ユーザー定義のメモリー解放関数の、コンテキスト・ポインタを指定します。

memptr (IN)

解放されるメモリーへのポインタです。

xtramemsz (IN)

環境の継続時間中に割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

コールによりユーザーに割り当てられた、サイズxtramemszのユーザー・メモリーのポインタを戻します。

charset (IN)

現行の環境ハンドルに対するクライアント側キャラクタ・セットです。0 (ゼロ)の場合は、NLS_LANG設定が使用されます。OCI_UTF16IDは有効な設定で、メタデータおよびCHARデータで使用されます。

ncharset (IN)

現行の環境ハンドルに対するクライアント側各国語キャラクタ・セットです。0 (ゼロ)の場合は、NLS_NCHAR設定が使用されます。OCI_UTF16IDは有効な設定で、NCHARデータで使用されます。

戻り値

OCI_SUCCESS - 環境ハンドルは正常に作成されました。

OCI_ERROR - エラーが発生しました。

コメント

このコールにより、ユーザーによって指定されたモードを使用して、すべてのOCIコールの環境が作成されます。

OCIEnvNlsCreate()を使用して環境ハンドルを作成すると、バインド・ハンドルおよび定義ハンドルの実際の長さと戻される長さは、常にバイト単位で表されます。これは、次のコールに適用されます。

- OCIBindByName()

- OCIBindByPos()

- OCIBindDynamic()

- OCIDefineByPos()

- OCIDefineDynamic()

環境の作成時に、この関数を使用してcharset IDおよびncharset IDを設定できます。これは、OCIEnvCreate()関数を拡張した関数です。

この関数は、クライアント側データベースおよび各国語キャラクタ・セットとしてcharsetおよびncharsetを0 (ゼロ)以外の値に設定し、NLS_LANGおよびNLS_NCHARで指定した値を置換します。charsetおよびncharsetが0 (ゼロ)の場合、この関数はOCIEnvCreate()の動作と完全に同じになります。charsetは、暗黙的なフォーム属性を持つメタデータおよびデータのエンコーディングを制御し、ncharsetは、SQLCS_NCHARフォーム属性を持つデータのエンコーディングを制御します。

OCI_UTF16IDは、OCIEnvNlsCreate()では設定できますが、NLS_LANGまたはNLS_NCHARでは設定できません。NLS_LANGおよびNLS_NCHARのキャラクタ・セットIDにアクセスするには、OCINlsEnvironmentVariableGet()を使用します。

このコールでは、残りのOCI関数で使用される環境ハンドルが戻されます。OCIには、それぞれ独自の環境モードを持つ複数の環境が存在する可能性があります。この関数では、どのモードで初期化を要求されても、プロセス・レベルの初期化を実行します。たとえば、環境をOCI_THREADEDで初期化した場合は、OCIで使用されるすべてのライブラリもそのスレッド・モードで初期化されます。

N置換をオンにすると、OCIStmtPrepare()またはOCIStmtPrepare2()関数では、SQLテキストに対してN置換が実行され、生成されたSQLテキストは文ハンドルに格納されます。このため、アプリケーションがOCI_ATTR_STATEMENTを使用してSQLテキストをOCI文ハンドルから取得する場合、元のSQLテキストではなく変更されたSQLテキストが戻されます。

kshシェルでN置換をオンにするには、次のように指定します。

export ORA_NCHAR_LITERAL_REPLACE=TRUE

cshシェルでN置換をオンにするには、次のように指定します。

setenv ORA_NCHAR_LITERAL_REPLACE TRUE

リモート・データベースのリリースが10.2より前である場合、N置換は実行されません。

OCIライブラリを使用してDLLまたは共有ライブラリを記述している場合は、非推奨のOCIInitialize()コールのかわりにこのコールを使用します。

関連項目:

- xtramemszパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください。

- 関連する関数でN置換を設定する方法を示すコード例については、「OCIEnvCreate()」を参照してください。

OCI_SUPPRESS_NLS_VALIDATIONおよびOCI_ENABLE_NLS_VALIDATIONに関しては、デフォルトで、クライアントとサーバーのキャラクタ・セットが同一で、クライアントとサーバーが両方ともOracle Database 11gリリース1 (11.1)以上である場合は、パフォーマンス向上のために文字データはOCIで検証されません。したがって、アプリケーションで不完全なマルチバイト文字を持つ文字列が挿入される場合(バインド変数の末尾など)、このような文字列はデータベースでそのまま保持されることがあります。

クライアントまたはサーバーがOracle Database 11gリリース1 (11.1)より前のリリースである場合、OCIで不完全な文字は使用できません。

Oracle Database 10gリリース2 (10.2)までデフォルトであったOCI_ENABLE_NLS_VALIDATIONモードでは、不完全なマルチバイト文字がデータベースで保持されなくなります(クライアントおよびサーバーのキャラクタ・セットが同一である場合)。アプリケーションで不完全なマルチバイト文字が生成される可能性があり、クライアントおよびサーバーのキャラクタ・セットが同一である環境でアプリケーションが実行可能な場合は、そのような不完全な文字が除去されるように、OCI_ENABLE_NLS_VALIDATIONモードを明示的に使用することをお薦めします。

関連関数

OCIHandleAlloc()、OCIHandleFree()、OCITerminate()、OCINlsEnvironmentVariableGet()

OCILogoff()

用途

OCILogon2()またはOCILogon()を使用して取得したセッションを解放します。

構文

sword OCILogoff ( OCISvcCtx      *svchp
OCIError       *errhp );

パラメータ

svchp (IN)

OCILogon()またはOCILogon2()のコールに使用されたサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

この関数は、OCILogon2()またはOCILogon()を使用して取得したセッションを解放するために使用します。OCILogon()を使用した場合、この関数はその接続およびセッションを終了します。OCILogon2()を使用した場合、このコールの動作は、対応するOCILogon2()関数がコールされたときのmodeによって決まります。デフォルトでは、この関数は、セッションまたは接続をクローズします。接続プーリングの場合、この関数は、セッションをクローズして接続をプールに戻します。セッション・プーリングの場合、この関数は、セッションと接続のペアをプールに戻します。

関連項目:
アプリケーションでのログオンおよびログオフの詳細は、「アプリケーションの初期化、接続およびセッション作成」を参照してください。

関連関数

OCILogon()、OCILogon2()

OCILogon()

用途

単純なログイン・セッションを作成します。

構文

sword OCILogon ( OCIEnv          *envhp,
OCIError        *errhp,
OCISvcCtx       **svchp,
const OraText   *username,
ub4             uname_len,
const OraText   *password,
ub4             passwd_len,
const OraText   *dbname,
ub4             dbname_len );

パラメータ

envhp (IN)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

svchp (IN/OUT)

サービス・コンテキスト・ポインタです。

username (IN)

ユーザー名です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

uname_len (IN)

usernameの長さは、エンコーディングの有無に関係なく、バイト単位です。

password (IN)

ユーザーのパスワードです。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

passwd_len (IN)

passwordの長さは、エンコーディングの有無に関係なく、バイト単位です。

dbname (IN)

接続先のデータベース名です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

dbname_len (IN)

dbnameの長さは、エンコーディングの有無に関係なく、バイト単位です。

コメント

この関数は、アプリケーションのためのログイン・セッションを作成するときに使用します。

注意:
TPモニター・アプリケーションなどの複雑なセッションを必要とするユーザーは、「アプリケーションの初期化、接続およびセッション作成」を参照してください。

このコールは、渡されたサービス・コンテキスト・ハンドルの割当てを行います。このコールは、セッションに対応付けられたサーバーとユーザー・セッション・ハンドルの暗黙的な割当ても実行します。これらのハンドルは、サービス・コンテキスト・ハンドルに対してOCIArrayDescriptorAlloc()をコールすることにより取り出せます。

関連関数

OCILogoff()

OCILogon2()

用途

セッションを取得します。このセッションは、基礎となる新規の接続があるセッション、既存の接続プールから仮想接続によって開始されたセッション、または既存のセッション・プールからのセッションである場合があります。この関数がコールされるときのmodeによって、動作が決まります。

構文

sword OCILogon2 ( OCIEnv          *envhp,
OCIError        *errhp,
OCISvcCtx       **svchp,
const OraText   *username,
ub4             uname_len,
const OraText   *password,
ub4             passwd_len,
const OraText   *dbname,
ub4             dbname_len );
ub4             mode );

パラメータ

envhp (IN)

OCI環境ハンドルです。接続プーリングおよびセッション・プーリングの場合は、それぞれのプールが作成されたときの環境ハンドルに設定する必要があります。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

svchp (IN/OUT)

OCIサービス・コンテキスト・ポインタのアドレスです。サーバーおよびセッション・ハンドルが格納されます。

デフォルトでは、新しいセッションおよびサーバー・ハンドルが割り当てられ、接続およびセッションが開始し、サービス・コンテキストにこれらのハンドルが移入されます。

接続プーリングの場合、新しいセッション・ハンドルが割り当てられ、接続プールから仮想接続によってセッションが開始します。

セッション・プーリングの場合、サービス・コンテキストには、セッション・プールからセッション・ハンドルとサーバー・ハンドルの既存のペアが移入されます。

ユーザーは、サーバーの属性、およびサービス・コンテキスト・ポインタに関連付けられたユーザーまたはセッション・ハンドルは変更できないことに注意してください。変更を行うと、OCIAttrSet()コールでエラーが戻されます。

変更できるサービス・コンテキスト属性は、OCI_ATTR_STMTCACHESIZEのみです。

username (IN)

セッションを認証するために使用するユーザー名です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

uname_len (IN)

usernameの長さは、エンコーディングの有無に関係なく、バイト単位です。

password (IN)

ユーザーのパスワードです。接続プーリングでこのパラメータがNULLの場合、OCILogon2()では、プロキシ・ユーザーのログインとみなされます。このような場合は、プール・ユーザーがプロキシ・ユーザーの認証に使用され、プロキシ接続が暗黙的に作成されます。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

passwd_len (IN)

passwordの長さは、エンコーディングの有無に関係なく、バイト単位です。

dbname (IN)

デフォルトでは、Oracle Databaseへの接続で使用する接続文字列を示します。

接続プーリングの場合は、仮想接続を取得してセッションを開始するための接続プールを示します。この値は、OCIConnectionPoolCreate()コールによって戻されます。

セッション・プーリングの場合は、セッションを取得するプールを示します。これは、OCISessionPoolCreate()コールによって戻されます。

dbnameは、OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

dbname_len (IN)

dbnameの長さです。セッション・プーリングおよび接続プーリングの場合、この値は、それぞれOCISessionPoolCreate()コールまたはOCIConnectionPoolCreate()コールによって戻されます。

mode (IN)

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

- OCI_DEFAULT

- OCI_LOGON2_CPOOL

- OCI_LOGON2_SPOOL

- OCI_LOGON2_STMTCACHE

- OCI_LOGON2_PROXY

デフォルト(プーリング以外の場合)では、次のモードが有効です。

OCI_DEFAULT－OCILogon()のコールと等価です。

OCI_LOGON2_STMTCACHE－ 文キャッシュを使用可能にします。

接続プーリングの場合は、次のモードが有効です。

OCI_LOGON2_CPOOLまたはOCI_CPOOL - 接続プーリングを使用する場合に設定する必要があります。

OCI_LOGON2_STMTCACHE－ 文キャッシュを使用可能にします。

接続プーリングでプロキシ認証を使用するには、パスワードはNULLに設定する必要があります。ユーザーには、OCILogon2()コールで提供されたユーザー名によって認証されるセッションが、OCIConnectionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。

セッション・プーリングの場合は、次のモードが有効です。

OCI_LOGON2_SPOOL - セッション・プーリングを使用する場合に設定する必要があります。

OCI_LOGON2_STMTCACHE－ 文キャッシュを使用可能にします。

OCI_LOGON2_PROXY: プロキシ認証を使用します。ユーザーには、OCILogon2()コールで提供されたユーザー名によって認証されるセッションが、OCISessionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。

コメント

なし。

関連関数

OCILogon()、OCILogoff()、OCISessionGet()、OCISessionRelease()

OCIServerAttach()

用途

OCIオペレーションの対象となるデータ・ソースへのアクセス・パスを作成します。

構文

sword OCIServerAttach ( OCIServer     *srvhp,
OCIError      *errhp,
const OraText *dblink,
sb4           dblink_len,
ub4           mode );

パラメータ

srvhp (IN/OUT)

このコールにより初期化される未初期化サーバー・ハンドルです。初期化済のサーバー・ハンドルを渡すとエラーが発生します。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

dblink (IN)

使用するデータベース・サーバーを指定します。このパラメータは、接続文字列またはサービス・ポイントを指定する文字列を指示します。接続文字列がNULLの場合、このコールは、デフォルト・ホストに接続します。文字列自体がUTF-16エンコーディング・モードであるかないかは、アプリケーションの環境ハンドルのmodeまたは設定によって決まります。dblinkの長さは、dblink_lenで指定します。dblinkポインタは、戻り時にコール元によって解放されます。

mode=OCI_CPOOL時の接続先プールの名前です。この名前は、OCIConnectionPoolCreate()で作成された接続プールのpoolNameパラメータと同じ名前であることが必要です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

dblink_len (IN)

dblinkが指し示す文字列の長さです。接続文字列名または別名を有効にするには、dblink_lenは0 (ゼロ)以外にしてください。値はバイト単位です。

mode=OCI_CPOOL時のpoolNameの長さは、エンコーディングの有無に関係なく、バイト単位です。

mode (IN)

様々な操作モードを指定します。次のモードが有効です。

- OCI_DEFAULT - エンコーディングについて、この値では、サーバー・ハンドルで環境ハンドルの設定が使用されることを示しています。

- OCI_CPOOL - 接続プーリングを使用します。

連結済のサーバー・ハンドルは、任意の接続セッション・ハンドルに設定されている可能性があるため、ここでのmode値は、セッション・ハンドルに対しては無効です。

コメント

このコールは、OCIアプリケーションと特定のサーバー間の対応付けを作成するときに使用します。

このコールでは、接続プーリングが有効になった時点で、OCIConnectionPoolCreate()がコールされ、poolNameが指定されていると想定しています。

このコールは、サーバー・コンテキスト・ハンドルを初期化しますが、ハンドルはOCIHandleAlloc()のコールを使用して事前に割り当てる必要があります。このコールによって初期化されたサーバー・コンテキスト・ハンドルは、OCIAttrSet()のコールを介してサービス・コンテキストに対応付けられます。対応付けを行うと、そのサーバーに対してOCIオペレーションを実行できます。

複数のサーバーに対してアプリケーションを実行している場合、複数のサーバー・コンテキスト・ハンドルを維持できます。OCIオペレーションは、現在サービス・コンテキストに対応付けられているサーバー・コンテキストに対して実行されます。

OCIServerAttach()が正常に完了すると、Oracle Databaseシャドウ・プロセスが開始されます。Oracle Databaseシャドウ・プロセスをクリーン・アップするには、OCISessionEnd()およびOCIServerDetach()をコールする必要があります。コールしないと、シャドウ・プロセスが蓄積され、LinuxまたはUNIXシステムのプロセス数が足りなくなります。データベースが再起動したときにプロセス数が不足している場合は、データベースが起動しないことがあります。

例

例16-2は、OCIServerAttach()の使用方法を説明しています。このコード・セグメントでは、サーバー・ハンドルを割り当て、連結コールを行い、サービス・コンテキスト・ハンドルを割り当て、最後にそれにサーバー・コンテキストを設定します。

例16-2 OCIServerAttach()コールの使用

OCIHandleAlloc( (void  *) envhp, (void  **) &srvhp, (ub4)
OCI_HTYPE_SERVER, 0, (void  **) 0);
OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
OCIHandleAlloc( (void  *) envhp, (void  **) &svchp, (ub4)
OCI_HTYPE_SVCCTX, 0, (void  **) 0);
/* set attribute server context in the service context */
OCIAttrSet( (void  *) svchp, (ub4) OCI_HTYPE_SVCCTX, (void  *) srvhp,
(ub4) 0, (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);

関連関数

OCIServerDetach()

OCIServerDetach()

用途

OCIオペレーションの対象となるデータ・ソースへのアクセス・パスを削除します。

構文

sword OCIServerDetach ( OCIServer   *srvhp,
OCIError    *errhp,
ub4         mode );

パラメータ

srvhp (IN)

未初期化状態にリセットされる初期化済サーバー・コンテキストへのハンドルです。ハンドルは割当て解除されません。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

mode (IN)

様々な操作モードを指定します。有効なモードはデフォルト・モード用のOCI_DEFAULTのみです。

コメント

このコールは、OCIオペレーションの対象となるデータ・ソースへのアクセス・パスを削除します。アクセス・パスは、OCIServerAttach()のコールによって確立されました。

関連関数

OCIServerAttach()

OCISessionBegin()

用途

ユーザー・セッションを作成し、指定のサーバーに対してユーザー・セッションを開始します。

構文

sword OCISessionBegin ( OCISvcCtx     *svchp,
OCIError      *errhp,
OCISession    *usrhp,
ub4           credt,
ub4           mode );

パラメータ

svchp (IN)

サービス・コンテキストへのハンドルです。svchpには、有効なサーバー・ハンドルを設定する必要があります。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

usrhp (IN/OUT)

このコールによって初期化されるユーザー・セッション・コンテキストへのハンドルです。

credt (IN)

ユーザー・セッションの作成に使用する資格証明のタイプを指定します。credtの有効な値は次のとおりです。

- OCI_CRED_RDBMS - 資格証明としてデータベースのユーザー名とパスワードを使用して認証します。このコールの前に、ユーザー・セッション・コンテキストにOCI_ATTR_USERNAMEとOCI_ATTR_PASSWORD属性を設定しておく必要があります。

- OCI_CRED_EXT - 外部資格証明を使用して認証します。ユーザー名とパスワードは提供されません。

mode (IN)

様々な操作モードを指定します。次のモードが有効です。

- OCI_DEFAULT - このモードでは、戻されるユーザー・セッション・コンテキストは、svchpに指定されたサーバー・コンテキストとともにのみ設定できます。エンコーディングについては、サーバー・ハンドルでは、環境ハンドルの設定が使用されます。

- OCI_MIGRATE - このモードでは、新しいユーザー・セッション・コンテキストを、サービス・ハンドル内で別のサーバー・ハンドルで設定できます。このモードにより、ユーザー・セッション・コンテキストが確立されます。移行可能なセッションを作成するには、サービス・ハンドルが移行不可能なユーザー・セッションですでに設定されている必要があります。これは、移行可能なセッションの「作成者」セッションになります。つまり、移行可能なセッションは、移行不可能な親セッションを持つ必要があります。
セッションが下位の接続プールを使用する場合、OCI_MIGRATEは使用しないでください。セッションの移行と多重化はユーザーに意識させることなく行われます。

- OCI_SYSDBA - このモードでは、ユーザーは、SYSDBAアクセス用に認証されます。

- OCI_SYSOPER - このモードでは、ユーザーは、SYSOPERアクセス用に認証されます。

- OCI_PRELIM_AUTH - このモードは、特定の管理タスクを認証するためにOCI_SYSDBAまたはOCI_SYSOPERとともにのみ使用できます。

- OCI_STMT_CACHE - 指定のサービス・ハンドルにおいてデフォルト・サイズの文キャッシュが可能です。アプリケーションが後からそのサービス・ハンドルでOCI_ATTR_STMTCACHESIZEを使用してサイズを明示的に設定する場合、このモードを渡すのはオプションです。

コメント

OCISessionBegin()コールは、サービス・コンテキスト・ハンドルに設定されたサーバー・セットに対して、ユーザーを認証するときに使用します。

注意:
セッションを開始するときは戻されたエラーをすべてチェックしてください。たとえば、アカウントのパスワードの期限が切れた場合は、ORA-28001エラーが戻されます。

リリース8.1以上では、サーバー・ハンドルに要求を行う前に、そのサーバー・ハンドルに対してOCISessionBegin()をコールする必要があります。OCISessionBegin()は、サーバー・ハンドルによってサービス・コンテキスト内に指定されたユーザーによるOracle Databaseへの接続に対する認証のみをサポートします。つまり、OCIServerAttach()をコールしてサーバー・ハンドルを初期化した後、指定のサーバーに対してユーザーを認証するためにOCISessionBegin()をコールする必要があります。

Unicodeを使用する場合は、modeまたは環境ハンドルを適切に設定し、セッション・ハンドルusrhpで設定されたユーザー名とパスワードをUnicodeにする必要があります。この関数をコールしてユーザー名とパスワードでセッションを開始する前に、OCIAttrSet()をコールして、これら2つのUnicode文字列を対応するバイト長でセッション・ハンドルに設定しておく必要があります。これは、OCIAttrSet()がvoidポインタのみを受け入れるためです。次に、OCISessionBegin()により文字列バッファが解釈されます。

指定のサーバー・ハンドルに対して、最初にOCISessionBegin()をコールした場合は、ユーザー・セッションは、移行可能モード(OCI_MIGRATE)では作成されません。

サーバー・ハンドルに対してOCISessionBegin()をコールした後、アプリケーションではOCISessionBegin()を再度コールし、別のユーザー・セッション・ハンドルを、別の(または同じ)資格証明と別の(または同じ)操作モードを使用して初期化できます。アプリケーションでユーザーをOCI_MIGRATEモードで認証する場合、サービス・ハンドルは、移行不可能なユーザー・ハンドルに関連付けられている必要があります。このユーザー・ハンドルのユーザーIDは、移行可能なユーザー・セッションの所有者IDになります。移行可能なすべてのセッションは、移行不可能な親セッションを持つ必要があります。

OCI_MIGRATEを指定しない場合、ユーザー・セッション・コンテキストは、svchpに設定されたサーバー・ハンドルと同じサーバー・ハンドルでしか使用できません。OCI_MIGRATEモードを指定した場合、ユーザー認証は、別のサーバー・ハンドルで設定できます。ただし、ユーザー・セッション・コンテキストは、同じデータベース・インスタンスに解決するサーバー・ハンドルでのみ使用できます。セキュリティ・チェックは、セッションの切替え中に行われます。セッションは、ユーザーIDが作成者のユーザーIDまたは固有のユーザーIDと同一であるプロセスに現在接続している移行不可能なセッションがある場合にかぎり、そのプロセスへ移行できます。

仮想サーバー・ハンドルが接続プールを指し示している(modeがOCI_CPOOLに設定された状態でOCIServerAttach()がコールされた)場合、OCISessionBegin()へのコールでOCI_MIGRATEフラグを設定しないでください。Oracle Databaseは、互換性上の理由によってのみ、このフラグを渡すことをサポートします。接続プールを使用するときに、ユーザーには、セッションが実際の接続に対して透過的に多重化される独自の専用(仮想)接続を持っているように感じられるため、OCI_MIGRATEフラグは使用しないでください。

OCI_SYSDBA、OCI_SYSOPERおよびOCI_PRELIM_AUTHは、主ユーザー・セッション・コンテキストでのみ使用できます。

OCISessionBegin()のコール用に資格証明を与えるために、2通りの方法がサポートされています。最初の方法は、OCISessionBegin()に渡されるユーザー・セッション・ハンドル内にデータベース認証用の有効なユーザー名とパスワードのペアを用意することです。この方法では、OCIAttrSet()を使用して、ユーザー・セッション・ハンドルに対してOCI_ATTR_USERNAME属性およびOCI_ATTR_PASSWORD属性を設定します。これにより、OCI_CRED_RDBMSを指定してOCISessionBegin()がコールされます。

注意:
ユーザー名とパスワード属性は、OCISessionEnd()を使用してユーザー・セッション・ハンドルを終了しても変更されず、以降のOCISessionBegin()のコールで再使用できます。再使用しない場合は、次回のOCISessionBegin()コールの前に新しい値を設定しなおす必要があります。

2つ目の方法は、外部資格証明を使用することです。この方法では、OCISessionBegin()をコールする前に、ユーザー・セッション・ハンドルについて属性を設定する必要はありません。資格証明のタイプはOCI_CRED_EXTです。これは、Oracle7のconnect/構文と等価です。すでにOCI_ATTR_USERNAMEおよびOCI_ATTR_PASSWORDに値が設定してある場合、OCI_CRED_EXTを使用すると、これらの値は無視されます。

資格証明を設定するもう1つの方法では、OCI_MIGSESSION属性とともに、認証されているユーザーのセッションIDを使用します。このIDは、OCIAttrGet()コールを使用して認証されたユーザーのセッション・ハンドルから抽出できます。

例

例16-3は、OCISessionBegin()の使用方法を説明しています。この例では、ユーザー・セッション・ハンドルを割り当て、ユーザー名とパスワードを設定し、OCISessionBegin()をコールして、最後にサービス・コンテキスト内にユーザー・セッションを設定します。

例16-3 OCISessionBegin()コールの使用

/* allocate a user session handle */
OCIHandleAlloc((void  *)envhp, (void  **)&usrhp, (ub4)
OCI_HTYPE_SESSION, (size_t) 0, (void  **) 0);
OCIAttrSet((void  *)usrhp, (ub4)OCI_HTYPE_SESSION, (void  *)"hr",
(ub4)strlen("hr"), OCI_ATTR_USERNAME, errhp);
OCIAttrSet((void  *)usrhp, (ub4)OCI_HTYPE_SESSION, (void  *)"hr",
(ub4)strlen("hr"), OCI_ATTR_PASSWORD, errhp);
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_DEFAULT));
OCIAttrSet((void  *)svchp, (ub4)OCI_HTYPE_SVCCTX, (void  *)usrhp,
(ub4)0, OCI_ATTR_SESSION, errhp);

関連関数

OCISessionEnd()

OCISessionEnd()

用途

OCISessionBegin()によって作成されたユーザー・セッション・コンテキストを終了します。

構文

sword OCISessionEnd ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCISession      *usrhp,
ub4             mode );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。svchpには、有効なサーバー・ハンドルおよびユーザー・セッション・ハンドルを対応付ける必要があります。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

usrhp (IN)

このユーザーの認証を解除します。このパラメータがNULLとして渡された場合は、サービス・コンテキスト・ハンドル内のユーザーの認証が解除されます。

mode (IN)

有効なモードはOCI_DEFAULTのみです。

コメント

サービス・コンテキストに対応付けられているユーザー・セキュリティ・コンテキストがこのコールによって無効化されます。ユーザー・セッション・コンテキスト用の記憶域は解放されません。サービス・コンテキストによって指定されたトランザクションが暗黙的にコミットされます。トランザクション・ハンドルは、明示的に割り当てられ、使用されていない場合は、解放されます。このユーザーのためにサーバー上に割り当てられていたリソースが解放されます。ユーザー・セッション・ハンドルは、OCISessionBegin()の次回のコールで再使用できます。

関連関数

OCISessionBegin()

OCISessionGet()

用途

セッションを取得します。このセッションは、基礎となる新規の接続があるセッション、既存の接続プールから仮想接続によって開始されたセッション、または既存のセッション・プールからのセッションである場合があります。この関数がコールされるときのmodeによって、動作が決まります。

構文

sword OCISessionGet ( OCIenv            *envhp,
OCIError          *errhp,
OCISvcCtx         **svchp,
OCIAuthInfo       *authInfop,
OraText           *dbName,
ub4               dbName_len,
const OraText     *tagInfo,
ub4               tagInfo_len,
OraText           **retTagInfo,
ub4               *retTagInfo_len,
boolean           *found,
ub4               mode );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。接続プーリングおよびセッション・プーリングの場合は、それぞれのプールが作成されたときの環境ハンドルに設定する必要があります。

errhp (IN/OUT)

OCIエラー・ハンドルです。

svchp (OUT)

OCIサービス・コンテキスト・ポインタのアドレスです。サーバーおよびセッション・ハンドルが格納されます。

デフォルトでは、新しいセッションおよびサーバー・ハンドルが割り当てられ、接続およびセッションが開始し、サービス・コンテキストにこれらのハンドルが移入されます。

接続プーリングの場合、新しいセッション・ハンドルが割り当てられ、接続プールから仮想接続によってセッションが開始します。

セッション・プーリングの場合、サービス・コンテキストには、セッション・プールからセッション・ハンドルとサーバー・ハンドルの既存のペアが移入されます。

サーバーの属性、およびサービス・コンテキスト・ポインタに関連付けられたユーザー・ハンドルとセッション・ハンドルは変更しないでください。変更を行うと、OCIAttrSet()コールでエラーが戻されます。

変更できるサービス・コンテキスト属性は、OCI_ATTR_STMTCACHESIZEのみです。

authInfop (IN)

セッションの取得時に使用する認証情報ハンドルです。

接続プーリングの場合、デフォルトでは、このハンドルはセッション・ハンドルのすべての属性を使用できます。

セッション・プーリングの場合、認証情報ハンドルは、セッション・プールのモードがOCI_SPC_HOMOGENEOUS以外の場合のみ使用されます。

OCIAuthInfoハンドルで設定できる属性は、セッション作成前属性とセッション作成後属性に分類できます。セッション作成前属性は次のとおりです。

セッション作成前属性

セッション作成前属性は、セッションを作成する前に指定する必要があるOCI属性です。これらの属性は、セッションの作成に使用され、セッションの作成後には変更できません。セッション作成前属性は次のとおりです。

OCI_ATTR_USERNAME

OCI_ATTR_PASSWORD

OCI_ATTR_CONNECTION_CLASS

OCI_ATTR_PURITY

OCI_ATTR_PROXY_CREDENTIALS

OCI_ATTR_DISTINGUISHED_NAME

OCI_ATTR_CERTIFICATE

OCI_ATTR_INITIAL_CLIENT_ROLES

OCI_ATTR_APPCTX_SIZE

OCI_ATTR_EDITION

OCI_ATTR_DRIVER_NAME

セッション作成後属性

セッション作成後属性は、セッションを作成した後で指定できるものです。これらは、セッションの作成後に、何度でも自由に変更できます。セッションが作成された後は、OCISessionハンドルで次の属性を設定できます。

OCI_ATTR_CLIENT_IDENTIFIER

OCI_ATTR_CURRENT_SCHEMA

OCI_ATTR_MODULE

OCI_ATTR_ACTION

OCI_ATTR_CLIENT_INFO

OCI_ATTR_COLLECT_CALL_TIME

OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE

OCI_ATTR_SESSION_STATE

関連項目:

- 「OCIでのセッション・プーリング」

- demoディレクトリのcdemosp.c

- 属性の詳細は、「ユーザー・セッション・ハンドル属性」を参照してください。

- 「コメント」の項

dbName (IN)

デフォルトでは、Oracle Databaseへの接続で使用する接続文字列を示します。

接続プーリングの場合は、仮想接続を取得してセッションを開始するための接続プールを示します。この値は、OCIConnectionPoolCreate()コールによって戻されます。

セッション・プーリングの場合は、セッションを取得するプールを示します。これは、OCISessionPoolCreate()コールによって戻されます。

dbName_len (IN)

dbNameの長さです。セッション・プーリングおよび接続プーリングの場合、この値は、それぞれOCISessionPoolCreate()またはOCIConnectionPoolCreate()のコールによって戻されます。

tagInfo (IN)

このパラメータは、セッション・プーリングでのみ使用します。

これは、ユーザーが使用するセッションのタイプを示します。デフォルト・セッションを使用する場合、ユーザーはこのパラメータをNULLに設定する必要があります。このパラメータの詳しい説明は、「コメント」を参照してください。

tagInfo_len (IN)

バイトで示したtagInfoの長さです。セッション・プーリングでのみ使用します。

retTagInfo (OUT)

このパラメータは、セッション・プーリングでのみ使用します。これは、ユーザーに戻されるセッションのタイプを示します。このパラメータの詳しい説明は、「コメント」を参照してください。

retTagInfo_len (OUT)

バイトで示したretTagInfoの長さです。セッション・プーリングでのみ使用します。

found (OUT)

このパラメータは、セッション・プーリングでのみ使用します。ユーザーが要求したセッションのタイプが戻された場合(つまり、tagInfoとretTagInfoの値が同じ場合)、foundはTRUEに設定されます。それ以外の場合、foundはFALSEに設定されます。

mode (IN)

次のモードが有効です。

- OCI_DEFAULT

- OCI_SESSGET_CPOOL

- OCI_SESSGET_SPOOL

- OCI_SESSGET_CREDPROXY

- OCI_SESSGET_CREDEXT - 異種プールでのみサポートされています。

- OCI_SESSGET_PURITY_NEW

- OCI_SESSGET_PURITY_SELF

- OCI_SESSGET_SPOOL_MATCHANY

- OCI_SESSGET_STMTCACHE

- OCI_SESSGET_SYSDBA

デフォルト(プーリング以外)の場合では、次のモードが有効です。

OCI_SESSGET_STMTCACHE - セッションでの文キャッシュを使用可能にします。

OCI_SESSGET_CREDEXT - 外部資格証明を使用して認証されたセッションを戻します。

OCI_SESSGET_SYSDBA - プーリング以外またはセッション・プーリングについてSYSDBA権限を持つセッションを戻します。

接続プーリングの場合は、次のモードが有効です。

OCI_SESSGET_CPOOL - 接続プーリングを使用する場合に設定する必要があります。

OCI_SESSGET_STMTCACHE - セッションでの文キャッシュを使用可能にします。

OCI_SESSGET_CREDPROXY - プロキシ・セッションを戻します。ユーザーには、OCISessionGet()コールで提供されたユーザー名によって認証されるセッションが、OCIConnectionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。

OCI_SESSGET_CREDEXT - 外部資格証明を使用して認証されたセッションを戻します。

セッション・プーリングの場合は、次のモードが有効です。

OCI_SESSGET_SPOOL - セッション・プーリングを使用する場合に設定する必要があります。

OCI_SESSGET_SYSDBA - プーリング以外またはセッション・プーリングについてSYSDBA権限を持つセッションを戻します。

OCI_SESSGET_CREDEXT - 外部資格証明を使用して認証されたセッションを戻します。

OCI_SESSGET_CREDPROXY－ ユーザーには、OCISessionGet()コールで提供されたユーザー名によって認証されるセッションが、OCISessionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。

OCI_SESSGET_SPOOL_MATCHANY - タグ付けの動作を参照します。このモードに設定すると、要求されたタグと異なるタグを持つセッションを戻すことができます。「コメント」の項を参照してください。

データベース常駐接続プーリング(DRCP)の場合は、次のモードが有効です。

OCI_SESSGET_PURITY_SELF - アプリケーションでは前に使用したセッションを使用できます。アプリケーション固有のタグを指定することもできます。

OCI_SESSGET_PURITY_NEW - アプリケーションには、前のセッション状態で保持されていない新規セッションが必要です。これは、デフォルトです。

コメント

ユーザーは、タグを使用して、プール内のセッションをカスタマイズできます。クライアントは、デフォルト・セッションまたはタグが付いていないセッションをプールから取得して、特定の属性(グローバリゼーション設定など)をセッションに設定し、OCISessionRelease()コールでそのセッションをプールに戻すと、セッションに適切なラベル(タグ)を付けることができます。

ユーザーまたは他のユーザーは、OCISessionGet()コールで同じタグを指定して、同じ属性を持つセッションを要求できます。

タグ'A'を持つセッションをユーザーが要求し、一致するセッションが使用不可である場合は、適切に認証されたタグなしのセッション(NULLタグを持つセッション)が戻されます(そのセッションが使用可能な場合)。タグなしのセッションが使用不可で、OCI_SESSGET_SPOOL_MATCHANYが指定されている場合は、適切に認証されて異なるタグを持つセッションが戻されます。OCI_SESSGET_SPOOL_MATCHANYが設定されていない場合は、異なるタグを持つセッションが戻されることはありません。

例16-4は、セッション・プーリングを指定したOCI_ATTR_MODULEの使用方法を説明しています。

例16-4 OCIセッション・プーリングを指定したOCI_ATTR_MODULE属性の使用

Oratext *module = (Oratext*) "mymodule";
/* Allocate the pool handle */
checkerr(errhp,OCIHandleAlloc(envhp,(void**)&poolhp,
OCI_HTYPE_SPOOL,0,0));

checkerr(errhp,OCISessionPoolCreate(envhp,
errhp,poolhp,&poolname,&pnamelen,
(oratext*)conn_str,
len,min,max,incr,0,0,0,0,OCI_DEFAULT));

/* Allocate the auth handle for session get */
checkerr(errhp, OCIHandleAlloc(envhp,
(void**)&authp, OCI_HTYPE_AUTHINFO, 0,0));

checkerr(errhp,OCIAttrSet(authp, OCI_HTYPE_AUTHINFO,
username, strlen((char*)username), OCI_ATTR_USERNAME,errhp);
checkerr(errhp,OCIAttrSet(authp, OCI_HTYPE_AUTHINFO,
password, strlen((char*)password), OCI_ATTR_PASSWORD,
errhp));

checkerr(errhp,OCISessionGet(envhp,errhp,
&svchp,authp,poolname, pnamelen,0,0,0,0,0,
OCI_SESSGET_SPOOL));

/* Get the user handle from the service context handle */
checkerr(errhp, OCIAttrGet(svhcp, OCI_HTYPE_SVCCTX, &usrhp_svc,
0,OCI_ATTR_SESSION,errhp));

/* Set module name on the user handle that you obtained */
checkerr (errhp, OCIAttrSet(usrhp_svc, OCI_HTYPE_SESSION, module,
strlen((char*)module), OCI_ATTR_MODULE,errhp));
/* Make Database calls. */

OCIセッション・プールでサポートされている属性の制限

OCIセッション・プールを指定した、次のセッション作成前属性を使用できます。

OCI_ATTR_EDITION
OCI_ATTR_DRIVER_NAME
OCI_ATTR_USERNAME,
OCI_ATTR_PASSWORD,
OCI_ATTR_CONNECTION_CLASS,
OCI_ATTR_PURITY

ただし、OCI_ATTR_EDITIONおよびOCI_ATTR_DRIVERNAMEは、OCISPoolハンドルの属性であるOCIAuthInfoハンドルで設定することによって、OCISessionPoolCreate()のコール中にのみ、指定することができます。これらは、個々のOCISessionGet()コールに渡されるOCIAuthInfoハンドルでは、指定することはできません。これにより、OCIセッション・プールの一部であるすべてのセッションがこれらの属性の統一した値を持つことが保証されます。

例16-5は、OCIセッション・プールを指定したOCI_ATTR_EDITION属性の使用方法を示しています。

例16-5 OCIセッション・プーリングを指定したOCI_ATTR_EDITION属性の使用

/* allocate the auth handle to be set on the spool handle */
checkerr(errhp, OCIHandleAlloc(envhp,(void**)&authp_sp,
OCI_HTYPE_AUTHINFO, 0,0));

/* Set the edition on the auth handle */

checkerr(errhp,OCIAttrSet(authp_sp, OCI_HTYPE_AUTHINFO,
"Patch_Bug_12345", strlen("Patch_Bug_12345"),
OCI_ATTR_EDITION,errhp));

/* Allocate the pool handle */
checkerr(errhp,OCIHandleAlloc(envhp,(void**)&poolhp,
OCI_HTYPE_SPOOL,0,0));

/* Set the auth handle created above on the spool handle */
checkerr(errhp,OCIAttrSet(poolhp, OCI_HTYPE_SPOOL,authp_sp,
0,OCI_ATTR_SPOOL_AUTH,errhp));
checkerr(errhp,OCISessionPoolCreate(envhp,
errhp,poolhp,&poolname,&pnamelen,
(oratext*)conn_str,
len,min,max,incr,0,0,0,0,OCI_DEFAULT));

/* Allocate the auth handle for session get */
checkerr(errhp, OCIHandleAlloc(envhp,
(void**)&authp_sessget, OCI_HTYPE_AUTHINFO, 0,0));

checkerr(errhp,OCIAttrSet(authp_sessget, OCI_HTYPE_AUTHINFO,
username, strlen((char*)username), OCI_ATTR_USERNAME,errhp);
checkerr(errhp,OCIAttrSet(authp_sessget, OCI_HTYPE_AUTHINFO,
password, strlen((char*)password), OCI_ATTR_PASSWORD,
errhp));

checkerr(errhp,OCISessionGet(envhp,errhp,
&svchp,authp_sessget,poolname, pnamelen,0,0,0,0,0,
OCI_SESSGET_SPOOL));

OCIセッション・プールを指定した、すべてのセッション作成後属性を使用できます。ただし、セッション・プールは、セッションをエージ・アウトし、プール内で既存のセッションを再利用し、新しいセッションを透過的に再作成することが可能であるため、アプリケーションでは、プールからのセッションの取得後に必要とするセッション作成後属性を明示的に設定することをお薦めします。これにより、OCIセッション・プールによって戻された特定のセッションにかかわらず、アプリケーション・ロジックが機能することが保証されます。

関連関数

OCISessionRelease()、OCISessionPoolCreate()、OCISessionPoolDestroy()

OCISessionPoolCreate()

用途

OCIセッション・プーリングおよびデータベース常駐接続プーリング(DRCP)で使用するセッション・プールを初期化します。データベースに対して、sessMinの数のセッションおよび接続を開始します。この関数をコールする前に、OCIHandleAlloc()をコールしてセッション・プール・ハンドルのメモリーを割り当ててください。

構文

sword OCISessionPoolCreate ( OCIEnv           *envhp,
OCIError         *errhp,
OCISPool         *spoolhp,
OraText          **poolName,
ub4              *poolNameLen,
const OraText    *connStr,
ub4              connStrLen,
ub4              sessMin,
ub4              sessMax,
ub4              sessIncr,
OraText          *userid,
ub4              useridLen,
OraText          *password,
ub4              passwordLen,
ub4              mode );

パラメータ

envhp (IN)

セッション・プールで作成する環境ハンドルへのポインタです。

errhp (IN/OUT)

OCIErrorGet()に渡すことができるエラー・ハンドルです。

spoolhp (IN/OUT)

初期化するセッション・プール・ハンドルへのポインタです。

poolName (OUT)

戻されるセッション・プールの名前です。これは、環境内にあるすべてのセッション・プール間で一意の名前です。この値をOCISessionGet()コールに渡す必要があります。

poolNameLen (OUT)

バイトで示したpoolNameの長さです。

connStr (IN)

接続先のデータベースのTNS別名です。

connStrLen (IN)

バイトで示したconnStrの長さです。

sessMin (IN)

セッション・プールの最小セッション数を指定します。

この数のセッションがOCISessionPoolCreate()で開始されます。セッションの開始後は、必要なときのみセッションをオープンします。

この値は、modeがOCI_SPC_HOMOGENEOUSに設定されている場合に使用されます。それ以外の場合、この値は無視されます。

sessMax (IN)

セッション・プールでオープンできる最大セッション数を指定します。最大数に達すると、追加のセッションはオープンしません。有効な値は1以上です。

sessIncr (IN)

現行のセッション数がsessMax未満の場合、アプリケーションでは、開始するセッションに次回の増分を設定できます。有効な値は0 (ゼロ)以上です。

sessMin + sessIncrがsessMaxを超えることはできません。

userid (IN)

セッションを開始するために使用するユーザーIDを指定します。

関連項目:
「認証に関する注意」

useridLen (IN)

バイトで示したユーザーIDの長さです。

password (IN)

ユーザーIDに対応するパスワードです。

passwordLen (IN)

バイトで示したパスワードの長さです。

mode (IN)

次のモードがサポートされています。

- OCI_DEFAULT - 新しいセッション・プールを作成します。

- OCI_SPC_REINITIALIZE - セッション・プールの作成後、プール属性を動的に変更する(sessMin、sessMaxおよびsessIncrパラメータを変更する)場合は、modeをOCI_SPC_REINITIALIZEに設定してOCISessionPoolCreate()をコールします。modeがOCI_SPC_REINITIALIZEに設定されている場合、connStr、useridおよびpasswordは無視されます。

- OCI_SPC_STMTCACHE - セッション・プール用にOCIの文キャッシュが作成されます。OCIの文キャッシュを使用可能にしてプールが作成されていない場合は、サーバー側の文キャッシュが自動的に使用されます。通常、クライアント側の文キャッシュを使用した方がパフォーマンスが向上することに注意してください。

関連項目:
「OCIでの文キャッシュ」

- OCI_SPC_HOMOGENEOUS - プール内のすべてのセッションは、OCISessionPoolCreate()に渡されるユーザー名とパスワードを使用して認証されます。この場合、OCISessionGet()に渡される認証ハンドル(authInfopパラメータ)は無視されます。sessMinおよびSessIncrの値は、この場合のみ使用されます。このモードでは、プロキシ・セッションは作成できません。このモードはデータベース常駐接続プーリング(DRCP)で使用できます。

- OCI_SPC_NO_RLB - デフォルトでは、クライアントとサーバーにサポート機能があれば、セッション・プール内で実行時接続ロード・バランシングが有効化されます。これをオフにするには、OCISessionPoolCreate()の新しいモードであるOCI_SPC_NO_RLBモードを使用します。このモードを使用できるのは、プール作成時のみです。作成済のプールに対してこのモードを渡すと、ORA-24411エラーがスローされます。

コメント

認証に関する注意

セッション・プールでは、データベースへの接続として、ダイレクト接続とプロキシ接続の2通りの接続があります。プロキシ接続を行う場合、ユーザーにはConnect through Proxy権限が必要です。

関連項目:
プロキシ接続の詳細は、次を参照してください。

- 「プロキシ経由のクライアント・アクセス」

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

- 『Oracle Database概要』

セッション・プールの作成時に、useridおよびpasswordを指定する場合と指定しない場合があります。これらの値がNULLの場合は、このプールでプロキシ接続を行うことができません。modeをOCI_SPC_HOMOGENEOUSに設定した場合は、プロキシ接続を行うことができません。

useridとpasswordのペアは、OCISessionGet()コールの認証ハンドルを使用して指定することもできます。modeをOCI_SESSGET_CREDPROXYに設定してこの関数をコールした場合、ユーザーには、OCISessionGet()コールで提供されたuseridによって認証されるセッションが、OCISessionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。この場合、OCISessionGet()コールのパスワードは無視されます。

modeをOCI_SESSGET_CREDPROXYに設定しないでOCISessionGet()をコールした場合、ユーザーは、OCISessionGet()コールで提供された資格証明によって認証されるダイレクト・セッションを取得します。このコールで資格証明が提供されなかった場合、ユーザーは、OCISessionPoolCreate()コールの資格証明によって認証されるセッションを取得します。

例

例16-6は、実行時ロード・バランシングが無効化する方法を示しています。

例16-6 実行時ロード・バランシングの無効化

OCISessionPoolCreate(envhp, errhp, spoolhp, (OraText **)&poolName,
(ub4 *)&poolNameLen,
database, (ub4) strlen ((const signed char *) database),
sessMin, sessMax, sessIncr, (OraText *) appusername,
(ub4) strlen ((const signed char *) appusername),
(OraText *) apppassword,
(ub4) strlen ((const signed char *) apppassword),
OCI_SPC_HOMOGENEOUS | OCI_SPC_NO_RLB);

関連関数

OCISessionRelease()、OCISessionGet()、OCISessionPoolDestroy()

OCISessionPoolDestroy()

用途

セッション・プールを破棄します。

構文

sword OCISessionPoolDestroy ( OCISPool     *spoolhp,
OCIError     *errhp,
ub4          mode );

spoolhp (IN/OUT)

破棄するセッション・プールのセッション・プール・ハンドルです。

errhp (IN/OUT)

OCIErrorGet()に渡すことができるエラー・ハンドルです。

mode (IN)

現在、OCISessionPoolDestroy()がサポートするモードはOCI_DEFAULTおよびOCI_SPD_FORCEです。

modeをOCI_SPD_FORCEに設定してこの関数をコールし、アクティブなセッションがプール内に存在する場合、そのセッションはクローズし、プールは破棄されます。ただし、このモードを設定せず、ビジーなセッションがプール内に存在する場合は、エラーが戻されます。

関連関数

OCISessionPoolCreate()、OCISessionRelease()、OCISessionGet()

OCISessionRelease()

用途

OCISessionGet()を使用して取得したセッションを解放します。このコールの動作は、対応するOCISessionGet()関数をコールしたときのmodeによって決まります。デフォルトでは、この関数は、セッションまたは接続をクローズします。接続プーリングの場合、この関数は、セッションをクローズして接続をプールに戻します。セッション・プーリングの場合、この関数は、セッションと接続のペアをプールに戻し、保留状態のトランザクションがコミットされます。

構文

sword OCISessionRelease ( OCISvcCtx       *svchp,
OCIError        *errhp,
OraText         *tag,
ub4             tag_len,
ub4             mode );

パラメータ

svchp (IN)

対応するOCISessionGet()のコール時に移入されたサービス・コンテキストです。

デフォルトでは、このハンドルに関連付けられたセッションおよび接続はクローズされます。

接続プーリングの場合は、セッションがクローズされ、接続がプールに対して解放されます。

セッション・プーリングの場合は、このサービス・コンテキストに関連付けられたセッションと接続のペアがプールに対して解放されます。

errhp (IN/OUT)

OCIエラー・ハンドルです。

tag (IN)

このパラメータは、セッション・プーリングでのみ使用します。

OCI_SESSRLS_RETAGモードが指定されていない場合、このパラメータは無視されます。その場合、セッションには、このタグを使用してラベルが付けられ、プールに戻されます。このパラメータがNULLの場合、セッションにタグは付けられません。

tag_len (IN)

このパラメータは、セッション・プーリングでのみ使用します。

タグの長さです。OCI_SESSRLS_RETAGモードが設定されていない場合、このパラメータは無視されます。

mode (IN)

次のモードがサポートされています。

- OCI_DEFAULT

- OCI_SESSRLS_DROPSESS

- OCI_SESSRLS_RETAG

接続プーリングの場合、デフォルトでは、OCI_DEFAULTのみ使用できます。

OCI_SESSRLS_DROPSESSおよびOCI_SESSRLS_RETAGは、セッション・プーリングでのみ使用できます。

OCI_SESSRLS_DROPSESSに設定すると、セッションはセッション・プールから削除されます。

OCI_SESSRLS_RETAGに設定した場合のみ、セッションのタグが変更されます。このモード以外に設定すると、tagパラメータおよびtag_lenパラメータは無視されます。

コメント

tagパラメータを使用する際には、正しいタグを渡すように注意してください。デフォルト・セッションが要求され、ユーザーが(ALTER SESSIONコマンドを使用して)そのセッションの特定のプロパティを設定する場合、ユーザーは、正しいタグを使用してこのセッションにラベルを付ける必要があります。

ただし、ユーザーがタグ付けされたセッションを要求して取得し、そのセッションのプロパティを変更した場合、ユーザーは、別のタグ(ある場合)を渡す必要があります。

セッション・プール・レイヤーで正しく処理が実行されるために、アプリケーション開発者は、正しいタグをOCISessionGet()コールおよびOCISessionRelease()コールに渡すように注意してください。

関連関数

OCISessionGet()、OCISessionPoolCreate()、OCISessionPoolDestroy()、OCILogon2()

OCITerminate()

用途

共有メモリー・サブシステムからプロセスを連結解除して共有メモリーを解放します。

構文

sword OCITerminate ( ub4    mode);

パラメータ

mode (IN)

コール固有モードです。有効な値は次のとおりです。

- OCI_DEFAULT - デフォルトのコールを実行します。

コメント

OCITerminate()は、プロセスごとに一度だけコールする必要があり、これはOCIEnvCreate()、OCIEnvNlsCreate()および非推奨OCIInitialize()コールと同等のものです。このコールは、共有メモリー・サブシステムからのプロセスのデタッチおよび停止を試みます。また、追加のプロセス・クリーンアップ操作も実行します。同じ共有メモリーに接続している2つ以上のプロセスが同時にOCITerminate()をコールした場合、最も速かったコールにより共有メモリー・サブシステムが完全に解放され、その後のコールは終了されます。

関連関数

OCIInitialize()、OCIEnvCreate()、OCIEnvNlsCreate()

ハンドル関数および記述子関数

表16-3は、この項で説明しているOCIハンドル関数および記述子関数を示しています。

表16-3 ハンドル関数および記述子関数

関数

用途

「OCIArrayDescriptorAlloc()」

記述子の配列を割り当てます。

「OCIArrayDescriptorFree()」

記述子の配列を解放します。

「OCIAttrGet()」

ハンドルの属性値を取得します。

「OCIAttrSet()」

ハンドルまたは記述子の属性値を設定します。

「OCIDescriptorAlloc()」

記述子またはLOBロケータの割当てと初期化を行います。

「OCIDescriptorFree()」

割当て済の記述子を解放します。

「OCIHandleAlloc()」

ハンドルの割当てと初期化を行います。

「OCIHandleFree()」

割当て済のハンドルを解放します。

「OCIParamGet()」

パラメータ記述子を取得します。

「OCIParamSet()」

CORハンドルにパラメータ記述子を設定します。

OCIArrayDescriptorAlloc()

用途

記述子の配列を割り当てます。

構文

sword OCIArrayDescriptorAlloc ( const  void   *parenth,
void          **descpp,
const ub4     type,
ub4           array_size,
const size_t  xtramem_sz,
void          **usrmempp);

パラメータ

parenth (IN)

環境ハンドルです。

descpp (OUT)

必要な型を持つ記述子の連続配列へのポインタを戻します。

type (IN)

割り当てられる記述子またはLOBロケータの型を指定します。型のリストは、「OCIDescriptorAlloc()」を参照してください。

array_size (IN)

割り当てる記述子の数を指定します。指定した数の記述子をコールで割り当てることができなければ、エラーがスローされます。

xtramem_sz (IN)

記述子の存続期間中アプリケーションで使用するために割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

記述子の存続期間中コールによってユーザー用に割り当てられた、サイズxtramem_szのユーザー・メモリーのポインタを戻します。

コメント

このコールは、成功した場合はOCI_SUCCESSを、メモリー不足条件が発生した場合は該当するエラーを戻します。

関連項目:
xtramem_szパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください。

例

例16-7を変更して、多数の記述子を割り当てることができます。

例16-7 多数の記述子の割当て

OCIDateTime *descpp1[500];
...
for (i = 0; i!=500; i++)
{
/* Allocate descriptors */
OCIDescriptorAlloc((void  *)envhp,(void  **)&descpp1[i], OCI_DTYPE_TIMESTAMP_TZ,
0,(void  **)0);
}
...

例16-7のforループは、例16-8に示すように、単一コールで置き換えることができます。

例16-8 記述子の配列のを割当て

OCIArrayDescriptorAlloc((void *)envhp,(void **)&descpp1,
OCI_DTYPE_TIMESTAMP_TZ, 500, 0, (void **)0);

関連関数

OCIDescriptorAlloc()、OCIArrayDescriptorFree()

OCIArrayDescriptorFree()

用途

前に割り当てた記述子の配列を解放します。

構文

sword OCIArrayDescriptorFree ( void       **descp,
const ub4  type );

パラメータ

descp (IN)

割当済記述子の配列へのポインタです。

type (IN)

解放する記憶域の型を指定します。「OCIDescriptorAlloc()」に示す型を参照してください。

コメント

記述子を割り当てるときにOCIDescriptorAlloc()を使用しても、解放するときにOCIArrayDescriptorFree()を使用すると、エラーが戻されます。

OCIArrayDescriptorAlloc()を使用して割り当てた記述子は、OCIArrayDescriptorFree()を使用して解放する必要があります。配列全体を一度に解放する場合は注意してください。OCIArrayDescriptorAlloc()で戻されたポインタdescppをOCIArrayDescriptorFree()に適切に渡します。そうしない場合、メモリーがリークすることがあります。

関連関数

OCIArrayDescriptorAlloc()

OCIAttrGet()

用途

ハンドルの属性値を取得します。

構文

sword OCIAttrGet ( const void     *trgthndlp,
ub4            trghndltyp,
void           *attributep,
ub4            *sizep,
ub4            attrtype,
OCIError       *errhp );

パラメータ

trgthndlp (IN)

ハンドル・タイプのポインタです。実際のハンドルは、文ハンドルやセッション・ハンドルなどの場合があります。このコールによってエンコーディングを取得すると、ユーザーは環境ハンドルまたは文ハンドルと照合してチェックできます。

trghndltyp (IN)

ハンドル・タイプです。次の型が有効です。

- OCI_DTYPE_PARAM、パラメータ記述子用

- OCI_HTYPE_STMT、文ハンドル用

- 表2-1の任意のハンドル・タイプ、または表2-2の任意の記述子。

attributep (OUT)

属性値の格納場所へのポインタです。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングです。

sizep (OUT)

attributepがvoidポインタであるため、属性値のサイズは常にバイト単位です。文字列以外の属性のサイズはOCIライブラリですでに認識されているため、ほとんどの属性に対してNULLで渡すことができます。text*パラメータの場合は、ub4へのポインタを渡して文字列の長さを取得する必要があります。

attrtype (IN)

取り出される属性のタイプです。ハンドル・タイプとその読取り可能な属性は、付録Aにリストされています。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

このコールは、ハンドルの特定の属性を取得するときに使用します。OCI_DTYPE_PARAMは暗黙的におよび明示的に記述する場合に使用します。このパラメータ記述子は、ダイレクト・パス・ロードでも使用します。暗黙的な記述の場合、パラメータ記述子には選択リストごとに列記述があります。明示的な記述の場合、パラメータ記述子には記述する各スキーマ・オブジェクトについての記述情報が含まれています。トップレベル・パラメータ記述子にそれ自体が記述子となる属性がある場合、OCIAttrGet()への後続コールで属性の型としてOCI_ATTR_PARAMを使用し、環境ハンドルまたは文ハンドルのUnicode情報を取得します。

関連項目:
「OCIDescribeAny()の使用例」および「選択リスト項目の記述」

OCIAttrGet()に密接に関連している関数はOCIDescribeAny()で、この関数は、表、ビュー、シノニム、プロシージャ、ファンクション、パッケージ、順序および型などの既存のスキーマ・オブジェクトを記述する汎用的な記述コールです。このコールは、OCIAttrGet()コールを使用して取得できるオブジェクト固有の属性を記述ハンドルに移入します。

次に、この記述ハンドルに対するOCIParamGet()コールによって、指定位置のパラメータ記述子が戻されます。パラメータ位置は1から開始します。パラメータ記述子に対してOCIAttrGet()をコールすると、ストアド・プロシージャまたはファンクション・パラメータの特定の属性、あるいは表の列記述子が戻されます。OCIDescribeAny()によってスキーマ・オブジェクト記述全体がクライアント側にキャッシュされているため、これらの後続コールは、サーバーへのラウンドトリップを別に行う必要がありません。記述ハンドルに対するOCIAttrGet()コールによって、位置の総数も戻すことができます。

特にUTF-16モードでループを実行する場合は、属性に対応している同じポインタ変数を再利用し、OCIAttrGet()のコール後にその内容をローカル変数にコピーしてください。複数のポインタを同じ属性に使用すると、メモリー・リークが発生する可能性があります。

関連関数

OCIAttrSet()

OCIAttrSet()

用途

ハンドルまたは記述子の属性値を設定します。

構文

sword OCIAttrSet ( void        *trgthndlp,
ub4         trghndltyp,
void        *attributep,
ub4         size,
ub4         attrtype,
OCIError    *errhp );

パラメータ

trgthndlp (IN/OUT)

その属性が変更されるハンドルのポインタです。

trghndltyp (IN/OUT)

ハンドル・タイプです。

attributep (IN)

属性値のポインタです。この属性値がターゲット・ハンドルにコピーされます。属性値がポインタの場合は、そのポインタのみがコピーされ、ポインタの内容はコピーされません。文字列属性は、OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

size (IN)

属性値のサイズです。サイズはOCIライブラリですでにわかっているため、ほとんどの属性に対して0 (ゼロ)で渡すことができます。text*属性では、エンコーディングに関係なく、バイト単位で文字列の長さを設定するためにub4で渡す必要があります。

attrtype (IN)

設定される属性のタイプです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

ハンドル・タイプとその書込み可能な属性については、付録Aのリストを参照してください。

関連関数

OCIArrayDescriptorAlloc()

OCIDescriptorAlloc()

用途

記述子またはLOBロケータを格納する記憶域を割り当てます。

構文

sword OCIDescriptorAlloc ( const void    *parenth,
void          **descpp,
ub4           type,
size_t        xtramem_sz,
void          **usrmempp);

パラメータ

parenth (IN)

環境ハンドルです。

descpp (OUT)

目的の型の記述子またはLOBロケータを戻します。

type (IN)

割り当てられる記述子またはLOBロケータの型を指定します。

- OCI_DTYPE_SNAP - C型のスナップショット記述子OCISnapshotの生成を指定します。

- OCI_DTYPE_LOB - C型のLOB値型ロケータ(BLOBまたはCLOBの場合) OCILobLocatorの生成を指定します。

- OCI_DTYPE_FILE - C型のFILE値型ロケータOCILobLocatorの生成を指定します。

- OCI_DTYPE_ROWID - C型のROWID記述子OCIRowidの生成を指定します。

- OCI_DTYPE_DATE - C型のANSI DATE記述子OCIDateTimeの生成を指定します。

- OCI_DTYPE_PARAM - C型の読取り専用パラメータ記述子OCIParamの生成を指定します。

- OCI_DTYPE_TIMESTAMP - C型のTIMESTAMP記述子OCIDateTimeの生成を指定します。

- OCI_DTYPE_TIMESTAMP_TZ - C型のTIMESTAMP WITH TIME ZONE記述子OCIDateTimeの生成を指定します。

- OCI_DTYPE_TIMESTAMP_LTZ - C型のTIMESTAMP WITH LOCAL TIME ZONE記述子OCIDateTimeの生成を指定します。

- OCI_DTYPE_INTERVAL_YM - C型のINTERVAL YEAR TO MONTH記述子OCIIntervalの生成を指定します。

- OCI_DTYPE_INTERVAL_DS - C型のINTERVAL DAY TO SECOND記述子OCIIntervalの生成を指定します。

- OCI_DTYPE_COMPLEXOBJECTCOMP - C型の複合オブジェクト検索記述子OCIComplexObjectCompの生成を指定します。

- OCI_DTYPE_AQENQ_OPTIONS - C型のアドバンスト・キューイング・エンキュー・オプション記述子OCIAQEnqOptionsの生成を指定します。

- OCI_DTYPE_AQDEQ_OPTIONS - C型のアドバンスト・キューイング・デキュー・オプション記述子OCIAQDeqOptionsの生成を指定します。

- OCI_DTYPE_AQMSG_PROPERTIES - C型のアドバンスト・キューイング・メッセージ・プロパティ記述子OCIAQMsgPropertiesの生成を指定します。

- OCI_DTYPE_AQAGENT - C型のアドバンスト・キューイング・エージェント記述子OCIAQAgentの生成を指定します。

- OCI_DTYPE_AQNFY - C型のアドバンスト・キューイング通知記述子OCIAQNotifyの生成を指定します。

- OCI_DTYPE_AQLIS_OPTIONS - C型のアドバンスト・キューイング・リスニング記述子OCIAQListenOptsの生成を指定します。

- OCI_DTYPE_AQLIS_MSG_PROPERTIES - C型のアドバンスト・キューイング・メッセージ・プロパティ記述子OCIAQLisMsgPropsの生成を指定します。

- OCI_DTYPE_SRVDN - C型の識別名記述子OCIServerDNsの生成を指定します。

- OCI_DTYPE_UCB - C型のユーザー・コールバック記述子OCIUcbの生成を指定します。

xtramem_sz (IN)

記述子の存続期間中アプリケーションで使用するために割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

記述子の存続期間中コールによってユーザー用に割り当てられた、サイズxtramem_szのユーザー・メモリーのポインタを戻します。

コメント

typeで指定された型に対応する、割当ておよび初期化済の記述子のポインタを戻します。成功した場合は、非NULL記述子またはLOBロケータが戻ります。エラー発生時に診断は利用できません。

このコールは、成功した場合はOCI_SUCCESSを、メモリー不足エラーが発生した場合はOCI_INVALID_HANDLEを戻します。

関連項目:
xtramem_szパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください。

関連関数

OCIDescriptorFree()、OCIArrayDescriptorAlloc()、OCIArrayDescriptorFree()

OCIDescriptorFree()

用途

割当て済記述子の割当てを解除します。

構文

sword OCIDescriptorFree ( void     *descp,
ub4      type );

パラメータ

descp (IN)

割り当てられた記述子です。

type (IN)

解放する記憶域の型を指定します。「OCIDescriptorAlloc()」に示す型を参照してください。

コメント

このコールにより、記述子に対応付けられた記憶域が解放されます。OCI_SUCCESSまたはOCI_INVALID_HANDLEを戻します。記述子はすべて明示的に割当てを解除できますが、環境ハンドルの割当てを解除すると、OCIで記述子の割当てが解除されます。

関連関数

OCIDescriptorAlloc()

OCIHandleAlloc()

用途

割当ておよび初期化済ハンドルのポインタを戻します。

構文

sword OCIHandleAlloc ( const void    *parenth,
void          **hndlpp,
ub4           type,
size_t        xtramem_sz,
void          **usrmempp );

パラメータ

parenth (IN)

環境ハンドルです。

hndlpp (OUT)

ハンドルを戻します。

type (IN)

割り当てられるハンドルの型を指定します。使用可能なハンドルについては、表2-1で説明しています。

xtramem_sz (IN)

割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

コールによりユーザーに割り当てられた、サイズxtramem_szのユーザー・メモリーのポインタを戻します。

コメント

typeで指定された型に対応する、割当ておよび初期化済のハンドルのポインタを戻します。成功時には非NULLハンドルが戻ります。すべてのハンドルが、親ハンドルとして渡される環境ハンドルと対応付けて割り当てられます。

エラー発生時に診断は利用できません。このコールは、成功した場合はOCI_SUCCESSを、エラーが発生した場合はOCI_INVALID_HANDLEを戻します。

ハンドルは、OCIコールに渡す前にOCIHandleAlloc()を使用して割り当てる必要があります。

関連項目:
ユーザー・メモリー割当て用のxtramem_szパラメータの使用方法の詳細は、「ユーザー・メモリーの割当て」を参照してください。

関連関数

OCIHandleFree()

OCIHandleFree()

用途

このコールは、ハンドルの割当てを明示的に解除します。

構文

sword OCIHandleFree ( void      *hndlp,
ub4       type );

パラメータ

hndlp (IN)

OCIHandleAlloc()により割り当てられるハンドルです。

type (IN)

解放する記憶域の型を指定します。ハンドルについては、表2-1で説明しています。

コメント

このコールは、ハンドルに対応付けられている記憶域で、typeパラメータに指定された型に該当するものを解放します。

このコールは、OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERRORを戻します。

ハンドルはすべて明示的に割当て解除できます。OCIでは、親ハンドルの割当てを解除すると、子ハンドルの割当てが自動的に解除されます。

文ハンドルが解放されると、文ハンドルに関連付けられたカーソルがクローズされますが、実際のカーソルのクローズはサーバーへの次回のラウンドトリップまで延期されます。アプリケーションによりカーソルを即時にクローズする必要がある場合、OCIHandleFree()コールの後にOCIServerVersion()またはOCIPing()などのサーバー・ラウンドトリップ・コールを実行できます。

関連関数

OCIHandleAlloc()

OCIParamGet()

用途

記述ハンドルまたは文ハンドル内の指定位置にあるパラメータの記述子を戻します。

構文

sword OCIParamGet ( const void        *hndlp,
ub4               htype,
OCIError          *errhp,
void              **parmdpp,
ub4               pos );

パラメータ

hndlp(IN)

文ハンドルまたは記述ハンドルです。OCIParamGet()関数は、このハンドル用のパラメータ記述子を戻します。

htype (IN)

hndlpパラメータに渡されるハンドルの型です。次の型が有効です。

- OCI_DTYPE_PARAM、パラメータ記述子用

- OCI_HTYPE_COMPLEXOBJECT、複合オブジェクト検索ハンドル用

- OCI_HTYPE_STMT、文ハンドル用

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

parmdpp (OUT)

ハンドル・タイプOCI_DTYPE_PARAMの、posパラメータで指定された位置におけるパラメータの記述子です。

pos (IN)

文ハンドルまたは記述ハンドルにおける位置番号です。この位置にあるパラメータ記述子が戻ります。

注意:
指定位置にパラメータ記述子がない場合は、OCI_ERRORが戻されます。

コメント

このコールは、記述ハンドルまたは文ハンドル内の指定位置にあるパラメータの記述子を戻します。パラメータ記述子は、常にOCIライブラリによって内部的に割り当てられます。また、OCIDescriptorFree()を使用して解放できます。たとえば、文を実行するたびに同じ列のメタデータをフェッチする場合は、OCIParamGet()の各コール間でパラメータ記述子を明示的に解放しないかぎり、プログラムではメモリーがリークします。

関連項目:
パラメータ記述子の属性の詳細は、付録Aを参照してください。

関連関数

OCIArrayDescriptorAlloc()、OCIAttrSet()、OCIParamSet()、OCIDescriptorFree()

OCIParamSet()

用途

CORハンドルへの複合オブジェクト検索(COR)記述子を設定します。

構文

sword OCIParamSet ( void           *hndlp,
ub4            htype,
OCIError       *errhp,
const void     *dscp,
ub4            dtyp,
ub4            pos );

パラメータ

hndlp (IN/OUT)

ハンドル・ポインタです。

htype (IN)

ハンドル・タイプです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

dscp (IN)

複合オブジェクト検索記述子ポインタです。

dtyp (IN)

記述子型です。COR記述子の型は、OCI_DTYPE_COMPLEXOBJECTCOMPです。

pos (IN)

位置番号です。

コメント

CORハンドルにはOCIHandleAlloc()を、記述子にはOCIDescriptorAlloc()を使用して、それぞれ前もって割り当てておく必要があります。記述子の属性は、OCIAttrSet()を使用して設定します。

関連項目:
複合オブジェクト検索の詳細は、「複合オブジェクト検索」を参照してください。

関連関数

OCIParamGet()

バインド関数、定義関数および記述関数

表16-4は、この項で説明しているバインド関数、定義関数および記述関数を示しています。

表16-4 バインド関数、定義関数および記述関数

関数

用途

「OCIBindArrayOfStruct()」

静的配列バインド用のスキップ・パラメータを設定します。

「OCIBindByName()」

名前によりバインドします。

「OCIBindByPos()」

位置によりバインドします。

「OCIBindDynamic()」

OCI_DATA_AT_EXECモードでバインドした後、追加属性を設定します。

「OCIBindObject()」

名前付きデータ型のバインド用の追加属性を設定します。

「OCIDefineArrayOfStruct()」

静的配列定義用の追加属性を設定します。

「OCIDefineByPos()」

出力変数の関連性を定義します。

「OCIDefineDynamic()」

OCI_DYNAMIC_FETCHモードでの定義用の追加属性を設定します。

「OCIDefineObject()」

名前付きデータ型の定義用の追加属性を設定します。

「OCIDescribeAny()」

既存のスキーマ・オブジェクトを記述します。

「OCIStmtGetBindInfo()」

バインドおよびインジケータ変数名とハンドルを取得します。

OCIBindArrayOfStruct()

用途

静的配列バインド用のスキップ・パラメータを設定します。

構文

sword OCIBindArrayOfStruct ( OCIBind     *bindp,
OCIError    *errhp,
ub4         pvskip,
ub4         indskip,
ub4         alskip,
ub4         rcskip );

パラメータ

bindp (IN/OUT)

バインド構造体へのハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

pvskip (IN)

次のデータ値用のスキップ・パラメータです。

indskip (IN)

次のインジケータ値または構造体のためのスキップ・パラメータです。

alskip (IN)

次の実際の長さ値のためのスキップ・パラメータです。

rcskip (IN)

次の列レベルのリターン・コード値のためのスキップ・パラメータです。

コメント

このコールは、静的配列バインドに必要なスキップ・パラメータを設定します。これは、OCIBindByName()またはOCIBindByPos()の後続コールです。初期バインド・コールによって戻されたバインド・ハンドルがOCIBindArrayOfStruct()コールのパラメータとして使用されます。

関連項目:
スキップ・パラメータの詳細は、「OCIでの構造体配列のバインドと定義」を参照してください。

関連関数

OCIBindByName()、OCIBindByPos()

OCIBindByName()

用途

プログラム変数とSQL文またはPL/SQLブロック内のプレースホルダを関連付けます。

構文

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 );

パラメータ

stmtp (IN/OUT)

処理中のSQLまたはPL/SQL文への文ハンドルです。

bindpp (IN/OUT)

このコールによって暗黙的に割り当てられるバインド・ハンドルのポインタを保存するポインタです。この特定の入力値に対するバインド情報はすべて、このバインド・ハンドルによってメンテナンスされます。このコールのデフォルトのエンコーディングは、modeパラメータに異なる値がないかぎり、stmtpでのUTF-16の設定に依存します。ハンドルは、文ハンドルの割当てが解除されたときに暗黙的に解放されます。入力時には、このポインタの値はNULLまたは有効なバインド・ハンドルにしてください。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

placeholder (IN)

文ハンドルに関連付けられている文内の変数にマップされ、名前で指定するプレースホルダです。placeholderのエンコーディングは、環境のエンコーディングと常に整合性が保たれている必要があります。つまり、文がUTF-16で準備された場合は、プレースホルダも同様にします。プレースホルダは、文字列型パラメータとして(text *)でキャストし、NULLで終了させる必要があります。

placeh_len (IN)

エンコーディングに関係なく、placeholderにバイト数で指定された名前の長さです。

valuep (IN/OUT)

データ値へのポインタまたはdtyパラメータで指定された型のデータ値の配列です。OCIAttrSet()関数をコールして、OCI_ATTR_CHARSET_IDをOCI_UTF16ID (または非推奨のOCI_UCS2ID)として設定した場合、このデータはUTF-16 (以前の名はUCS-2)文字列になることがあります。OCI_UTF16IDは、OCI_UCS2IDに代わる新しい指定です。

さらに、OCIStmtPrepare()で説明したように、ユーザーがOCIAttrSet()をコールして、バインド・ハンドル用に設定された文字を手動でリセットしないかぎり、valuep文字列型のデフォルト・エンコーディングは、OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングになります。

関連項目:
「バインド・ハンドル属性」

データ値配列は、PL/SQL表にマップする、またはSQL複数行操作用のデータを提供するために指定できます。バインド値配列が提供された場合、これはOCI用語では配列バインドと呼ばれます。

SQLT_NTYまたはSQLT_REFバインドの場合、valuepパラメータは無視されます。OUTバッファへのポインタは、OCIBindObject()によって初期化されるpgvppパラメータ内に設定されます。

modeがOCI_IOVに設定されている場合は、OCIIOV構造体のベース・アドレスを渡します。

value_sz (IN)

このバインド変数に対して、(valuepを使用して渡された)任意のデータ値の最大可能サイズ(バイト単位)です。このサイズは常にバイト単位のサイズになります。配列バインドの場合、これはalenpパラメータで指定される実際のサイズで可能な要素の最大サイズです。

クライアント・アプリケーションではサイズが不明な記述子、ロケータまたはREFの場合は、特定の型へのポインタのサイズ、たとえばsizeof (OCILobLocator *)などが使用されます。

モードがOCI_IOVの場合でも同様です。

dty (IN)

バインドされる値のデータ型です。名前付きデータ型(SQLT_NTY)とREF (SQLT_REF)は、アプリケーションがオブジェクト・モードで初期化されている場合のみ有効です。名前付きデータ型またはREFの場合は、バインド・ハンドルで追加コールを行い、データ型固有の属性を設定する必要があります。

indp (IN/OUT)

インジケータ変数または配列へのポインタです。SQLT_NTY以外のデータ型の場合は、sb2またはsb2の配列へのポインタです。

SQLT_NTYに対しては、このポインタは無視され、インジケータ構造体またはインジケータ構造体配列の実際のポインタが後続のコールOCIBindObject()で初期化されます。このパラメータは、動的バインドでは無視されます。

関連項目:
「標識変数」

alenp (IN/OUT)

配列要素の実際の長さの配列へのポインタです。

OCIEnvNlsCreate() (推奨するOCI環境ハンドル作成インタフェース)を使用している場合、alenpの長さは、INバインドには一貫してバイト単位になり、OUTバインドにはバイト単位でレポートされます。SQLT_VCS (2バイトの長さの接頭辞)およびSQLT_LVC (4バイトの長さの接頭辞)の型で、長さの接頭辞に対しても、同じ処理が一貫して保持されます。UCS2またはNCHARの場合は、特別な例外はありません。

古いOCI環境ハンドル作成インタフェース(OCIEnvCreate()または非推奨のOCIEnvInit()のいずれか)を使用している場合、alenpの長さは、通常、バイト単位です。ただし、キャラクタ・セットがOCI_UC2ID (= OCI_UTF16ID)の場合、またはOCI_ATTR_CHAR_COUNT属性が対応するOCIBindハンドルで設定されている場合のみ、alenpの長さは、INバインドには文字単位になり、OUTバインドにも文字単位でレポートされます。SQLT_VCS (2バイトの長さの接頭辞)およびSQLT_LVC (4バイトの長さの接頭辞)の型で、長さの接頭辞に対して同じ処理が保持されます。

このパラメータは、動的バインドでは無視されます。

rcodep (OUT)

列レベルのリターン・コードの配列へのポインタです。このパラメータは、動的バインドでは無視されます。

maxarr_len (IN)

最大配列長パラメータ(ユーザーの配列で対応可能な要素の最大可能数)です。PL/SQL索引付き表バインド用にのみ使用します。

curelep (IN/OUT)

現行の配列長パラメータ(操作の実行前後の配列内の実際の要素の数へのポインタ)です。PL/SQL索引付き表バインド用にのみ使用します。

mode (IN)

コーディングの一貫性を確保するために、このパラメータは理論的にはOCIStmtPrepare()で使用される可能性のある3つの値すべてを受け入れることができます。バインド変数のエンコーディングは、この変数を含む文のエンコーディングと常に同じにする必要があるため、文のエンコーディング以外のエンコーディングを指定するとエラーが発生します。このため、modeで推奨される設定はOCI_DEFAULTです。この設定により、バインド変数で文と同じエンコーディングが指定されます。

次のモードが有効です。

- OCI_DEFAULT－ デフォルト・モード。文ハンドルstmtpは、親の環境ハンドルに指定されている内容を使用します。

- OCI_BIND_SOFT - ソフト・バインド・モード。このモードでは、コールのパフォーマンスが向上します。これが最初のバインドであるか、dtyまたはvalue_szのような一部の入力値が前のバインドから変更されている場合、このモードは無視されます。文が実行されていない場合は、エラーが戻されます。渡されたバインド・ハンドルが有効でない場合、予期しない動作が発生します。

- OCI_DATA_AT_EXEC - このモードが選択される場合、value_szパラメータは、実行時に提供可能なデータの最大サイズを定義します。アプリケーションは、OCIライブラリのランタイムINデータ・バッファをいつでも何回でも提供できる状態にしておく必要があります。ランタイム・データは、次の2つの方法のどちらかを使用して提供されます。

- OCIBindDynamic()への後続コールによって登録されるユーザー定義関数を使用するコールバック。

- OCIで提供されるコールを使用するポーリング・メカニズム。コールバックが定義されていない場合は、このモードになります。

関連項目:
OCI_DATA_AT_EXECモードの使用方法の詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

modeがOCI_DATA_AT_EXECに設定されているときは、メイン・コールでvaluep、indp、alenpおよびrcodepに値を指定しないでください。indpおよびalenpに対しては、0 (ゼロ)を渡してください。値は、OCIBindDynamic()を使用し、登録されているコールバック関数を介して指定してください。

- OCI_IOV - データの不連続アドレスをバインドします。valuepパラメータはOCIIOV *型である必要があります。

関連項目:
「複数バッファのバインドと定義」

割り当てたバッファは、不要になった際にクライアント側で解放する必要があります。

コメント

このコールは、基本バインド操作を実行するときに使用します。バインドは、プログラム変数のアドレスとSQL文またはPL/SQLブロック内のプレースホルダの関連付けを作成します。このバインド・コールは、バインドされるデータの型も指定し、実行時にデータを提供するメソッドも指示できます。

エンコーディングの決定は、文ハンドルの設定をデフォルトとして使用してバインド・ハンドルで行うか、modeパラメータを明示的に指定してその設定を上書きして行うことができます。

OCIBindByName()は、bindppパラメータによって指示されたバインド・ハンドルの暗黙的な割当ても行います。**bindppに非NULLポインタが渡されると、このポインタはOCIHandleAlloc()またはOCIBindByName()のコールで以前に割り当てられた有効なハンドルを指し示していると、OCIでは想定されます。

OCIアプリケーション内のデータは、プレースホルダに静的または動的にバインドできます。実行の直前にすべてのINバインド・データとOUTバインド・バッファが正しく定義された場合、バインドは静的になります。アプリケーションの要求によって、INバインド・データとOUTバインド・バッファが実行時にクライアント・ライブラリに提供された場合、バインドは動的になります。動的バインドを指定するには、このコールのmodeパラメータをOCI_DATA_AT_EXECに設定します。

関連項目:
動的バインドの詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

OCIBindByName()とOCIBindByPos()は、パラメータとしてバインド・ハンドルを取りますが、これはバインド・コールによって暗黙的に割り当てられます。アプリケーションでバインドしているすべてのプレースホルダに別個のバインド・ハンドルが割り当てられます。

特定のデータ型をバインドする際または入力データを特定の方法で処理する際に必要となる特定の属性を指定する場合は、次の追加バインド・コールが必要です。

- 構造体配列が使用されている場合、OCIBindArrayOfStruct()をコールして必要なスキップ・パラメータを設定してください。

- 実行時にデータが動的に提供されている場合、アプリケーションでユーザー定義のコールバック関数を使用するときにはOCIBindDynamic()をコールしてコールバックを登録します。

- alenpに64キロバイト(KB)を超える長さが必要な場合は、OCIBindDynamic()を使用します。

- 名前付きデータ型がバインドされている場合、OCIBindObject()をコールしてその他の必要情報を指定する必要があります。

- RETURNING句を含む文を使用する場合は、このコールの後にOCIBindDynamic()をコールする必要があります。

INバインドの場合、OCIStmtExecute()のコールの前に、配列の各要素、各要素の実際の長さ、および実際の配列長の値を設定する必要があります。

OUTバインドの場合、OCIStmtExecute()のコールの後で、配列の各要素、各要素の実際の長さ、および実際の配列長の値がサーバーから戻されます。

関連関数

OCIBindDynamic()、OCIBindObject()、OCIBindArrayOfStruct()

OCIBindByPos()

用途

プログラム変数とSQL文またはPL/SQLブロック内のプレースホルダを関連付けます。

構文

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 );

パラメータ

stmtp (IN/OUT)

処理中のSQLまたはPL/SQL文への文ハンドルです。

bindpp (IN/OUT)

このコールによって暗黙的に割り当てられるバインド・ハンドルのアドレスです。この特定の入力値に対するバインド情報はすべて、このバインド・ハンドルによってメンテナンスされます。ハンドルは、文ハンドルの割当てが解除されたときに暗黙的に解放されます。入力時には、このポインタの値はNULLまたは有効なバインド・ハンドルにしてください。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

position (IN)

OCIBindByPos()がコールされている場合、プレースホルダの属性が位置別に指定されます。

valuep (IN/OUT)

データ値のアドレスまたはdtyパラメータで指定されたタイプのデータ値配列です。データ値配列は、PL/SQL表にマップする、またはSQL複数行操作用のデータを提供するために指定できます。バインド値配列が提供された場合、これはOCI用語では配列バインドと呼ばれます。

LOBでは、バッファ・ポインタは、OCILobLocator型のLOBロケータのポインタにする必要があります。ポインタのアドレスを指定します。

SQLT_NTYまたはSQLT_REFバインドの場合、valuepパラメータは無視されます。OUTバッファへのポインタは、OCIBindObject()によって初期化されるpgvppパラメータ内に設定されます。

OCI_ATTR_CHARSET_ID属性がOCI_UTF16ID (下位互換性のために保持されている、非推奨になったOCI_UCS2IDの置換え)に設定されている場合は、対応するバインド・コールとの間で受渡しを行うデータは、すべてUTF-16エンコーディングとみなされます。

modeがOCI_IOVに設定されている場合は、OCIIOV構造体のベース・アドレスを渡します。

関連項目:
「バインド・ハンドル属性」

value_sz (IN)

このバインド変数に対して、(valuepを使用して渡された)任意のデータ値の最大可能サイズ(バイト単位)です。このサイズは常にバイト単位のサイズになります。配列バインドの場合、これはalenpパラメータで指定される実際のサイズで可能な要素の最大サイズです。

クライアント・アプリケーションではサイズが不明な記述子、ロケータまたはREFの場合は、特定の型へのポインタのサイズ、たとえばsizeof (OCILobLocator *)などが使用されます。

モードがOCI_IOVの場合でも同様です。

dty (IN)

バインドされる値のデータ型です。名前付きデータ型(SQLT_NTY)とREF (SQLT_REF)は、アプリケーションがオブジェクト・モードで初期化されている場合のみ有効です。名前付きデータ型またはREFの場合は、バインド・ハンドルで追加コールを行い、データ型固有の属性を設定する必要があります。

indp (IN/OUT)

インジケータ変数または配列へのポインタです。すべてのデータ型について、これはsb2またはsb2値の配列へのポインタです。唯一の例外はSQLT_NTYで、このポインタは無視され、インジケータ構造体またはインジケータ構造体配列への実際のポインタがOCIBindObject()で初期化されます。indpパラメータは、動的バインドでは無視されます。valuepがOUTパラメータである場合、OCI_IND_NULLを指し示すようにindpを設定する必要があります。

関連項目:
「標識変数」

alenp (IN/OUT)

配列要素の実際の長さの配列へのポインタです。

OCIEnvNlsCreate() (推奨するOCI環境ハンドル作成インタフェース)を使用している場合、alenpの長さは、INバインドには一貫してバイト単位になり、OUTバインドにはバイト単位でレポートされます。SQLT_VCS (2バイトの長さの接頭辞)およびSQLT_LVC (4バイトの長さの接頭辞)の型で、長さの接頭辞に対しても、同じ処理が一貫して保持されます。UCS2またはNCHARの場合は、特別な例外はありません。

古いOCI環境ハンドル作成インタフェース(OCIEnvCreate()または非推奨のOCIEnvInit()のいずれか)を使用している場合、alenpの長さは、通常、バイト単位です。ただし、キャラクタ・セットがOCI_UC2ID (= OCI_UTF16ID)の場合、またはOCI_ATTR_CHAR_COUNT属性が対応するOCIBindハンドルで設定されている場合のみ、alenpの長さは、INバインドには文字単位になり、OUTバインドにも文字単位でレポートされます。SQLT_VCS (2バイトの長さの接頭辞)およびSQLT_LVC (4バイトの長さの接頭辞)の型で、長さの接頭辞に対して同じ処理が保持されます。

このパラメータは、動的バインドでは無視されます。

rcodep (OUT)

列レベルのリターン・コードの配列へのポインタです。このパラメータは、動的バインドでは無視されます。

maxarr_len (IN)

最大配列長パラメータ(ユーザーの配列で対応可能な要素の最大可能数)です。PL/SQL索引付き表バインド用にのみ使用します。

curelep (IN/OUT)

現行の配列長パラメータ(操作の実行前後の配列内の実際の要素の数へのポインタ)です。PL/SQL索引付き表バインド用にのみ使用します。

mode (IN)

このパラメータに有効なモードは次のとおりです。

- OCI_DEFAULT－ これはデフォルト・モードです。

- OCI_BIND_SOFT - ソフト・バインド・モード。このモードでは、コールのパフォーマンスが向上します。これが最初のバインドであるか、dtyまたはvalue_szのような一部の入力値が前のバインドから変更されている場合、このモードは無視されます。文が実行されていない場合は、エラーが戻されます。渡されたバインド・ハンドルが有効でない場合、予期しない動作が発生します。

- OCI_DATA_AT_EXEC - このモードが選択される場合、value_szパラメータは、実行時に提供可能なデータの最大サイズを定義します。アプリケーションは、OCIライブラリのランタイムINデータ・バッファをいつでも何回でも提供できる状態にしておく必要があります。ランタイム・データは、次いずれかの方法で提供されます。

- OCIBindDynamic()への後続コールによって登録されるユーザー定義関数を使用するコールバック。

- OCIで提供されるコールを使用するポーリング・メカニズム。コールバックが定義されていない場合は、このモードになります。

関連項目:
OCI_DATA_AT_EXECモードの使用方法の詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

modeがOCI_DATA_AT_EXECに設定されているときは、メイン・コールでvaluep、indp、alenpおよびrcodepに値を指定しないでください。indpおよびalenpに対しては、0 (ゼロ)を渡してください。値は、OCIBindDynamic()を使用し、登録されているコールバック関数を介して指定してください。

- OCI_IOV - データの不連続アドレスをバインドします。valuepパラメータはOCIIOV *型である必要があります。

関連項目:
「複数バッファのバインドと定義」

割り当てたバッファは、不要になった際にクライアント側で解放する必要があります。

コメント

このコールは、基本バインド操作を実行するときに使用します。バインドは、プログラム変数のアドレスとSQL文またはPL/SQLブロック内のプレースホルダの関連付けを作成します。このバインド・コールは、バインドされるデータの型も指定し、実行時にデータを提供するメソッドも指示できます。

この関数は、bindppパラメータによって指示されたバインド・ハンドルの暗黙的な割当ても行います。**bindppに非NULLポインタが渡されると、このポインタはOCIHandleAlloc()またはOCIBindByPos()のコールで以前に割り当てられた有効なハンドルを指し示していると、OCIでは想定されます。

OCIアプリケーション内のデータは、プレースホルダに静的または動的にバインドできます。操作の実行の直前にすべてのINバインド・データとOUTバインド・バッファが正しく定義された場合、バインドは静的になります。アプリケーションの要求によって、INバインド・データとOUTバインド・バッファが実行時にクライアント・ライブラリに提供された場合、バインドは動的になります。動的バインドを指定するには、このコールのmodeパラメータをOCI_DATA_AT_EXECに設定します。

関連項目:
動的バインドの詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

OCIBindByName()とOCIBindByPos()は、パラメータとしてバインド・ハンドルを取りますが、これはバインド・コールによって暗黙的に割り当てられます。アプリケーションでバインドしているすべてのプレースホルダに別個のバインド・ハンドルが割り当てられます。

特定のデータ型をバインドする際または入力データを特定の方法で処理する際に必要となる特定の属性を指定する場合は、次の追加バインド・コールが必要です。

- 構造体配列が使用されている場合、OCIBindArrayOfStruct()をコールして必要なスキップ・パラメータを設定してください。

- 実行時にデータが動的に提供されている場合、アプリケーションでユーザー定義のコールバック関数を使用するときにはOCIBindDynamic()をコールしてコールバックを登録します。

- alenpに64KBを超える長さが必要な場合は、OCIBindDynamic()を使用します。

- 名前付きデータ型がバインドされている場合、OCIBindObject()をコールしてその他の必要情報を指定する必要があります。

- RETURNING句を含む文を使用する場合は、このコールの後にOCIBindDynamic()をコールする必要があります。

INバインドの場合、OCIStmtExecute()のコールの前に、配列の各要素、各要素の実際の長さ、および実際の配列長の値を設定する必要があります。

OUTバインドの場合、OCIStmtExecute()のコールの後で、配列の各要素、各要素の実際の長さ、および実際の配列長の値がサーバーから戻されます。

関連関数

OCIBindDynamic()、OCIBindObject()、OCIBindArrayOfStruct()

OCIBindDynamic()

用途

動的データ割当て用のユーザー・コールバックを登録します。

構文

sword OCIBindDynamic ( OCIBind     *bindp,
OCIError    *errhp,
void        *ictxp,
OCICallbackInBind         (icbfp)(
void             *ictxp,
OCIBind          *bindp,
ub4              iter,
ub4              index,
void             **bufpp,
ub4              *alenp,
ub1              *piecep,
void             **indpp ),
void             *octxp,
OCICallbackOutBind        (ocbfp)(
void             *octxp,
OCIBind          *bindp,
ub4              iter,
ub4              index,
void             **bufpp,
ub4              **alenpp,
ub1              *piecep,
void             **indpp,
ub2              **rcodepp ) );

パラメータ

bindp (IN/OUT)

OCIBindByName()またはOCIBindByPos()のコールにより戻されるバインド・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

ictxp (IN)

コールバック関数icbfpに必要なコンテキスト・ポインタです。

icbfp (IN)

実行時にINバインド値またはピースのポインタを戻すコールバック関数です。コールバックは、次のパラメータを取ります。

ictxp (IN/OUT)

このコールバック関数用のコンテキスト・ポインタです。

bindp (IN)

このバインド変数を一意に指定するために渡されたバインド・ハンドルです。

iter (IN)

0 (ゼロ)ベースの実行繰返し値。

index (IN)

カレント配列の索引(PL/SQLの配列バインド用)。SQLでは行の索引です。値は0 (ゼロ)以上、バインド・コールのcurelepパラメータ値以下です。

bufpp (OUT)

バッファまたは記憶域のポインタです。記述子の場合、*bufppにはその記述子へのポインタが含まれています。たとえば、次のパラメータを定義する場合、*bufppには*lobpではなくlobpを設定します。

OCILobLocator    *lobp;

REFの場合はそのアドレスを渡します。つまり、*bufppに対して&my_refを渡します。

OCI_ATTR_CHARSET_ID属性がOCI_UTF16ID (下位互換性のために保持されている、非推奨になったOCI_UCS2IDの置換え)に設定されている場合は、対応するバインド・コールとの間で受渡しを行うデータは、すべてUTF-16エンコーディングとみなされます。

関連項目:
「バインド・ハンドル属性」

alenp (OUT)

バインド値またはバインド・ピースを読み取った後に、OCIがそのサイズを書き込むための格納場所へのポインタです。記述子の場合、記述子へのポインタのサイズ、たとえばsizeof(OCILobLocator *)を渡します。

piecep (OUT)

バインド値のピースです。この値は、OCI_ONE_PIECE、OCI_FIRST_PIECE、OCI_NEXT_PIECEまたはOCI_LAST_PIECEのいずれかです。ピース単位の操作をサポートしていないデータ型の場合は、OCI_ONE_PIECEを渡す必要があります。そうしない場合、エラーが発生します。

indpp (OUT)

インジケータ値を含みます。これは、sb2値のポインタ、あるいは名前付きデータ型をバインドするインジケータ構造体のポインタです。

octxp (IN)

コールバック関数ocbfp()に必要なコンテキスト・ポインタです。

ocbfp (IN)

実行時にOUTバインド値またはピースのポインタを戻すコールバック関数です。コールバックは、次のパラメータを取ります。

octxp (IN/OUT)

このコールバック関数用のコンテキスト・ポインタです。

bindp (IN)

このバインド変数を一意に指定するために渡されたバインド・ハンドルです。

iter (IN)

0 (ゼロ)ベースの実行繰返し値。

index (IN)

カレント配列のPL/SQL用索引(配列バインド用)です。SQLの場合、カレント反復の行番号です。値は0 (ゼロ)以上、バインド・コールのcurelepパラメータ値以下です。

bufpp (OUT)

バインド値またはバインド・ピースを書き込むバッファのポインタ。

OCI_ATTR_CHARSET_ID属性がOCI_UTF16ID (下位互換性のために保持されている、非推奨になったOCI_UCS2IDの置換え)に設定されている場合は、対応するバインド・コールとの間で受渡しを行うデータは、すべてUTF-16エンコーディングとみなされます。詳細は、「バインド・ハンドル属性」を参照してください。

alenpp (IN/OUT)

バインド値またはバインド・ピースを読み取った後に、OCIがそのサイズを書き込むための格納場所へのポインタです。コード・ポイント内にあるときは、Unicodeエンコーディングの場合(OCI_ATTR_CHARSET_ID属性がOCI_UTF16IDに設定されている場合)を除いてバイト単位です。

piecep (IN/OUT)

コールバック(アプリケーション)からOracle Databaseへ、次のようにピース値を戻します。

- IN－値はOCI_ONE_PIECEまたはOCI_NEXT_PIECEです。

- OUT－INの値に応じて異なります。

- IN値がOCI_ONE_PIECEの場合、OUT値はOCI_ONE_PIECEまたはOCI_FIRST_PIECEです。

- IN値がOCI_NEXT_PIECEの場合、OUT値はOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

indpp (OUT)

インジケータ値を含みます。これは、sb2値のポインタ、あるいは名前付きデータ型をバインドするインジケータ構造体のポインタです。

rcodepp (OUT)

リターン・コードにポインタを戻します。

コメント

このコールは、OCIBindByName()またはOCIBindByPos()の以前のコールでOCI_DATA_AT_EXECモードが指定された場合に、データの用意または受取り用のユーザー定義コールバック関数を登録するときに使用されます。

コールバック関数ポインタは、コールが成功した場合にはOCI_CONTINUEを戻します。OCI_CONTINUE以外のリターン・コードは、クライアントが処理の即時終了を求めていることを示します。

関連項目:
OCI_DATA_AT_EXECモードの詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

記憶領域のアドレスを渡す際は、コールバックからアプリケーションが復帰した後も必ずその記憶領域が存在するようにしてください。したがって、このような記憶域はスタック上に割り当てないでください。

注意:
OCIEnvNlsCreate()を使用して環境ハンドルを作成すると、バインド・ハンドルおよび定義ハンドルの実際の長さと戻される長さは、常にバイト単位になります。

関連関数

OCIBindByName()、OCIBindByPos()

OCIBindObject()

用途

名前付きデータ型(オブジェクト)のバインドに必要な追加属性を設定します。

構文

sword OCIBindObject ( OCIBind          *bindp,
OCIError         *errhp,
const OCIType    *type,
void             **pgvpp,
ub4              *pvszsp,
void             **indpp,
ub4              *indszp, );

パラメータ

bindp (IN/OUT)

OCIBindByName()またはOCIBindByPos()のコールにより戻されるバインド・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

type (IN)

バインドされているプログラム変数の型を示すTDOを指し示します。OCITypeByName()をコールして取り出します。SQLのREFではオプションですが、PL/SQLのREFでは必須です。

pgvpp (IN/OUT)

プログラム変数バッファのアドレスです。配列では、pgvppはアドレス配列を示します。バインド変数がOUT変数でもある場合は、オブジェクト・キャッシュ内にOUT名前付きデータ型値またはREFが割り当てられ、REFが戻されます。

pgvppは、OCI_DATA_AT_EXECモードが設定されている場合、無視されます。名前付きデータ型バッファは、実行時に要求されます。静的配列バインドでは、OCIBindArrayOfStruct()コールを使用してスキップ係数を指定できます。スキップ係数は、値に対する次のポインタのアドレスおよびインジケータ構造体、各自のサイズを計算するために使用されます。

pvszsp (OUT) [オプション]

プログラム変数のサイズを指し示します。入力では、名前付きデータ型のサイズは必要ありません。配列の場合、pvszspはub4の配列です。OUTバインド変数の戻り時の場合、これは名前付きデータ型および受信したREFのサイズを指し示します。OCI_DATA_AT_EXECモードが設定されている場合、pvszspは無視されます。この場合、実行時にバッファのサイズが取得されます。

indpp (IN/OUT) [オプション]

パラレル・インジケータ構造体を含むプログラム変数バッファのアドレスです。配列では、indppはポインタ配列を示します。バインド変数がOUTバインド変数でもある場合は、オブジェクト・キャッシュにメモリーが割り当てられ、OUTインジケータ値が格納されます。すべてのOUT値が受け取られた実行操作終了時には、indppは、新たに割り当てられたこれらのインジケータ構造体のポインタを指し示します。SQLT_NTYバインドの場合のみ必要です。indppパラメータは、OCI_DATA_AT_EXECモードが設定されている場合、無視されます。この場合、インジケータは実行時に要求されます。

indszp (IN/OUT)

INインジケータ構造体プログラム変数のサイズを指し示します。配列の場合、sb2の配列です。OUTバインド変数の戻り時の場合、これは受信したOUTインジケータ構造体のサイズを指し示します。OCI_DATA_AT_EXECモードが設定されている場合、indszpは無視されます。この場合、インジケータのサイズは実行時に要求されます。

コメント

この関数は、名前付きデータ型またはREFをバインドする追加属性を設定します。OCI環境が非オブジェクト・モードで初期化されているときにこの関数をコールした場合は、エラーが戻ります。

このコールは、定義される名前付きデータ型用にデータ型OCITypeの型記述子オブジェクト(TDO)をパラメータとして取ります。TDOは、OCITypeByName()をコールして取り出すことができます。

OCIBindByName()またはOCIBindByPos()にOCI_DATA_AT_EXECモードが指定された場合、INバッファのポインタは、OCIBindDynamic()コールに登録されたコールバックicbfpを使用するか、OCIStmtSetPieceInfo()コールによって取得されます。

バッファはOUTデータに対して動的に割り当てられます。これらのバッファへのポインタは、次のいずれかの方法で戻されます。

- OCIBindDynamic()によって登録されたocbfp()をコールします。

- OCIStmtExecute()がOCI_NEED_DATAを戻したときにコールされたOCIStmtSetPieceInfo()によって渡されたバッファ内のバッファに対するポインタを設定します。

クライアント・ライブラリが割り当てたバッファのメモリーは、不要になったときにOCIObjectFree()コールを使用して解放する必要があります。

関連関数

OCIBindByName()、OCIBindByPos()

OCIDefineArrayOfStruct()

用途

構造体配列(複数行、複数列)のフェッチで使用される静的配列定義に必要な追加属性を指定します。

構文

sword OCIDefineArrayOfStruct ( OCIDefine   *defnp,
OCIError    *errhp,
ub4         pvskip,
ub4         indskip,
ub4         rlskip,
ub4         rcskip );

パラメータ

defnp (IN/OUT)

OCIDefineByPos()のコールにより戻された定義構造体のハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

pvskip (IN)

次のデータ値用のスキップ・パラメータです。

indskip (IN)

次のインジケータ位置のためのスキップ・パラメータです。

rlskip (IN)

次の戻り長さ値のためのスキップ・パラメータです。

rcskip (IN)

次のリターン・コードのためのスキップ・パラメータです。

コメント

このコールは、OCIDefineByPos()の後続コールです。アプリケーションでオブジェクトを含む構造体配列をバインドしている場合、最初にOCIDefineObject()をコールして、次にOCIDefineArrayOfStruct()をコールする必要があります。

関連項目:
「スキップ・パラメータ」

関連関数

OCIDefineByPos()、OCIDefineObject()

OCIDefineByPos()

用途

選択リスト内の項目を型と出力データ・バッファに関連付けます。

構文

sword OCIDefineByPos ( OCIStmt     *stmtp,
OCIDefine   **defnpp,
OCIError    *errhp,
ub4         position,
void        *valuep,
sb4         value_sz,
ub2         dty,
void        *indp,
ub2         *rlenp,
ub2         *rcodep,
ub4         mode );

パラメータ

stmtp (IN/OUT)

要求されたSQL問合せ操作へのハンドルです。

defnpp (IN/OUT)

定義ハンドルのポインタへのポインタです。このパラメータをNULLで渡すと、定義ハンドルが暗黙的に割り当てられます。再定義の場合は、非NULLハンドルをこのパラメータに渡すことができます。このハンドルは、この列用の定義情報を格納するために使用されます。

注意:
ユーザーはこのポインタを追跡する必要があります。同じ列位置に対する2回目のOCIDefineByPos()のコールでは、同じポインタが戻されるとはかぎりません。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

position (IN)

選択リストでのこの値の位置です。位置は1から始まり、左から右へ番号が振られます。値0 (ゼロ)の場合は、ROWID (表の1行のグローバル一意識別子)が選択されます。

valuep (IN/OUT)

dtyパラメータに指定されているタイプのバッファまたはバッファの配列のポインタです。単独のフェッチ・コールで複数の行をフェッチする場合は、複数のバッファを指定できます。

LOBでは、バッファ・ポインタは、OCILobLocator型のLOBロケータのポインタにする必要があります。ポインタのアドレスを指定します。

modeがOCI_IOVに設定されている場合は、OCIIOV構造体のベース・アドレスを渡します。

value_sz (IN)

各valuepバッファのバイト・サイズです。データがVARCHAR2形式で内部的に格納されている場合、必要な文字数がバイト単位のバッファ・サイズと異なるときは、OCIAttrSet()を使用して追加指定できます。

マルチバイト変換環境では、指定したバイト数が、処理する文字数に対して不十分な場合、切捨てエラーが発生します。

OCI_ATTR_CHARSET_ID属性がOCI_UTF16ID (下位互換性のために保持されている、非推奨になったOCI_UCS2IDの置換え)に設定されている場合は、対応する定義コールとの間で受渡しを行うデータは、すべてUTF-16エンコーディングとみなされます。

modeがOCI_IOVに設定されている場合は、データ値のサイズを渡します。

関連項目:
「バインド・ハンドル属性」

dty (IN)

データ型です。名前付きデータ型(SQLT_NTY)とREF (SQLT_REF)は、環境がオブジェクト・モードで初期化されている場合のみ有効です。

SQLT_CHRとSQLT_LNGをCLOB列に、SQLT_BINとSQLT_LBIをBLOB列に指定できます。

関連項目:
データ型コードおよび値については、第3章のリストを参照してください。

indp (IN)

インジケータ変数または配列へのポインタです。スカラー・データ型の場合は、sb2またはsb2の配列へのポインタです。SQLT_NTY定義の場合は無視されます。SQLT_NTY定義では、名前付きデータ型のインジケータ構造体または名前付きデータ型のインジケータ構造体配列のポインタは、後続のOCIDefineObject()コールによって関連付けられます。

関連項目:
「標識変数」

rlenp (IN/OUT)

フェッチされたデータの長さの配列のポインタです。

OCIEnvNlsCreate() (推奨するOCI環境ハンドル作成インタフェース)を使用している場合、rlenpの長さは、一貫してバイト単位でレポートされます。SQLT_VCS (2バイトの長さの接頭辞)およびSQLT_LVC (4バイトの長さの接頭辞)の型で、長さの接頭辞に対しても、同じ処理が一貫して保持されます。UCS2またはNCHARの場合は、特別な例外はありません。

古いOCI環境ハンドル作成インタフェース(OCIEnvCreate()または非推奨のOCIEnvInit()のいずれか)を使用している場合、rlenpの長さは、通常、バイト単位です。ただし、キャラクタ・セットがOCI_UC2ID (= OCI_UTF16ID)の場合、またはOCI_ATTR_CHAR_COUNT属性が対応するOCIBindハンドルで設定されている場合、rlenpの長さは文字単位でレポートされます。SQLT_VCS (2バイトの長さの接頭辞)およびSQLT_LVC (4バイトの長さの接頭辞)の型で、長さの接頭辞に対して同じ処理が保持されます。

rcodep (OUT)

列レベルのリターン・コードの配列のポインタです。

mode (IN)

次のモードが有効です。

- OCI_DEFAULT - これはデフォルトのモードです。

- OCI_DEFINE_SOFT - ソフト定義モード。このモードでは、コールのパフォーマンスが向上します。これが最初の定義であるか、dtyまたはvalue_szのような一部の入力パラメータが前の定義から変更されている場合、このモードは無視されます。無効な定義ハンドルが渡された場合、予期しない動作が発生します。文が実行されていない場合は、エラーが戻されます。

- OCI_DYNAMIC_FETCH - フェッチするときにデータを動的に割り当てる必要があるアプリケーションでは、このモードを使用する必要があります。OCIDefineDynamic()コールを使用したコールバックを定義できます。実行時に提供されるデータの最大サイズは、value_szパラメータによって定義されます。クライアント・ライブラリで、フェッチ済データを戻すためのバッファが必要な場合は、このコールバックが呼び出され、ピースまたはすべてのデータを戻すための実行時バッファが提供されます。

関連項目:
「ROWIDの暗黙的フェッチ」

- OCI_IOV - データの不連続アドレスを定義します。valuepパラメータはOCIIOV *型である必要があります。

関連項目:
「複数バッファのバインドと定義」

コメント

このコールは、Oracle Databaseから取り出されたデータを受け取る出力バッファを定義します。この定義は、SELECT文がOCIアプリケーションにデータを戻すときに必要なローカル・ステップです。

このコールは、選択リスト項目用の定義ハンドルの暗黙的な割当ても行います。*defnppに非NULLポインタが渡されると、このポインタはOCIHandleAlloc()またはOCIDefineByPos()のコールで以前に割り当てられた有効なハンドルを指し示していると、OCIでは想定されます。別のアドレスに対してハンドルを再定義しているアプリケーションの場合はこれがあてはまるため、複数のフェッチに同じ定義ハンドルを再利用できます。

列をフェッチするための属性の定義は、1つ以上のコールで実行されます。最初のコールは、フェッチを指定するために必要な最小限の属性を定義するOCIDefineByPos()です。

ある種のデータ型またはフェッチ・モードでは、OCIDefineByPos()のコールの後に、次の追加定義コールが必要です。

- 複数列を配列フェッチするためのスキップ・パラメータを設定するには、OCIDefineArrayOfStruct()のコールが必要です。

- 名前付きデータ型(つまり、オブジェクトやコレクション)またはREFのフェッチに適切な属性を設定するには、OCIDefineObject()のコールが必要です。この場合、OCIDefineByPos()内のデータ・バッファ・ポインタは無視されます。

- 名前付きデータ型の列を持つ複数行をフェッチするには、OCIDefineByPos()の後に、OCIDefineArrayOfStruct()とOCIDefineObject()の両方をコールする必要があります。

LOB定義では、バッファ・ポインタは、OCIDescriptorAlloc()コールによって割り当てられるOCILobLocator型のLOBロケータのポインタにしてください。LOB列には、LOBの値ではなく、常にLOBロケータが戻ります。LOB値は、フェッチしたロケータに対してOCI LOBコールを使用するとフェッチできます。これと同じ方式がすべての記述子データ型で適用されます。

NCHAR (固定長および可変長)では、バッファ・ポインタは、必要なNCHAR文字を保持するのに十分なバイト配列を指し示している必要があります。

ネストした表の列は、他のすべての名前付きデータ型と同じように定義およびフェッチされます。

記述子またはロケータの配列を定義するときに、記述子またはロケータのポインタ配列を渡す必要があります。

キャラクタ列の配列を定義するときに、文字バッファ配列を渡す必要があります。

このコールのmodeパラメータにOCI_DYNAMIC_FETCHが設定された場合は、クライアント・アプリケーションから実行時にデータを動的にフェッチできます。ランタイム・データは、次の2つの方法で用意できます。

- OCIDefineDynamic()の後続コールによって登録する必要があるユーザー定義関数を使用するコールバック。クライアント・ライブラリがフェッチしたデータを戻すためにバッファが必要になると、このコールバックが呼び出され、用意されたランタイム・バッファがデータの一部または全部を戻します。

- OCIで提供されるコールを使用するポーリング・メカニズム。コールバックが定義されていない場合は、このモードになります。この場合、フェッチ・コールによりOCI_NEED_DATAエラー・コードが戻され、データはピース単位のポーリング・メソッドで用意されます。

関連項目:

- OCI_DYNAMIC_FETCHモードの使用方法の詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

- 定義の詳細は、「OCIでの定義の概要」を参照してください。

- 「ROWIDの暗黙的フェッチ」

関連関数

OCIDefineArrayOfStruct()、OCIDefineDynamic()、OCIDefineObject()

OCIDefineDynamic()

用途

OCIDefineByPos()でOCI_DYNAMIC_FETCHモードが選択されたときに必要な追加属性を設定します。

構文

sword OCIDefineDynamic ( OCIDefine   *defnp,
OCIError    *errhp,
void        *octxp,
OCICallbackDefine       (ocbfp)(
void           *octxp,
OCIDefine      *defnp,
ub4            iter,
void           **bufpp,
ub4            **alenpp,
ub1            *piecep,
void           **indpp,
ub2            **rcodep );

パラメータ

defnp (IN/OUT)

OCIDefineByPos()のコールにより戻される定義構造体へのハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

octxp (IN)

コールバック関数のコンテキストを指し示します。

ocbfp (IN)

コールバック関数を指し示します。この関数は実行時にコールされ、検索されるフェッチ済データまたはそのピースを格納するバッファへのポインタを取得します。このコールバックは、インジケータ、リターン・コードおよびデータ・ピースとインジケータの長さも指定します。

注意:
通常、OCI関数では、INパラメータはOCIに渡すデータを表し、OUTパラメータはOCIから戻されるデータを表します。コールバックの場合、これが逆になります。INはOCIからコールバックに渡されるデータ、OUTはコールバックからOCIに渡されるデータです。

コールバック・パラメータは次のとおりです。

octxp (IN/OUT)

すべてのコールバック関数へ引数として渡されるコンテキスト・ポインタです。クライアント・ライブラリがフェッチしたデータを戻すためにバッファが必要になると、このコールバックが呼び出され、用意されたランタイム・バッファがデータの一部または全部を戻します。

defnp (IN)

定義ハンドルです。

iter (IN)

このカレント・フェッチのいずれかの列(0 (ゼロ)ベース)を指定します。

bufpp (OUT)

列値を格納するバッファへのポインタを戻します。つまり、*bufppは列値に対する適切な記憶域を指し示します。

alenpp (IN/OUT)

これは、*bufppに提供している記憶域のサイズを設定するために、アプリケーションで使用します。データがバッファにフェッチされると、alenppはデータの実サイズをバイト単位で示します。最初のコールで提供したバッファの長さが、サーバーから戻されるデータをすべて格納するのに十分でない場合は、コールバックが再びコールされるというようになります。

piecep (IN/OUT)

コールバック(アプリケーション)からOCIへ、次のようにピース値を戻します。

piecepパラメータは、フェッチされるピースが最初のピース(OCI_FIRST_PIECE)、その後続のピース(OCI_NEXT_PIECE)、最後のピース(OCI_LAST_PIECE)のいずれであるかを示します。プログラムでは、コールバックが次にコールされたとき、または一連のコールバックが終了した後に、そのピースを処理できます。

- IN－値はOCI_ONE_PIECE、OCI_FIRST_PIECEまたはOCI_NEXT_PIECEです。

- OUT－INの値に応じて異なります。

- IN値がOCI_ONE_PIECEである場合、OUT値はOCI_ONE_PIECEです。

- IN値がOCI_FIRST_PIECEである場合、OUT値はOCI_ONE_PIECEまたはOCI_FIRST_PIECEです。

- IN値がOCI_NEXT_PIECEである場合、OUT値はOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

indpp (IN)

インジケータ変数ポインタです。

rcodep (IN)

リターン・コード変数ポインタです。

コメント

このコールは、OCIDefineByPos()のコールでOCI_DYNAMIC_FETCHモードが選択されている場合、必要な追加属性を設定するために使用されます。OCI_DYNAMIC_FETCHモードが選択されているときにOCIDefineDynamic()のコールがスキップされた場合、アプリケーションでは、OCIコール(OCIStmtGetPieceInfo()およびOCIStmtSetPieceInfo())を使用してデータ・ピース単位がフェッチされます。

注意:
OCIEnvNlsCreate()を使用して環境ハンドルを作成すると、バインド・ハンドルおよび定義ハンドルの実際の長さと戻される長さは、常にバイト単位になります。

関連項目:
OCI_DYNAMIC_FETCHモードの詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

関連関数

OCIDefineObject()、OCIBindDynamic()

OCIDefineObject()

用途

名前付きデータ型またはREFの定義のために必要な追加属性を設定します。

構文

sword OCIDefineObject ( OCIDefine       *defnp,
OCIError        *errhp,
const OCIType   *type,
void            **pgvpp,
ub4             *pvszsp,
void            **indpp,
ub4             *indszp );

パラメータ

defnp (IN/OUT)

以前OCIDefineByPos()のコールで割り当てられた定義ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

type (IN) [オプション]

プログラム変数のタイプを示す型記述子オブジェクト(TDO)を指し示します。このパラメータはSQLT_REF型の変数のオプションであり、使用しない場合はNULLとして渡せます。

pgvpp (IN/OUT)

プログラム変数バッファのポインタを指し示します。配列では、pgvppはポインタ配列を示します。フェッチした名前付きデータ型インスタンス用のメモリーは、オブジェクト・キャッシュ内に動的に割り当てられます。すべての値を受け取ったフェッチの終了時に、pgvppは、新たに割り当てられた名前付きデータ型インスタンスのポインタを示します。名前付きデータ型インスタンスが不要になった際には、アプリケーションからOCIObjectFree()をコールして、これらの割当てを解除する必要があります。

注意:
アプリケーションでバッファを暗黙的にキャッシュに割り当てるには、*pgvppをNULLとして渡す必要があります。

pvszsp (IN/OUT)

プログラム変数のサイズを指し示します。配列では、ub4配列です。

indpp (IN/OUT)

パラレル・インジケータ構造体を含むプログラム変数バッファのポインタを指し示します。配列では、ポインタ配列を示します。インジケータ構造体を格納するためのメモリーがオブジェクト・キャッシュ内に割り当てられます。すべての値を受け取ったフェッチの終了時には、indppは、新たに割り当てられたインジケータ構造体のポインタを示しています。

indszp (IN/OUT)

インジケータ構造体プログラム変数のサイズを指し示します。配列では、ub4配列です。

コメント

この関数は、初期定義情報を設定するOCIDefineByPos()の後続コールです。このコールは、名前付きデータ型定義のために必要な追加属性を設定します。OCI環境が非オブジェクト・モードで初期化されているときにこの関数をコールした場合は、エラーが戻ります。

このコールは、定義される名前付きデータ型用にデータ型OCITypeの型記述子オブジェクト(TDO)をパラメータとして取ります。TDOは、OCIDescribeAny()をコールして取り出すことができます。

関連項目:

- OCIプロセス環境の初期化の詳細は、「OCIEnvCreate()」および「OCIEnvNlsCreate()」を参照してください。

- 複数バッファの使用例は、「複数バッファのバインドと定義」を参照してください。

関連関数

OCIDefineByPos()

OCIDescribeAny()

用途

既存のスキーマ・オブジェクトおよびサブスキーマ・オブジェクトを記述します。

構文

sword OCIDescribeAny ( OCISvcCtx       *svchp,
OCIError        *errhp,
void            *objptr,
ub4             objptr_len,
ub1             objptr_typ,
ub1             info_level,
ub1             objtyp,
OCIDescribe     *dschp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

objptr (IN)

このパラメータは次のいずれかです。

1. 記述されるオブジェクト名を含む文字列。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

2. TDOに対するREFのポインタ(型用)。

3. TDOのポインタ(型用)。

前述の各値は、objptr_typに適切な値を渡すことで区別されます。このパラメータは非NULLにしてください。

1の場合、オブジェクト名を含む文字列は、hr.employees.employee_id@mydbのように、name1[.name2 ...][@linkname]の書式にしてください。データベース・リンクは、Oracle8i 以上のデータベースでのみ使用できます。オブジェクト名は、次のSQLルールによって解釈されます。

- name1が入力されobjtypがOCI_PTYPE_SCHEMAの場合にのみ、名前は、指定されたスキーマを参照します。Oracle Databaseは、リリース8.1以上である必要があります。

- name1が入力されobjtypがOCI_PTYPE_DATABASEの場合にのみ、名前は、指定されたデータベースを参照します。database_name@db_link_nameによりリモート・データベースを記述する場合、リモートOracle Databaseはリリース8.1以上である必要があります。

- name1が入力され、objtypがOCI_PTYPE_SCHEMAまたはOCI_PTYPE_DATABASE以外の場合にのみ、名前は、カレント・ユーザーのカレント・スキーマ内の名前付きオブジェクト(表、ビュー、プロシージャ、ファンクション、パッケージ、型、シノニム、順序)を参照します。Oracle7 Serverに接続したときは、有効な型はプロシージャおよびファンクションのみです。

- name1.name2.name3 ...と入力した場合、オブジェクト名は、name1という名前のスキーマ内にあるスキーマ・オブジェクトまたはサブスキーマ・オブジェクトを参照します。たとえば、文字列hr.employees.department_idの場合、hrはスキーマ名、employeesはスキーマ内の表名、department_idは表の列名です。

objnm_len (IN)

objptrが指し示す名前文字列の長さです。名前が渡される場合は、0 (ゼロ)以外にしてください。objptrがTDOまたはそのREFへのポインタの場合は、0 (ゼロ)でもかまいません。

objptr_typ (IN)

objptrに渡されるオブジェクトのタイプです。次の値が有効です。

- OCI_OTYPE_NAME、objptrがスキーマ・オブジェクトの名前を示す場合

- OCI_OTYPE_REF、objptrがTDOに対するREFへのポインタの場合

- OCI_OTYPE_PTR、objptrがTDOのポインタの場合

info_level (IN)

今後の拡張要素のために確保されています。OCI_DEFAULTを渡します。

objtyp (IN)

記述されるスキーマ・オブジェクトのタイプです。次の値が有効です。

- OCI_PTYPE_TABLE (表用)

- OCI_PTYPE_VIEW (ビュー用)

- OCI_PTYPE_PROC (プロシージャ用)

- OCI_PTYPE_FUNC (ファンクション用)

- OCI_PTYPE_PKG (パッケージ用)

- OCI_PTYPE_TYPE (型用)

- OCI_PTYPE_SYN (シノニム用)

- OCI_PTYPE_SEQ (順序用)

- OCI_PTYPE_SCHEMA (スキーマ用)

- OCI_PTYPE_DATABASE (データベース用)

- OCI_PTYPE_UNK (不明なスキーマ・オブジェクト用)

dschp (IN/OUT)

コール後のオブジェクトに関する記述情報とともに移入されている記述ハンドルです。NULL以外にしてください。

コメント

このコールは、表、ビュー、シノニム、プロシージャ、ファンクション、パッケージ、順序、型、スキーマおよびデータベースなどの既存のスキーマ・オブジェクトを記述する汎用的な記述コールです。このコールでは、表内の列などのサブスキーマ・オブジェクトも記述できます。このコールは、 OCIAttrGet()コールを使用して取得できるオブジェクト固有の属性を記述ハンドルに移入します。

記述ハンドルに対するOCIParamGet()は、指定位置のパラメータ記述子を戻します。パラメータ位置は1から開始します。パラメータ記述子に対してOCIAttrGet()をコールすると、ストアド・プロシージャまたはファンクション・パラメータの特定の属性、あるいは表の列記述子が戻されます。OCIDescribeAny()によってスキーマ・オブジェクト記述全体がクライアント側にキャッシュされているため、これらの後続コールは、サーバーへのラウンドトリップを別に行う必要がありません。記述ハンドルに対するOCIAttrGet()は、位置の総数も戻します。

記述ハンドルに対してOCI_ATTR_DESC_PUBLIC属性が設定されている場合、カレント・スキーマに名前付きオブジェクトが存在せずname1のみが指定されているときは、このオブジェクトはパブリック・シノニムとして参照されます。

関連項目:
記述操作の詳細は、第6章を参照してください。

関連関数

OCIArrayDescriptorAlloc()、OCIParamGet()

OCIStmtGetBindInfo()

用途

バインドおよびインジケータ変数名を取得します。

構文

sword OCIStmtGetBindInfo ( OCIStmt      *stmtp,
OCIError     *errhp,
ub4          size,
ub4          startloc,
sb4          *found,
OraText      *bvnp[],
ub1          bvnl[],
OraText      *invp[],
ub1          inpl[],
ub1          dupl[],
OCIBind      *hndl[] );

パラメータ

stmtp (IN)

OCIStmtPrepare()によって準備される文ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

size (IN)

各配列の要素数です。

startloc (IN)

バインド情報の取得を開始するバインド変数の位置です。

found (IN)

式abs(found)は、開始位置にかかわらず、文のバインド変数の総数を指定します。戻されたバインド変数の数が用意されたサイズよりも少ない場合は正数に、そうでない場合は負数になります。

bvnp (OUT)

バインド変数名を保持するポインタの配列です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングです。

bvnl (OUT)

各bvnp要素の長さを保持する配列です。長さはバイト単位です。

invp (OUT)

インジケータ変数名を保持するポインタの配列です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

inpl (OUT)

各invp要素の長さを保持するポインタの配列です。バイト単位です。

dupl (OUT)

バインド位置が他と重複しているかどうかにより、その要素値が0または1になる配列です。

hndl (OUT)

バインド位置のバインドが完了している場合にバインド・ハンドルを戻す配列です。重複していると、ハンドルは戻りません。

コメント

このコールは、文が準備された後にバインド変数に関する情報を戻します。バインド名、インジケータ名および重複バインドかどうかなどの情報が含まれます。このコールでは、対応付けられたバインド・ハンドルがあれば、それも戻します。バインド変数の区別ごとの数ではなく、総数をfoundパラメータに設定します。

文にバインド変数が含まれない場合、または起動時に指定した開始バインド位置が文に存在しない場合、OCI_NO_DATAが戻されます。

SELECT INTOリスト変数はバインドとはみなされていないため、この関数には含まれません。

このコールの前に、OCIStmtPrepare()のコールを使用して文を準備する必要があります。文ハンドルのエンコーディング設定によって、Unicode文字列が取り出されるかどうかが決定されます。

このコールは、ローカルで処理されます。

関連関数

OCIStmtPrepare()

17 その他のOCIリレーショナル関数

この章では、前の章に続いて、OCIリレーショナル関数の詳細を説明します。各関数コールの詳細を説明するとともに、使用しているアプリケーションでOCI関数をコールする方法についても説明します。

関連項目:
コード例は、Oracle Databaseのインストールに含まれているデモ・プログラムを参照してください。詳細は、付録Bを参照してください。

この章は、次の項目で構成されています。

- リレーショナル関数の概要

- 文関数

- LOB関数

- Streamsアドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数

- ダイレクト・パス・ロード関数

- スレッド管理関数

- トランザクション関数

- その他の関数

リレーショナル関数の概要

この章では、OCIリレーショナル関数コールについて説明します。この章と前の章で説明する関数は、基本OCIにおける関数です。

関連項目:
リターン・コードおよびエラー処理の詳細は、「OCIでのエラー処理」を参照してください。

OCI関数の規則

各関数を記述する際に使用される規則は、「OCI関数の規則」を参照してください。

文関数

表17-1は、この項で説明している文関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。

表17-1 文関数

関数

用途

「OCIStmtExecute()」

実行する文をサーバーに送信します。

「OCIStmtFetch2()」

問合せから行をフェッチし、(スクロール可能な)結果セットから行をフェッチします。

「OCIStmtGetPieceInfo()」

ピース単位操作のためのピース情報を取得します。

「OCIStmtPrepare()」

実行するSQL文またはPL/SQL文を準備します。

「OCIStmtPrepare2()」

実行するSQL文またはPL/SQL文を準備します。有効な文キャッシュがある場合は、それを使用することもできます。

「OCIStmtRelease()」

文ハンドルを解放します。

「OCIStmtSetPieceInfo()」

ピース単位操作のためのピース情報を設定します。

OCIStmtExecute()

用途

アプリケーション要求をサーバーに対応付けます。

構文

sword OCIStmtExecute ( OCISvcCtx           *svchp,
OCIStmt             *stmtp,
OCIError            *errhp,
ub4                 iters,
ub4                 rowoff,
const OCISnapshot   *snap_in,
OCISnapshot         *snap_out,
ub4                 mode );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

stmtp (IN/OUT)

文ハンドルです。サーバーで実行される文および対応付けられたデータを定義します。svchpがOracle7 Serverを指し示しているときに、リリース8.x以上でのみサポートされるデータ型のバインドを持つ文ハンドルを渡すと無効になります。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

iters (IN)

SELECT文以外の場合、この文が実行される回数は、iters - rowoffの場合と同じになります。

SELECT文では、itersが0(ゼロ)以外の場合は、文ハンドルに対する定義を行う必要があります。実行すると、itersが事前定義バッファにフェッチされ、プリフェッチ行カウントに従ってさらに行がプリフェッチされます。SELECT文によって取り出される行数が不明の場合は、itersを0 (ゼロ)に設定します。

この関数は、SELECT文以外に対してiters=0の場合は、エラーを戻します。

注意:
配列DML操作の場合は、iters <= 32767を設定することで、より高いパフォーマンスが得られます。

rowoff (IN)

この複数行実行に関連する配列バインドのデータが始まる開始索引です。

snap_in (IN)

このパラメータは、オプションです。指定する場合は、OCI_DTYPE_SNAP型のスナップショット記述子を指示する必要があります。この記述子の内容は、直前のコールのsnap_outパラメータから取得する必要があります。この記述子は、SQLがSELECT文でない場合は無視されます。この機能を使用すると、Oracle Databaseへの複数サービス・コンテキストによって、データベースのコミット済データに関して同じ一貫性のあるスナップショットを参照できます。ただし、同じスナップショットを使用している場合でも、1つのコンテキスト内でコミットされていないデータは、他のコンテキストでは認識されません。

snap_out (OUT)

このパラメータは、オプションです。指定する場合は、OCI_DTYPE_SNAP型の記述子を指示する必要があります。この記述子には、現行のOracle Databaseのシステム変更番号(SCN)が暗号化されて格納されており、後続のOCIStmtExecute()コールのsnap_inへの入力値として使用できます。「スナップショットが古すぎます」というエラーを回避するため、この記述子は必要以上に長く使用しないでください。

mode (IN)

次のモードが有効です。

- OCI_BATCH_ERRORS - このモードの詳細は、「バッチ・エラー・モード」を参照してください。

- OCI_COMMIT_ON_SUCCESS - このモードで文を実行した場合、実行が正常に終了すると、実行後にカレント・トランザクションがコミットされます。

- OCI_DEFAULT - このモードでOCIStmtExecute()をコールすると文が実行されます。また、選択リストに関する記述情報が暗黙的に戻されます。

- OCI_DESCRIBE_ONLY - このモードは、実行前に問合せを記述するユーザー用です。OCIStmtExecute()をこのモードでコールすると、文は実行されませんが、選択リスト記述は戻されます。パフォーマンスを最大にするために、アプリケーションではデフォルト・モードで文を実行し、実行に伴う暗黙的な記述を使用することをお薦めします。

- OCI_EXACT_FETCH - アプリケーションが前もってフェッチしている行数を正確に認識している場合に使用します。このモードは、Oracle Databaseリリース8以上のモードではプリフェッチをオフにするため、実行コールの前に定義する必要があります。このmodeを使用すると、必要な行のフェッチ後にカーソルが消されるため、サーバー側のリソース使用率が低下する場合があります。

- OCI_PARSE_ONLY - このモードを使用すると、ユーザーは実行前に問合せを解析できます。このモードで実行すると問合せが解析され、SQL内に解析エラーがある場合は、そのエラーが戻されます。このモードではサーバーへの追加ラウンドトリップが発生することに注意する必要があります。パフォーマンスを向上させるには、バンドル操作の一部として文を解析するデフォルト・モードで、文を実行することをお薦めします。

- OCI_STMT_SCROLLABLE_READONLY - 結果セットをスクロール可能に設定する場合は必須です。結果セットは更新できません。詳細は、「結果のフェッチ」を参照してください。このモードは、他のモードとの併用はできません。

これらのモードは相互排他的ではなく、組み合せて使用できます。ただし、OCI_STMT_SCROLLABLE_READONLYを除きます。

コメント

この関数は、プリコンパイルされたSQL文を実行するために使用します。アプリケーションは、実行コールを使用して要求をサーバーに対応付けます。

SELECT文が実行されると、選択リストの記述が応答として暗黙的に使用可能になります。この記述は、記述、フェッチおよび型変換定義用にクライアント側にバッファ処理されます。したがって、選択リストの記述は、実行後のみに行うのが最善の方法です。

関連項目:
「選択リスト項目の記述」

SELECT文の場合は、一部の結果も暗黙的に使用可能となります。実行終了の時点で行が受け取られ、バッファ処理されます。行数が少ない問合せでは、プリフェッチすることでフェッチの最後に達したときにサーバー内のメモリーが解放され、これによってメモリーの使用量が削減されるように最適化できます。プリフェッチする行数を結果セットごとに設定する属性設定コールが定義されています。

SELECT文では、文ハンドルは、それが実行されたサービス・コンテキストに対する参照を実行終了時に暗黙的に保持しています。サービス・コンテキストの完全性は、ユーザーにメンテナンスの義務があります。暗黙的な参照は、文ハンドルが解放されるまたはフェッチが取り消される、あるいはフェッチ条件の最後に達するまで保持されます。

DDL文を再実行するには、OCIStmtPrepare()またはOCIStmtPrepare2()を使用して文を再度準備する必要があります。

注意:
OCIStmtExecute()コール前に出力変数がSELECT文に対して定義されている場合は、itersで指定した行数が定義済の出力バッファに直接フェッチされ、プリフェッチ・カウントと同じ数の追加行がプリフェッチされます。追加行がない場合、フェッチはOCIStmtFetch2()または非推奨のOCIStmtFetch()をコールしないで完了します。

関連項目:
「OCIでのポーリング・モード操作」

関連関数

OCIStmtPrepare()

OCIStmtFetch2()

用途

(スクロール可能な)結果セットから行をフェッチします。非推奨になったOCIStmtFetch()のかわりに、このフェッチ・コールを使用することをお薦めします。

構文

sword OCIStmtFetch2 ( OCIStmt     *stmthp,
OCIError    *errhp,
ub4         nrows,
ub2         orientation,
sb4         fetchOffset,
ub4         mode );

パラメータ

stmthp (IN/OUT)

これは(スクロール可能な)結果セットの文ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

nrows (IN)

現行の位置からフェッチされる行数です。

orientation (IN)

受け入れ可能な値は、次のとおりです。

- OCI_DEFAULT - OCI_FETCH_NEXTと同じ結果が得られます。

- OCI_FETCH_CURRENT - 現在行を取得します。

- OCI_FETCH_NEXT - 現行位置の次の行を取得します。これは、デフォルトです(OCI_DEFAULTと同じ結果が得られます)。スクロール不可の文ハンドルに使用します。

- OCI_FETCH_FIRST - 結果セットの最初の行を取得します。

- OCI_FETCH_LAST - 結果セットの最後の行を取得します。

- OCI_FETCH_PRIOR - 結果セットの現在行の前の行に結果セットを位置指定します。このモードを使用して、前の行からも複数の行をフェッチできます。

- OCI_FETCH_ABSOLUTE - 絶対的な位置指定を使用して結果セットの行番号(fetchOffsetパラメータで指定)をフェッチします。

- OCI_FETCH_RELATIVE - 相対的な位置指定を使用して結果セットの行番号(fetchOffsetパラメータで指定)をフェッチします。

fetchOffset (IN)

現在行の位置を変更するためにorientationパラメータと併用するオフセットです。

mode (IN)

OCI_DEFAULTを渡します。

コメント

フェッチ・コールは、非推奨のOCIStmtFetch()コールにfetchOffsetパラメータを追加した場合と同じように機能します。スクロール可能かどうかに関係なく、すべての文ハンドルに使用できます。スクロール不可の文ハンドルの場合、orientationで唯一受け入れ可能な値はOCI_FETCH_NEXTで、fetchOffsetパラメータは無視されます。

新しいアプリケーションには、このコールOCIStmtFetch2()の使用をお薦めします。

orientationがOCI_FETCH_RELATIVEに設定されているfetchOffsetは、次のすべてのコールと等価です。

- fetchOffsetの値が0 (ゼロ)のOCI_FETCH_CURRENT。

- fetchOffsetの値が1のOCI_FETCH_NEXT。

- fetchOffsetの値が-1のOCI_FETCH_PRIOR。

OCI_ATTR_ROW_COUNTには、フェッチされた最上位の行の絶対値が含まれます。

OCI_FETCH_ABSOLUTEとOCI_FETCH_RELATIVEを除くすべてのorientationモードでは、fetchOffset値は無視されます。

このコールを使用すると、OCI_FETCH_LASTを使用してから、OCI_ATTR_CURRENT_POSITIONに対してOCIAttrGet()をコールすることで、結果セット内の行数を判断することもできます。ただし、このコールの応答時間はかなり長くなります。OCI_FETCH_LAST orientationを使用したnrowsが1より大きい値に設定されている場合、nrowsは1であるとみなされます。

リターン・コードは、非推奨のOCIStmtFetch()の場合と同じです。ただし、スクロール可能な文ハンドルのフェッチ(または実行)のたびに、リターン・コードOCI_NO_DATAを含むOER(1403)が戻されます。また、アプリケーションが要求するすべての行がフェッチされるわけではありません。

nrowsパラメータに0 (ゼロ)を設定してOCIStmtFetch2()をコールした場合は、カーソルが取り消されます。

サーバー側のリソースをスクロール・カーソル用に解放するには、スクロール可能な文ハンドルを明示的に取り消すか(つまり、0 (ゼロ)行でフェッチする)、または解放する必要があります。スクロール不可な文ハンドルは、OER(1403)を受け取ると暗黙的に取り消されます。

OCI_ATTR_ROWS_FETCHEDを使用して、最後のフェッチ・コールでユーザーのバッファに正常にフェッチされた行数を検索します。

関連項目:

- 「OCIでのスクロール・カーソルの使用」

- 「OCIでのポーリング・モード操作」

関連関数

OCIStmtExecute()、OCIBindByPos()

OCIStmtGetPieceInfo()

用途

ピース単位操作用のピース情報を戻します。

構文

sword OCIStmtGetPieceInfo( const OCIStmt  *stmtp,
OCIError       *errhp,
void           **hndlpp,
ub4            *typep,
ub1            *in_outp,
ub4            *iterp,
ub4            *idxp,
ub1            *piecep );

パラメータ

stmtp (IN)

戻されたOCI_NEED_DATAが実行される際の文です。

errhp (OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

hndlpp (OUT)

バインド、バインドの定義ハンドル、またはランタイム・データが要求または提供されている定義のいずれかへのポインタを戻します。

typep (OUT)

hndlppが指し示すハンドルのタイプです。タイプには、OCI_HTYPE_BIND (バインド・ハンドル用)またはOCI_HTYPE_DEFINE (定義ハンドル用)があります。

in_outp (OUT)

INバインド値に対してデータが必要な場合、OCI_PARAM_INを戻します。データがOUTバインド変数または定義位置値として取得できる場合はOCI_PARAM_OUTが戻ります。

iterp (OUT)

複数行操作の行数を戻します。

idxp (OUT)

PL/SQL配列バインド操作の配列要素の索引です。

piecep (OUT)

OCI_ONE_PIECE、OCI_FIRST_PIECE、OCI_NEXT_PIECEまたはOCI_LAST_PIECEのいずれかの事前定義値を戻します。

コメント

実行コールまたはフェッチ・コールからOCI_NEED_DATAが戻され、動的なバインド、定義の値またはピースが取得または戻されると、OCIStmtGetPieceInfo()から、バインド・ハンドルまたは定義ハンドル、反復、索引番号、ピース情報などの関連情報が戻されます。

関連項目:

- OCIStmtGetPieceInfo()の使用方法の詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

- 「OCIでのポーリング・モード操作」

関連関数

OCIArrayDescriptorAlloc()、OCIAttrSet()、OCIStmtExecute()、OCIStmtFetch() (非推奨)、OCIStmtFetch2()、OCIStmtSetPieceInfo()

OCIStmtPrepare()

用途

実行するSQL文またはPL/SQL文を準備します。

構文

sword OCIStmtPrepare ( OCIStmt       *stmtp,
OCIError      *errhp,
const OraText *stmt,
ub4           stmt_len,
ub4           language,
ub4           mode );

パラメータ

stmtp (IN)

実行対象の文に関連付けられた文ハンドルです。デフォルトでは、導出元の環境ハンドルのエンコーディング設定が含まれています。文をUTF-16エンコーディングで準備できるのは、UTF-16環境のみです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

stmt (IN)

実行されるSQL文またはPL/SQL文です。NULLで終了する文字列にしてください。つまり、最後の文字は、エンコーディングによってはNULLバイトの数値です。文は、OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

パラメータを必ず(text *)にキャストしてください。文がUTF-16で準備されると、バインド・バッファと定義バッファのキャラクタ・セットは、UTF-16にデフォルト設定されます。

stmt_len (IN)

文の長さです。エンコーディングによって、文字数またはバイト数の単位になります。0(ゼロ)以外の値である必要があります。

language (IN)

V7構文またはネイティブ構文を指定します。可能な値は次のとおりです。

- OCI_V7_SYNTAX - V7 Oracle解析構文。

- OCI_NTV_SYNTAX - サーバーのバージョンに依存する構文。

mode (IN)

OCIEnvCreate()コールのmodeに類似しています。ただし、このコールは必然的に継承されたモード設定を上書きできるため、優先度が高くなります。

可能な値はOCI_DEFAULT (デフォルト・モード)のみです。文ハンドルstmtpは、親の環境ハンドルに指定されている内容を使用します。

コメント

このコールは、OCIアプリケーションで実行するSQL文またはPL/SQL文を準備するために使用します。OCIStmtPrepare()コールは、アプリケーション要求を定義します。

modeパラメータは、文の内容がUTF-16でエンコーディングされているかどうかを判断します。文の長さは、コードポイント数またはバイト数で、エンコーディングによって異なります。

文ハンドルは、親の環境ハンドルからエンコーディング設定を継承しますが、このコールのmodeによって、文ハンドル自体のエンコーディング設定も変更できます。

後続のバインド・コールで初期化されるこの文のデータ値は、この文ハンドルの設定をデフォルトとして使用するバインド・ハンドル内に格納されます。

このコールは、この文ハンドルと特定のサーバー間の対応付けは作成しません。

DDL文を再実行する前に、この関数の2回目のコールを実行してください。

関連項目:
このコールの使用方法の詳細は、「文の準備」を参照してください。

関連関数

OCIArrayDescriptorAlloc()、OCIStmtExecute()、OCIStmtPrepare2()

OCIStmtPrepare2()

用途

実行するSQL文またはPL/SQL文を準備します。有効な文キャッシュがある場合は、それを使用することもできます。

構文

sword OCIStmtPrepare2 ( OCISvcCtx      *svchp,
OCIStmt        **stmthp,
OCIError       *errhp,
const OraText  *stmttext,
ub4            stmt_len,
const OraText  *key,
ub4            keylen,
ub4            language,
ub4            mode );

パラメータ

svchp (IN)

文に関連付けるサービス・コンテキストです。

stmthp (OUT)

戻される文ハンドルへのポインタです。

errhp (IN)

診断のためのエラー・ハンドルへのポインタです。

stmttext (IN)

文のテキストです。stmttextのセマンティックは、OCIStmtPrepare()のセマンティックと同じです(つまり、文字列はNULLで終了)。

stmt_len (IN)

文のテキストの長さです。

key (IN)

文キャッシュの場合のみ指定します。文キャッシュ内の文を検索するために使用されるキーです。このキーが指定されると、文のテキストおよび他のパラメータは無視され、このキーのみに基づいて検索が行われます。

keylen (IN)

文キャッシュの場合のみ指定します。キーの長さです。

language (IN)

V7構文またはネイティブ構文を指定します。可能な値は次のとおりです。

- OCI_V7_SYNTAX - V7 Oracle解析構文。

- OCI_NTV_SYNTAX - サーバーのバージョンに依存する構文。

mode (IN)

この関数では、文キャッシュを使用することも使用しないことも可能です。使用するかどうかは、接続またはセッション・プールの作成時に決まります。セッションに対してキャッシュが使用可能な場合はセッション内のすべての文がキャッシュ可能で、キャッシュが使用可能でない場合はすべての文がキャッシュされません。

有効なモードは次のとおりです。

- OCI_DEFAULT - キャッシュは使用可能ではありません。これは唯一有効な設定です。文がキャッシュ内に見つからなかった場合は、このモードでは文ハンドルが新しく割り当てられ、実行用の文ハンドルが準備されます。文がキャッシュ内に見つからず、次のいずれかの状況が適用される場合、後続のアクションは次のようになります。

- テキストのみが指定された場合: 新しい文が割り当てられて準備され、戻されます。タグNULLです。OCI_SUCCESSが戻されます。

- タグのみが指定された場合: stmthpはNULLになります。OCI_ERRORが戻されます。

- テキストとキーの両方が指定された場合: 新しい文が割り当てられて準備され、戻されます。タグNULLです。戻された文はタグがNULLである点で要求した文とは異なるため、OCI_SUCCESS_WITH_INFOが戻ります。

- OCI_PREP2_CACHE_SEARCHONLY: このケースで、文が見つからなかった(NULLの文ハンドルが戻された)場合は、さらに処置が必要です。文が見つかった場合は、OCI_SUCCESSが戻ります。見つからない場合は、OCI_ERRORが戻ります。

- OCI_PREP2_GET_PLSQL_WARNINGS - セッションで警告が有効になっており、PL/SQLプログラムがコンパイルされて警告が発行された場合、実行の戻りステータスはOCI_SUCCESS_WITH_INFOになります。警告に対応する新しいエラー番号をOCIErrorGet()で検索します。

関連関数

OCIStmtRelease()

OCIStmtRelease()

用途

OCIStmtPrepare2()のコールで取得した文ハンドルを解放します。

構文

sword OCIStmtRelease ( OCIStmt        *stmthp,
OCIError       *errhp,
const OraText  *key,
ub4            keylen,
ub4            mode );

パラメータ

stmthp (IN/OUT)

OCIStmtPrepare2()によって戻される文ハンドルです。

errhp (IN)

診断に使用するエラー・ハンドルです。

key (IN)

文キャッシュの場合のみ有効です。キャッシュ内の文に関連付けられているキーです。これは、コール元によって渡されるSQL文字列です。NULLのキーが渡された場合、文はタグ付けされません。

keylen (IN)

文キャッシュの場合のみ有効です。キーの長さです。

mode (IN)

次のモードが有効です。

- OCI_DEFAULT

- OCI_STRLS_CACHE_DELETE－ 文キャッシュの場合のみ有効です。文は、それ以上キャッシュに保持されません。

関連関数

OCIStmtPrepare2()

OCIStmtSetPieceInfo()

用途

ピース単位操作用のピース情報を設定します。

構文

sword OCIStmtSetPieceInfo ( void              *hndlp,
ub4               type,
OCIError          *errhp,
const void        *bufp,
ub4               *alenp,
ub1               piece,
const void        *indp,
ub2               *rcodep );

パラメータ

hndlp (IN/OUT)

バインド・ハンドルまたは定義ハンドルです。

type (IN)

ハンドルのタイプです。

errhp (OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

bufp (IN/OUT)

データ値またはデータ・ピースがINバインド変数である場合、それを含む格納場所へのポインタです。そうでない場合、bufpが格納場所へのポインタになり、OUTバインド変数および定義変数のピースまたは値を取得します。名前付きデータ型またはREFの場合、オブジェクトまたはREFへのポインタが戻されます。

alenp (IN/OUT)

ピースまたは値の長さです。同じSQL文を実行する間にこのパラメータを変更しないでください。

piece (IN)

ピース・パラメータです。次の値が有効です。

- OCI_ONE_PIECE

- OCI_FIRST_PIECE

- OCI_NEXT_PIECE

- OCI_LAST_PIECE

このパラメータは、INバインド変数でのみ使用されます。

indp (IN/OUT)

インジケータです。sb2値へのポインタまたは名前付きデータ型(SQLT_NTY)とREF (SQLT_REF)用のインジケータ構造体へのポインタです。つまり、データ型に応じて、*indpはsb2またはvoid *になります。

rcodep (IN/OUT)

リターン・コードです。

コメント

実行コールにより、動的IN/OUTバインド値またはピースを取得するOCI_NEED_DATAが戻されると、OCIStmtSetPieceInfo()により、バッファ、長さ、現在処理中のピース、インジケータおよびこの列のリターン・コードなどのピース情報が設定されます。

関連項目:

- OCIStmtSetPieceInfo()の使用方法の詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

- 「OCIでのポーリング・モード操作」

関連関数

OCIArrayDescriptorAlloc()、OCIAttrSet()、OCIStmtExecute()、OCIStmtFetch() (非推奨)、OCIStmtFetch2()、OCIStmtGetPieceInfo()

LOB関数

表17-2は、この項で説明している、LOBロケータを使用するLOB関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。

注意:
LOBへのアクセスには、LOB用のデータ・インタフェースを使用するというもう1つの方法があります。次の場所で説明するように、CLOB列の文字データまたはBLOB列のRAWデータをバインドまたは定義できます。

- INSERT文およびUPDATE文の使用方法および使用例は、「LOBデータのバインド」を参照してください。

- SELECT文の使用方法および使用例は、「LOBデータの定義」を参照してください。

- 第7章「LOBおよびBFILEの操作」

表17-2 LOB関数

関数

用途

「OCIDurationBegin()」

一時LOBのためのユーザー期間を開始します。

「OCIDurationEnd()」

一時LOBのためのユーザー期間を終了します。

「OCILobAppend()」

1つのLOBを別のLOBの後に追加します。

「OCILobArrayRead()」

複数のロケータのLOBデータを読み取ります。

「OCILobArrayWrite()」

複数のロケータのLOBデータを書き込みます。

「OCILobAssign()」

1つのLOBロケータを別のLOBロケータに割り当てます。

「OCILobCharSetForm()」

LOBロケータからキャラクタ・セットを取得します。

「OCILobCharSetId()」

LOBロケータからキャラクタ・セットIDを取得します。

「OCILobClose()」

オープンされているLOBをクローズします。

「OCILobCopy2()」

LOBの一部または全部を別のLOBにコピーします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

「OCILobCreateTemporary()」

一時LOBを作成します。

「OCILobDisableBuffering()」

LOBバッファリングをオフにします。

「OCILobEnableBuffering()」

LOBバッファリングをオンにします。

「OCILobErase2()」

LOBの一部を消去します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

「OCILobFileClose()」

オープンされているBFILEをクローズします。

「OCILobFileCloseAll()」

オープンされているすべてのFILEをクローズします。

「OCILobFileExists()」

サーバー上のファイルの存在をチェックします。

「OCILobFileGetName()」

LOBロケータからディレクトリ・オブジェクトとファイル名を取得します。

「OCILobFileIsOpen()」

サーバー上のファイルがこのロケータでオープンされているかどうかをチェックします。

「OCILobFileOpen()」

BFILEをオープンします。

「OCILobFileSetName()」

LOBロケータにディレクトリ・オブジェクトとファイル名を設定します。

「OCILobFlushBuffer()」

LOBバッファをフラッシュします。

「OCILobFreeTemporary()」

一時LOBを解放します。

「OCILobGetChunkSize()」

LOBのチャンク・サイズを取得します。

OCILobGetContentType()

SecureFileのユーザー指定コンテンツ・タイプ文字列(ファイル形式識別子)を取り出します。

「OCILobGetLength2()」

LOBの長さを取得します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

「OCILobGetOptions()」

SecureFileのオプション設定を取得します。

「OCILobGetStorageLimit()」

内部LOB (BLOB、CLOBまたはNCLOB)の最大長(バイト単位)を取得します。

「OCILobIsEqual()」

2つのLOBロケータが等しいか比較します。

「OCILobIsOpen()」

LOBがオープンされているかどうかをチェックします。

「OCILobIsTemporary()」

特定のLOBが一時LOBかどうかを判断します。

「OCILobLoadFromFile2()」

BFILEからLOBをロードします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

「OCILobLocatorAssign()」

1つのLOBロケータを別のLOBロケータに割り当てます。

「OCILobLocatorIsInit()」

LOBロケータが初期化されているかどうかをチェックします。

「OCILobOpen()」

LOBをオープンします。

「OCILobRead2()」

LOBの一部を読み取ります。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

OCILobSetContentType()

SecureFileのユーザー指定コンテンツ・タイプ文字列を格納します。

「OCILobSetOptions()」

既存のSecureFileと新規に作成されたSecureFileのオプション設定を有効化します。

「OCILobTrim2()」

LOBを切り捨てます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

「OCILobWrite2()」

LOBに書き込みます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

「OCILobWriteAppend2()」

LOBの末尾からデータを書き込みます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

OCI LOBコールのパラメータについて、次の点に注意してください。

- 固定幅のクライアント側キャラクタ・セットの場合、offsetパラメータとamountパラメータは、CLOBとNCLOBでは常に文字数、BLOBとBFILEでは常にバイト数です。

- 可変幅のクライアント側キャラクタ・セットの場合は、一般に次のルールが適用されます。

- amount (amtp)パラメータ - amountパラメータがサーバー側のLOBを参照する場合、その内容は文字数です。amountパラメータがクライアント側のバッファを参照する場合、amountはバイト数です。
詳細は、OCILobGetLength() (非推奨)、OCILobGetLength2()、OCILobRead() (非推奨)、OCILobRead2()、OCILobWrite() (非推奨)、OCILobWrite2()などの各LOBコールを参照してください。

- offset (offset)パラメータ - クライアント側のキャラクタ・セットが可変幅かどうかに関係なく、offsetパラメータは、CLOBとNCLOBでは常に文字数、BLOBとBFILEでは常にバイト数です。

- LOB操作では、多くの場合、クライアント側のキャラクタ・セットに関係なく、amountパラメータはCLOBとNCLOBの文字数です。これらのLOB操作には、OCILobCopy2()、OCILobErase2()、OCILobGetLength2()、OCILobLoadFromFile2()、OCILobTrim2()などがあります。これらのすべての操作では、サーバー上のLOBデータの量を参照します。

ストリーミング操作とは、ピース単位でLOBの読取りまたは書込みを行うことです。ストリームは、ポーリング・メカニズムを使用するか、またはユーザー定義コールバックを登録して実装できます。

OCIDurationBegin()

用途

一時LOBのためのユーザー期間を開始します。

構文

sword OCIDurationBegin ( OCIEnv              *env,
OCIError            *err,
const OCISvcCtx     *svc,
OCIDuration         parent,
OCIDuration         *duration );

パラメータ

env (IN/OUT)

NULLポインタを渡します。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

svc (IN)

OCIサービス・コンテキスト・ハンドルです。NULL以外にしてください。

parent (IN)

親の継続時間の時間番号です。次のいずれかです。

- OCI_DURATION_STATEMENT

- OCI_DURATION_SESSION

duration (OUT)

新しく作成されたユーザー期間固有の識別子です。

コメント

この関数によってユーザー期間が開始されます。リリース8.1以上では、一時LOBを作成する際にユーザー期間を使用できます。ユーザーは複数のアクティブなユーザー期間を同時に利用できます。ユーザー期間をネストする必要はありません。durationパラメータは、このコールによって作成された期間を識別するための一意の番号を戻すために使用します。

関連項目:
「一時LOBの継続時間」

関連関数

OCIDurationEnd()

OCIDurationEnd()

用途

一時LOBのためのユーザー期間を終了します。

構文

sword OCIDurationEnd ( OCIEnv             *env,
OCIError           *err,
const OCISvcCtx    *svc,
OCIDuration        duration );

パラメータ

env (IN/OUT)

NULLポインタを渡します。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

svc (IN)

OCIサービス・コンテキストです。これは、カートリッジ・サービスに対してNULLとして渡されます。

duration (IN)

ユーザー期間を識別するための番号です。

コメント

この関数によってユーザー期間が終了します。ユーザー期間に割り当てられていた一時LOBが解放されます。

関連項目:
「一時LOBの継続時間」

関連関数

OCIDurationBegin()

OCILobAppend()

用途

別のLOBの末尾にLOB値を指定どおりに追加します。

構文

sword OCILobAppend ( OCISvcCtx        *svchp,
OCIError         *errhp,
OCILobLocator    *dst_locp,
OCILobLocator    *src_locp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

dst_locp (IN/OUT)

一意に宛先LOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

src_locp (IN)

一意にソースLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

コメント

別のLOBの末尾にLOB値を指定どおりに追加します。データは、ソースから宛先の末尾にコピーされます。コピー元LOBおよびコピー先LOBは、すでに存在している必要があります。宛先LOBは、新たに書き込まれるデータにあわせて拡張されます。許される最大長(4GB)を超える宛先LOBの拡張とNULL LOBのコピーはエラーになります。

ソースと宛先のLOBロケータは同じ型にしてください(つまり、両方ともBLOBまたは両方ともCLOB)。LOBバッファリングは、ロケータのどちらの型に対しても使用可能にしないでください。この関数では、ソースまたは宛先としてのBFILEロケータを受け入れません。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連関数

OCILobTrim() (非推奨)、OCILobTrim2()、OCILobWrite() (非推奨)、OCILobWrite2()、OCILobCopy() (非推奨)、OCILobCopy2()、OCIErrorGet()、OCILobWriteAppend() (非推奨)、OCILobWriteAppend2()

OCILobArrayRead()

用途

1回のラウンドトリップで複数のロケータのLOBデータを読み取ります。この関数は、4GBのサイズ制限なしにすべてのLOBに対して使用できます。

構文

sword OCILobArrayRead ( OCISvcCtx                *svchp,
OCIError                 *errhp,
ub4                      *array_iter,
OCILobLocator            **locp_arr,
oraub8                   *byte_amt_arr,
oraub8                   *char_amt_arr,
oraub8                   *offset_arr,
void                     **bufp_arr,
oraub8                   bufl_arr,
ub1                      piece,
void                     *ctxp,
OCICallbackLobArrayRead  (cbfp)
(
void          *ctxp,
ub4           array_iter,
const void    *bufp,
oraub8        lenp,
ub1           piecep
void          **changed_bufpp,
oraub8        *changed_lenp
)
ub2                      csid,
ub1                      csfrm );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

array_iter (IN/OUT)

IN - このパラメータは、LOBロケータ配列のサイズを指定します。ポーリングでは、このパラメータが関連するのは最初のコールのみで、後続のコールでは無視されます。

OUT - ポーリング・モードの場合に、このパラメータは読取り元の要素の配列索引を指定します。

locp_arr (IN)

LOBまたはBFILEロケータの配列です。

byte_amt_arr (IN/OUT)

oraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータのバイト数に対応します。

IN: データベースから読み取るバイト数です。BLOBおよびBFILEに対して常に使用されます。CLOBおよびNCLOBに対しては、char_amt_arrの該当値が0 (ゼロ)の場合のみ使用されます。

OUT: ユーザー・バッファに読み取られるバイト数です。

char_amt_arr (IN/OUT)

oraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータの文字数に対応します。

IN: ユーザー・バッファに読み取られる最大文字数です。BLOBおよびBFILEの場合は無視されます。

OUT: ユーザー・バッファに読み取られる文字数です。BLOBおよびBFILEの場合は未定義になります。

offset_arr (IN)

oraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。文字LOB (CLOB、NCLOB)ではLOBの先頭からの文字数であり、バイナリLOBまたはBFILEではバイト数です。先頭位置は1です。

bufp _arr (IN/OUT)

ピースの読取り先バッファへのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。

bufl_arr (IN)

バッファ配列のバッファ長を示すoraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。

piece (IN)

OCI_ONE_PIECE: コールではポーリングは想定されません。示された量がバッファ長より大きい場合、バッファには可能なかぎり格納されます。

ポーリングでは、最初にOCI_FIRST_PIECE、後続のコールでOCI_NEXT_PIECEを渡します。OCI_FIRST_PIECEはコールバックの使用時に渡される必要があります。

ctxp (IN)

コールバック関数用のコンテキスト・ポインタです。NULLにできます。

cbfp (IN)

各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、ピースごとにOCI_NEED_DATAが戻ります。

コールバック関数は、OCI_CONTINUEを戻して読取りを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの読取りは終了します。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

array_iter (IN)

読取り元の要素の索引です。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。

lenp (IN)

bufpにおけるカレント・ピースのバイト長です。

piecep (IN)

ピースは、OCI_FIRST_PIECE、OCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ・データのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。サーバーとクライアントの設定が同一である場合を除き、サーバーのキャラクタ・セットとはみなされません。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - データベース・キャラクタ・セットID

- SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。csfrmが指定されていない場合は、デフォルトが使用されます。

コメント

NULL属性のLOBまたはBFILEから読み取るとエラーになります。

注意:
LOBを読み取るかまたは書き込むときは、指定されたキャラクタ・セット・フォーム(csfrm)がロケータのフォームと一致している必要があります。

BFILEの場合は、オペレーティング・システム・ファイルがサーバー上に存在しており、それらのファイルは、入力ロケータを使用してOCILobFileOpen()またはOCILobOpen()によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がOracle Databaseにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。

OCILobArrayRead()に対してポーリング・モードを使用するとき、最初のコールではoffset_arrおよびamt_arrの値を指定する必要がありますが、その後のOCILobArrayRead()のポーリング・コールではこれらの値を指定する必要はありません。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

注意:
OCILobArrayRead()操作を終了して文ハンドルを解放するには、OCIBreak()コールを使用します。

次の点は、ストリーム・モードでのLOBデータの読取りに適用されます。

- ポーリング・モードを使用する場合は、最初のOCILobArrayRead()コールでのみchar_amt_arr、byte_amt_arrおよびoffset_arrパラメータを指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。byte_amt_arrおよびchar_amt_arrの両方が0 (ゼロ)を指すように設定されており、OCI_FIRST_PIECEが渡された場合、ポーリング・モードが想定され、LOBの末尾までデータが読み取られます。出力では、byte_amt_arrは、現在のピースに読み取られるバイト数を示します。CLOBおよびNCLOBでは、char_amt_arrは現在のピースに読み取られる文字数を示します。

- コールバックを使用する場合、lenpパラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenpパラメータをチェックします。

- ポーリングを使用する場合、byte_amt_arrパラメータを確認し、現在のピースでバッファに格納されている量を確認します。CLOBおよびNCLOBでは、char_amt_arrはバッファに読み取られる文字数も戻します。

UTF-16形式でデータを読み取るには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

関連項目:

- Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください。

- BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

- LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

- 付録B「OCIデモ・プログラム」

- ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

関連関数

OCIErrorGet()、OCILobWrite2()、OCILobFileSetName()、OCILobWriteAppend2()、OCILobArrayWrite()

OCILobArrayWrite()

用途

1回のラウンドトリップで複数のロケータのLOBデータを書き込みます。この関数は、4GBのサイズ制限なしにすべてのLOBに対して使用できます。

構文

sword OCILobArrayWrite ( OCISvcCtx             *svchp,
OCIError              *errhp,
ub4                   *array_iter,
OCILobLocator         **locp_arr,
oraub8                *byte_amt_arr,
oraub8                *char_amt_arr,
oraub8                *offset_arr,
void                  **bufp_arr,
oraub8                *bufl_arr,
ub1                   piece,
void                  *ctxp,
OCICallbackLobArrayWrite (cbfp)
(
void     *ctxp,
ub4      array_iter,
void     *bufp,
oraub8   *lenp,
ub1      *piecep
void     **changed_bufpp,
oraub8   *changed_lenp
)
ub2             csid,
ub1             csfrm );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

array_iter (IN/OUT)

IN - このパラメータは、LOBロケータ配列のサイズを指定します。ポーリングでは、このパラメータが関連するのは最初のコールのみで、後続のコールでは無視されます。

OUT - ポーリング・モードの場合に、このパラメータは書込み先の要素の配列索引を指定します。

locp_arr (IN/OUT)

LOBロケータの配列です。

byte_amt_arr (IN/OUT)

oraub8変数へのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータのバイト数に対応します。

IN: データベースに書き込むバイト数です。BLOBでは必ず使用されます。CLOBおよびNCLOBに対しては、char_amt_arrが0 (ゼロ)の場合のみ使用されます。

OUT: データベースに書き込むバイト数です。

char_amt (IN/OUT)

oraub8変数へのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータの文字数に対応します。

IN: データベースに書き込む最大文字数です。BLOBでは無視されます。

OUT: データベースに書き込む文字数です。BLOBでは未定義となります。

offset_arr (IN)

oraub8変数へのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。配列内の各エントリは、LOB値の先頭からの絶対オフセットです。文字LOB (CLOB、NCLOB)ではLOBの先頭からの文字数であり、BLOBではバイト数です。先頭位置は1です。

bufp_arr (IN/OUT)

ロケータのピースが書き込まれるバッファへのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。

bufl_arr (IN)

バッファ配列のバッファ長を示すoraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。

注意:
このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、bufl_arrの値を必要に応じて調整する必要があります。

piece (IN)

書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECEです。

ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE、OCI_NEXT_PIECEおよびOCI_LAST_PIECEがあります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

cbfp (IN)

各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、ピースごとにOCI_NEED_DATAが戻ります。コールバック関数は、OCI_CONTINUEを戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。

コールバックは、次のパラメータを取ります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

array_iter (IN)

書込み先の要素の索引です。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。このパラメータは、OCILobArrayWrite()ルーチンに入力として渡されるbufpと同じです。

lenp (IN/OUT)

buffer (IN)内のデータのバイト数、およびbufp (OUT)内のカレント・ピースのバイト数です。

piecep (OUT)

ピースはOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ内のデータのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - データベース・キャラクタ・セットID

- SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。

コメント

LOBにデータが存在する場合は、バッファに格納されたデータによって上書きされます。バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。

注意:
LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm)を指定します。
piece、csidおよびcsfrmパラメータは、配列のすべてのロケータで同じです。

OCILobArrayWrite()に対してポーリング・モードを使用するとき、最初のコールではoffset_arr、byte_amt_arrおよびchar_amt_arrの値を指定する必要がありますが、その後のOCILobArrayWrite()のポーリング・コールでは指定する必要はありません。

pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。

コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufp_arrから書き込まれます。コールバック関数が定義されていない場合、OCILobArrayWrite()は、OCI_NEED_DATAエラー・コードを戻します。LOBのピースの書込みを続けるには、アプリケーションでOCILobArrayWrite()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。

pieceパラメータの値がOCI_LAST_PIECEのときは、ポーリングまたはコールバック方式が使用されているかどうかに関係なく、ピース単位書込み操作は終了します。

(どの入力方法を使用した場合も)データベースに渡されるデータの量が、byte_amt_arrまたはchar_amt_arrパラメータに指定された量より少ない場合は、ORA-22993エラーが戻されます。

この関数は内部LOBでのみ有効です。BFILEは読取り専用なので、取り扱えません。LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

byte_amt_arrおよびchar_amt_arrが0 (ゼロ)を指すように設定され、OCI_FIRST_PIECEが入力として指定されている場合、ポーリング・モードが想定され、OCI_LAST_PIECEを指定するまでデータが書き込まれます。CLOBおよびNCLOBでは、byte_amt_arrおよびchar_amt_arrは、それぞれバイト数および文字数で、各ピースごとに書き込まれるデータを戻します。BLOBでは、byte_amt_arrは各ピースごとに書き込まれるバイト数を戻しますが、出力についてchar_amt_arrは未定義です。

UTF-16形式でデータを書き込むには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:

- Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください。

- LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

- 付録B「OCIデモ・プログラム」

- ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

関連関数

OCIErrorGet()、OCILobRead2()、OCILobAppend()、OCILobCopy() (非推奨)、OCILobCopy2()、OCILobWriteAppend2()、OCILobArrayRead()

OCILobAssign()

用途

LOBまたはBFILEロケータを別のロケータに割り当てます。

構文

sword OCILobAssign ( OCIEnv                *envhp,
OCIError              *errhp,
const OCILobLocator   *src_locp,
OCILobLocator         **dst_locpp );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

src_locp (IN)

コピー元のLOBまたはBFILEロケータです。

dst_locpp (IN/OUT)

コピー先となるLOBまたはBFILEロケータです。コール元で、OCIDescriptorAlloc()をコールしてコピー先のロケータに領域を割り当てる必要があります。

コメント

ソース・ロケータを宛先ロケータに割り当てます。割当て後は、両方のロケータは同じLOB値を参照します。内部LOBの場合は、宛先ロケータが表に格納されているときにのみ、ソース・ロケータのLOB値が宛先ロケータのLOB値にコピーされます。したがって、宛先ロケータが格納されているオブジェクトのフラッシュを発行すると、LOB値がコピーされます。

OCILobAssign()は一時LOBには使用できません。OCI_INVALID_HANDLEエラーが生成されます。一時LOBには、OCILobLocatorAssign()を使用します。

BFILEでは、ファイルを参照するロケータのみが表にコピーされます。オペレーティング・システム・ファイル自体はコピーされません。

BFILEロケータを内部LOBロケータに割り当てるとエラーが発生します(逆の場合も同様)。

ソース・ロケータがバッファリング可能な内部LOB用でLOBバッファリング・サブシステムを介したLOBデータの変更に使用されており、そのバッファが書込み後フラッシュされていない場合には、ソース・ロケータが宛先ロケータに割り当てられない場合があります。これは、LOBごとに1つのロケータしかLOBバッファリング・サブシステムを介してLOBデータを変更できないためです。

入力宛先ロケータの値は、OCIDescriptorAlloc()のコールによって割り当てられている必要があります。たとえば、次のように宣言します。

OCILobLocator     *source_loc = (OCILobLocator *) 0;
OCILobLocator     *dest_loc = (OCILobLocator *) 0;

例17-1は、アプリケーションによるsource_locロケータの割当て方法を示しています。

例17-1 source_locソース・ロケータの割当て

if (OCIDescriptorAlloc((void  *) envhp, (void  **) &source_loc,
(ub4) OCI_DTYPE_LOB, (size_t) 0, (void  **) 0))
handle_error;

次に、表のLOBがsource_locに選択され、初期化されます。例17-2に示すように、アプリケーションでは、OCILobAssign()コールを発行してsource_locの値をdest_locに割り当てる前に、宛先ロケータdest_locを割り当てる必要があります。

例17-2 dest_loc宛先ロケータのの割当て

if (OCIDescriptorAlloc((void  *) envhp, (void  **) &dest_loc,
(ub4)OCI_DTYPE_LOB, (size_t) 0, (void  **) 0))
handle_error;
if (OCILobAssign(envhp, errhp, source_loc, &dest_loc))
handle_error

関連関数

OCIErrorGet()、OCILobIsEqual()、OCILobLocatorAssign()、OCILobLocatorIsInit()、OCILobEnableBuffering()

OCILobCharSetForm()

用途

LOBロケータのキャラクタ・セット・フォームを取得します。

構文

sword OCILobCharSetForm ( OCIEnv                *envhp,
OCIError              *errhp,
const OCILobLocator   *locp,
ub1                   *csfrm );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

キャラクタ・セット・フォームを取得するためのLOBロケータです。

csfrm (OUT)

入力LOBロケータのキャラクタ・セット・フォームです。入力ロケータのlocpがBLOBまたはBFILE用の場合、バイナリのLOBとBFILEにはキャラクタ・セットという概念がないため、csfrmには0 (ゼロ)が設定されます。コール元では、csfrm (ub1)用の領域を割り当てる必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - データベース・キャラクタ・セットID (デフォルト)

- SQLCS_NCHAR - NCHARキャラクタ・セットID

コメント

入力CLOBまたはNCLOBロケータのキャラクタ・セット・フォームをcsfrm出力パラメータに戻します。

関連関数

OCIErrorGet()、OCILobCharSetId()、OCILobLocatorIsInit()

OCILobCharSetId()

用途

LOBロケータのデータベース・キャラクタ・セットIDを取得します。

構文

sword OCILobCharSetId ( OCIEnv                  *envhp,
OCIError                *errhp,
const OCILobLocator     *locp,
ub2                     *csid );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

キャラクタ・セットIDを取得するためのLOBロケータです。

csid (OUT)

入力LOBロケータのデータベース・キャラクタ・セットIDです。入力ロケータがBLOBまたはBFILE用の場合、バイナリLOBまたはバイナリ・ファイルにはキャラクタ・セットという概念がないため、csidには0 (ゼロ)が設定されます。コール元は、csid ub2用の領域を割り当てる必要があります。

コメント

入力CLOBまたはNCLOBロケータのキャラクタ・セットIDをcsid出力パラメータに戻します。

関連関数

OCIErrorGet()、OCILobCharSetForm()、OCILobLocatorIsInit()

OCILobClose()

用途

オープンしているLOBまたはBFILEをクローズします。

構文

sword OCILobClose ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCILobLocator  *locp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

クローズするLOBです。ロケータは、内部LOBまたは外部LOBを参照できます。

コメント

オープンしている内部または外部LOBをクローズします。BFILEは存在しているが、オープンしていない場合、エラーは戻りません。内部LOBがオープンしていない場合は、エラーが戻されます。

LOBのクローズでは、内部LOBと外部LOBのどちらに対してもサーバーへのラウンドトリップが必要です。内部LOBの場合、closeはクローズ・コールに依存するその他のコードをトリガーし、外部LOB (BFILE)の場合、closeはサーバー側のオペレーティング・システム・ファイルを実際にクローズします。

すべてのLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。ただし、LOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。

エラーが戻された場合、それ以降LOBはオープンとしてマークは付けられませんが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOBおよび非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。これが起こった場合は、LOB列のファンクション索引とドメイン索引を再作成します。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があるため、ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:
「LOBのオープンおよびクローズのための関数」

関連関数

OCIErrorGet()、OCILobOpen()、OCILobIsOpen()

OCILobCopy2()

用途

LOB値の全体または一部を別のLOB値にコピーします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobCopy2 ( OCISvcCtx        *svchp,
OCIError         *errhp,
OCILobLocator    *dst_locp,
OCILobLocator    *src_locp,
oraub8           amount,
oraub8           dst_offset,
oraub8           src_offset );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

dst_locp (IN/OUT)

一意に宛先LOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

src_locp (IN)

一意にソースLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

amount (IN)

ソースLOBから宛先LOBにコピーされる文字数(CLOBまたはNCLOB)またはバイト数(BLOB)です。このパラメータが受け入れる最大値はUB8MAXVAL (18446744073709551615)です。UB8MAXVALを指定することは、指定されたソースおよび宛先のオフセットを使用して、ソースLOBの全体を宛先LOBにコピーすることも意味します。

dst_offset (IN)

これは、宛先LOB用の絶対オフセットです。文字LOBでは、LOBの先頭から書込みを開始する位置までの文字数です。バイナリLOBでは、LOBの先頭から書込みを開始する位置までのバイト数です。オフセットは1から始まります。

src_offset (IN)

これは、ソースLOBの絶対オフセットです。文字LOBでは、LOBの先頭からの文字数です。バイナリLOBでは、バイト数です。オフセットは1から始まります。

コメント

内部LOB値全体または一部を別の内部LOB値に指定されたとおりにコピーします。データは、ソースから宛先にコピーされます。ソース(src_locp) LOBと宛先(dst_locp) LOBが存在している必要があります。

重複除外を有効にした列またはパーティションの全SecureFileを同じ列またはパーティション内のLOBにコピーすると、コピー内容が重複除外されます。

宛先のコピー開始位置にデータが存在する場合は、ソース・データによって上書きされます。宛先のコピー開始位置がカレント・データの終了位置を超えている場合は、0(ゼロ)バイトの充填文字(BLOBの場合)または空白(CLOBの場合)が、宛先LOBのカレント・データの末尾と、ソースから新たに書き込まれたデータの先頭との間に書き込まれます。新規に書き込むデータが宛先LOBの現行の長さよりも大きい場合、宛先LOBは、そのデータにあわせて拡張されます。許される最大長(つまり、4GB)を超える宛先LOBの拡張とNULL LOBのコピーはエラーになります。LOBのサイズが4GBを超える場合は、OCILobCopy2()を使用します。

ソースと宛先のLOBロケータは同じ型にしてください(つまり、両方ともBLOBまたは両方ともCLOB)。LOBバッファリングは、ロケータのどちらに対しても使用可能にしないでください。

この関数では、ソースまたは宛先としてのBFILEロケータを受け入れません。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

注意:
ソースLOBの長さを判断するには、OCILobGetLength2()をコールします。

関連関数

OCIErrorGet()、OCILobRead2()、OCILobAppend()、OCILobWrite2()、OCILobWriteAppend2()

OCILobCreateTemporary()

用途

一時LOBを作成します。

構文

sword OCILobCreateTemporary(OCISvcCtx          *svchp,
OCIError           *errhp,
OCILobLocator      *locp,
ub2                csid,
ub1                csfrm,
ub1                lobtype,
boolean            cache,
OCIDuration        duration);

パラメータ

svchp (IN)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一時LOBを指し示すロケータです。ロケータをこの関数に渡す前に、OCIDescriptorAlloc()を使用してロケータを割り当てる必要があります。このロケータは、LOBを指し示しているかどうかに関係なく、いずれの場合も一時LOBにより上書きされます。

csid (IN)

LOBキャラクタ・セットIDです。Oracle8i以上ではOCI_DEFAULTを渡します。

csfrm (IN)

バッファ・データのLOBキャラクタ・セット・フォームです。csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - CLOBを作成するためのデータベース・キャラクタ・セットID。OCI_DEFAULTを使用して、CLOBを暗黙的に作成することもできます。

- SQLCS_NCHAR - NCLOBを作成するためのNCHARキャラクタ・セットID。

デフォルト値はSQLCS_IMPLICITです。

lobtype (IN)

作成するLOBの型です。次の値が有効です。

- OCI_TEMP_BLOB - 一時BLOBの場合

- OCI_TEMP_CLOB - 一時CLOBまたはNCLOBの場合

cache (IN)

一時LOBをキャッシュに読み取る必要がある場合はTRUEを、その必要がない場合はFALSEを渡します。NOCACHE機能の場合、デフォルトはFALSEです。

duration (IN)

一時LOBの継続時間です。次に示す値が有効です。

- OCI_DURATION_SESSION

- OCI_DURATION_CALL

コメント

この関数は、ユーザーの一時表領域に一時LOBとそれに対応する索引を作成します。

この関数が完了すると、locpパラメータは、長さが0 (ゼロ)の空の一時LOBを指し示します。

一時LOBの存続期間は、durationパラメータによって決まります。一時LOBは、この期間の最後に解放されます。アプリケーションからOCILobFreeTemporary()コールを使用すると、一時LOBをより早く解放できます。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

関連項目:
一時LOBとその継続時間の詳細は、「一時LOBのサポート」を参照してください。

関連関数

OCILobFreeTemporary()、OCILobIsTemporary()、OCIDescriptorAlloc()、OCIErrorGet()

OCILobDisableBuffering()

用途

入力ロケータのLOBバッファリングを使用禁止にします。

構文

sword OCILobDisableBuffering ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCILobLocator  *locp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。

コメント

入力内部LOBロケータのLOBバッファリングを使用禁止にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムは使用されません。このコールでは、バッファリング・サブシステムでの変更は暗黙的にはフラッシュされません。ユーザーは、OCILobFlushBuffer()をコールして変更を明示的にフラッシュする必要があります。

この関数は、BFILEロケータを受け入れません。

関連関数

OCILobEnableBuffering()、OCIErrorGet()、OCILobFlushBuffer()

OCILobEnableBuffering()

用途

入力ロケータのLOBバッファリングを使用可能にします。

構文

sword OCILobEnableBuffering ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCILobLocator  *locp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。

コメント

入力内部LOBロケータのLOBバッファリングを使用可能にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムが使用されます。

ロケータのLOBバッファリングが使用可能な状態で、そのロケータがルーチンOCILobAppend()、OCILobCopy() (非推奨)、OCILobCopy2()、OCILobErase() (非推奨)、OCILobErase2()、OCILobGetLength() (非推奨)、OCILobGetLength2()、OCILobLoadFromFile() (非推奨)、OCILobLoadFromFile2()、OCILobTrim() (非推奨)、OCILobTrim2()、OCILobWriteAppend() (非推奨)またはOCILobWriteAppend2()のいずれかに渡されると、エラーが戻ります。

この関数は、BFILEロケータを受け入れません。

関連関数

OCILobDisableBuffering()、OCIErrorGet()、OCILobWrite() (非推奨)、OCILobWrite2()、OCILobRead() (非推奨)、OCILobRead2()、OCILobFlushBuffer()、OCILobWriteAppend() (非推奨)、OCILobWriteAppend2()

OCILobErase2()

用途

内部LOBデータの一部を指定のオフセットの位置から消去します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobErase2 ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCILobLocator   *locp,
oraub8          *amount,
oraub8          offset );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

amount (IN/OUT)

消去する文字数(CLOBまたはNCLOBの場合)またはバイト数(BLOBの場合)です。INでは、値は消去する文字数またはバイト数を表します。OUTでは、値は消去された実際の文字数またはバイト数です。

offset (IN)

データの消去を開始するLOB値の、先頭からの絶対オフセット(CLOBまたはNCLOBの場合は文字数、BLOBの場合はバイト数)です。オフセットは1から始まります。

コメント

実際に消去した文字数またはバイト数が戻ります。BLOBの場合、消去するということは、0 (ゼロ)バイトの充填文字で既存のLOB値を上書きするということです。CLOBの場合は、既存のLOB値が空白で上書きされます。

この関数は内部LOBにのみ有効で、BFILEには使用できません。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連関数

OCIErrorGet()、OCILobErase2()、OCILobRead2()、OCILobAppend()、OCILobCopy2()、OCILobWrite2()、OCILobWriteAppend2()

OCILobFileClose()

用途

オープンしているBFILEをクローズします。

構文

sword OCILobFileClose ( OCISvcCtx            *svchp,
OCIError             *errhp,
OCILobLocator        *filep );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN/OUT)

クローズするBFILEを参照するBFILEロケータへのポインタです。

コメント

オープンしているBFILEをクローズします。内部LOBに対してこの関数をコールするとエラーになります。BFILEは存在しているが、オープンしていない場合、エラーは戻りません。

この関数は、特定のBFILEロケータに対して初めてコールしたときにかぎり有効です。同じBFILEロケータを使用してこの関数を続けてコールしても何も行われません。

関連項目:
BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

関連関数

OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileIsOpen()、OCILobFileOpen()、OCILobOpen()、OCILobIsOpen()

OCILobFileCloseAll()

用途

指定のサービス・コンテキストでオープンしているすべてのBFILEをクローズします。

構文

sword OCILobFileCLoseAll ( OCISvcCtx   *svchp,
OCIError    *errhp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

指定のサービス・コンテキストでオープンしているすべてのBFILEをクローズします。

関連項目:
BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

関連関数

OCILobFileClose()、OCIErrorGet()、OCILobFileExists()、OCILobFileIsOpen()

OCILobFileExists()

用途

サーバーのオペレーティング・システムにBFILEが存在するかどうかをテストします。

構文

sword OCILobFileExists ( OCISvcCtx        *svchp,
OCIError         *errhp,
OCILobLocator    *filep,
boolean          *flag );

パラメータ

svchp (IN)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN)

ファイルを参照するBFILEロケータへのポインタです。

flag (OUT)

サーバーにBFILEが存在する場合はTRUEを、存在しない場合はFALSEを戻します。

コメント

サーバーのファイル・システムにBFILEが存在するかどうかをチェックします。内部LOBに対してこの関数をコールするとエラーになります。

関連項目:
BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

関連関数

OCIErrorGet()、OCILobFileClose()、OCILobFileCloseAll()、OCILobFileIsOpen()、OCILobOpen()、OCILobIsOpen()

OCILobFileGetName()

用途

BFILEロケータのディレクトリ・オブジェクトおよびファイル名を取得します。

構文

sword OCILobFileGetName ( OCIEnv                   *envhp,
OCIError                 *errhp,
const OCILobLocator      *filep,
OraText                  *dir_alias,
ub2                      *d_length,
OraText                  *filename,
ub2                      *f_length );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN)

ディレクトリ・オブジェクトおよびファイル名を取得するためのBFILEロケータです。

dir_alias (OUT)

ディレクトリ・オブジェクトが配置されているバッファです。これはUTF-16で可能です。ディレクトリ・オブジェクト用の十分な領域を割り当てる必要があります。ディレクトリ・オブジェクトの最大長は30バイトです。

d_length (IN/OUT)

次の用途に使用できます(Unicodeのコードポイントまたはバイト単位が可能です)。

- IN: 入力dir_alias文字列の長さ

- OUT: 戻されるdir_alias文字列の長さ

filename (OUT)

ファイル名が配置されているバッファです。ファイル名用の十分な領域を割り当てる必要があります。ファイル名の最大長は255バイトです。

f_length (IN/OUT)

次の用途に使用できます(バイト数単位)。

- IN: 入力filenameバッファの長さ

- OUT: 戻されるfilename文字列の長さ

コメント

このBFILEロケータに対応付けられたディレクトリ・オブジェクトとファイル名を戻します。環境ハンドルによって、Unicodeかどうかが判断されます。内部LOBに対してこの関数をコールするとエラーになります。

関連項目:
BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

関連関数

OCILobFileSetName()、OCIErrorGet()

OCILobFileIsOpen()

用途

BFILEがオープンしているかどうかをテストします。

構文

sword OCILobFileIsOpen ( OCISvcCtx        *svchp,
OCIError         *errhp,
OCILobLocator    *filep,
boolean          *flag );

パラメータ

svchp (IN)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN)

確認するBFILEロケータへのポインタです。

flag (OUT)

この特定のロケータを使用してBFILEがオープンされた場合はTRUEを、オープンされなかった場合はFALSEを戻します。

コメント

サーバー上のファイルがfilep BFILEロケータを使用してオープンされたかどうかをチェックします。内部LOBに対してこの関数をコールするとエラーになります。

OCILobFileOpen()またはOCILobOpen()コマンドに入力BFILEロケータが渡されなかった場合、ファイルはそのロケータによってオープンされていないとみなされます。ただし、別のロケータがそのファイルをオープンしていることがあります。オープンは、特定のロケータに対応付けられます。

関連項目:
BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

関連関数

OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileClose()、OCILobFileOpen()、OCILobOpen()、OCILobIsOpen()

OCILobFileOpen()

用途

読取り専用アクセス用にサーバーのファイル・システム上のBFILEをオープンします。

構文

sword OCILobFileOpen ( OCISvcCtx            *svchp,
OCIError             *errhp,
OCILobLocator        *filep,
ub1                  mode );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN/OUT)

オープンするBFILEです。ロケータがBFILEを参照していない場合はエラーが発生します。

mode (IN)

ファイルをオープンするモードです。有効なモードはOCI_FILE_READONLYのみです。

コメント

サーバーのファイル・システムのBFILEをオープンします。BFILEは、読取り専用アクセス用にオープンできます。BFILEは、Oracle Databaseを通して書き込むことはできません。内部LOBに対してこの関数をコールするとエラーになります。

この関数は、特定のBFILEロケータに対して初めてコールしたときにかぎり有効です。同じBFILEロケータを使用してこの関数を続けてコールしても何も行われません。

関連項目:
BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

関連関数

OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileClose()、OCILobFileIsOpen()、OCILobOpen()、OCILobIsOpen()

OCILobFileSetName()

用途

BFILEロケータ内にディレクトリ・オブジェクトとファイル名を設定します。

構文

sword OCILobFileSetName ( OCIEnv             *envhp,
OCIError           *errhp,
OCILobLocator      **filepp,
const OraText      *dir_alias,
ub2                d_length,
const OraText      *filename,
ub2                f_length );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。UTF-16設定が含まれます。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filepp (IN/OUT)

ディレクトリ・オブジェクトおよびファイル名を設定するBFILEロケータへのポインタです。

dir_alias (IN)

BFILEロケータに設定するディレクトリ・オブジェクト名(OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングが必要)が含まれたバッファです。

d_length (IN)

入力dir_aliasパラメータの長さ(バイト単位)です。

filename (IN)

BFILEロケータに設定するファイル名(OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングが必要)が含まれたバッファです。

f_length (IN)

入力filenameパラメータの長さ(バイト単位)です。

コメント

内部LOBに対してこの関数をコールするとエラーになります。

関連項目:
BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

関連関数

OCILobFileGetName()、OCIErrorGet()

OCILobFlushBuffer()

用途

このLOBのすべてのバッファをサーバーにフラッシュするか、または書き込みます。

構文

sword OCILobFlushBuffer ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCILobLocator   *locp
ub4             flag );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

LOBを一意に参照する内部ロケータです。

flag (IN)

このフラグをOCI_LOB_BUFFER_FREEに設定すると、LOBのバッファ・リソースは、フラッシュの後に解放されます。「コメント」の項を参照してください。

コメント

入力ロケータによって参照されるLOBに関連するバッファリング・サブシステムに加えられた変更を、サーバーにフラッシュします。このルーチンでは、バッファのデータをデータベースのLOBに実際に書き込みます。LOBバッファリングは入力LOBロケータに対して使用可能にしてください。

このフラッシュ操作のデフォルトでは、別のバッファLOB操作への再割当て用にバッファ・リソースは解放されません。バッファを明示的に解放する場合は、flagパラメータをOCI_LOB_BUFFER_FREEに設定できます。

クライアント・アプリケーションでフラッシュ後のバッファ値を読み取る予定で、あらかじめバッファの現在値が望む値であることがわかっている場合、サーバーからデータを再度読み取る必要はありません。

バッファの解放による影響はユーザーにはほとんど認識されません。ただし、LOB内の同じ範囲に次にアクセスするときに、サーバーをラウンドトリップすることになり、バッファ・リソースの取得およびLOBから読み取られるデータによるバッファの初期化のための追加コストがかかります。このオプションは、オンボード・メモリーが少ないクライアント環境用です。

関連関数

OCILobEnableBuffering()、OCIErrorGet()、OCILobWrite() (非推奨)、OCILobWrite2()、OCILobRead() (非推奨)、OCILobRead2()、OCILobDisableBuffering()、OCILobWriteAppend() (非推奨)、OCILobWriteAppend2()

OCILobFreeTemporary()

用途

一時LOBを解放します。

構文

sword OCILobFreeTemporary( OCISvcCtx          *svchp,
OCIError           *errhp,
OCILobLocator      *locp);

パラメータ

svchp (IN/OUT)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

解放するLOBを一意に参照するロケータです。

コメント

このロケータが指し示す一時LOBの内容を解放します。ロケータ自体は、OCIDescriptorFree() がコールされるまで解放されません。

locpパラメータで渡されるLOBロケータが一時LOBを指し示していない場合は、エラーを戻します。LOBロケータが次のようであることが原因である可能性があります。

- 永続LOBを指し示しています。

- 解放された一時LOBを指し示しています。

- 何も指し示していません。

関連関数

OCILobCreateTemporary()、OCILobIsTemporary()、OCIErrorGet()

OCILobGetChunkSize()

用途

LOBのチャンク・サイズを取得します。

構文

sword OCILobGetChunkSize ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCILobLocator   *locp,
ub4             *chunk_size );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

使用可能なチャンク・サイズを取得する内部LOBです。

chunk_size (OUT)

記憶域パラメータBASICFILEを使用するLOBの場合、内部LOB値を格納するために使用するチャンク領域の量です。これは、ユーザーがLOB値の読取りまたは書込み時に使用する量です。可能な場合は、チャンクの先頭などのチャンクの境界で書込みを開始し、1つのチャンクを1回で書き込みます。

chunk_sizeパラメータは、BLOB、CLOBおよびNCLOBに対して、バイト数で戻されます。

記憶域パラメータSECUREFILEを使用するLOBの場合、chunk_sizeは推奨サイズであり、下位互換性のために提供されています。

コメント

内部LOBを含む表を作成する際には、ユーザーがチャンク係数を指定できます。これは、Oracle Databaseのブロック数の倍数です。これは、LOB値のアクセス時または変更時にLOBデータ・レイヤーによって使用されるチャンク・サイズに対応します。チャンクの一部はシステム関連情報の格納に使用され、それ以外の部分にLOB値が格納されます。このファンクションは、LOB値を格納するLOBチャンクで使用される領域容量を戻します。アプリケーションがこのチャンク・サイズの倍数を使用して読取りまたは書込みリクエストを発行すると、パフォーマンスが向上します。LOBチャンクはバージョン化され、すべての書込みがチャンクを基準に行われると、余分なバージョン分割が行われず、重複もしないため、書込みの場合にはさらに利点があります。ユーザーは同一チャンクに対してwriteコールを複数回発行するかわりに、1つのチャンク内でwriteコールを十分な数だけまとめることができます。

関連項目:
「LOBの読取り/書込みパフォーマンスの向上」

関連関数

OCIErrorGet()、OCILobGetStorageLimit()、OCILobRead() (非推奨)、OCILobRead2()、OCILobAppend()、OCILobCopy() (非推奨)、OCILobCopy2()、OCILobWrite() (非推奨)、OCILobWrite2()、OCILobWriteAppend() (非推奨)、OCILobWriteAppend2()

OCILobGetContentType()

用途

SecureFile内のデータのユーザー指定コンテンツ・タイプ文字列を取得します(設定されている場合)。

構文

sword OCILobGetContentType ( OCIEnv         *envhp,
OCISvcCtx      *svchp,
OCIError       *errhp,
OCILobLocator  *lobp,
oratext        *contenttypep,
ub4            *contenttypelenp,
ub4            mode );

パラメータ

envhp (IN)

環境ハンドルです。

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

lobp (IN)

一意にLOBを参照するLOBロケータです。

contenttypep (IN/OUT)

正常に実行された後、コンテンツ・タイプが格納されるバッファへのポインタです。この関数をコールする前に、バッファを割り当てる必要があります。割当てバッファのサイズは>= OCI_LOB_CONTENTTYPE_MAXSIZEであることが必要です。

contenttypelenp (IN/OUT)

このフィールドをcontenttypepバッファのサイズに設定します。コールが正常に実行された後、このフィールドは、戻されたcontenttypepのサイズを保持します。

mode (IN)

今後の使用のために確保されています。現時点では0 (ゼロ)を渡します。

コメント

この関数はSecureFileでのみ機能します。lobpがSecureFileでない場合、SECUREFILE_WRONGTYPEエラーが戻されます。lobpがバッファリングされた一時LOBまたは抽象LOBである場合、SECUREFILE_BADLOBエラーが戻されます。

SecureFileにcontenttypeが関連付けられていない場合、バッファcontenttypepは変更されず、contenttypeの長さ(contenttypelenp)が0 (ゼロ)で戻されます。

ContentType文字列の最大可能サイズは次のように定義されています。

#define OCI_LOB_CONTENTTYPE_MAXSIZE 128

ContentTypeはASCII (つまり、1バイトまたは7ビットUTF8)です。

関連関数

OCILobSetContentType()

OCILobGetLength2()

用途

LOBの長さを取得します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobGetLength2 ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCILobLocator  *locp,
oraub8         *lenp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

一意にLOBを参照するLOBロケータです。内部LOBでは、このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。BFILEの場合は、OCILobFileSetName()、SELECT文またはOCIObjectPin()を使用してロケータを設定できます。

lenp (OUT)

出力時、LOBがNULLではない場合、LOBの長さを示します。文字LOBでは文字数であり、バイナリLOBおよびBFILEではLOBのバイト数です。

コメント

LOBの長さを取得します。LOBがNULLの場合、長さは未定義です。BFILEの長さにはEOF (存在する場合)が含まれます。空の内部LOBの長さは0 (ゼロ)です。

クライアント側のキャラクタ・セットが可変幅かどうかに関係なく、出力の長さは、CLOBとNCLOBでは文字数、BLOBとBFILEではバイト数です。

注意:
以前のOCILobErase2()またはOCILobWrite2()のコールによってLOBに書き込まれた0 (ゼロ)バイトや空白の充填文字も、長さの一部になります。

関連関数

OCIErrorGet()、OCILobFileSetName()、OCILobGetLength2()、OCILobRead2()、OCILobWrite2()、OCILobCopy2()、OCILobAppend()、OCILobLoadFromFile2()、OCILobWriteAppend2()

OCILobGetOptions()

用途

指定のSecureFile LOBについて指定の入力オプション・タイプに対応する、有効化された設定を取得します。

構文

sword OCILobGetOptions ( OCISvcCtx         *svchp,
OCIError          *errhp,
OCILobLocator     *locp,
ub4               option_types,
void              *optionsp,
ub4               optionslenp,
ub4               mode );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBまたはBFILEを参照するLOBロケータまたはBFILEロケータです。このロケータは、svchpに指定したサーバーから取得されるようにしてください。

option_types (IN)

ビット単位の包含OR (記号「|」)で結合可能な指定のオプション・タイプです。

- 圧縮: OCI_LOB_OPT_COMPRESS

- 暗号化: OCI_LOB_OPT_ENCRYPT

- 重複除外: OCI_LOB_OPT_DEDUPLICATE

optionsp (OUT)

指定の各オプション・タイプの現行設定です。可能な値は次のとおりです。

- OCI_LOB_OPT_COMPRESS_ON

- OCI_LOB_OPT_ENCRYPT_ON

- OCI_LOB_OPT_DEDUPLICATE_ON

optionslenp (OUT)

optionspで示した値の長さです。

mode (IN)

今後の使用のために確保されています。0 (ゼロ)を渡します。

コメント

指定できるのは、列で有効化されているオプション・タイプのみです。列で有効化されていないオプション・タイプの値を取得しようとすると、エラーが戻されます。たとえば、圧縮が有効化されているLOB列があり、option_typesパラメータにOCI_LOB_OPT_ENCRYPTを設定してOCILobGetOptions()をコールすると、エラーが発生します。

戻り値はvoidポインタとしてキャストされたub4ポインタであり、今後のオプション・タイプおよび値の拡張が可能です。戻されるoptionslenpはsizeof(ub4)である必要があります。

関連関数

OCILobSetOptions()

OCILobGetStorageLimit()

用途

内部LOB (BLOB、CLOBまたはNCLOB)の最大長(バイト単位)を取得します。

構文

sword OCILobGetStorageLimit ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCILobLocator  *locp,
oraub8         *limitp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

一意にLOBを参照するLOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

limitp (OUT)

データベースに格納できるLOBの最大長(バイト単位)です。

コメント

ブロック・サイズの範囲は2から32KBであるため、LOBの場合、最大LOBサイズの範囲は8から128TBです。

関連項目:
「4GBより大きいサイズのLOBの使用」

関連関数

OCILobGetChunkSize()

OCILobIsEqual()

用途

2つのLOBまたはBFILEロケータの等価を比較します。

構文

sword OCILobIsEqual ( OCIEnv                  *envhp,
const OCILobLocator     *x,
const OCILobLocator     *y,
boolean                 *is_equal );

パラメータ

envhp (IN)

OCI環境ハンドルです。

x (IN)

比較するLOBロケータです。

y (IN)

比較するLOBロケータです。

is_equal (OUT)

LOBロケータが等価の場合はTRUE、等価でない場合はFALSEです。

コメント

指定されたLOBまたはBFILEロケータの等価を比較します。2つのLOBまたはBFILEロケータは、どちらも同じLOBまたはBFILE値を参照している場合のみ等価になります。

この関数では、2つのNULLロケータは等価とはみなされません。

関連関数

OCILobAssign()、OCILobLocatorIsInit()

OCILobIsOpen()

用途

LOBまたはBFILEがオープンされているかどうかを確認します。

構文

sword OCILobIsOpen ( OCISvcCtx        *svchp,
OCIError         *errhp,
OCILobLocator    *locp,
boolean          *flag );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

確認するLOBロケータへのポインタです。ロケータは、内部LOBまたは外部LOBを参照できます。

flag (OUT)

内部LOBがオープンされている場合、または入力ロケータを使用してBFILEがオープンされた場合は、TRUEを戻します。それ以外はFALSEを戻します。

コメント

内部LOBがオープンされているかどうか、またはBFILEが入力ロケータを使用してオープンされているかどうかをチェックします。

BFILEの場合

入力BFILEロケータがOCILobOpen()またはOCILobFileOpen()に渡されていない場合は、BFILEロケータによるBFILEのオープンは行わないとみなされます。ただし、別のBFILEロケータによってBFILEがオープンされている場合はあります。別のロケータを使用して、そのBFILEに対して複数のオープンが実行されることがあります。つまり、オープンはBFILEの特定のロケータに関連付けられています。

内部LOBの場合

オープンは、ロケータではなくLOBに関連付けられます。locator1がLOBをオープンした場合は、locator2もオープン時にそのLOBを参照します。

内部LOBの場合、このコールでは、サーバー上の状態によって、LOBがオープンしているかどうかを確認するため、サーバー・ラウンドトリップが必要です。外部LOB (BFILE)の場合も、サーバー側のオペレーティング・システム・ファイルによってそのLOBがオープンされているかどうかを確認するため、ラウンドトリップが必要です。

関連項目:
「LOBのオープンおよびクローズのための関数」

関連関数

OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileClose()、OCILobFileIsOpen()、OCILobFileOpen()、OCILobOpen()

OCILobIsTemporary()

用途

ロケータが一時LOBを指し示しているかどうかを確認します。

構文

sword OCILobIsTemporary(OCIEnv            *envhp,
OCIError          *errhp,
OCILobLocator     *locp,
boolean           *is_temporary);

パラメータ

envhp (IN)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

確認するロケータです。

is_temporary (OUT)

ロケータが一時LOBを指し示している場合はTRUEを、そうでない場合はFALSEを戻します。

コメント

この関数は、ロケータが一時LOBを指し示しているかどうかを調べるためにロケータを確認します。指し示している場合は、is_temporaryがTRUEに設定されます。そうでない場合は、is_temporaryがFALSEに設定されます。

関連関数

OCILobCreateTemporary()、OCILobFreeTemporary()

OCILobLoadFromFile2()

用途

ファイルの全体または一部を内部LOBにロードおよびコピーします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobLoadFromFile2 ( OCISvcCtx        *svchp,
OCIError         *errhp,
OCILobLocator    *dst_locp,
OCILobLocator    *src_locp,
oraub8           amount,
oraub8           dst_offset,
oraub8           src_offset );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

dst_locp (IN/OUT)

BLOB型、CLOB型またはNCLOB型の宛先内部LOBを一意に参照するロケータです。

src_locp (IN/OUT)

ソースBFILEを一意に参照するロケータです。

amount (IN)

ロードされるバイト数です。

dst_offset (IN)

これは、宛先LOB用の絶対オフセットです。文字LOBでは、LOBの先頭から書込みを開始する位置までの文字数です。バイナリLOBでは、LOBの先頭から読取りを開始する位置までのバイト数です。オフセットは1から始まります。

src_offset (IN)

これは、ソースBFILEの絶対オフセットです。BFILEの先頭からのバイト数です。オフセットは1から始まります。

コメント

BFILE値の一部またはすべてを指定どおりに内部LOBにロードおよびコピーします。データは、ソースBFILEから宛先の内部LOB (BLOBまたはCLOB)にコピーされます。BFILEデータをCLOBまたはNCLOBにコピーするときに、キャラクタ・セットの変換は実行されません。バイナリ・データがBLOBにロードされるときにも、キャラクタ・セット変換は実行されません。このため、BFILEデータは、データベースのLOBと同じキャラクタ・セットにする必要があります。これを検証するエラー・チェックは実行されません。

ソース(src_locp) LOBと宛先(dst_locp) LOBが存在している必要があります。宛先のコピー開始位置にデータが存在する場合は、ソース・データによって上書きされます。宛先のコピー開始位置がカレント・データの終了位置を超えている場合は、0 (ゼロ)バイトの充填文字(BLOBの場合)または空白(CLOBの場合)が、宛先LOBのデータの末尾と、ソースから新たに書き込まれたデータの先頭との間に書き込まれます。新規に書き込むデータが宛先LOBの現行の長さよりも大きい場合、宛先LOBは、そのデータにあわせて拡張されます。

許される最大長(4GB)を超える宛先LOBの拡張(4GBを超えるサイズのLOBに使用する場合はOCILobLoadFromFile2()を参照)と、NULL BFILEのコピーは、エラーになります。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連関数

OCIErrorGet()、OCILobAppend()、OCILobWrite2()、OCILobTrim2()、OCILobCopy2()、OCILobGetLength2()、OCILobLoadFromFile2()、OCILobWriteAppend2()

OCILobLocatorAssign()

用途

LOBまたはBFILEロケータを別のロケータに割り当てます。

構文

sword OCILobLocatorAssign ( OCISvcCtx            *svchp,
OCIError             *errhp,
const OCILobLocator  *src_locp,
OCILobLocator         **dst_locpp );

パラメータ

svchp (IN/OUT)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

src_locp (IN)

コピー元のLOBまたはBFILEロケータです。

dst_locpp (IN/OUT)

コピー先となるLOBまたはBFILEロケータです。コール元で、OCIDescriptorAlloc()をコールしてOCILobLocatorに領域を割り当てる必要があります。

コメント

このコールは、ソース・ロケータを宛先ロケータに割り当てます。割当て後は、両方のロケータは同じLOBデータを参照します。内部LOBの場合は、宛先ロケータが表に格納されているときのみ、ソース・ロケータのLOBデータが宛先ロケータのLOBデータにコピーされます。このため、宛先ロケータが含まれているオブジェクトにフラッシュを発行すると、LOBデータがコピーされます。BFILEの場合、オペレーティング・システム・ファイルを参照するロケータのみが表にコピーされ、オペレーティング・システム・ファイルはコピーされません。

このコールはOCILobAssign()と似ていますが、OCILobLocatorAssign()はOCI環境ハンドル・ポインタではなく、OCIサービス・ハンドル・ポインタを使用します。また、OCILobLocatorAssign()は一時LOBに対して使用できますが、OCILobAssign()は使用できません。

注意:
OCILobLocatorAssign()関数が正常に終了しなかった場合、ターゲット・ロケータは以前の状態にはリストアされません。ターゲット・ロケータは、初期化しなおすまで、後続の操作で使用しないでください。

宛先ロケータが一時LOBに対するロケータの場合、宛先一時LOBは、ソースLOBロケータを割り当てる前に解放されます。

ソースLOBロケータから一時LOBを参照すると、宛先ロケータが一時LOBにも作成されます。ソース・ロケータと宛先ロケータは、理論的には異なる一時LOBになります。OCI_DEFAULTモードでは、ソースの一時LOBがディープ・コピーされ、その一時LOBの新しいディープ・コピーを参照するために宛先ロケータが作成されます。したがって、OCILobLocatorAssign()をコールした後は、OCILobIsEqual()でFALSEが戻ります。ただし、OCI_OBJECTモードの場合は、ディープ・コピー数を最小化するために最適化が行われるため、ソース・ロケータと宛先ロケータは、いずれかのLOBロケータを介して変更が行われるまで、同じLOBを指し示します。したがって、最初の変更が行われるまで、OCILobLocatorAssign()直後のOCILobIsEqual()では、TRUEが戻ります。これらのいずれの場合にも、OCILobLocatorAssign()後のソースまたは宛先に対する変更は、他方(つまり、宛先またはソース)のLOBには反映されません。ソースおよび宛先が同じLOBを指し示し、変更を他方にも反映する場合は、等号を使用して、2つのLOBロケータ・ポインタが同じLOBロケータを参照するようにします。

関連関数

OCIErrorGet()、OCILobAssign()、OCILobIsEqual()、OCILobLocatorIsInit()

OCILobLocatorIsInit()

用途

指定されたLOBまたはBFILEロケータが初期化されているかどうかをテストします。

構文

sword OCILobLocatorIsInit ( OCIEnv               *envhp,
OCIError             *errhp,
const OCILobLocator  *locp,
boolean              *is_initialized );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

確認するLOBまたはBFILEロケータです。

is_initialized (OUT)

特定のLOBまたはBFILEロケータが初期化されているとTRUE、初期化されていないとFALSEを戻します。

コメント

指定されたLOBまたはBFILEロケータが初期化されているかどうかをテストします。

内部LOBロケータは、次のいずれかの方法で初期化できます。

- NULL以外のLOBをロケータに選択します。

- OCIObjectPin()を使用して、LOB属性がNULL以外のオブジェクトを確保します。

- OCIAttrSet()を使用して、ロケータをEmpty値に設定します。

関連項目:
「LOBロケータ属性」

BFILEロケータは、次のいずれかの方法で初期化できます。

- NULL以外のBFILEをロケータに選択します。

- OCIObjectPin()を使用して、BFILE属性がNULL以外のオブジェクトを確保します。

- OCILobFileSetName()をコールします。

関連関数

OCIErrorGet()、OCILobIsEqual()

OCILobOpen()

用途

指定されたモードでLOB (内部または外部)をオープンします。

構文

sword OCILobOpen ( OCISvcCtx        *svchp,
OCIError         *errhp,
OCILobLocator    *locp,
ub1              mode );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

オープンするLOBです。ロケータは、内部LOBまたは外部LOBを参照できます。

mode (IN)

LOBまたはBFILEをオープンするモードです。Oracle8i以上の場合、LOBに対する有効なモードは、OCI_LOB_READONLYおよびOCI_LOB_READWRITEです。OCI_FILE_READONLYは、OCILobFileOpen()の入力モードとして使用します。入力ロケータがBFILEに対するロケータの場合、OCI_FILE_READONLYはOCILobOpen()とともに使用できます。

コメント

同じLOBを2度オープンするとエラーが発生します。BFILEは、読取り/書込みモードではオープンできません。読取り専用モードでオープンされているLOBまたはBFILEに書込みを行うと、エラーが戻されます。

LOBのオープンでは、内部LOBと外部LOBのどちらに対してもサーバーへのラウンドトリップが必要です。内部LOBをオープンすると、そのオープン・コールに応じて他のコードが実行されます。外部LOB (BFILE)をオープンすると、サーバー側のオペレーティング・システム・ファイルがオープンされるため、ラウンドトリップが必要です。

LOBを操作するために、LOBをオープンする必要はありません。ファンクション索引、拡張索引作成機能またはコンテキストを使用し、複数のコールを行ってLOBに対する更新または書込みを行う場合は、最初にOCILobOpen()をコールし、次に、そのLOBを必要な回数だけ更新し、最後にOCILobClose()をコールします。この一連の操作によって、索引は、書込み操作ごとに更新されるのではなく、すべての書込み操作の最後に1回更新されます。

すべてのLOB操作をオープン・コールとクローズ・コールで囲む必要はありません。ただし、LOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。

エラーが戻された場合、それ以降LOBはオープンとしてマークは付けられませんが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOBおよび非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。これが起こった場合は、LOB列のファンクション索引とドメイン索引を再作成します。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があるため、ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:
「LOBのオープンおよびクローズのための関数」

関連関数

OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileClose()、OCILobFileIsOpen()、OCILobFileOpen()、OCILobIsOpen()

OCILobRead2()

用途

LOBまたはBFILEの一部をコールの指定どおりにバッファに読み取ります。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobRead2 ( OCISvcCtx          *svchp,
OCIError           *errhp,
OCILobLocator      *locp,
oraub8             *byte_amtp,
oraub8             *char_amtp,
oraub8             offset,
void               *bufp,
oraub8             bufl,
ub1                piece,
void               *ctxp,
OCICallbackLobRead2 (cbfp)
( void          *ctxp,
const void    *bufp,
oraub8        lenp,
ub1           piecep
void          **changed_bufpp,
oraub8        *changed_lenp
)
ub2                csid,
ub1                csfrm );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

一意にLOBまたはBFILEを参照するLOBまたはBFILEロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

byte_amtp(IN/OUT)

IN: データベースから読み取るバイト数です。BLOBおよびBFILEに対して常に使用されます。CLOBおよびNCLOBに対しては、char_amtpが0 (ゼロ)の場合のみ使用されます。

OUT: ユーザー・バッファに読み取られるバイト数です。

char_amtp(IN/OUT)

IN: ユーザー・バッファに読み取られる最大文字数です。BLOBおよびBFILEの場合は無視されます。

OUT: ユーザー・バッファに読み取られる文字数です。BLOBおよびBFILEの場合は未定義になります。

offset (IN)

入力時、これはLOB値の先頭からの絶対オフセットです。文字LOB (CLOB、NCLOB)ではLOBの先頭からの文字数であり、バイナリLOBまたはBFILEではバイト数です。先頭位置は1です。

ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。

bufp (IN/OUT)

ピースの読取り先バッファへのポインタです。buflのメモリー長が割り当てられるとみなされます。

bufl (IN)

オクテットで示したバッファの長さです。buflパラメータがバイト数で指定され、amtpパラメータが文字で指定されている場合、この値は、CLOBおよびNCLOBのamtp値(csfrm=SQLCS_NCHAR)とは異なります。

piece (IN)

OCI_ONE_PIECE: コールではポーリングは想定されません。示された量がバッファ長より大きい場合、バッファには可能なかぎり格納されます。

ポーリングでは、最初にOCI_FIRST_PIECE、後続のコールでOCI_NEXT_PIECEを渡します。OCI_FIRST_PIECEはコールバックの使用時に渡される必要があります。

ctxp (IN)

コールバック関数用のコンテキスト・ポインタです。NULLにできます。

cbfp (IN)

各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、ピースごとにOCI_NEED_DATAが戻ります。

コールバック関数は、OCI_CONTINUEを戻して読取りを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの読取りは終了します。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。

lenp (IN)

bufpにおけるカレント・ピースのバイト長です。

piecep (IN)

ピースは、OCI_FIRST_PIECE、OCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ・データのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。サーバーとクライアントの設定が同一である場合を除き、サーバーのキャラクタ・セットとはみなされません。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - データベース・キャラクタ・セットID

- SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。csfrmが指定されていない場合は、デフォルトが使用されます。

コメント

LOBまたはBFILEの一部をコールの指定どおりにバッファに読み取ります。NULL属性のLOBまたはBFILEから読み取るとエラーになります。

注意:
LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm)を指定します。

BFILEの場合は、オペレーティング・システム・ファイルがサーバー上に存在しており、それらのファイルは、入力ロケータを使用してOCILobFileOpen()またはOCILobOpen()によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がOracle Databaseにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。

OCILobRead2()に対してポーリング・モードを使用するとき、最初のコールではoffsetおよびamtpの値を指定する必要がありますが、その後のOCILobRead2()のポーリング・コールではこれらの値を指定する必要はありません。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

注意:
OCILobRead2()操作を終了して文ハンドルを解放するには、OCIBreak()コールを使用します。

次の点は、ストリーム・モードでのLOBデータの読取りに適用されます。

- ポーリング・モードを使用する場合は、最初のOCILobRead2()コールでchar_amtp、byte_amtpおよびoffsetパラメータを指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。byte_amtpおよびchar_amtpの両方が0 (ゼロ)を指すように設定されており、OCI_FIRST_PIECEが渡された場合、ポーリング・モードが想定され、LOBの末尾までデータが読み取られます。出力では、byte_amtpは、現在のピースに読み取られるバイト数を示します。CLOBおよびNCLOBでは、char_amtpは現在のピースに読み取られる文字数を示します。

- コールバックを使用する場合、lenパラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenパラメータをチェックします。

- ポーリングを使用する場合、byte_amtpパラメータを参照し、現在のピースでバッファに格納されている量を確認します。CLOBおよびNCLOBでは、char_amtpはバッファに読み取られる文字数も戻します。

UTF-16形式でデータを読み取るには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

関連項目:

- Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください。

- BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

- LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

- 付録B「OCIデモ・プログラム」

- ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

- 「OCIでのポーリング・モード操作」

関連関数

OCIErrorGet()、OCILobWrite2()、OCILobFileSetName()、OCILobWriteAppend2()

OCILobSetContentType()

用途

SecureFile内のデータのコンテンツ・タイプ文字列を、アプリケーションで使用できるものに設定します。

構文

sword OCILobSetContentType ( OCIEnv        *envhp,
OCISvcCtx     *svchp,
OCIError      *errhp,
OCILobLocator *lobp,
const oratext *contenttypep,
ub4           contenttypelen,
ub4           mode);

パラメータ

envhp (IN)

環境ハンドルです。

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

lobp (IN)

一意にLOBを参照するLOBロケータです。

contenttypep (IN)

指定のLOBに対して設定されるcontenttypeです。

contenttypelen (IN)

バイトで示したcontenttypeのサイズです。このサイズはOCI_LOB_CONTENTTYPE_MAXSIZEバイト以下であることが必要です。

mode (IN)

今後の使用のために確保されています。現時点では0 (ゼロ)を渡します。

コメント

この関数はSecureFileでのみ機能します。lobpがSecureFileでない場合、SECUREFILE_WRONGTYPEエラーが戻されます。lobpがバッファリングされた一時LOBまたは抽象LOBである場合、SECUREFILE_BADLOBエラーが戻されます。

ContentType文字列の最大可能サイズは次のように定義されています。

#define OCI_LOB_CONTENTTYPE_MAXSIZE 128

ContentTypeはASCII (つまり、1バイトまたは7ビットUTF8)です。

SecureFileについて設定された既存のcontenttypeを消去するには、contenttypepを(oratext *)0、contenttypelenを0に設定したOCILobSetContentType()をコールします。

関連関数

OCILobGetContentType()

OCILobSetOptions()

用途

SecureFile LOBのオプション設定を有効化します。

構文

sword OCILobSetOptions ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCILobLocator   *locp,
ub4             option_types,
void            *optionsp,
ub4             optionslen,
ub4             mode );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照するLOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

option_types (IN)

ビット単位の包含OR (「|」)を使用して、複数のオプション・タイプと値を指定できます。LOB列で有効化されていないoption_types値を指定すると、エラーになります。

- 圧縮: OCI_LOB_OPT_COMPRESS

- 重複除外: OCI_LOB_OPT_DEDUPLICATE

optionsp (IN)

可能な設定は、次のとおりです。

- OCI_LOB_OPT_COMPRESS_OFF

- OCI_LOB_OPT_COMPRESS_ON

- OCI_LOB_OPT_DEDUPLICATE_OFF

- OCI_LOB_OPT_DEDUPLICATE_ON

optionslen (IN)

optionspで示した値の長さです。この時点で有効な長さはsizeof(ub4)のみです。

mode (IN)

今後の使用のために確保されています。0 (ゼロ)を渡します。

関連関数

OCILobGetOptions()

OCILobTrim2()

用途

LOB値を短い長さに切り捨てます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobTrim2 ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCILobLocator   *locp,
oraub8          newlen );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

newlen (IN)

現在の長さ以下である必要がある、LOB値の新しい長さです。文字LOBでは文字数であり、バイナリLOBおよびBFILEではLOBのバイト数です。

コメント

この関数では、LOBデータを指定の長さに切り捨てます。newlenが現行のLOBの長さより長い場合は、エラーが戻されます。この関数は内部LOBでのみ有効です。BFILEには使用できません。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連関数

OCIErrorGet()、OCILobRead2()、OCILobAppend()、OCILobCopy2()、OCILobErase2()、OCILobTrim2()、OCILobWrite2()、OCILobWriteAppend2()

OCILobWrite2()

用途

バッファをLOBに書き込みます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobWrite2 ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCILobLocator   *locp,
oraub8          *byte_amtp,
oraub8          *char_amtp,
oraub8          offset,
void            *bufp,
oraub8          buflen,
ub1             piece,
void            *ctxp,
OCICallbackLobWrite2 (cbfp)
(
void     *ctxp,
void     *bufp,
oraub8   *lenp,
ub1      *piecep
void     **changed_bufpp,
oraub8   *changed_lenp
)
ub2             csid,
ub1             csfrm );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

byte_amtp(IN/OUT)

IN: データベースに書き込むバイト数です。BLOBでは必ず使用されます。CLOBおよびNCLOBに対しては、char_amtpが0 (ゼロ)の場合のみ使用されます。

OUT: データベースに書き込むバイト数です。ポーリング・モードでは、バイト単位のピースの長さ(書込みのみ)です。

char_amtp(IN/OUT)

IN: データベースに書き込む最大文字数です。BLOBでは無視されます。

OUT: データベースに書き込む文字数です。BLOBでは未定義となります。ポーリング・モードでは、文字単位のピースの長さ(書込みのみ)です。

offset (IN)

入力時、これはLOB値の先頭からの絶対オフセットです。文字LOBではLOBの先頭からの文字数であり、バイナリLOBではバイト数です。先頭位置は1です。

ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。

bufp (IN)

ピースの書込み元バッファへのポインタです。バッファ内のデータの長さは、buflenで渡された値であると想定しています。ポーリング・メソッドを使用してピース単位でデータが書き込まれている場合でも、bufpにはこのコール起動時のLOBの最初のピースを含める必要があります。コールバックを指定した場合は、bufpを使用してデータを指定しないでください。指定した場合、エラーが発生します。

buflen (IN)

バッファ内のデータの長さ(バイト数)です。量がchar_amtpパラメータを使用して文字数で指定され、buflenパラメータがバイト数で指定されている場合、この値は、CLOBおよびNCLOBのchar_amtp値とは異なります。

注意:
このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、buflenの値を必要に応じて調整する必要があります。

piece (IN)

書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECEです。

ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE、OCI_NEXT_PIECEおよびOCI_LAST_PIECEがあります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

cbfp (IN)

ピース単位書込みで各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、標準ポーリング・メソッドが使用されます。

コールバック関数は、OCI_CONTINUEを戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。コールバックは、次のパラメータを取ります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。このパラメータは、OCILobWrite()ルーチンに入力として渡されるbufpと同じです。

lenp (IN/OUT)

buffer (IN)内のデータのバイト数、およびbufp (OUT)内のカレント・ピースのバイト数です。

piecep (OUT)

ピースはOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ内のデータのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - データベース・キャラクタ・セットID

- SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。

コメント

バッファを指定どおりに内部LOBに書き込みます。LOBにデータが存在する場合は、バッファに格納されたデータによって上書きされます。バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。

注意:
LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm)を指定します。

OCILobWrite2()に対してポーリング・モードを使用するとき、最初のコールではoffset、byte_amtpおよびchar_amtpの値を指定する必要がありますが、その後のOCILobWrite2()のポーリング・コールでは指定する必要はありません。

pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。

コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufpから書き込まれます。コールバック関数が定義されていない場合、OCILobWrite2()は、OCI_NEED_DATAエラー・コードを戻します。LOBのピースの書込みを続けるには、アプリケーションでOCILobWrite2()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。

pieceパラメータの値がOCI_LAST_PIECEのときは、ポーリングまたはコールバック方式が使用されているかどうかに関係なく、ピース単位書込み操作は終了します。

(どの入力方法を使用した場合も)データベースに渡されるデータの量が、byte_amtpまたはchar_amtpパラメータに指定された量より少ない場合は、ORA-22993エラーが戻されます。

この関数は内部LOBでのみ有効です。BFILEは読取り専用のため、取り扱えません。LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

byte_amtpおよびchar_amtpが0 (ゼロ)を指すように設定され、OCI_FIRST_PIECEが入力として指定されている場合、ポーリング・モードが想定され、OCI_LAST_PIECEを指定するまでデータが書き込まれます。CLOBおよびNCLOBでは、byte_amtpおよびchar_amtpは、それぞれバイト数および文字数で、各ピースごとに書き込まれるデータを戻します。BLOBでは、byte_amtpは各ピースごとに書き込まれるバイト数を戻しますが、出力についてchar_amtpは未定義です。

UTF-16形式でデータを書き込むには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:

- Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください。

- LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

- 付録B「OCIデモ・プログラム」

- ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

- 「OCIでのポーリング・モード操作」

関連関数

OCIErrorGet()、OCILobRead2()、OCILobAppend()、OCILobCopy2()、OCILobWriteAppend2()

OCILobWriteAppend2()

用途

LOBの末尾からデータの書込みを開始します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobWriteAppend2 ( OCISvcCtx           *svchp,
OCIError            *errhp,
OCILobLocator       *locp,
oraub8              *byte_amtp,
oraub8              *char_amtp,
void                *bufp,
oraub8              buflen,
ub1                 piece,
void                *ctxp,
OCICallbackLobWrite2 (cbfp)
(
void     *ctxp,
void     *bufp,
oraub8   *lenp,
ub1      *piecep
void     **changed_bufpp,
oraub8   *changed_lenp
)
ub2 csid,
ub1 csfrm);

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。

byte_amtp(IN/OUT)

IN: データベースに書き込むバイト数です。BLOBで使用されます。CLOBおよびNCLOBに対しては、char_amtpが0 (ゼロ)の場合のみ使用されます。

OUT: データベースに書き込むバイト数です。

char_amtp(IN/OUT)

IN: データベースに書き込む最大文字数です。BLOBでは無視されます。

OUT: データベースに書き込む文字数です。BLOBでは未定義となります。

bufp(IN)

ピースの書込み元バッファへのポインタです。バッファ内のデータの長さは、buflenで渡された値であると想定しています。ピース単位でデータが書き込まれている場合でも、bufpにはこのコール起動時のLOBの最初のピースを含める必要があります。コールバックを指定した場合は、bufpを使用してデータを指定しないでください。指定した場合、エラーが発生します。

buflen (IN)

バッファ内のデータの長さ(バイト数)です。このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、buflenの値を必要に応じて調整する必要があります。

piece (IN)

書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECEです。ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE、OCI_NEXT_PIECEおよびOCI_LAST_PIECEがあります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

cbfp (IN)

ピース単位書込みで各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、標準ポーリング・メソッドが使用されます。コールバック関数は、OCI_CONTINUEを戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。コールバックは、次のパラメータを取ります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。

lenp (IN/OUT)

buffer (IN)内のデータのバイト数、およびbufp (OUT)内のカレント・ピースのバイト数です。

piecep (OUT)

ピースはOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に書き込むピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ・データのキャラクタ・セットIDです。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - データベース・キャラクタ・セットID

- SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。

コメント

バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufpから書き込まれます。コールバック関数が定義されていない場合、OCILobWriteAppend2()は、OCI_NEED_DATAエラー・コードを戻します。

LOBのピースの書込みを続けるには、アプリケーションでOCILobWriteAppend2()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。pieceパラメータの値がOCI_LAST_PIECEのときは、ピース単位の書込みは終了します。

LOBバッファリングが有効な場合、OCILobWriteAppend2()関数はサポートされません。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

byte_amtpおよびchar_amtpが0 (ゼロ)を指すように設定され、OCI_FIRST_PIECEが入力として指定されている場合、ポーリング・モードが想定され、OCI_LAST_PIECEを指定するまでデータが書き込まれます。CLOBおよびNCLOBでは、byte_amtpおよびchar_amtpは、それぞれバイト数および文字数で、各ピースごとに書き込まれるデータを戻します。BLOBでは、byte_amtpは各ピースごとに書き込まれるバイト数を戻しますが、出力についてchar_amtpは未定義です。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:
「LOBの読取り/書込みパフォーマンスの向上」

関連関数

OCIErrorGet()、OCILobRead2()、OCILobAppend()、OCILobCopy2()、OCILobWrite2()

Streamsアドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数

表17-3は、この項で説明しているStreamsアドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。

関連項目:
Streamsアドバンスト・キューイング・プログラムの詳細は、「OCIデモ・プログラム」を参照してください。

表17-3 アドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数

関数

用途

「OCIAQDeq()」

アドバンスト・キューイングのデキュー操作を実行します。

「OCIAQDeqArray()」

メッセージ配列をデキューします。

「OCIAQEnq()」

アドバンスト・キューイングのエンキュー操作を実行します。

「OCIAQEnqArray()」

メッセージ配列をエンキューします。

「OCIAQListen2()」

リストのエージェントの代理として1つ以上のキューをリスニングします。バッファ・メッセージおよび永続キューをサポートします。

「OCISubscriptionDisable()」

サブスクリプションの登録を使用禁止にして、通知をオフにします。

「OCISubscriptionEnable()」

サブスクリプションについての通知を使用可能にします。

「OCISubscriptionPost()」

通知を受信するようにサブスクリプションに転記します。

「OCISubscriptionRegister()」

サブスクリプションを登録します。

「OCISubscriptionUnRegister()」

サブスクリプションの登録を解除します。

OCIAQDeq()

用途

OCIでのStreamsアドバンスト・キューイングを使用したデキュー操作を実行します。

構文

sword OCIAQDeq ( OCISvcCtx           *svch,
OCIError            *errh,
OraText             *queue_name,
OCIAQDeqOptions     *dequeue_options,
OCIAQMsgProperties  *message_properties,
OCIType             *payload_tdo,
void                **payload,
void                **payload_ind,
OCIRaw              **msgid,
ub4                 flags );

パラメータ

svch (IN)

OCIサービス・コンテキストです。

errh (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

queue_name (IN)

デキュー操作のためのターゲット・キューです。

dequeue_options (IN)

デキュー操作のオプションです。OCI型定数OCI_DTYPE_AQDEQ_OPTIONSを使用してOCIAQDeqOptions記述子に格納されます。

OCI_DTYPE_AQDEQ_OPTIONSには、次の値を持つ追加属性OCI_ATTR_MSG_DELIVERY_MODEがあります(Oracle Database 10gリリース2から導入されました)。

- OCI_MSG_PERSISTENT (デフォルト)

- OCI_MSG_BUFFERED

- OCI_MSG_PERSISTENT_OR_BUFFERED

message_properties (OUT)

メッセージ用のメッセージ・プロパティです。プロパティは、OCI型定数OCI_DTYPE_AQMSG_PROPERTIESを使用してOCIAQMsgProperties記述子に格納されます。この定数には、次の値があります。

- OCI_AQ_PERSISTENT (デフォルト)

- OCI_AQ_BUFFERED

payload_tdo (IN)

オブジェクト型のTDO (型記述子オブジェクト)です。RAWキューでは、このパラメータがSYS.RAWのTDOを指し示す必要があります。

payload (IN/OUT)

オブジェクト型のインスタンスであるプログラム変数バッファのポインタへのポインタです。RAWキューでは、このパラメータがOCIRawのインスタンスを指し示す必要があります。

payload用のメモリーは、オブジェクト・キャッシュに動的に割り当てられます。payloadインスタンスが不要になったときは、アプリケーションからOCIObjectFree()をコールし、割当て解除もできます。プログラム変数バッファへのポインタ(*payload)がNULLで渡された場合、そのバッファは暗黙的にキャッシュに割り当てられます。

アプリケーションでは、OCIAQDeq()が最初にコールされたときにpayloadにNULLを渡し、そのpayloadに、OCIでメモリーを割り当てるようにできます。後続のOCIAQDeq()コールでは、前に割り当てられたメモリーへのポインタが使用されます。

payload用にTDOを取得するには、OCITypeByName()またはOCITypeByRef()を使用します。

OCIによって、ユーザーがpayloadの属性(テキストなど)を設定できる関数が提供されます。これらの属性の設定については、「オブジェクト属性の操作」を参照してください。

payload_ind (IN/OUT)

オブジェクト型のパラレル・インジケータ情報構造を含むプログラム変数バッファ・ポインタへのポインタです。

payload_indへのメモリー割当てルールは、payloadに対するルールと同じです。

msgid (OUT)

メッセージIDです。

flags (IN)

現行では使用されていません。OCI_DEFAULTとして渡されます。

コメント

このコールを使用するには、ユーザーがAQ_USER_ROLEまたはDBMS_AQパッケージを実行する権限を所有している必要があります。このコールを使用するには、OCI環境をオブジェクト・モードで初期化する必要があります(OCIEnvCreate()、OCIEnvNlsCreate()またはOCIInitialize() (非推奨)を使用)。

関連項目:

- 「OCIおよびStreamsアドバンスト・キューイング」

- 『Oracle Streamsアドバンスト・キューイング・ユーザーズ・ガイドおよびリファレンス』

関連関数

OCIAQEnq()、OCIAQListen2()、OCIInitialize() (非推奨)、OCIEnvCreate()、OCIEnvNlsCreate()

OCIAQDeqArray()

用途

メッセージの配列をキューからデキューします。配列内のメッセージはすべて同じオプションによりデキューされ、同じキュー・テーブル・ペイロード列TDOが含まれます。

構文

sword OCIAQDeqArray ( OCISvcCtx           *svchp,
OCIError            *errhp,
OraText             *queue_name,
OCIAQDeqOptions     *deqopt,
ub4                 *iters,
OCIAQMsgProperties  **msgprop,
OCIType             *payload_tdo,
void                **payload,
void                **payload_ind,
OCIRaw              **msgid,
void                *ctxp,
OCICallbackAQDeq    (cbfp)
(
void         *ctxp,
void         **payload,
void         **payload_ind
),
ub4                 flags );

パラメータ

svchp (IN)

OCIサービス・コンテキストです(OCIAQDeq()から変更なし)。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです(OCIAQDeq()から変更なし)。

queue_name (IN)

メッセージのデキュー元となるキューの名前です(OCIAQDeq()から変更なし)。

deqopt (IN)

OCIAQDeqOptions記述子へのポインタです(OCIAQDeq()から変更なし)。

OCI_DTYPE_AQDEQ_OPTIONS OCI型定数には、次の値を持つ追加属性OCI_ATTR_MSG_DELIVERY_MODEがあります(Oracle Database 10gリリース2から導入されました)。

- OCI_MSG_PERSISTENT (デフォルト)

- OCI_MSG_BUFFERED

- OCI_MSG_PERSISTENT_OR_BUFFERED

iters (IN/OUT)

入力では、デキューするメッセージ数です。出力では、正常にデキューされたメッセージ数です。

msgprop (OUT)

OCI型定数OCI_DTYPE_AQMSG_PROPERTIESのOCIAQMsgProperties記述子へのポインタの配列です。この定数には、次の値があります。

- OCI_AQ_PERSISTENT (デフォルト)

- OCI_AQ_BUFFERED

payload_tdo (OUT)

キュー・テーブルのペイロード列のTDOへのポインタです。

payload (OUT)

デキューされたメッセージへのポインタの配列です。

payload_ind (OUT)

インジケータへのポインタの配列です。

msgid (OUT)

デキューされたメッセージのメッセージIDへのポインタの配列です。

ctxp (IN)

コールバック関数に渡されるコンテキストです。

cbfp (IN)

デキューされたメッセージが格納されるバッファ・ポインタを指定するために登録できるコールバックです。NULLの場合、メッセージはpayloadが指し示すバッファにデキューされます。

flags (IN)

現行では使用されていません。OCI_DEFAULTとして渡されます。

コメント

このコールを使用するには、ユーザーがAQ_USER_ROLEまたはDBMS_AQパッケージを実行する権限を所有している必要があります。このコールを使用するには、OCI環境をオブジェクト・モードで初期化する必要があります(OCIEnvCreate()、OCIEnvNlsCreate()またはOCIInitialize() (非推奨)を使用)。

OCIAQDeqOptionsで指定した0 (ゼロ)以外の待機時間は、キューにメッセージがない場合のみ認識されます。キューに、デキューの対象であるメッセージが含まれる場合、OCIAQDeqArray()関数はitersメッセージまでをデキューし、ただちに戻します。

この関数は、非ブロック化モードではサポートされません。

関連項目:

- 「OCIおよびStreamsアドバンスト・キューイング」

- 『Oracle Streamsアドバンスト・キューイング・ユーザーズ・ガイドおよびリファレンス』

関連関数

OCIAQDeq()、OCIAQEnqArray()、OCIAQListen2()、OCIInitialize() (非推奨)、OCIEnvCreate()、OCIEnvNlsCreate()

OCIAQEnq()

用途

Streamsアドバンスト・キューイングを使用したエンキュー操作を実行します。

構文

sword OCIAQEnq ( OCISvcCtx           *svch,
OCIError            *errh,
OraText             *queue_name,
OCIAQEnqOptions     *enqueue_options,
OCIAQMsgProperties  *message_properties,
OCIType             *payload_tdo,
void                **payload,
void                **payload_ind,
OCIRaw              **msgid,
ub4                 flags );

パラメータ

svch (IN)

OCIサービス・コンテキストです。

errh (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

queue_name (IN)

エンキュー操作のためのターゲット・キューです。

enqueue_options (IN)

エンキュー操作のオプション。OCIAQEnqOptions記述子に格納されています。

message_properties (IN)

メッセージ用のメッセージ・プロパティです。プロパティは、Oracle Database 10gリリース2で導入されたOCI型定数OCI_DTYPE_AQMSG_PROPERTIESのOCIAQMsgProperties記述子に格納されます。

OCI_DTYPE_AQMSG_PROPERTIES記述子には、次の値を持つOCI_ATTR_MSG_DELIVERY_MODE属性があります。

- OCI_MSG_PERSISTENT (デフォルト)

- OCI_MSG_BUFFERED

payload_tdo (IN)

オブジェクト型のTDO (型記述子オブジェクト)です。RAWキューでは、このパラメータがSYS.RAWのTDOを指し示す必要があります。

payload (IN)

オブジェクト型のインスタンスを指し示すポインタへのポインタです。RAWキューでは、このパラメータがOCIRawのインスタンスを指し示す必要があります。

OCIによって、ユーザーがpayloadの属性(テキストなど)を設定できる関数が提供されます。

関連項目:
これらの属性の設定については、「オブジェクト属性の操作」を参照してください。

payload_ind (IN)

オブジェクト型のパラレル・インジケータ情報構造を含むプログラム変数バッファ・ポインタへのポインタです。

msgid (OUT)

メッセージIDです。

flags (IN)

現行では使用されていません。OCI_DEFAULTとして渡されます。

コメント

このコールを使用するには、ユーザーがAQ_USER_ROLEまたはDBMS_AQパッケージを実行する権限を所有している必要があります。

このコールを使用するには、OCI環境をオブジェクト・モードで初期化する必要があります(OCIEnvCreate()、OCIEnvNlsCreate()またはOCIInitialize() (非推奨)を使用)。

関連項目:

- OCIおよびアドバンスト・キューイングの詳細は、「OCIおよびStreamsアドバンスト・キューイング」 を参照してください。

- 『Oracle Streamsアドバンスト・キューイング・ユーザーズ・ガイドおよびリファレンス』

payload用にTDOを取得するには、OCITypeByName()またはOCITypeByRef()を使用します。

関連関数

OCIAQDeq()、OCIAQListen2()、OCIInitialize() (非推奨)、OCIEnvCreate()、OCIEnvNlsCreate()

OCIAQEnqArray()

用途

メッセージの配列をキューにエンキューします。メッセージの配列は同じオプションによりエンキューされ、同じペイロード列TDOが含まれます。

構文

sword OCIAQEnqArray ( OCISvcCtx              *svchp,
OCIError               *errhp,
OraText                *queue_name,
OCIAQEnqOptions        *enqopt,
ub4                    *iters,
OCIAQMsgProperties     **msgprop,
OCIType                *payload_tdo,
void                   **payload,
void                   **payload_ind,
OCIRaw                 **msgid,
void                   *ctxp,
OCICallbackAQEnq       (cbfp)
(
void        *ctxp,
void        **payload,
void        **payload_ind
),
ub4                    flags );

パラメータ

svchp (IN)

サービス・コンテキストです(OCIAQEnq()から変更なし)。

errhp (IN/OUT)

エラー・ハンドルです(OCIAQEnq()から変更なし)。

queue_name (IN)

メッセージがエンキューされるキューの名前です(OCIAQEnq()から変更なし)。

enqopt (IN)

OCIAQEnqOptions記述子へのポインタです(OCIAQEnq()から変更なし)。

iters (IN/OUT)

入力では、エンキューするメッセージ数です。出力では、正常にエンキューされたメッセージ数です。

msgprop (IN)

Oracle Database 10gリリース2で導入されたOCI型定数OCI_DTYPE_AQMSG_PROPERTIESのOCIAQMsgProperties記述子へのポインタの配列です。

OCI_DTYPE_AQMSG_PROPERTIESには、次の値を持つOCI_ATTR_MSG_DELIVERY_MODE属性があります。

- OCI_MSG_PERSISTENT (デフォルト)

- OCI_MSG_BUFFERED

payload_tdo (IN)

キュー・テーブルのペイロード列のTDOへのポインタです。

payload (IN)

エンキューされるメッセージへのポインタの配列です。

payload_ind (IN)

インジケータへのポインタの配列、またはNULLポインタの配列です(標識変数が使用されていない場合)。

msgid (OUT)

エンキューされたメッセージのメッセージIDへのポインタの配列、またはNULLポインタの配列です(メッセージIDが戻されない場合)。

ctxp (IN)

登録されたコールバック関数に渡されるコンテキストです。

cbfp (IN)

メッセージを動的に提供するために登録できるコールバックです。NULLの場合、OCIAQEnqArray()をコールする前に、すべてのメッセージを具体化する必要があります。

flags (IN)

現行では使用されていません。OCI_DEFAULTとして渡されます。

コメント

この関数は、非ブロック化モードではサポートされません。

関連関数

OCIAQEnq()、OCIAQDeqArray()、OCIAQListen2()、OCIInitialize() (非推奨)、OCIEnvCreate()、OCIEnvNlsCreate()

OCIAQListen2()

用途

リストのエージェントのかわりに1つ以上のキューをリスニングします。バッファ・メッセージおよび永続キューをサポートします。Oracle Database 10gリリース2から導入されました。

構文

sword OCIAQListen2 (OCISvcCtx         *svchp,
OCIError          *errhp,
OCIAQAgent        **agent_list,
ub4               num_agents,
OCIAQListenOpts   *lopts,
OCIAQAgent        **agent,
OCIAQLisMsgProps  *lmops,
ub4               flags);

パラメータ

svchpp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

agent_list (IN)

メッセージを監視するエージェントのリストです。

num_agents (IN)

エージェント・リスト内のエージェント数です。

lopts (IN)

型定数OCI_DTYPE_AQLIS_OPTIONSには、次の属性があります。

- OCI_ATTR_WAIT - リスニング・コールの最大待機時間(秒単位)

- OCI_ATTR_MSG_DELIVERY_MODE - 次のいずれかの値です。

- OCI_MSG_PERSISTENT

- OCI_MSG_BUFFERED

- OCI_MSG_PERSISTENT_OR_BUFFERED

agent (OUT)

メッセージの出力先のエージェントです。OCIAgentはOCI記述子です。

lmops (OUT)

OCI_DTYPE_AQLIS_MSG_PROPERTIES (リスニング・メッセージ・プロパティ)には、1つの属性、OCI_ATTR_MSG_DELIVERY_MODEがあります。この属性は、次の値を持ちます。

- OCI_MSG_PERSISTENT

- OCI_MSG_BUFFERED

flags (IN)

現行では使用されていません。OCI_DEFAULTとして渡されます。

コメント

メッセージが存在し、リスト内のエージェントに対してそのメッセージを使用する準備ができたときに戻されるブロッキング・コールです。待機時間が終了してもメッセージが検出されない場合は、エラーが戻されます。

関連関数

OCIAQEnq()、OCIAQDeq()、OCISvcCtxToLda()、OCISubscriptionEnable()、OCISubscriptionPost()、OCISubscriptionRegister()、OCISubscriptionUnRegister()

OCISubscriptionDisable()

用途

サブスクリプションの登録を使用禁止にして、すべての通知をオフにします。

構文

ub4 OCISubscriptionDisable ( OCISubscription   *subscrhp,
OCIError          *errhp
ub4               mode );

パラメータ

subscrhp (IN)

OCI_ATTR_SUBSCR_NAMEおよびOCI_ATTR_SUBSCR_NAMESPACE属性が設定されたサブスクリプション・ハンドルです。

関連項目:
「サブスクリプション・ハンドル属性」

errhp (OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

mode (IN)

コール固有モードです。有効な値はOCI_DEFAULTのみです。OCI_DEFAULTは、デフォルトのコールを実行します。サブスクリプションが使用可能になるまで、このサブスクリプションの通知をすべて破棄します。

コメント

このコールは、一時的に通知をオフにするときに使用します。コードの重要なセクションを実行しているときに使用して、アプリケーションが中断されないようにします。

この操作をするときは、接続または認証は必要ありません。このコールの前に、サブスクリプション・ハンドルによって指定されたサブスクリプションの登録を行ってください。

OCISubscriptionDisable()を実行した後は、OCISubscriptionEnable()を実行するまですべての通知が破棄されます。

関連関数

OCIAQListen2()、OCISubscriptionEnable()、OCISubscriptionPost()、OCISubscriptionRegister()、OCISubscriptionUnRegister()

OCISubscriptionEnable()

用途

使用禁止にしたサブスクリプションの登録を使用可能にします。すべての通知がオンになります。

構文

ub4 OCISubscriptionEnable ( OCISubscription   *subscrhp,
OCIError          *errhp
ub4               mode );

パラメータ

subscrhp (IN)

OCI_ATTR_SUBSCR_NAMEおよびOCI_ATTR_SUBSCR_NAMESPACE属性が設定されたサブスクリプション・ハンドルです。

関連項目:
「サブスクリプション・ハンドル属性」

errhp (OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

mode (IN)

コール固有モードです。有効な値はOCI_DEFAULTのみです。この値は、デフォルトのコールを実行します。次の使用可能化が実行されるまで、このサブスクリプションの通知はすべてバッファリングされます。

コメント

このコールは、サブスクリプションの登録を使用禁止にした後に、通知をオンにするときに使用します。

この操作をするときは、接続または認証は必要ありません。このコールを実行する前に、指定されたサブスクリプションの登録を行ってください。

関連関数

OCIAQListen2()、OCISvcCtxToLda()、OCISubscriptionPost()、OCISubscriptionRegister()、OCISubscriptionUnRegister()

OCISubscriptionPost()

用途

サブスクリプションに転記し、そのサブスクリプションに対して登録されたすべてのクライアントが通知を受信できるようにします。

構文

ub4 OCISubscriptionPost ( OCISvcCtx         *svchp,
OCISubscription   **subscrhpp,
ub2               count,
OCIError          *errhp
ub4               mode );

パラメータ

svchp (IN)

OCIサービス・コンテキストです(バージョン7より後)。このサービス・コンテキストには、有効な認証されたユーザー・ハンドルが必要です。

subscrhpp (IN)

サブスクリプション・ハンドルの配列です。この配列の各要素は、OCI_ATTR_SUBSCR_NAMEおよびOCI_ATTR_SUBSCR_NAMESPACE属性が設定されたサブスクリプション・ハンドルにしてください。

関連項目:
「サブスクリプション・ハンドル属性」

このコールの前に、各サブスクリプション・ハンドルに対してOCI_ATTR_SUBSCR_PAYLOAD属性を設定する必要があります。設定されていない場合、ペイロードはNULLであるとみなされ、重要な登録を行ったクライアントが通知を受信したときに、ペイロードが配布されません。OCIAttrSet()コールでは、ペイロードへの参照は記録されますが、内容はコピーされないため、コール元は転送が行われるまでペイロードを保存する必要があります。

count (IN)

サブスクリプション・ハンドル配列の要素数です。

errhp (OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

mode (IN)

コール固有モードです。有効な値はOCI_DEFAULTのみです。この値は、デフォルトのコールを実行します。

コメント

サブスクリプションに転記されるときに、必要に応じてサブスクリプション名およびペイロードの識別を行うことができます。ペイロードが関連付けられない場合は、ペイロードの長さは0に設定されます。

このコールは、最も効果的な転送を保証します。通知は、登録されたクライアントに対して最大で1回行われます。

このコールは、主に非永続通知に使用し、複数のシステム・イベントが発生する場合に役立ちます。アプリケーションでより確実な保証が必要な場合は、アドバンスト・キューイング機能を使用し、キューにエンキューします。

関連関数

OCIAQListen2()、OCISvcCtxToLda()、OCISubscriptionEnable()、OCISubscriptionRegister()、OCISubscriptionUnRegister()

OCISubscriptionRegister()

用途

メッセージ通知に対するコールバックを登録します。

構文

ub4 OCISubscriptionRegister ( OCISvcCtx         *svchp,
OCISubscription   **subscrhpp,
ub2               count,
OCIError          *errhp
ub4               mode );

パラメータ

svchp (IN)

OCIサービス・コンテキストです(バージョン7より後)。このサービス・コンテキストには、有効な認証されたユーザー・ハンドルが必要です。

subscrhpp (IN)

サブスクリプション・ハンドルの配列です。この配列の各要素は、次のすべての属性が設定されたサブスクリプション・ハンドルである必要があります。

- OCI_ATTR_SUBSCR_NAME

- OCI_ATTR_SUBSCR_NAMESPACE

- OCI_ATTR_SUBSCR_RECPTPROTO

それ以外の場合はエラーが戻されます。

次のいずれかの属性も設定する必要があります。

- OCI_ATTR_SUBSCR_CALLBACK

- OCI_ATTR_SUBSCR_CTX

- OCI_ATTR_SUBSCR_RECPT

関連項目:
ハンドル属性の詳細は、「サブスクリプション・ハンドル属性」を参照してください。

subscrhpp[i]によって示された登録に対して通知を受信すると、subscrhpp[i]に対してコンテキスト(OCI_ATTR_SUBSCR_CTX)が設定された状態で、subscrhpp[i]に対して設定されたユーザー定義コールバック関数(OCI_ATTR_SUBSCR_CALLBACK)が呼び出されるか、subscrhpp[i]に対して設定された(OCI_ATTR_SUBSCR_RECPT)に電子メールが送信されます。あるいは、subscrhpp[i]のサブスクライバにプロシージャに対する適切な権限がある場合は、subscrhpp[i]に対して設定されたPL/SQLプロシージャ(OCI_ATTR_SUBSCR_RECPT)がデータベースで呼び出されます。

count (IN)

サブスクリプション・ハンドル配列の要素数です。

errhp (OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

mode (IN)

コール固有モードです。次の値が有効です。

- OCI_DEFAULT: サーバーのDN記述子にサーバーのDNが1つのみ存在する場合に使用します。登録要求がデータベースに送信されます。データベース接続を使用できない場合、登録要求は迂回してLDAPサーバーに送信されます。

- OCI_REG_LDAPONLY - 登録要求は直接LDAPサーバーに送信されます。サーバーのDN記述子にサーバーのDNが複数存在する場合、またはデータベース接続を使用できないことが確かである場合に、このモードを使用します。

新しいクライアント・プロセスが起動するか、または以前のクライアント・プロセスが停止して再度起動するときは常に、重要なすべてのサブスクリプションに対して登録する必要があります。クライアントが起動したまま、サーバーが最初に停止してから再度起動した場合、クライアントはDISCONNECTEDである登録に対して引き続き通知を受信します。ただし、CONNECTED登録に対する通知は、サーバーが停止して再度起動した後は欠落するため、クライアントが受信することはありません。

コメント

このコールは、サブスクリプションの登録に対して呼び出します。重要なサブスクリプション名および呼び出される関連コールバックを識別します。重要な複数のサブスクリプションを同時に登録できます。

このインタフェースは、非同期モードのメッセージ配信の場合にのみ有効です。非同期モードでは、サブスクライバが登録コールの発行およびコールバックの指定を行います。サブスクリプション条件と一致するメッセージを受信すると、コールバックが呼び出されます。次に、コールバックから明示的なmessage_receive (デキュー)が発行され、メッセージが取り出されます。

ユーザーは、登録時にネームスペース属性をOCI_SUBSCR_NAMESPACE_AQに設定して、サブスクリプション・ハンドルを指定する必要があります。

サブスクリプション名は、シングル・コンシューマ・キューの登録の場合は文字列SCHEMA.QUEUEで、マルチ・コンシューマ・キューの登録の場合は文字列SCHEMA.QUEUE:CONSUMER_NAMEです。この文字列は大文字にします。

各ネームスペースには、独自の権限モデルがあります。登録を行っているユーザーに、指定されたサブスクリプションのネームスペースで登録する権限がない場合は、エラーが戻されます。

関連関数

OCIAQListen2()、OCISvcCtxToLda()、OCISubscriptionEnable()、OCISubscriptionPost()、OCISubscriptionUnRegister()

OCISubscriptionUnRegister()

用途

サブスクリプションの登録を解除して、通知をオフにします。

構文

ub4 OCISubscriptionUnRegister ( OCISvcCtx         *svchp,
OCISubscription   *subscrhp,
OCIError          *errhp
ub4               mode );

パラメータ

svchp (IN)

OCIサービス・コンテキストです(バージョン7より後)。このサービス・コンテキストには、有効な認証されたユーザー・ハンドルが必要です。

subscrhp (IN)

OCI_ATTR_SUBSCR_NAMEおよびOCI_ATTR_SUBSCR_NAMESPACE属性が設定されたサブスクリプション・ハンドルです。

関連項目:
「サブスクリプション・ハンドル属性」

errhp (OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

mode (IN)

コール固有モードです。次の値が有効です。

- OCI_DEFAULT: サーバーのDN記述子にサーバーのDNが1つのみ存在する場合に使用します。登録要求がデータベースに送信されます。データベース接続を使用できない場合、登録要求は迂回してLDAPサーバーに送信されます。

- OCI_REG_LDAPONLY - 登録要求は直接LDAPサーバーに送信されます。サーバーのDN記述子にサーバーのDNが複数存在する場合、またはデータベース接続を使用できないことが確かである場合に、このモードを使用します。

コメント

サブスクリプションの登録を解除すると、その後は特定のサブスクリプションに関する通知を受信できなくなります。通知を再開する場合は、サブスクリプションに対して再登録を行ってください。

別の登録が行われると、重要なクライアントのリストからユーザーが削除されるため、解除前に配信されていた通知はすべて配信されなくなります。

関連関数

OCIAQListen2()、OCISvcCtxToLda()、OCISubscriptionEnable()、OCISubscriptionPost()、OCISubscriptionRegister()

ダイレクト・パス・ロード関数

表17-4は、この項で説明しているダイレクト・パス・ロード関数を示しています。

表17-4 ダイレクト・パス・ロード関数

関数

用途

「OCIDirPathAbort()」

ダイレクト・パス処理を終了します。

「OCIDirPathColArrayEntryGet()」

列配列内の特定のエントリを取得します。

「OCIDirPathColArrayEntrySet()」

列配列内の特定のエントリを特定の値に設定します。

「OCIDirPathColArrayReset()」

行配列の状態をリセットします。

「OCIDirPathColArrayRowGet()」

特定の行番号の基本行ポインタを取得します。

「OCIDirPathColArrayToStream()」

列配列からダイレクト・パス・ストリーム形式に変換します。

「OCIDirPathDataSave()」

データ・セーブポイントを実行するか、またはロードされたデータをコミットしてロード操作を終了します。

「OCIDirPathFinish()」

ロードされたデータを終了およびコミットします。

「OCIDirPathFlushRow()」

非推奨です。

「OCIDirPathLoadStream()」

ダイレクト・パス・ストリーム形式に変換されたデータをロードします。

「OCIDirPathPrepare()」

行の変換またはロードを行うために、ダイレクト・パス・インタフェースを準備します。

「OCIDirPathStreamReset()」

ダイレクト・パス・ストリームの状態をリセットします。

OCIDirPathAbort()

用途

ダイレクト・パス処理を終了します。

構文

sword OCIDirPathAbort   ( OCIDirPathCtx          *dpctx,
OCIError               *errhp );

パラメータ

dpctx (IN)

ダイレクト・パス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

ダイレクト・パス処理のかわりにサーバーによって維持されていたすべての状態は、終了によって破棄されます。ダイレクト・パス・ロードの場合、終了操作前にロードされたデータは問合せで参照できなくなります。ロードされていなかったデータが、まだセグメントの領域を使用している可能性があります。索引メンテナンス処理などのロード完了処理は行われません。

関連関数

OCIDirPathFinish()、OCIDirPathPrepare()、OCIDirPathLoadStream()、OCIDirPathStreamReset()、OCIDirPathDataSave()

OCIDirPathColArrayEntryGet()

用途

列配列内の指定のエントリを取得します。

構文

sword OCIDirPathColArrayEntryGet ( OCIDirPathColArray   *dpca,
OCIError             *errhp,
ub4                  rownum,
ub2                  colIdx,
ub1                  **cvalpp,
ub4                  *clenp,
ub1                  *cflgp );

パラメータ

dpca (IN/OUT)

ダイレクト・パス列配列ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

rownum (IN)

0 (ゼロ)ベースの行オフセットです。

colIdx (IN)

列パラメータ・リストの作成時に使用される列の索引です。

cvalpp (IN/OUT)

列データのポインタへのポインタです。

clenp (IN/OUT)

列データの長さへのポインタです。

cflgp (IN/OUT)

列フラグへのポインタです。

次のいずれかの値が戻されます。

- OCI_DIRPATH_COL_COMPLETE - 列にすべてのデータが存在します。

- OCI_DIRPATH_COL_NULL - 列がNULLです。

- OCI_DIRPATH_COL_PARTIAL - 一部の列データが提供されます。

コメント

cflgpがOCI_DIRPATH_COL_NULLに設定されている場合、cvalppパラメータおよびclenpパラメータには値が設定されません。

関連関数

OCIDirPathColArrayEntrySet()、OCIDirPathColArrayRowGet()、OCIDirPathColArrayReset()、OCIDirPathColArrayToStream()

OCIDirPathColArrayEntrySet()

用途

列配列内の指定のエントリを提供される値に設定します。

構文

sword OCIDirPathColArrayEntrySet ( OCIDirPathColArray   *dpca,
OCIError             *errhp,
ub4                  rownum,
ub2                  colIdx,
ub1                  *cvalp,
ub4                  clen,
ub1                  cflg );

パラメータ

dpca (IN/OUT)

ダイレクト・パス列配列ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

rownum (IN)

0 (ゼロ)ベースの行オフセットです。

colIdx (IN)

列パラメータ・リストの作成時に使用される列の索引です。

cvalp (IN)

列データへのポインタです。

clen (IN)

列データの長さです。

cflg (IN)

列フラグです。次のいずれかの値が戻されます。

- OCI_DIRPATH_COL_COMPLETE - 列にすべてのデータが存在します。

- OCI_DIRPATH_COL_NULL - 列がNULLです。

- OCI_DIRPATH_COL_PARTIAL - 一部の列データが提供されます。

コメント

cflgがOCI_DIRPATH_COL_NULLに設定されている場合、cvalpパラメータおよびclenパラメータは使用されません。

例

次の例では、列配列内の最初の行のデータのソースにaddr、長さにlenを設定します。この例では、列は、colIdによって識別されます。

err = OCIDirPathColArrayEntrySet(dpca, errhp, (ub2)0, colId, addr, len,
OCI_DIRPATH_COL_COMPLETE);

関連関数

OCIDirPathColArrayRowGet()、OCIDirPathColArrayRowGet()、OCIDirPathColArrayReset()、OCIDirPathColArrayToStream()

OCIDirPathColArrayReset()

用途

列配列の状態をリセットします。

構文

sword OCIDirPathColArrayReset ( OCIDirPathColArray   *dpca,
OCIError             *errhp );

パラメータ

dpca (IN)

ダイレクト・パス列配列ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

列配列の状態は、大きな列内でピース単位操作を行うとき、および列のロード中にエラーが発生したときに、リセットする必要があります。最後のOCIDirPathColArrayReset()コールによってOCI_NEED_DATAまたはOCI_CONTINUEが戻された場合、列配列はリセットしないでください。これは、まだ行の変換中であるためです。OCI_DIRPATH_COL_ERRORを使用して、OCI_NEED_DATAから現在の行を削除してください。

関連関数

OCIDirPathColArrayEntryGet()、OCIDirPathColArrayEntrySet()、OCIDirPathColArrayRowGet()、OCIDirPathColArrayToStream()

OCIDirPathColArrayRowGet()

用途

特定の行番号の列配列行ポインタを取得します。

構文

sword OCIDirPathColArrayRowGet ( OCIDirPathColArray   *dpca,
OCIError             *errhp,
ub4                  rownum,
ub1                  ***cvalppp,
ub4                  **clenpp,
ub1                  **cflgpp );

パラメータ

dpca (IN/OUT)

ダイレクト・パス列配列ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

rownum (IN)

0 (ゼロ)ベースの行オフセットです。

cvalppp (IN/OUT)

列データのポインタのベクトルへのポインタです。

clenpp (IN/OUT)

列データの長さのベクトルへのポインタです。

cflgpp (IN/OUT)

列フラグのベクトルへのポインタです。

コメント

指定行の列配列エントリにポインタが戻ります。ポインタが戻ると、アプリケーションでは簡単なポインタ計算をして特定行の列間で反復処理を行います。このインタフェースを使用すると、各列でOCIDirPathColArrayEntrySet()をコールする場合と比べて、行の列配列エントリの取得または設定を効率的に行うことができます。アプリケーションから、列配列の境界を超えてメモリーを参照解除しないでください。列配列の次元は、列配列の属性として取得できます。

関連関数

OCIDirPathColArrayRowGet()、OCIDirPathColArrayEntrySet()、OCIDirPathColArrayReset()、OCIDirPathColArrayToStream()

OCIDirPathColArrayToStream()

用途

列配列形式からダイレクト・パス・ストリーム形式に変換します。

構文

sword OCIDirPathColArrayToStream ( OCIDirPathColArray     *dpca,
OCIDirPathCtx  const   *dpctx,
OCIDirPathStream       *dpstr,
OCIError               *errhp,
ub4                    rowcnt,
ub4                    rowoff );

パラメータ

dpca (IN)

ダイレクト・パス列配列ハンドルです。

dpctx (IN)

ロードされているオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。

dpstr (IN/OUT)

ダイレクト・パス・ストリーム・ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

rowcnt (IN)

列配列内の行数です。

rowoff (IN)

列配列内の開始索引です。

コメント

このインタフェースは、外部形式の列配列表現データを、ダイレクト・パス・ストリーム形式に変換するときに使用します。変換された形式は、OCIDirPathLoadStream()を使用したロードに適しています。

ダイレクト・パス・ストリーム形式の列データは、Oracle Databaseの内部表現のデータに変換されます。すべての変換は、この2タスク・インタフェースのクライアント側で行われ、すべての変換エラーは、このインタフェースへのコールと同時に発生します。エラーが発生した行および列に関する情報は、列配列ハンドルの属性として取得できます。

スレッド環境では、同時に行われるOCIDirPathColArrayToStream()操作によって同じダイレクト・パス・コンテキスト・ハンドルが参照されることがあります。ただし、このインタフェースでは、ダイレクト・パス・コンテキスト・ハンドルは変更されません。

このコールのリターン・コードは次のとおりです。

- OCI_SUCCESS－ 列配列内のすべてのデータがストリーム形式に正常に変換されました。列配列属性OCI_ATTR_ROW_COUNTは処理された行数です。

- OCI_ERROR - 変換時に発生したエラーです。エラー・ハンドルにはエラー情報が含まれています。列配列属性OCI_ATTR_ROW_COUNTは、最後のコールで正常に変換された行数です。属性OCI_ATTR_COL_COUNTには、エラーの原因となった列の列配列に対する列索引が含まれています。ストリーム変換に対する列配列がOCI_ERRORを戻した後は、必ずストリームをロードする必要があります。ストリームは、ロードされるまでリセットまたは変換できません。

- OCI_CONTINUE － 列配列内のすべてのデータがストリーム形式に変換できたわけではありません。ストリーム・バッファの領域が不足しているため、すべての列配列データを格納できません。コール元は、データをロードするか、ファイルにデータを保存するか、または別のストリームを使用して再度OCIDirPathColArrayToStream()をコールし、列配列データの残りを変換する必要があります。列配列属性OCI_ATTR_ROW_COUNTは、最後のコールで正常に変換された行数です。行オフセットは次の変換のために更新する必要があります。内部状態は列を追跡して変換を続行します。OCI_ATTR_ROW_COUNT値は、コール元が前の行オフセットに追加する必要があります。

- OCI_NEED_DATA - 列配列内のデータはすべて正常に変換されましたが、不完全な列が生成されました。コール元は生成されたストリームをロードし、必要な場合は行の残りを繰り返し指定する必要があります。列配列属性OCI_ATTR_ROW_COUNTは、最後のコールで正常に変換された行数です。属性OCI_ATTR_COL_COUNTには、不完全であるとマークが付けられた列の列配列に対する列索引が含まれています。

関連関数

OCIDirPathColArrayEntryGet()、OCIDirPathColArrayEntrySet()、OCIDirPathColArrayRowGet()、OCIDirPathColArrayReset()

OCIDirPathDataSave()

用途

要求されたアクションに応じて、データ・セーブポイントを実行するか、またはロードされたデータをコミットしてダイレクト・パス・ロード操作を終了します。

構文

sword OCIDirPathDataSave ( OCIDirPathCtx          *dpctx,
OCIError               *errhp,
ub4                    action  );

パラメータ

dpctx (IN)

ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

action (IN)

OCIDirPathDataSave()のアクション・パラメータの値は次のとおりです。

- OCI_DIRPATH_DATASAVE_SAVEONLY - データ・セーブポイントのみ実行します。

- OCI_DIRPATH_DATASAVE_FINISH - ロードされたデータをコミットしてダイレクト終了関数をコールします。

コメント

戻り値OCI_SUCCESSは、バックエンドによるデータ・セーブポイントまたは終了ロジックが正常に実行されたことを示します。

LOBでは、データ・セーブポイントは実行できません。

終了ロジックの実行は、割り当てられたリソースが解放されないため、ロードの正常終了とは異なります。

関連関数

OCIDirPathAbort()、OCIDirPathFinish()、OCIDirPathPrepare()、OCIDirPathStreamReset()

OCIDirPathFinish()

用途

ダイレクト・パス・ロード操作を終了します。

構文

sword OCIDirPathFinish (   OCIDirPathCtx          *dpctx,
OCIError               *errhp );

パラメータ

dpctx (IN)

ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

ロードが完了して、ロードされたデータがコミットされるときに、ダイレクト・パス終了関数がコールされます。すべてのストリームがロードされるまで終了はできず、部分的にロードされた行というものは存在しません。

戻り値OCI_SUCCESSは、バックエンドによるロードが正常に終了したことを示します。

関連関数

OCIDirPathAbort()、OCIDirPathDataSave()、OCIDirPathPrepare()、OCIDirPathStreamReset()

OCIDirPathFlushRow()

用途

サーバーから部分的にロードされた行をフラッシュします。この関数は非推奨です。

構文

sword OCIDirPathFlushRow (   OCIDirPathCtx          *dpctx,
OCIError               *errhp );

パラメータ

dpctx (IN)

ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

この関数は、行の一部がロードされたときに必要ですが、アプリケーションで次に処理するピースで変換エラーが発生します。現在、部分状態の行のみが廃棄されます。サーバーが、現在、ダイレクト・パス・コンテキストに関連するオブジェクトに対する部分状態の行を処理していない場合、この関数は何も行いません。

関連関数

OCIDirPathAbort()、OCIDirPathFinish()、OCIDirPathPrepare()、OCIDirPathLoadStream()

OCIDirPathLoadStream()

用途

ダイレクト・パス・ストリーム形式に変換されたデータをロードします。

構文

sword OCIDirPathLoadStream (   OCIDirPathCtx          *dpctx,
OCIDirPathStream       *dpstr,
OCIError               *errhp );

パラメータ

dpctx (IN)

ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。

dpstr (IN)

ロードするストリームのダイレクト・パス・ストリーム・ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

インタフェースからエラーが戻されたときは、ストリームのソースとなった列配列内の列に関する情報を、ダイレクト・パス・ストリームの属性として取得できます。また、エラーが発生したストリーム内のオフセットも、ストリームの属性として取得できます。

この関数のリターン・コードは次のとおりです。

- OCI_SUCCESS－ ストリーム内のすべてのデータが正常にロードされました。

- OCI_ERROR－ データのロード中にエラーが発生しました。問題は、パーティションのマッピング・エラー、NULL制約の違反、ファンクション索引評価エラー、またはエクステントを割り当てられないなどの領域条件の不足である可能性があります。OCI_ATTR_ROW_COUNTは、最後のコールで正常にロードされた行数です。

- OCI_NEED_DATA－ 最後の行が完全な行ではありませんでした。コール元は、行の残りをロードする必要があります。ストリームのソースが列配列である場合は、属性OCI_ATTR_ROW_COUNTは、最後のコールで正常にロードされた完全な行の数になります。

- OCI_NO_DATA - 空のストリームまたは完全に処理されているストリームをロードしようとしました。

OCI_SUCCESS、OCI_NEED_DATAまたはOCI_NO_DATAが戻されるまでは、ストリームを何度でもロードする必要があります。たとえば、OCI_ERRORがOCIDirPathLoadStream()から戻された場合、ストリームはリセットできません。

関連関数

OCIDirPathAbort()、OCIDirPathDataSave()、OCIDirPathFinish()、OCIDirPathPrepare()、OCIDirPathStreamReset()

OCIDirPathPrepare()

用途

行の変換またはロードを行う前に、ダイレクト・パス・ロード・インタフェースを準備します。

構文

sword OCIDirPathPrepare (   OCIDirPathCtx          *dpctx,
OCISvcCtx              *svchp,
OCIError               *errhp );

パラメータ

dpctx (IN)

ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。

svchp (IN)

サービス・コンテキストです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

操作するオブジェクトの名前、列データの外部属性、およびすべてのロード・オプションの設定後、行の変換またはロードの前にOCIDirPathPrepare()を使用してダイレクト・パス・インタフェースを準備する必要があります。

戻り値OCI_SUCCESSは、ダイレクト・パス・ロード操作を行うために、バックエンドが適切に初期化されたことを示しています。0 (ゼロ)以外の戻り値は、エラーを示します。戻される可能性のあるエラーは次のとおりです。

- コンテキストが無効です。

- サーバーに接続されていません。

- オブジェクト名が設定されていません。

- すでに準備されています(2度準備することはできません)。

- オブジェクトがダイレクト・パス処理に適切ではありません。

関連関数

OCIDirPathAbort()、OCIDirPathDataSave()、OCIDirPathFinish()、OCIDirPathStreamReset()

OCIDirPathStreamReset()

用途

ダイレクト・パス・ストリームの状態をリセットします。

構文

sword OCIDirPathStreamReset ( OCIDirPathStream       *dpstr,
OCIError               *errhp );

パラメータ

dpstr (IN)

ダイレクト・パス・ストリーム・ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

ダイレクト・パス・ストリームでは、次のOCIDirPathColArrayToStream()コールがストリームへの書込みを開始する場所を示す状態を維持します。通常、データはストリームの末尾に追加されます。ストリームは、正常にロードされる(ロードによってOCI_SUCCESS、OCI_NEED_DATAまたはOCI_NO_DATAが戻される)まではリセットできません。

関連関数

OCIDirPathAbort()、OCIDirPathDataSave()、OCIDirPathFinish()、OCIDirPathPrepare()

スレッド管理関数

表17-5は、この項で説明しているスレッド管理関数を示しています。

表17-5 スレッド管理関数

関数

用途

「OCIThreadClose()」

スレッド・ハンドルをクローズします。

「OCIThreadCreate()」

新しいスレッドを作成します。

「OCIThreadHandleGet()」

コールが行われたスレッドのOCIThreadHandleを取り出します。

「OCIThreadHndDestroy()」

スレッド・ハンドルの破棄および割当て解除を行います。

「OCIThreadHndInit()」

スレッド・ハンドルの割当ておよび初期化を行います。

「OCIThreadIdDestroy()」

スレッドIDの破棄および割当て解除を行います。

「OCIThreadIdGet()」

コールが行われたスレッドのOCIThreadIdを取り出します。

「OCIThreadIdInit()」

スレッドIDの割当ておよび初期化を行います。

「OCIThreadIdNull()」

特定のOCIThreadIdがNULLスレッドIDかどうかを判断します。

「OCIThreadIdSame()」

2つのOCIThreadIdが同じスレッドを表しているかどうかを判断します。

「OCIThreadIdSet()」

OCIThreadIdを別のOCIThreadIdに設定します。

「OCIThreadIdSetNull()」

指定されたOCIThreadIdにNULLスレッドIDを設定します。

「OCIThreadInit()」

OCIThreadコンテキストを初期化します。

「OCIThreadIsMulti()」

アプリケーションがマルチスレッド環境とシングル・スレッド環境のどちらで動作しているかを、コール元に通知します。

「OCIThreadJoin()」

コール側スレッドから別のスレッドに結合できるようにします。

「OCIThreadKeyDestroy()」

keyが指し示しているキーの破棄および割当て解除を行います。

「OCIThreadKeyGet()」

コール側スレッドのキーの現在の値を取得します。

「OCIThreadKeyInit()」

キーを作成します。

「OCIThreadKeySet()」

コール側スレッドのキー値を設定します。

「OCIThreadMutexAcquire()」

コールが行われたスレッドに対してmutexを取得します。

「OCIThreadMutexDestroy()」

mutexの破棄および割当て解除を行います。

「OCIThreadMutexInit()」

mutexの割当ておよび初期化を行います。

「OCIThreadMutexRelease()」

mutexを解放します。

「OCIThreadProcessInit()」

OCIThreadプロセスの初期化を行います。

「OCIThreadTerm()」

OCIThreadコンテキストを解放します。

OCIThreadClose()

用途

スレッド・ハンドルをクローズします。

構文

sword OCIThreadClose ( void             *hndl,
OCIError         *err,
OCIThreadHandle  *tHnd );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

tHnd (IN/OUT)

クローズするOCIThreadスレッド・ハンドルです。

コメント

tHndパラメータは、OCIThreadHndInit()を使用して初期化する必要があります。同一OCIThreadCreate()コールから戻されたスレッド・ハンドルおよびスレッドIDは、OCIThreadClose()コール後はどちらも無効になります。

関連関数

OCIThreadCreate()

OCIThreadCreate()

用途

新しいスレッドを作成します。

構文

sword OCIThreadCreate ( void             *hndl,
OCIError         *err,
void (*start)    (void *),
void             *arg,
OCIThreadId      *tid,
OCIThreadHandle  *tHnd );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

start (IN)

新しいスレッドが実行を開始する関数です。

arg (IN)

startが指し示している関数に渡す引数です。

tid (IN/OUT)

NULLでない場合は、新しいスレッドにIDを取得します。

tHnd (IN/OUT)

NULLでない場合は、新しいスレッドにハンドルを取得します。

コメント

argから渡された引数を使用して、startが指し示している関数コールを実行すると、新しいスレッドが開始します。その関数が復帰すると、新しいスレッドは終了します。関数は値を戻さず、パラメータvoidを受け入れます。tHndがNULL以外の場合にかぎり、OCIThreadCreate()コールはOCIThreadClose()コールに一致する必要があります。

tHndがNULLの場合は、生成されるスレッドの終了のタイミングが不明のため、*tid内に配置されたスレッドIDはコール側スレッドでは無効になります。

tidパラメータはOCIThreadIdInit()によって初期化し、tHndはOCIThreadHndInit()によって初期化します。

関連関数

OCIThreadClose()、OCIThreadIdInit()、OCIThreadHndInit()

OCIThreadHandleGet()

用途

コールが行われたスレッドのOCIThreadHandle を取り出します。

構文

sword OCIThreadHandleGet ( void             *hndl,
OCIError         *err,
OCIThreadHandle  *tHnd );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

tHnd (IN/OUT)

NULL以外の場合は、スレッドのスレッド・ハンドルを配置する場所です。

コメント

tHndパラメータは、OCIThreadHndInit()を使用して初期化する必要があります。

この関数によって取り出されるスレッド・ハンドルtHndは、使用後にOCIThreadClose()を使用してクローズし、OCIThreadHndDestroy()を使用して破棄する必要があります。

関連関数

OCIThreadHndDestroy()、OCIThreadHndInit()、OCIThreadClose()

OCIThreadHndDestroy()

用途

スレッド・ハンドルの破棄および割当て解除を行います。

構文

sword OCIThreadHndDestroy ( void             *hndl,
OCIError         *err,
OCIThreadHandle  **thnd );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

thnd (IN/OUT)

破棄するスレッド・ハンドルへのポインタのアドレスです。

コメント

thndパラメータは、OCIThreadHndInit()を使用して初期化する必要があります。

関連関数

OCIThreadHandleGet()、OCIThreadHndInit()

OCIThreadHndInit()

用途

スレッド・ハンドルの割当ておよび初期化を行います。

構文

sword OCIThreadHndInit ( void            *hndl,
OCIError        *err,
OCIThreadHandle **thnd );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

thnd (OUT)

初期化するスレッド・ハンドルへのポインタのアドレスです。

関連関数

OCIThreadHandleGet()、OCIThreadHndDestroy()

OCIThreadIdDestroy()

用途

スレッドIDの破棄および割当て解除を行います。

構文

sword OCIThreadIdDestroy (void         *hndl,
OCIError     *err,
OCIThreadId  **tid );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

tid (IN/OUT)

破棄するスレッドIDへのポインタです。

コメント

tidパラメータは、OCIThreadHndInit()を使用して初期化する必要があります。

関連関数

OCIThreadIdGet()、OCIThreadIdInit()、OCIThreadIdNull()、OCIThreadIdSame()、OCIThreadIdSet()、OCIThreadIdSetNull()

OCIThreadIdGet()

用途

コールされるスレッドのOCIThreadIdを取り出します。

構文

sword OCIThreadIdGet ( void         *hndl,
OCIError     *err,
OCIThreadId  *tid );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

tid (OUT)

コール側スレッドのIDを配置する場所を指し示す必要があります。

コメント

tidパラメータは、OCIThreadHndInit()を使用して初期化する必要があります。OCIThreadがシングル・スレッド環境で使用されている場合、OCIThreadIdGet()はtidで指し示される場所に常に同じ値を配置します。その値自体は重要ではありません。重要なのは、この値がNULLスレッドIDとは異なる値で、常に同じ値であるということです。

関連関数

OCIThreadIdDestroy()、OCIThreadIdInit()、OCIThreadIdNull()、OCIThreadIdSame()、OCIThreadIdSet()、OCIThreadIdSetNull()

OCIThreadIdInit()

用途

スレッドID tidの割当ておよび初期化を行います。

構文

sword OCIThreadIdInit ( void         *hndl,
OCIError     *err,
OCIThreadId  **tid );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

tid (OUT)

初期化するスレッドIDへのポインタです。

関連関数

OCIThreadIdDestroy()、OCIThreadIdGet()、OCIThreadIdNull()、OCIThreadIdSame()、OCIThreadIdSet()、OCIThreadIdSetNull()

OCIThreadIdNull()

用途

特定のOCIThreadIdがNULLスレッドIDかどうかを判断します。

構文

sword OCIThreadIdNull ( void         *hndl,
OCIError     *err,
OCIThreadId  *tid,
boolean      *result );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

tid (IN)

チェックするOCIThreadIdへのポインタです。

result (IN/OUT)

結果へのポインタです。

コメント

tidがNULLスレッドIDの場合、resultはTRUEに設定されます。それ以外の場合、resultはFALSEに設定されます。tidパラメータは、OCIThreadIdInit()を使用して初期化する必要があります。

関連関数

OCIThreadIdDestroy()、OCIThreadIdGet()、OCIThreadIdInit()、OCIThreadIdSame()、OCIThreadIdSet()、OCIThreadIdSetNull()

OCIThreadIdSame()

用途

2つのOCIThreadIdが同じスレッドを表しているかどうかを判断します。

構文

sword OCIThreadIdSame ( void          *hndl,
OCIError      *err,
OCIThreadId   *tid1,
OCIThreadId   *tid2,
boolean       *result );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

tid1 (IN)

最初のOCIThreadIdへのポインタです。

tid2 (IN)

2番目のOCIThreadIdへのポインタです。

result (IN/OUT)

結果へのポインタです。

コメント

tid1およびtid2が同じスレッドを表す場合、resultはTRUEに設定されます。それ以外の場合、resultはFALSEに設定されます。tid1とtid2の両方がNULLスレッドIDの場合、resultパラメータはTRUEに設定されます。パラメータtid1およびtid2は、OCIThreadIdInit()によって初期化します。

関連関数

OCIThreadIdDestroy()、OCIThreadIdGet()、OCIThreadIdInit()、OCIThreadIdNull()、OCIThreadIdSet()、OCIThreadIdSetNull()

OCIThreadIdSet()

用途

OCIThreadIdを別のOCIThreadIdに設定します。

構文

sword OCIThreadIdSet ( void         *hndl,
OCIError     *err,
OCIThreadId  *tidDest,
OCIThreadId  *tidSrc );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

tidDest (OUT)

設定後のOCIThreadIdの場所を指し示す必要があります。

tidSrc (IN)

設定前のOCIThreadIdを指し示す必要があります。

コメント

tidパラメータは、OCIThreadIdInit()を使用して初期化する必要があります。

関連関数

OCIThreadIdDestroy()、OCIThreadIdGet()、OCIThreadIdInit()、OCIThreadIdNull()、OCIThreadIdSame()、OCIThreadIdSetNull()

OCIThreadIdSetNull()

用途

指定されたOCIThreadIdにNULLスレッドIDを設定します。

構文

sword OCIThreadIdSetNull ( void         *hndl,
OCIError     *err,
OCIThreadId  *tid );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

tid (OUT)

NULLスレッドIDを設定するOCIThreadIdを指し示す必要があります。

コメント

tidパラメータは、OCIThreadIdInit()を使用して初期化する必要があります。

関連関数

OCIThreadIdDestroy()、OCIThreadIdGet()、OCIThreadIdInit()、OCIThreadIdNull()、OCIThreadIdSame()、OCIThreadIdSet()

OCIThreadInit()

用途

OCIThreadコンテキストを初期化します。

構文

sword OCIThreadInit ( void      *hndl,
OCIError  *err );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

コメント

戻されたポインタが指し示しているメモリーを、OCIThreadクライアントから検査しないでください。同時にOCIThreadInit()コールを実行してください。OCIThreadProcessInit()と異なり、他のコールより先に初期コールを行う必要はありません。

OCIThreadInit()の1回目のコールでは、OCIThreadコンテキストが初期化されます。また、そのコンテキストへのポインタを、システム情報も含めて保存します。2回目以降のOCIThreadInit()コールでは、同じコンテキストが戻されます。

各OCIThreadInit()コールは、結果的にOCIThreadTerm()コールに合致する必要があります。

関連関数

OCIThreadTerm()

OCIThreadIsMulti()

用途

アプリケーションがマルチスレッド環境とシングル・スレッド環境のどちらで動作しているかを、コール元に通知します。

構文

boolean OCIThreadIsMulti ( );

戻り値

TRUE - 環境がマルチスレッドの場合。

FALSE－ 環境がシングル・スレッドの場合。

関連関数

OCIThreadIdDestroy()、OCIThreadIdGet()、OCIThreadIdInit()、OCIThreadIdNull()、OCIThreadIdSame()、OCIThreadIdSet()

OCIThreadJoin()

用途

コール側スレッドが別のスレッドと結合できるようにします。

構文

sword OCIThreadJoin ( void             *hndl,
OCIError         *err,
OCIThreadHandle  *tHnd );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

tHnd (IN)

結合するスレッドのOCIThreadHandleです。

コメント

この関数は、指定されたスレッドが終了するまでコール元をブロックします。

tHndパラメータは、OCIThreadHndInit()を使用して初期化する必要があります。複数のスレッドをすべて同一のスレッドに結合した場合、結果は保証されていません。

関連関数

OCIThreadIdDestroy()、OCIThreadIdGet()、OCIThreadIdInit()、OCIThreadIdNull()、OCIThreadIdSame()、OCIThreadIdSet()

OCIThreadKeyDestroy()

用途

keyが指し示しているキーの破棄および割当て解除を行います。

構文

sword OCIThreadKeyDestroy ( void          *hndl,
OCIError      *err,
OCIThreadKey  **key );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

key (IN/OUT)

キーを破棄するOCIThreadKeyです。

コメント

これは、キー作成ルーチンに渡されるデストラクタ関数コールバックとは異なります。関数OCIThreadKeyDestroy()は、OCIThreadがkeyを作成する際に取得したすべてのリソースを終了させるのに使用します。OCIThreadKeyInit()のOCIThreadKeyDestFuncコールバックは、キー値デストラクタです。キー自体では動作しません。

この関数は、キーの使用が終了した後でコールする必要があります。OCIThreadKeyDestroy()関数をコールしないと、メモリー・リークが発生する可能性があります。

関連関数

OCIThreadKeyGet()、OCIThreadKeyInit()、OCIThreadKeySet()

OCIThreadKeyGet()

用途

コール側スレッドのキーの現在の値を取得します。

構文

sword OCIThreadKeyGet ( void          *hndl,
OCIError      *err,
OCIThreadKey  *key,
void          **pValue );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

key (IN)

キーです。

pValue (IN/OUT)

スレッド固有のキー値を配置する場所です。

コメント

OCIThreadKeyInit()を使用して作成されなかったキーに対して、この関数は使用しないでください。

コール側スレッドからキーに値が割り当てられていない場合は、pValueが指し示す場所にNULLが配置されます。

関連関数

OCIThreadKeyDestroy()、OCIThreadKeyInit()、OCIThreadKeySet()

OCIThreadKeyInit()

用途

キーを作成します。

構文

sword OCIThreadKeyInit (void                  *hndl,
OCIError              *err,
OCIThreadKey          **key,
OCIThreadKeyDestFunc  destFn );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

key (OUT)

新しいキーの作成を行うOCIThreadKeyです。

destFn (IN)

キーのデストラクタです。NULLでもかまいません。

コメント

このルーチンをコールするたびに、他のキーと異なる新しいキーの割当ておよび生成が行われます。この関数が正常に実行されると、割当ておよび初期化が行われたキーへのポインタが戻されます。このキーは、OCIThreadKeyGet()およびOCIThreadKeySet()とともに使用します。すべてのスレッドで、このキーの初期値はNULLです。

この関数を、keyパラメータに同じ値を指定して、複数回コールしないでください。

destFnパラメータがNULL以外の場合は、キーの値がNULL以外のスレッドが終了するたびに、destFnによって指し示されているルーチンがコールされます。そのルーチンがコールされるときのパラメータは、1つです。そのパラメータは、スレッド終了時のそのスレッドに対するキーの値です。キーにデストラクタ関数が不要な場合は、destFnにNULLを渡します。

関連関数

OCIThreadKeyDestroy()、OCIThreadKeyGet()、OCIThreadKeySet()

OCIThreadKeySet()

用途

コール側スレッドのキー値を設定します。

構文

sword OCIThreadKeySet ( void           *hndl,
OCIError       *err,
OCIThreadKey   *key,
void           *value );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

key (IN/OUT)

キーです。

value (IN)

キーに設定するスレッド固有の値です。

コメント

OCIThreadKeyInit()を使用して作成されなかったキーに対して、この関数は使用しないでください。

関連関数

OCIThreadKeyDestroy()、OCIThreadKeyGet()、OCIThreadKeyInit()

OCIThreadMutexAcquire()

用途

コールが行われたスレッドに対してmutexを取得します。

構文

sword OCIThreadMutexAcquire ( void            *hndl,
OCIError        *err,
OCIThreadMutex  *mutex );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

mutex (IN/OUT)

取得するmutexです。

コメント

mutexが別のスレッドによって保持されている場合は、mutexが取得できるまでコール側スレッドはブロックされます。

初期化されていないmutexは取得しないでください。

スレッドによってすでに保持されているmutexを取得するときに、この関数が使用されるかどうかは定義されていません。

関連関数

OCIThreadMutexDestroy()、OCIThreadMutexInit()、OCIThreadMutexRelease()

OCIThreadMutexDestroy()

用途

mutexの破棄および割当て解除を行います。

構文

sword OCIThreadMutexDestroy ( void           *hndl,
OCIError       *err,
OCIThreadMutex **mutex );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

mutex (IN/OUT)

破棄するmutexです。

コメント

不要になった各mutexは、破棄する必要があります。

初期化されていないmutex、またはスレッドに現在保持されているmutexを破棄しないでください。mutexの破棄は、そのmutexに対する他の操作と同時に行わないでください。また、mutexの破棄後は、そのmutexを使用しないでください。

関連関数

OCIThreadMutexAcquire()、OCIThreadMutexInit()、OCIThreadMutexRelease()

OCIThreadMutexInit()

用途

mutexの割当ておよび初期化を行います。

構文

sword OCIThreadMutexInit ( void            *hndl,
OCIError        *err,
OCIThreadMutex  **mutex );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

mutex (OUT)

初期化するmutexです。

コメント

すべてのmutexは、使用する前に初期化する必要があります。

複数のスレッドから同時に1つのmutexを初期化しないでください。また、mutexは、破棄されるまで初期化しなおさないでください(OCIThreadMutexDestroy()を参照)。

関連関数

OCIThreadMutexDestroy()、OCIThreadMutexAcquire()、OCIThreadMutexRelease()

OCIThreadMutexRelease()

用途

mutexを解放します。

構文

sword OCIThreadMutexRelease ( void            *hndl,
OCIError        *err,
OCIThreadMutex  *mutex );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

mutex (IN/OUT)

解放するmutexです。

コメント

mutexにブロックされているスレッドが存在する場合は、スレッドの1つがmutexを取得し、スレッドのブロックが解除されます。

初期化されていないmutexを解放しないでください。また、スレッドから、そのスレッドが保持していないmutexを解放しないでください。

関連関数

OCIThreadMutexDestroy()、OCIThreadMutexInit()、OCIThreadMutexAcquire()

OCIThreadProcessInit()

用途

OCIThreadプロセスの初期化を実行します。

構文

void OCIThreadProcessInit ( );

コメント

この関数をコールする必要があるかどうかは、OCIThreadの使用方法によって決まります。

シングル・スレッド・アプリケーションでは、この関数は必要に応じてコールします。コールする場合、1回目のコールは、他のOCIThread関数のコールよりも先に行う必要があります。この関数の2回目以降のコールには制限はありません。コールしても何も処理されません。

マルチスレッド・アプリケーションでは、この関数は必ずコールする必要があります。1回目のコールは、他のOCIThreadコールよりも先に行う必要があります。つまり、1回目のコールと同時に、他のOCIThread関数のコール(このコールも含みます)を行うことはできません。

この関数の2回目以降のコールには制限はありません。コールしても何も処理されません。

関連関数

OCIThreadIdDestroy()、OCIThreadIdGet()、OCIThreadIdInit()、OCIThreadIdNull()、OCIThreadIdSame()、OCIThreadIdSet()

OCIThreadTerm()

用途

OCIThreadコンテキストを解放します。

構文

sword OCIThreadTerm ( void      *hndl,
OCIError  *err );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーが発生してOCI_ERRORが戻された場合、そのエラーはerrに記録され、OCIErrorGet()のコールによって診断情報を取得できます。

コメント

この関数は、OCIThreadInit()への各コールに対して1回のみコールする必要があります。

同時にOCIThreadTerm()コールを行ってください。OCIThreadTerm()のコール回数がOCIThreadInit()のコール回数と異なる場合、処理は行われません。コール回数が同じ場合、OCIThreadTerm()はOCIThread層を終了し、コンテキストに割り当てられていたメモリーを解放します。この操作の後に、そのコンテキストを再使用しないでください。OCIThreadInit()をコールして新しいコンテキストを取得する必要があります。

関連関数

OCIThreadInit()

トランザクション関数

表17-6は、この項で説明しているトランザクション関数を示しています。

表17-6 トランザクション関数

関数

用途

「OCITransCommit()」

サービス・コンテキスト上のトランザクションをコミットします。

「OCITransDetach()」

サービス・コンテキストからトランザクションを連結解除します。

「OCITransForget()」

準備したグローバル・トランザクションを放棄します。

「OCITransMultiPrepare()」

単一セルに複数のブランチがあるトランザクションを準備します。

「OCITransPrepare()」

グローバル・トランザクションをコミットのために準備します。

「OCITransRollback()」

トランザクションをロールバックします。

「OCITransStart()」

サービス・コンテキスト上のトランザクションを開始します。

OCITransCommit()

用途

指定のサービス・コンテキストに対応付けられたトランザクションをコミットします。

構文

sword OCITransCommit ( OCISvcCtx    *svchp,
OCIError     *errhp,
ub4          flags );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

flags (IN)

グローバル・トランザクションの1フェーズ・コミットを最適化するためのフラグです。

OCI_DEFAULT - トランザクションが分散型でない場合、flagsパラメータは無視され、その値としてOCI_DEFAULTを渡すことができます。

OCI_TRANS_TWOPHASE－ 2フェーズ・コミットでは、グローバル・トランザクションを管理しているOCIアプリケーションは、flagsに対してこの値を渡す必要があります。デフォルトは1フェーズ・コミットです。

OCI_TRANS_WRITEIMMED－ (インメモリー)REDOバッファをオンラインREDOログに書き込むためのI/OがLGWR (バックグラウンドのログ・ライター・プロセス)によって開始されます。IMMEDIATEとは、メッセージをLGWRに送信してLGWRでメッセージを即時に処理し、トランザクションのREDOバッファを即時に書き出すことを示します。

OCI_TRANS_WRITEBATCH－ トランザクションのインメモリーREDOバッファをオンラインREDOログに書き込むためのI/OはLGWRによって発行されません。BATCHは、LGWRがREDOバッファをバッチ処理してからバッチ全体に対してI/Oを開始することを示します。BATCHとIMMEDIATEの両方を指定するとエラーが発生します。デフォルトはIMMEDIATEです。

OCI_TRANS_WRITEWAIT - これは、コミットのREDOバッファをオンラインREDOログに書き込むようLGWRに要求し、書き込まれるまではコミットを待機させます。WAITとは、トランザクションに対応するインメモリーREDOバッファが永続オンラインREDOログに書き込まれて初めてコミットが終了することを示します。

OCI_TRANS_WRITENOWAIT－ これは、コミットのREDOバッファをオンラインREDOログに書き込むようLGWRに要求しますが、バッファがオンラインREDOログに書き込まれるのを待たずにコミットは終了します。NOWAITとは、インメモリーREDOバッファをオンラインREDOログにフラッシュせずにコミットが終了することを示します。WAITとNOWAITの両方を指定するとエラーが発生します。デフォルトはWAITです。

注意:
OCI_TRANS_WRITENOWAITを使用すると、警告なしでトランザクションが消失する可能性があります。トランザクションの消失は、強制停止、強制起動、およびインスタンス障害やノード障害によって、警告なしに発生します。Oracle RACシステムでは、非同期にコミットされた場合、他のインスタンスでその変更を即時に読み取れない場合があります。

これら最後の4つのオプションは、分散型でないトップレベルのトランザクションのコミットのみに影響し、外部協調分散トランザクションでは無視されます。これらのオプションは、指定されている制限内容に応じてOR演算子を使用して結合できます。

コメント

サービス・コンテキストに現在対応付けられているトランザクションをコミットします。トランザクションがサーバーによるコミットが不可能なグローバル・トランザクションである場合、このコールは、トランザクションの状態をデータベースから取り出し、エラー・ハンドルを使用してユーザーに戻します。

複数のトランザクションを定義している場合、この関数は、サービス・コンテキストに現在対応付けられているトランザクションを処理します。データベースの変更時に作成される暗黙的ローカル・トランザクションのみを処理している場合は、その暗黙的トランザクションがコミットされます。

アプリケーションをオブジェクト・モードで実行している場合は、このトランザクションに対してオブジェクト・キャッシュで変更または更新されたオブジェクトもフラッシュされ、コミットされます。

正常な状況では、OCITransCommit()は、トランザクションがコミットされたかロールバックされたかを示す状態を戻します。グローバル・トランザクションでは、トランザクションがインダウトの状態、つまり、コミットも終了もされていない状態の場合もあり得ます。この場合、OCITransCommit()は、トランザクションの状態をサーバーから取り出します。そのステータスが戻ります。

例

例17-3は、「単純なローカル・トランザクション」に記述されている単純なローカル・トランザクションの使用方法を説明しています。

例17-3 単純なローカル・トランザクションでのOCITransCommit()の使用

int main()
{
OCIEnv *envhp;
OCIServer *srvhp;
OCIError *errhp;
OCISvcCtx *svchp;
OCIStmt *stmthp;
void      *tmp;
text sqlstmt[128];

OCIEnvCreate(&envhp, OCI_DEFAULT, (void  *)0, 0, 0, 0,
(size_t)0, (void  *)0);

OCIHandleAlloc( (void  *) envhp, (void  **) &errhp, (ub4) OCI_HTYPE_ERROR,
(size_t)0, (void  **) 0);
OCIHandleAlloc( (void  *) envhp, (void  **) &srvhp, (ub4) OCI_HTYPE_SERVER,
(size_t)0, (void  **) 0);

OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);

OCIHandleAlloc( (void  *) envhp, (void  **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
(size_t)0, (void  **) 0);

OCIHandleAlloc((void  *)envhp, (void  **)&stmthp, OCI_HTYPE_STMT, 0, 0);

OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)srvhp, 0,
OCI_ATTR_SERVER, errhp);

OCILogon(envhp, errhp, &svchp, (text *)"HR", strlen("HR"),
(text *)"HR", strlen("HR"), 0, 0);

/* update hr.employees employee_id=7902, increment salary */
sprintf((char *)sqlstmt, "UPDATE EMPLOYEES SET SALARY = SALARY + 1 \
WHERE  EMPLOYEE_ID = 7902");

OCIStmtPrepare(stmthp, errhp, sqlstmt, strlen((char *)sqlstmt),
OCI_NTV_SYNTAX, 0);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, 0);
OCITransCommit(svchp, errhp, (ub4) 0);

/* update hr.employees employee_id=7902, increment salary again, but rollback */
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, 0);
OCITransRollback(svchp, errhp, (ub4) 0);
}

関連関数

OCITransRollback()

OCITransDetach()

用途

グローバル・トランザクションの連結を解除します。

構文

sword OCITransDetach ( OCISvcCtx    *svchp,
OCIError     *errhp,
ub4          flags );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

flags (IN)

このパラメータ用に値OCI_DEFAULTを渡す必要があります。

コメント

サービス・コンテキスト・ハンドルからグローバル・トランザクションを連結解除します。このコールが終了した時点で、サービス・コンテキスト・ハンドルに現在連結されているトランザクションが非活動状態になります。このトランザクションは、後でOCITransStart()をコールしながらOCI_TRANS_RESUMEのフラグ値を指定するときに再開できます。

トランザクションの連結が解除されると、トランザクションの開始時にOCITransStart()のtimeoutパラメータに指定された値を使用して、サーバーのPMONプロセスによって削除されるまでブランチを非活動状態にしておける時間が判断されます。

注意:
トランザクションが同一の認可を持っている場合、トランザクションはその連結を解除したプロセス以外のプロセスによっても再開できます。トランザクションが実際に開始される前にこの関数がコールされると、この関数は何も行いません。

OCITransDetach()の使用方法を説明するコード例については、OCITransStart()の例の項を参照してください。

関連関数

OCITransStart()

OCITransForget()

用途

完了したグローバル・トランザクションをサーバーに放棄させます。

構文

sword OCITransForget ( OCISvcCtx     *svchp,
OCIError      *errhp,
ub4           flags );

パラメータ

svchp (IN)

トランザクションが常駐するサービス・コンテキスト・ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

flags (IN)

このパラメータ用にOCI_DEFAULTを渡す必要があります。

コメント

完了したグローバル・トランザクションを放棄します。サーバーにより、システムのペンディング・トランザクション表からトランザクションの状態が削除されます。

放棄されるトランザクションのXIDをトランザクション・ハンドルの属性として設定します(OCI_ATTR_XID)。

関連関数

OCITransCommit()、OCITransRollback()

OCITransMultiPrepare()

用途

単一セルに複数のブランチがあるトランザクションを準備します。

構文

sword OCITransMultiPrepare ( OCISvcCtx   *svchp,
ub4         numBranches,
OCITrans    **txns,
OCIError    **errhp);

パラメータ

srvchp (IN)

サービス・コンテキスト・ハンドルです。

numBranches (IN)

ブランチの数を指定します。この値は、次の2つのパラメータの配列サイズでもあります。

txns (IN)

準備するブランチのトランザクション・ハンドルの配列です。これらにはすべてOCI_ATTR_XIDが設定されます。グローバル・トランザクションIDは同じにしてください。

errhp (IN)

エラー・ハンドルの配列です。OCI_SUCCESSが戻されない場合、このパラメータによってどのブランチがどのエラーを受信したか示されます。

コメント

指定のグローバル・トランザクションをコミットできるように準備します。このコールは、分散トランザクションに対してのみ有効です。このコールは、コール元がトランザクションですべてのブランチを準備する場合にかぎり使用する拡張パフォーマンス機能です。

関連関数

OCITransPrepare()

OCITransPrepare()

用途

グローバル・トランザクションをコミットのために準備します。

構文

sword OCITransPrepare ( OCISvcCtx    *svchp,
OCIError     *errhp,
ub4          flags );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

flags (IN)

このパラメータ用にOCI_DEFAULTを渡す必要があります。

コメント

指定のグローバル・トランザクションをコミットできるように準備します。

このコールは、グローバル・トランザクションに対してのみ有効です。

このコールは、トランザクションが変更されていない場合はOCI_SUCCESS_WITH_INFOを戻します。エラー・ハンドルは、トランザクションが読取り専用であることを示します。flagsパラメータは、現在使用されていません。

関連関数

OCITransCommit()、OCITransForget()

OCITransRollback()

用途

カレント・トランザクションをロールバックします。

構文

sword OCITransRollback ( void         *svchp,
OCIError     *errhp,
ub4          flags );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。サービス・コンテキスト・ハンドル内に現在設定されているトランザクションがロールバックされます。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

flags (IN)

このパラメータ用に値OCI_DEFAULTを渡す必要があります。

コメント

カレント・トランザクション(最後のOCITransCommit()、またはOCISessionBegin()以降に実行された一連の文として定義されます)がロールバックされます。

アプリケーションがオブジェクト・モードで実行されている場合は、このトランザクションで修正または更新されたオブジェクト・キャッシュ内のオブジェクトも同様にロールバックされます。

現在アクティブでないグローバル・トランザクションをロールバックしようとすると、エラーになります。

例

OCITransRollback()の使用方法を説明するコード例については、OCITransCommit()の例の項を参照してください。

関連関数

OCITransCommit()

OCITransStart()

用途

トランザクションの開始を設定します。

構文

sword OCITransStart ( OCISvcCtx    *svchp,
OCIError     *errhp,
uword        timeout,
ub4          flags );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。flagsパラメータに新規トランザクションの開始が指定されている場合は、このコールの終了時点で、サービス・コンテキスト・ハンドル内のトランザクション・コンテキストが初期化されます。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

timeout (IN)

OCI_TRANS_RESUMEが指定されたときに、トランザクションが再開できるようになるまで待機する時間(秒)です。OCI_TRANS_NEWが指定されると、timeoutパラメータの指示する秒数間、非活動状態が続いたトランザクションは、システムによって自動的に終了します。トランザクションは、OCITransDetach()による連結解除から、OCITransStart()による再開までの間、非活動状態になります。

flags (IN)

新規トランザクションが開始中か、または既存のトランザクションが再開中であるかを指定します。シリアライズ可能または読取り専用ステータスも指定します。複数の値を指定できます。デフォルトでは、読取りトランザクションまたは書込みトランザクションが開始されます。フラグ値は次のとおりです。

- OCI_TRANS_NEW - 新規トランザクション・ブランチを開始します。デフォルトでは、密結合された移行可能なブランチが開始されます。

- OCI_TRANS_TIGHT - 密結合ブランチを明示的に指定します。

- OCI_TRANS_LOOSE - 疎結合ブランチを指定します。

- OCI_TRANS_RESUME - 既存のトランザクション・ブランチを再開します。

- OCI_TRANS_READONLY - 読取り専用トランザクションを開始します。

- OCI_TRANS_SERIALIZABLE - シリアライズ可能トランザクションを開始します。

- OCI_TRANS_SEPARABLE - 各コール後にトランザクションを分離します。
このフラグは、標準のトランザクションを使用してトランザクションが開始されたという警告を示します。リリース9.0.1のサーバーでは、分離されたトランザクションはサポートされていません。

コードまたはトランザクション・サービスにエラーがある場合は、エラー・メッセージが表示されます。このエラーは、すでに準備されていたトランザクションで処理を試みたことを示します。

コメント

この関数は、グローバル・トランザクションまたはシリアライズ可能トランザクションの開始を設定します。flagsパラメータに新規トランザクションの開始が指定されている場合は、このコールの終了時点で、サービス・コンテキスト・ハンドルに現在対応付けられているトランザクション・コンテキストが初期化されます。

トランザクションのXIDがトランザクション・ハンドルの属性として設定されます(OCI_ATTR_XID)。

例

例17-4および例17-5では、OCIトランザクション・コールを使用してグローバルなトランザクションを操作する方法を説明します。例17-4に示すような、様々なブランチで動作するシングル・セッションの概念は、図8-2で示しています。

例17-4 様々なブランチで動作するシングル・セッションでのOCITransStart()の使用

int main()
{
OCIEnv *envhp;
OCIServer *srvhp;
OCIError *errhp;
OCISvcCtx *svchp;
OCISession *usrhp;
OCIStmt *stmthp1, *stmthp2;
OCITrans *txnhp1, *txnhp2;
void      *tmp;
XID gxid;
text sqlstmt[128];

OCIEnvCreate(&envhp, OCI_DEFAULT, (void  *)0, 0, 0, 0,
(size_t)0, (void  *)0);

OCIHandleAlloc( (void  *) envhp, (void  **) &errhp, (ub4)
OCI_HTYPE_ERROR, 52, (void  **) &tmp);
OCIHandleAlloc( (void  *) envhp, (void  **) &srvhp, (ub4)
OCI_HTYPE_SERVER, 52, (void  **) &tmp);

OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);

OCIHandleAlloc( (void  *) envhp, (void  **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
52, (void  **) &tmp);

OCIHandleAlloc((void  *)envhp, (void  **)&stmthp1, OCI_HTYPE_STMT, 0, 0);
OCIHandleAlloc((void  *)envhp, (void  **)&stmthp2, OCI_HTYPE_STMT, 0, 0);

OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)srvhp, 0,
OCI_ATTR_SERVER, errhp);

/* set the external name and internal name in server handle */
OCIAttrSet((void  *)srvhp, OCI_HTYPE_SERVER, (void  *) "demo", 0,
OCI_ATTR_EXTERNAL_NAME, errhp);
OCIAttrSet((void  *)srvhp, OCI_HTYPE_SERVER, (void  *) "txn demo", 0,
OCI_ATTR_INTERNAL_NAME, errhp);

/* allocate a user context handle */
OCIHandleAlloc((void  *)envhp, (void  **)&usrhp, (ub4) OCI_HTYPE_SESSION,
(size_t) 0, (void  **) 0);

OCIAttrSet((void  *)usrhp, (ub4)OCI_HTYPE_SESSION, (void  *)"HR",
(ub4)strlen("HR"), OCI_ATTR_USERNAME, errhp);
OCIAttrSet((void  *)usrhp, (ub4)OCI_HTYPE_SESSION, (void  *)"HR",
(ub4)strlen("HR"),OCI_ATTR_PASSWORD, errhp);

OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS, 0);

OCIAttrSet((void  *)svchp, (ub4)OCI_HTYPE_SVCCTX,
(void  *)usrhp, (ub4)0, OCI_ATTR_SESSION, errhp);

/* allocate transaction handle 1 and set it in the service handle */
OCIHandleAlloc((void  *)envhp, (void  **)&txnhp1,  OCI_HTYPE_TRANS, 0, 0);
OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)txnhp1, 0,
OCI_ATTR_TRANS, errhp);

/* start a transaction with global transaction id = [1000, 123, 1] */
gxid.formatID = 1000; /* format id = 1000 */
gxid.gtrid_length = 3; /* gtrid = 123 */
gxid.data[0] = 1; gxid.data[1] = 2; gxid.data[2] = 3;
gxid.bqual_length = 1; /* bqual = 1 */
gxid.data[3] = 1;

OCIAttrSet((void  *)txnhp1, OCI_HTYPE_TRANS, (void  *)&gxid, sizeof(XID),
OCI_ATTR_XID, errhp);

/* start global transaction 1 with 60-second time to live when detached */
OCITransStart(svchp, errhp, 60, OCI_TRANS_NEW);

/* update hr.employees employee_id=7902, increment salary */
sprintf((char *)sqlstmt, "UPDATE EMPLOYEES SET SALARY = SALARY + 1 \
WHERE EMPLOYEE_ID = 7902");
OCIStmtPrepare(stmthp1, errhp, sqlstmt, strlen((char *)sqlstmt),
OCI_NTV_SYNTAX, 0);
OCIStmtExecute(svchp, stmthp1, errhp, 1, 0, 0, 0, 0);

/* detach the transaction */
OCITransDetach(svchp, errhp, 0);

/* allocate transaction handle 2 and set it in the service handle */
OCIHandleAlloc((void  *)envhp, (void  **)&txnhp2,  OCI_HTYPE_TRANS, 0, 0);

OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)txnhp2, 0,
OCI_ATTR_TRANS, errhp);

/* start a transaction with global transaction id = [1000, 124, 1] */
gxid.formatID = 1000; /* format id = 1000 */
gxid.gtrid_length = 3; /* gtrid = 124 */
gxid.data[0] = 1; gxid.data[1] = 2; gxid.data[2] = 4;
gxid.bqual_length = 1; /* bqual = 1 */
gxid.data[3] = 1;

OCIAttrSet((void  *)txnhp2, OCI_HTYPE_TRANS, (void  *)&gxid, sizeof(XID),
OCI_ATTR_XID, errhp);

/* start global transaction 2 with 90 second time to live when detached */
OCITransStart(svchp, errhp, 90, OCI_TRANS_NEW);

/* update hr.employees employee_id=7934, increment salary */
sprintf((char *)sqlstmt, "UPDATE EMPLOYEES SET SALARY = SALARY + 1 \
WHERE EMPLOYEE_ID = 7934");
OCIStmtPrepare(stmthp2, errhp, sqlstmt, strlen((char *)sqlstmt),
OCI_NTV_SYNTAX, 0);
OCIStmtExecute(svchp, stmthp2, errhp, 1, 0, 0, 0, 0);

/* detach the transaction */
OCITransDetach(svchp, errhp, 0);

/* Resume transaction 1, increment salary and commit it */
/* Set transaction handle 1 into the service handle */
OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)txnhp1, 0,
OCI_ATTR_TRANS, errhp);

/* attach to transaction 1, wait for 10 seconds if the transaction is busy */
/* The wait is clearly not required in this example because no other */
/* process/thread is using the transaction. It is only for illustration */
OCITransStart(svchp, errhp, 10, OCI_TRANS_RESUME);
OCIStmtExecute(svchp, stmthp1, errhp, 1, 0, 0, 0, 0);
OCITransCommit(svchp, errhp, (ub4) 0);

/* attach to transaction 2 and commit it */
/* set transaction handle2 into the service handle */
OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)txnhp2, 0,
OCI_ATTR_TRANS, errhp);
OCITransCommit(svchp, errhp, (ub4) 0);
}

例17-5 同じトランザクションを共有する複数のブランチで動作するシングル・セッションでのOCITransStart()の使用

int main()
{
OCIEnv *envhp;
OCIServer *srvhp;
OCIError *errhp;
OCISvcCtx *svchp;
OCISession *usrhp;
OCIStmt *stmthp;
OCITrans *txnhp1, *txnhp2;
void      *tmp;
XID gxid;
text sqlstmt[128];

OCIEnvCreate(&envhp, OCI_DEFAULT, (void  *)0, 0, 0, 0,
(size_t)0, (void  *)0);

OCIHandleAlloc( (void  *) envhp, (void  **) &errhp, (ub4) OCI_HTYPE_ERROR,
52, (void  **) &tmp);
OCIHandleAlloc( (void  *) envhp, (void  **) &srvhp, (ub4) OCI_HTYPE_SERVER,
52, (void  **) &tmp);

OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);

OCIHandleAlloc( (void  *) envhp, (void  **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
52, (void  **) &tmp);

OCIHandleAlloc((void  *)envhp, (void  **)&stmthp, OCI_HTYPE_STMT, 0, 0);

OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)srvhp, 0,
OCI_ATTR_SERVER, errhp);

/* set the external name and internal name in server handle */
OCIAttrSet((void  *)srvhp, OCI_HTYPE_SERVER, (void  *) "demo", 0,
OCI_ATTR_EXTERNAL_NAME, errhp);
OCIAttrSet((void  *)srvhp, OCI_HTYPE_SERVER, (void  *) "txn demo2", 0,
OCI_ATTR_INTERNAL_NAME, errhp);

/* allocate a user context handle */
OCIHandleAlloc((void  *)envhp, (void  **)&usrhp, (ub4) OCI_HTYPE_SESSION,
(size_t) 0, (void  **) 0);

OCIAttrSet((void  *)usrhp, (ub4)OCI_HTYPE_SESSION, (void  *)"HR",
(ub4)strlen("HR"), OCI_ATTR_USERNAME, errhp);
OCIAttrSet((void  *)usrhp, (ub4)OCI_HTYPE_SESSION, (void  *)"HR",
(ub4)strlen("HR"),OCI_ATTR_PASSWORD, errhp);

OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS, 0);

OCIAttrSet((void  *)svchp, (ub4)OCI_HTYPE_SVCCTX,
(void  *)usrhp, (ub4)0, OCI_ATTR_SESSION, errhp);

/* allocate transaction handle 1 and set it in the service handle */
OCIHandleAlloc((void  *)envhp, (void  **)&txnhp1,  OCI_HTYPE_TRANS, 0, 0);
OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)txnhp1, 0,
OCI_ATTR_TRANS, errhp);

/* start a transaction with global transaction id = [1000, 123, 1] */
gxid.formatID = 1000; /* format id = 1000 */
gxid.gtrid_length = 3; /* gtrid = 123 */
gxid.data[0] = 1; gxid.data[1] = 2; gxid.data[2] = 3;
gxid.bqual_length = 1; /* bqual = 1 */
gxid.data[3] = 1;

OCIAttrSet((void  *)txnhp1, OCI_HTYPE_TRANS, (void  *)&gxid, sizeof(XID),
OCI_ATTR_XID, errhp);

/* start global transaction 1 with 60-second time to live when detached */
OCITransStart(svchp, errhp, 60, OCI_TRANS_NEW);

/* update hr.employees employee_id=7902, increment salary */
sprintf((char *)sqlstmt, "UPDATE EMPLOYEES SET SALARY = SALARY + 1 \
WHERE EMPLOYEE_ID = 7902");
OCIStmtPrepare(stmthp, errhp, sqlstmt, strlen((char *)sqlstmt),
OCI_NTV_SYNTAX, 0);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, 0);

/* detach the transaction */
OCITransDetach(svchp, errhp, 0);

/* allocate transaction handle 2 and set it in the service handle */
OCIHandleAlloc((void  *)envhp, (void  **)&txnhp2,  OCI_HTYPE_TRANS, 0, 0);
OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)txnhp2, 0,
OCI_ATTR_TRANS, errhp);

/* start a transaction with global transaction id = [1000, 123, 2] */
/* The global transaction is tightly coupled with earlier transactions */
/* There is not much practical value in doing this but the example */
/* illustrates the use of tightly coupled transaction branches. */
/* In a practical case, the second transaction that tightly couples with */
/* the first can be executed from a different process/thread. */

gxid.formatID = 1000; /* format id = 1000 */
gxid.gtrid_length = 3; /* gtrid = 123 */
gxid.data[0] = 1; gxid.data[1] = 2; gxid.data[2] = 3;
gxid.bqual_length = 1; /* bqual = 2 */
gxid.data[3] = 2;

OCIAttrSet((void  *)txnhp2, OCI_HTYPE_TRANS, (void  *)&gxid,
sizeof(XID), OCI_ATTR_XID, errhp);

/* start global transaction 2 with 90-second time to live when detached */
OCITransStart(svchp, errhp, 90, OCI_TRANS_NEW);

/* update hr.employees employee_id=7902, increment salary */
/* This is possible even if the earlier transaction has locked this row */
/* because the two global transactions are tightly coupled */
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, 0);

/* detach the transaction */
OCITransDetach(svchp, errhp, 0);

/* Resume transaction 1 and prepare it. This returns */
/* OCI_SUCCESS_WITH_INFO because all branches except the last branch */
/* are treated as read-only transactions for tightly coupled transactions */

OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)txnhp1, 0,
OCI_ATTR_TRANS, errhp);
if (OCITransPrepare(svchp, errhp, (ub4) 0) == OCI_SUCCESS_WITH_INFO)
{
text errbuf[512];
ub4 buflen;
sb4 errcode;

OCIErrorGet ((void  *) errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
printf("OCITransPrepare - %s\n", errbuf);
}

/* attach to transaction 2 and commit it */
/* set transaction handle2 into the service handle */
OCIAttrSet((void  *)svchp, OCI_HTYPE_SVCCTX, (void  *)txnhp2, 0,
OCI_ATTR_TRANS, errhp);
OCITransCommit(svchp, errhp, (ub4) 0);
}

関連関数

OCITransDetach()

その他の関数

表17-7は、この項で説明しているその他のOCI関数を示しています。

表17-7 その他の関数

関数

用途

「OCIBreak()」

即時非同期ブレークを実行します。

「OCIClientVersion()」

クライアント・ライブラリのバージョンを戻します。

「OCIErrorGet()」

エラー・メッセージとOracleエラーを戻します。

「OCILdaToSvcCtx()」

Lda_Defをサービス・コンテキスト・ハンドルに切り替えます。

「OCIPasswordChange()」

パスワードを変更します。

「OCIPing()」

接続とサーバーがアクティブであることを確認します。

「OCIReset()」

OCIBreak()の後にコールされて、非同期操作およびプロトコルをリセットします。

「OCIRowidToChar()」

ユニバーサルROWIDを拡張文字(BASE64)表現に変換します。

「OCIServerRelease()」

Oracleリリース文字列を取得します。

「OCIServerVersion()」

Oracleバージョン文字列を取得します。

「OCISvcCtxToLda()」

サービス・コンテキスト・ハンドルをLda_Defに切り替えます。

「OCIUserCallbackGet()」

ハンドルに対して登録されたコールバックを識別します。

「OCIUserCallbackRegister()」

ユーザー作成コールバック関数を登録します。

OCIBreak()

用途

サーバーに対応付けられて現在実行中であるOCI関数は即時(非同期)終了します。

構文

sword OCIBreak ( void       *hndlp,
OCIError   *errhp );

パラメータ

hndlp (IN/OUT)

サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

このコールにより、サーバーに対応付けられて現在実行中であるOCI関数は即時(非同期)終了します。これは通常、サーバーで長時間実行されている処理中のOCIコールを停止するために使用します。これは、マルチスレッド・アプリケーションのユーザー・スレッドや、LinuxまたはUNIXシステムのユーザー・シグナル・ハンドラによって呼び出すことができます。ユーザー・シグナル・ハンドラで使用できるOCIコールはOCIBreak()のみです。

注意:
OCIBreak()は、Windows 2000やWindows XPなどのWindowsシステムで作動します。

このコールは、終了する関数を識別するためのパラメータとして、サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルを取得できます。

関連項目:

- 「サーバー・ハンドル属性」

- 「OCIでの非ブロック化モード」

- 「コールの取消し」

関連関数

OCIReset()

OCIClientVersion()

用途

実行時にクライアント・ライブラリの5桁のOracle Databaseバージョン番号を戻します。

構文

void OCIClientVersion ( sword        *major_version,
sword        *minor_version,
sword        *update_num,
sword        *patch_num,
sword        *port_update_num );

パラメータ

major_version (OUT)

バージョンです。

minor_version (OUT)

リリースです。

update_num (OUT)

更新番号です。

patch_num (OUT)

ライブラリに適用されたパッチ番号です。

port_update_num (OUT)

ライブラリに適用されたポート固有のパッチです。

コメント

OCIClientVersion()は、アプリケーションの実行に使用しているOCIクライアントのバージョンを戻します。これは、アプリケーションが実行時に認識する際に役に立ちます。アプリケーションまたはテスト・プログラムは、この関数を呼び出すことにより、特定のOCIクライアント・システムのバージョンおよびパッチ・セットを確認できます。また、アプリケーションがクライアントのパッチ・セットのレベルに応じて異なるコードパスを使用する必要がある場合も、この関数が役に立ちます。

OCIClientVersion()以外にも、OCI_MAJOR_VERSIONとOCI_MINOR_VERSIONという2つのマクロが定義されています。これらのマクロは、様々なOCIクライアントのバージョンで作成および実行できる汎用アプリケーションを作成するときに役に立ちます。たとえば、次のようにします。

....
#if (OCI_MAJOR_VERSION > 9)
...
#endif
....

関連関数

OCIServerRelease()

OCIErrorGet()

用途

指定されたバッファ内のエラー・メッセージとOracle Databaseエラー・コードを戻します。

構文

sword OCIErrorGet ( void       *hndlp,
ub4        recordno,
OraText    *sqlstate,
sb4        *errcodep,
OraText    *bufp,
ub4        bufsiz,
ub4        type );

パラメータ

hndlp (IN)

エラー・ハンドル(通常)、または環境ハンドル(OCIEnvCreate()およびOCIHandleAlloc()に関するエラー用)です。

recordno (IN)

アプリケーションが情報を検索する検索先の状態レコードを示します。1から始まります。

sqlstate (OUT)

リリース8.x以上ではサポートされていません。

errcodep (OUT)

戻されたエラー・コードです。

bufp (OUT)

戻されたエラー・メッセージ・テキストです。

bufsiz (IN)

エラー・メッセージについて指定されたバッファのサイズ(バイト数)です。エラー・メッセージの長さがbufsizより長い場合、切り捨てられたエラー・メッセージ・テキストがbufpに戻されます。

typeがOCI_HTYPE_ERRORに設定されている場合、切捨て時のOCIErrorGet()からのリターン・コードはOCI_ERRORになります。クライアントは、より大きいバッファを指定し、OCIErrorGet()を再度コールできます。

メッセージ・テキスト全体を収容するのにbufsizが十分で、メッセージを正常にbufpにコピーできた場合、OCIErrorGet()のリターン・コードはOCI_SUCCESSになります。

type (IN)

ハンドルのタイプ(OCI_HTYPE_ERRORまたはOCI_HTYPE_ENV)です。

コメント

この関数は、SQL文はサポートしていません。hndlpは、通常、エラー・ハンドルですが、環境ハンドルの場合もあります。メッセージは、常に環境ハンドルに設定されたエンコーディングで取得する必要があります。エラーに関して複数の診断レコードが存在する場合は、この関数を複数回コールできます。

リターン・コードがOCI_SUCCESSである場合、OCIErrorGet()をコールしないでください。これをコールした場合、前に実行された文からのエラー・メッセージがOCIErrorGet()により見つかります。

エラー・ハンドルは、最初はOCIHandleAlloc()のコールで割り当てられます。

注意:
レコードがなくなる(OCI_NO_DATAが戻される)まで、繰り返しOCIErrorGet()をコールすると、複数の診断レコードを取り出すことができます。OCIErrorGet()は、最大1個の診断レコードを戻します。

関連項目:
「OCIでのエラー処理」

例

例17-6に、OCIErrorGet()を使用したエラー・チェック関数の単純な例を示します。

例17-6 OCIErrorGet()を使用したエラー・チェック

static void checkerr(OCIError *errhp, sword status)
{
text errbuf[512];
ub4 buflen;
sb4 errcode;

if (status == OCI_SUCCESS) return;

switch (status)
{
case OCI_SUCCESS_WITH_INFO:
printf("Error - OCI_SUCCESS_WITH_INFO\n");
OCIErrorGet ((void  *) errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
printf("Error - %s\n", errbuf);
break;
case OCI_NEED_DATA:
printf("Error - OCI_NEED_DATA\n");
break;
case OCI_NO_DATA:
printf("Error - OCI_NO_DATA\n");
break;
case OCI_ERROR:
OCIErrorGet ((void  *) errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
printf("Error - %s\n", errbuf);
break;
case OCI_INVALID_HANDLE:
printf("Error - OCI_INVALID_HANDLE\n");
break;
case OCI_STILL_EXECUTING:
printf("Error - OCI_STILL_EXECUTING\n");
break;
case OCI_CONTINUE:
printf("Error - OCI_CONTINUE\n");
break;
default:
printf("Error - %d\n", status);
break;
}
}

関連関数

OCIHandleAlloc()

OCILdaToSvcCtx()

用途

バージョン7のLda_Defをバージョン8以上のサービス・コンテキスト・ハンドルに変換します。

構文

sword OCILdaToSvcCtx ( OCISvcCtx  **svchpp,
OCIError   *errhp,
Lda_Def    *ldap );

パラメータ

svchpp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

ldap (IN/OUT)

OCISvcCtxToLda()によりこのサービス・コンテキストから戻されたOracle7ログイン・データ領域(LDA)です。

コメント

Oracle7のLda_Defをバージョン8以上のサービス・コンテキスト・ハンドルに変換します。変換されたサービス・コンテキスト・ハンドルをOCISvcCtxToLda()関数に渡すと、このコールの逆の変換ができます。

OCILdaToSvcCtx()コールは、OCISvcCtxToLda()から取得したLda_Defをサービス・コンテキスト・ハンドルに戻してリセットする場合にかぎり使用します。このコールは、Lda_defをサービス・コンテキスト・ハンドルに戻して再開されたLda_defを変換する場合には使用できません。

サービス・コンテキストがLda_Defに変換されている場合、使用できるのはOracle7コールのみです。Lda_Defをサービス・コンテキストにリセットせずにバージョン8以上のOCIコールを行っても実行されません。

サーバー・ハンドルまたはサービス・コンテキスト・ハンドルのOCI_ATTR_IN_V8_MODE属性によって、アプリケーションでは、そのアプリケーションの現在の実行モードが、Oracleバージョン7か、Oracleバージョン8以上かを判断できます。

関連項目:
付録A「ハンドルおよび記述子の属性」

関連関数

OCISvcCtxToLda()

OCIPasswordChange()

用途

アカウントのパスワードの変更を許可します。

構文

sword OCIPasswordChange ( OCISvcCtx     *svchp,
OCIError      *errhp,
const OraText *user_name,
ub4           usernm_len,
const OraText *opasswd,
ub4           opasswd_len,
const OraText *npasswd,
sb4           npasswd_len,
ub4           mode );

パラメータ

svchp (IN/OUT)

サービス・コンテキストへのハンドルです。サービス・コンテキスト・ハンドルは初期化され、サーバー・コンテキスト・ハンドルがそれに対応付けられている必要があります。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

user_name (IN)

ユーザー名を指定します。UTF-16エンコーディングが可能です。サービス・コンテキストが認証ハンドルで初期化されている場合は、最後の文字をNULL文字にする必要があります。

usernm_len (IN)

エンコーディングに関係なく、user_nameにバイト数で指定されたユーザー名文字列の長さです。usernm_lenの値は0 (ゼロ)以外にしてください。

opasswd (IN)

ユーザーの旧パスワードを指定します。UTF-16エンコーディングが可能です。

opasswd_len (IN)

opasswdで指定された旧パスワード文字列の長さ(バイト単位)です。opasswd_lenの値は0 (ゼロ)以外にしてください。

npasswd (IN)

ユーザーの新規パスワードを指定します。UTF-16エンコーディングが可能です。パスワード複雑度検証ルーチンがユーザーのプロファイルに指定され、新規パスワードの複雑度が検証される場合、新規パスワードは検証関数の複雑度要件に一致する必要があります。

npasswd_len (IN)

npasswdで指定された新規パスワード文字列の長さ(バイト単位)です。パスワード文字列を有効にするには、npasswd_lenは0 (ゼロ)以外にしてください。

mode (IN)

OCI_DEFAULT - 環境ハンドルの設定を使用します。

- OCI_UTF16 - 環境ハンドルの設定に関係なく、UTF-16エンコーディングを使用します。
user_name、opasswdおよびnpasswdで使用できるエンコーディングはUTF-16のみで、あとは使用するかしないかの選択のみです。

- OCI_AUTH - ユーザー・セッション・コンテキストが作成されていない場合は、このフラグを使用したコールによって作成され、パスワードが変更されます。コールが終了しても、ユーザー・セッション・コンテキストは消去されません。ユーザーはログインされたままです。
ユーザー・セッション・コンテキストが作成されている場合は、このフラグを使用したコールによってパスワードの変更のみが実行され、セッションへの影響はありません。ユーザーはログインされたままです。

コメント

このコールは、アカウントのパスワードの変更を許可します。このコールはOCISessionBegin()に類似していますが、次の点が異なります。

- ユーザー・セッションが確立されている場合、このコールでは、旧パスワードを使用しているアカウントを認証した後、パスワードを新規パスワードに変更します。

- ユーザー・セッションが確立されていない場合、このコールでは、ユーザー・セッションを確立して旧パスワードを使用しているアカウントを認証した後、パスワードを新規パスワードに変更します。

このコールは、アカウントのパスワードが期限切れになり、OCISessionBegin()が、エラー(ORA-28001)またはパスワードが期限切れであることを示す警告を戻したときに役に立ちます。

modeまたは環境ハンドルによって、UTF-16が使用されているかどうかが判断されます。

関連関数

OCISessionBegin()

OCIPing()

用途

サーバーへのラウンドトリップ・コールを行い、接続とサーバーがアクティブであることを確認します。

構文

sword OCIPing ( OCISvcCtx     *svchp,
OCIError      *errhp,
ub4           mode );

パラメータ

svchp (IN)

サービス・コンテキストへのハンドルです。サービス・コンテキスト・ハンドルは初期化され、サーバー・コンテキスト・ハンドルがそれに対応付けられている必要があります。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

mode (IN)

コールのモードです。OCI_DEFAULTを使用します。

コメント

OCIPing()は、サーバーに対してダミーのラウンドトリップ・コールを実行します。つまり、応答としてダミー・パケットがサーバーに送信されます。ラウンドトリップの完了後、OCIPing()が戻されます。このコール自体に対して、サーバーは操作を実行しません。

OCIPing()を使用して、サーバーに対する軽量コールを行うことができます。コールが正常に終了した場合は、接続とサーバーがアクティブであることを示します。コールがブロックされた場合、接続が別のスレッドによって使用されている可能性があります。このコールが失敗した場合、接続やサーバーに問題が発生している可能性があり、エラーをエラー・ハンドルから取り出すことができます。OCIPing()はラウンドトリップ・コールであるため、これを使用して、サーバーに対する保留状態のOCIクライアント側のコール(存在する場合)をすべてフラッシュすることもできます。たとえば、OCIHandleFree()の後にOCIPing()をコールすることにより、保留状態のコールの実行を強制し、バックエンド・カーソルをクローズすることができます。アプリケーションがバックエンド・カーソルを即時にクローズする必要がある場合、このコールが役に立ちます。

関連関数

OCIHandleFree()

OCIReset()

用途

割り込まれた非同期操作およびプロトコルをリセットします。非ブロック操作の処理中にOCIBreak()コールが発行された場合に、コールする必要があります。

構文

sword OCIReset ( void       *hndlp,
OCIError   *errhp );

パラメータ

hndlp(IN)

サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

このコールは、非ブロック・モードでのみコールされます。割り込まれた非同期操作およびプロトコルをリセットします。非ブロック操作の処理中にOCIBreak()コールが発行された場合に、OCIReset()をコールする必要があります。

関連関数

OCIBreak()

OCIRowidToChar()

用途

ユニバーサルROWIDを拡張文字(BASE64)表現に変換します。

構文

sword OCIRowidToChar ( OCIRowid      *rowidDesc,
OraText       *outbfp,
ub2           *outbflp
OCIError      *errhp );

パラメータ

rowidDesc (IN)

OCIDescriptorAlloc()で割り当てられ、前に実行されたSQL文で挿入されたROWID記述子です。

outbfp (OUT)

このコールが正常に実行された後、文字表現が格納されるバッファへのポインタです。

outbflp (IN/OUT)

出力バッファ長へのポインタです。実行前は、バッファ長にはoutbfpのサイズが格納されています。実行後は、変換されたバイト数が格納されます。

変換時に切捨てがある場合、outbfpには、変換を正常終了するために必要な長さが格納されます。エラーも戻されます。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

この変換を行った後は、文字形式のROWIDをOCIBindByPos()コールまたはOCIBindByName()コールにバインドし、指定されたROWIDの行の問合せに使用できます。

OCIServerRelease()

用途

Oracle Databaseリリース文字列を戻します。

構文

sword OCIServerRelease ( void         *hndlp,
OCIError     *errhp,
OraText      *bufp,
ub4          bufsz
ub1          hndltype
ub4          *version );

パラメータ

hndlp (IN)

サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

bufp (IN/OUT)

リリース文字列が戻されるバッファです。

bufsz (IN)

バイト数で示したバッファの長さです。

hndltype (IN)

関数に渡されたハンドル型です。

version (IN/OUT)

整数書式でのリリース文字列です。

コメント

バッファ・ポインタbufpは、NULL終端文字を含む、サイズbufszまでの文字列表現内のリリース情報を指し示しています。バッファ・サイズが小さい場合、結果はサイズbufszまで切り捨てられます。version引数には、5桁のOracle Databaseリリース文字列が整数形式で含まれており、これは次のマクロを使用して取得されます。

#define MAJOR_NUMVSN(v) ((sword)(((v) >> 24) & 0x000000FF))      /* version number */
#define MINOR_NUMRLS(v) ((sword)(((v) >> 20) & 0x0000000F))      /* release number */
#define UPDATE_NUMUPD(v) ((sword)(((v) >> 12) & 0x000000FF))     /* update number */
#define PORT_REL_NUMPRL(v) ((sword)(((v) >> 8) & 0x0000000F))    /* port release number */
#define PORT_UPDATE_NUMPUP(v) ((sword)(((v) >> 0) & 0x000000FF)) /* port update number */

関連関数

OCIServerVersion()

OCIServerVersion()

用途

Oracle Databaseバージョン文字列を戻します。

構文

sword OCIServerVersion ( void         *hndlp,
OCIError     *errhp,
OraText      *bufp,
ub4          bufsz
ub1          hndltype );

パラメータ

hndlp (IN)

サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

bufp (IN/OUT)

バージョン情報が戻されるバッファです。

bufsz (IN)

バイト数で示したバッファの長さです。

hndltype (IN)

関数に渡されたハンドル型です。

コメント

このコールは、Oracle Databaseのバージョン文字列を戻します。Unicodeの文字列が可能です(環境ハンドルでUnicodeと判断された場合)。

たとえば、アプリケーションが8.1.5 SunOSサーバー上で実行されている場合は、次のようなバージョン文字列がbufpに戻されます。

Oracle8i Enterprise Edition Release 8.1.5.0.0 - Production
With the Partitioning and Java options
PL/SQL Release 8.1.5.0.0 - Production

関連関数

OCIErrorGet()、OCIClientVersion()

OCISvcCtxToLda()

用途

バージョン8以上のサービス・コンテキスト・ハンドルとバージョン7のLda_Defとの間の切替えを行います。

構文

sword OCISvcCtxToLda ( OCISvcCtx    *srvhp,
OCIError     *errhp,
Lda_Def      *ldap );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

ldap (IN/OUT)

このコールによって初期化される、Oracle7スタイルのOCIコールのためのログイン・データ領域です。

コメント

OCIバージョン8以上のサービス・コンテキスト・ハンドルとOracle7のLda_Defとの間の切替えを行います。

この関数は、サービス・コンテキストが正常に初期化された後でのみコールできます。

サービス・コンテキストがLda_Defに変換されると、リリース7.x OCIコールで使用できるようになります(たとえば、obindps()、ofen())。

同じサーバー・ハンドルを共有する複数のサービス・コンテキストがある場合、Oracle7モードでは常に1つのサービス・コンテキストのみ可能です。

変換されたLda_DefをOCILdaToSvcCtx()関数に渡すと、このコールの逆の変換ができます。

サーバー・ハンドルまたはサービス・コンテキスト・ハンドルのOCI_ATTR_IN_V8_MODE属性によって、アプリケーションでは、そのアプリケーションの現在の実行モードが、Oracleバージョン7か、Oracleバージョン8以上かを判断できます。

関連項目:
付録A「ハンドルおよび記述子の属性」

関連関数

OCILdaToSvcCtx()

OCIUserCallbackGet()

用途

ハンドルに対して登録されたコールバックを判断します。

構文

sword OCIUserCallbackGet ( void    *hndlp,
ub4     type,
void    *ehndlp,
ub4     fcode,
ub4     when,
OCIUserCallback (*callbackp)
(
void   *ctxp,
void   *hndlp,
ub4  type,
ub4  fcode,
ub1  when,
sword  returnCode,
ub4  *errnop,
va_list arglist
),
void    **ctxpp,
OCIUcb  *ucbDesc );

パラメータ

hndlp(IN)

typeパラメータによって指定された型のハンドルです。

type (IN)

ハンドル・タイプです。有効なハンドル・タイプはOCI_HTYPE_ENVです。このコールバックは、環境ハンドル上で生成されたfcodeによって指定される関数の、すべてのコールに対して登録されます。

ehndlp (IN)

OCIエラー・ハンドルまたは環境ハンドルです。エラーがある場合は、ehndlpに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

fcode (IN)

OCI関数の一意の関数コードです。これらは表17-8にリスト表示されています。

when (IN)

コールバックがいつ呼び出されるかを定義します。次のモードが有効です。

- OCI_UCBTYPE_ENTRY - このコールバックは、OCI関数の開始時に呼び出されます。

- OCI_UCBTYPE_EXIT - このコールバックは、OCI関数の終了前に呼び出されます。

- OCI_UCBTYPE_REPLACE - このコールバックでOCI_CONTINUE以外が戻された場合は、次の置換コールバックおよびOCI関数に対するOCIコードはコールされません。かわりに、最後のコールバックの処理が開始されます。このパラメータの詳細は、「OCIUserCallbackRegister()」を参照してください。

callbackp (OUT)

コールバック関数ポインタへのポインタです。fcode、whenおよびhndlpの値に対して現在登録されている関数を戻します。この場合、コールバックが登録されていないときは、戻り値はNULLです。

関連項目:
callbackpのパラメータの詳細は、「OCIUserCallbackRegister()」 を参照してください。

ctxpp (OUT)

現在登録されているコールバックに対して戻されるコンテキストへのポインタです。

ucbDesc (IN)

OCIで指定される記述子です。この記述子は、環境コールバックでOCIによって渡されます。この記述子には、コールバックを登録する場合の優先度が格納されます。ucbDescパラメータにNULLを指定すると、このコールバックの優先度が最も高くなります。

パッケージで動的に登録されたユーザー・コールバックとは対照的に、静的に登録されたユーザー・コールバックは、使用するucb記述子がないため、NULL記述子を使用します。

コメント

この関数は、特定のハンドルに対して登録されているコールバックを検出します。

関連項目:
「コールバック関数の制限」

関連関数

OCIUserCallbackRegister()

OCIUserCallbackRegister()

用途

ユーザー作成コールバック関数を登録します。

構文

sword OCIUserCallbackRegister ( void    *hndlp,
ub4      type,
void    *ehndlp,
OCIUserCallback  (callback)
(
void    *ctxp,
void    *hndlp,
ub4     type,
ub4     fcode,
ub1     when,
sword   returnCode,
ub4     *errnop,
va_list arglist
),
void     *ctxp,
ub4      fcode,
ub4      when,
OCIUcb   *ucbDesc );

パラメータ

hndlp(IN)

typeパラメータによって指定された型のハンドルです。

type (IN)

ハンドル・タイプです。有効なハンドル・タイプはOCI_HTYPE_ENVです。このコールバックは、環境ハンドル上で生成されたfcodeによって指定される関数の、すべてのコールに対して登録されます。

ehndlp (IN)

OCIエラー・ハンドルまたは環境ハンドルです。エラーがある場合は、ehndlpに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。OCIEnvCallbackでは、エラー・ハンドルを使用することができないため、環境ハンドルはehndlpとして渡されます。

callback (IN)

コールバック関数ポインタです。OCIUserCallback関数プロトタイプの変数引数のリストは、OCI関数に渡されるパラメータです。OCIUserCallbackのtypedefについては、後で説明します。

最初のコールバックでOCI_CONTINUE以外が戻された場合、リターン・コードは後続の最初のコールバックまたは置換コールバック(存在する場合)に渡されます。このコールバックが最新の最初のコールバックで、置換コールバックがない場合、OCIコードは実行されてリターン・コードは無視されます。

置換コールバックがOCI_CONTINUE以外を戻した場合、後続の置換コールバックおよびOCIコードは迂回されて最後のコールバックの処理が開始されます。

終了コールバックがOCI_CONTINUE以外を戻した場合、戻り値はOCI関数によって戻されます。そうでない場合、OCIコードまたは置換コールバックからの戻り値(置換コールバックがOCI_CONTINUEを戻さず、結果的にOCIコードをバイパスした場合)が、このコールによって戻されます。

コールバックに対してNULL値が渡された場合は、when値および指定されたハンドルのコールバックが削除されます。これは、NULLのucbDescを含む指定のucbDesc値に対するコールバックを登録解除する方法です。

ctxp (IN)

コールバックのコンテキスト・ポインタです。

fcode (IN)

OCI関数の一意の関数コードです。これらは表17-8にリスト表示されています。

when (IN)

コールバックがいつ呼び出されるかを定義します。次のモードが有効です。

- OCI_UCBTYPE_ENTRY - このコールバックは、OCI関数の開始時に呼び出されます。

- OCI_UCBTYPE_EXIT - このコールバックは、OCI関数の終了前に呼び出されます。

- OCI_UCBTYPE_REPLACE - このコールバックでOCI_CONTINUE以外が戻された場合は、次の置換コールバックおよびOCI関数に対するOCIコードはコールされません。かわりに、最後のコールバックの処理が開始されます。

ucbDesc (IN)

OCIで指定される記述子です。この記述子は、環境コールバックでOCIによって渡されます。この記述子には、コールバックを登録する場合の優先度が格納されます。ucbDescパラメータにNULLを指定すると、このコールバックの優先度が最も高くなります。

パッケージで動的に登録されたユーザー・コールバックとは対照的に、静的に登録されたユーザー・コールバックは、使用するucb記述子がないため、NULL記述子を使用します。

コメント

この関数は、OCI環境にユーザー作成のコールバックを登録する場合に使用します。

このコールバックにより、アプリケーションで次の処理を行うことができます。

- デバッグおよびパフォーマンス測定のためにOCIコールをトレースします。

- 選択したOCIコールの後に、前処理または後処理を追加実行します。

- 指定された関数のコードを、外部キー・データ・ソースで実行する専用コードに置き換えます。

OCIでは、最初のコールバック、置換コールバックおよび最後のコールバックがサポートされています。

この3種類のコールバックは、モードOCI_UCBTYPE_ENTRY、OCI_UCBTYPE_REPLACEおよびOCI_UCBTYPE_EXITで識別されます。

次の制御フローがあります。

1. 最初のコールバックの実行。

2. 置換コールバックの実行。

3. OCIコードの実行。

4. 最後のコールバックの実行。

最初のコールバックは、プログラムがOCI関数に入るときに実行されます。

置換コールバックは、最初のコールバック実行の後に実行されます。置換コールバックからOCI_CONTINUEの値が戻された場合は、後続の置換コールバックまたは通常のOCI固有のコードが実行されます。置換コールバックからOCI_CONTINUE以外の値が戻される場合は、後続の置換コールバックおよびOCIコードは実行されません。

OCI関数が正常に実行された後または置換コールバックからOCI_CONTINUE以外が戻された後は、プログラムの制御は最後のコールバック(登録されている場合)に移ります。

置換コールバックまたは最後のコールバックからOCI_CONTINUE以外が戻された場合は、コールバックからのリターン・コードは、対応付けられたOCIコールから戻されます。

ハンドルに対して登録されているコールバックを判断するには、OCIUserCallbackGet()を使用します。

OCIUserCallback typedefのプロトタイプは次のとおりです。

typedef sword (*OCIUserCallback)
(void    *ctxp,
void    *hndlp,
ub4     type,
ub4     fcode,
ub4     when,
sword   returnCode,
sb4     *errnop,
va_list arglist );

OCIUserCallback関数プロトタイプへのパラメータは次のとおりです。

ctxp (IN)

登録コールバック関数内でctxpとして渡されるコンテキストです。

hndlp(IN)

typeパラメータで指定された型のハンドルです。コールバックを呼び出すためのハンドルです。OCI_HTYPE_ENV型以外は使用できないため、環境ハンドルenvはここに渡されます。

type (IN)

hndlpに対して登録された型です。有効なハンドル・タイプはOCI_HTYPE_ENVです。このコールバックは、環境ハンドル上で生成されたfcodeによって指定される関数の、すべてのコールに対して登録されます。

fcode (IN)

OCIコールの関数コードです。これらは表17-8にリスト表示されています。コールバックは、表17-3に示されているOCIコールに対してのみ登録できます。

when (IN)

コールバックのwhen値です。

returnCode (IN)

直前のコールバックまたはOCIコードからのリターン・コードです。1回目の最初のコールバックでは、OCI_SUCCESSが常に渡されます。後続のコールバックでは、OCIコードまたは前のコールバックからのリターン・コードが渡されます。

errnop (IN/OUT)

1回目の最初のコールバックをコールすると、*errnopの入力値は0 (ゼロ)になります。コールバックによりOCI_CONTINUE以外の値が戻される場合は、*errnopにエラー番号を設定する必要があります。この値は、OCIコール内に渡されるエラー・ハンドルで設定されます。

後続のすべてのコールバックの場合、*errnopの入力値はエラー・ハンドル内のエラー番号の値です。このため、前のコールバックからOCI_CONTINUEが戻されなかった場合、前のコールバックからの*errnopの出力値はエラー・ハンドル内の値となり、この値が、ここで後続のコールバックに渡されます。ただし、前のコールバックによってOCI_CONTINUEが戻された場合、エラー・ハンドル内の値はすべてここで渡されます。

*errnopにOracle以外のエラー番号が戻された場合は、そのエラー番号に対して適切なテキストを戻すために、コールバックをOCIErrorGet()関数に登録する必要があります。

arglist (IN)

これは、引数の可変数としてここに渡されるOCIコールのパラメータです。ユーザー・コールバックのデモ・プログラムに示されているように、va_argを使用して間接参照する必要があります。

関連項目:
付録B「OCIデモ・プログラム」

表17-8および表17-9は、OCI関数コードのリスト、およびOCIルーチン名とその関数番号を示しています。

表17-8 OCI関数コード

#

OCIルーチン

#

OCIルーチン

#

OCIルーチン

1

OCIInitialize

33

OCITransStart

65

OCIDefineByPos

2

OCIHandleAlloc

34

OCITransDetach

66

OCIBindByPos

3

OCIHandleFree

35

OCITransCommit

67

OCIBindByName

4

OCIDescriptorAlloc

36

(使用されていません)

68

OCILobAssign

5

OCIDescriptorFree

37

OCIErrorGet

69

OCILobIsEqual

6

OCIEnvInit

38

OCILobFileOpen

70

OCILobLocatorIsInit

7

OCIServerAttach

39

OCILobFileClose

71

OCILobEnableBuffering

8

OCIServerDetach

40

(使用されていません)

72

OCILobCharSetId

9

(使用されていません)

41

(使用されていません)

73

OCILobCharSetForm

10

OCISessionBegin

42

OCILobCopy

74

OCILobFileSetName

11

OCISessionEnd

43

OCILobAppend

75

OCILobFileGetName

12

OCIPasswordChange

44

OCILobErase

76

OCILogon

13

OCIStmtPrepare

45

OCILobGetLength

77

OCILogoff

14

(使用されていません)

46

OCILobTrim

78

OCILobDisableBuffering

15

(使用されていません)

47

OCILobRead

79

OCILobFlushBuffer

16

(使用されていません)

48

OCILobWrite

80

OCILobLoadFromFile

17

OCIBindDynamic

49

(使用されていません)

81

OCILobOpen

18

OCIBindObject

50

OCIBreak

82

OCILobClose

19

(使用されていません)

51

OCIServerVersion

83

OCILobIsOpen

20

OCIBindArrayOfStruct

52

(使用されていません)

84

OCILobFileIsOpen

21

OCIStmtExecute

53

(使用されていません)

85

OCILobFileExists

22

(使用されていません)

54

OCIAttrGet

86

OCILobFileCloseAll

23

(使用されていません)

55

OCIAttrSet

87

OCILobCreateTemporary

24

(使用されていません)

56

OCIParamSet

88

OCILobFreeTemporary

25

OCIDefineObject

57

OCIParamGet

89

OCILobIsTemporary

26

OCIDefineDynamic

58

OCIStmtGetPieceInfo

90

OCIAQEnq

27

OCIDefineArrayOfStruct

59

OCILdaToSvcCtx

91

OCIAQDeq

28

OCIStmtFetch

60

(使用されていません)

92

OCIReset

29

OCIStmtGetBindInfo

61

OCIStmtSetPieceInfo

93

OCISvcCtxToLda

30

(使用されていません)

62

OCITransForget

94

OCILobLocatorAssign

31

(使用されていません)

63

OCITransPrepare

95

(使用されていません)

32

OCIDescribeAny

64

OCITransRollback

96

OCIAQListen

表17-9 OCI関数コードの続き(97以降)

#

OCIルーチン

#

OCIルーチン

#

OCIルーチン

97

予約済

113

OCILobErase2

129

OCILobGetOptions

98

予約済

114

OCILobGetLength2

130

OCILobSetOptions

99

OCITransMultiPrepare

115

OCILobLoadFromFile2

131

OCILobFragementInsert

100

OCIConnectionPoolCreate

116

OCILobRead2

132

OCILobFragementDelete

101

OCIConnectionPoolDestroy

117

OCILobTrim2

133

OCILobFragementMove

102

OCILogon2

118

OCILobWrite2

134

OCILobFragementReplace

103

OCIRowidToChar

119

OCILobGetStorageLimit

135

OCILobGetDeduplicateRegions

104

OCISessionPoolCreate

120

OCIDBStartup

136

OCIAppCtxSet

105

OCISessionPoolDestroy

121

OCIDBShutdown

137

OCIAppCtxClearAll

106

OCISessionGet

122

OCILobArrayRead

138

OCILobGetContentType

107

OCISessionRelease

123

OCILobArrayWrite

139

OCILobSetContentType

108

OCIStmtPrepare2

124

OCIAQEnqStreaming

109

OCIStmtRelease

125

OCIAQGetReplayInfo

110

OCIAQEnqArray

126

OCIAQResetReplayInfo

111

OCIAQDeqArray

127

OCIArrayDescriptorAlloc

112

OCILobCopy2

128

OCIArrayDescriptorFree

関連関数

OCIUserCallbackGet()

18 OCIのナビゲーショナル関数と型関数

この章では、Oracle Databaseから取り出されたオブジェクトをナビゲートするOCIナビゲーショナル関数について説明します。さらに、ここには型記述子オブジェクト(TDO)を取得する関数の説明も含まれています。

関連項目:
コード例は、Oracle Databaseのインストールに含まれているデモ・プログラムを参照してください。詳細は、付録Bを参照してください。

この章は、次の項目で構成されています。

- ナビゲーショナル関数および型関数の概要

- OCIフラッシュまたはリフレッシュ関数

- OCIオブジェクトおよびキャッシュへのマークまたはマーク解除関数

- OCIのオブジェクト・ステータス取得関数

- その他のOCIオブジェクト関数

- OCIの確保関数、確保解除関数および解放関数

- OCIの型情報アクセッサ関数

ナビゲーショナル関数および型関数の概要

オブジェクト・ナビゲーショナル・パラダイムの中では、データは参照によって接続されたオブジェクトのグラフとして表現されます。このグラフの中のオブジェクトに到達するには、参照をたどります。OCIは、Oracle Database内のオブジェクトにナビゲーショナル・インタフェースを提供します。この章では、これらのコールについて説明します。

アプリケーションがOCIEnvCreate()、OCIEnvNlsCreate()またはOCIInitialize() (非推奨)をOCI_OBJECTモードでコールすると、OCIオブジェクト環境は初期化されます。

関連項目:
この章で説明されているコールの使用方法の詳細は、第11章および第14章を参照してください。

オブジェクト型と存続期間

オブジェクト・インスタンスは、Oracle Databaseで定義された型の状態変化です。この項では、OCIでのオブジェクト・インスタンスの記述方法について説明します。OCIでは、オブジェクト・インスタンスは型、存続期間および参照可能性によって次のように分類されます。

- 永続オブジェクトはオブジェクト型のインスタンスの1つです。永続オブジェクトは、サーバー内の表の行中に常駐し、セッション(接続)の継続時間より長く存在できます。永続オブジェクトは、オブジェクト識別子を格納するオブジェクト参照によって識別できます。永続オブジェクトは、そのオブジェクト参照を確保することで取得できます。

- 一時オブジェクトはオブジェクト型のインスタンスです。一時オブジェクトは、セッション(接続)の継続時間より長く存在することはできず、一時的な計算結果を格納します。一時オブジェクトは、一時オブジェクト識別子を格納する参照によって識別できます。

- 値はユーザー定義型(オブジェクト型またはコレクション型)のインスタンスの1つであるか、組込みOracle型のいずれかです。オブジェクトとは異なり、オブジェクト型の値は、参照ではなくメモリー・ポインタによって識別されます。

値はスタンドアロン値または埋込み値になります。スタンドアロン値は、通常、SELECT文を発行することで取得されます。OCIでは、クライアント・プログラムがSQL文を発行することで、オブジェクト表の行を選択して値に代入することもできます。データベース内の参照可能オブジェクトは、参照によって識別できない値として表現できます。また、スタンドアロン値は、VARCHARやRAWのように、オブジェクト内の表外格納属性にしたり、VARCHAR、RAW、オブジェクトのように、コレクション内の表外格納要素にできます。

埋込み値は、格納インスタンス内に物理的に格納されます。埋込み値は、数値やネストしたオブジェクトなどのオブジェクト内の表内格納属性、またはコレクション内の表内格納要素にできます。

すべての値は、OCIでは一時的なものであるとみなされます。つまり、OCIは値のデータベースへの自動フラッシュをサポートしないため、クライアントは、値をデータベースに格納するためのSQL文を明示的に実行する必要があります。埋込み値は、格納インスタンスがフラッシュされるときにフラッシュされます。

図18-1に、インスタンスの型と存続期間による分類方法を示します。型には、オブジェクトまたはオブジェクトの値を指定できます。存続期間には、永続(セッションの継続時間より長く存在できる)または一時(セッションの継続時間より長く存在できない)を指定できます。

図18-1 インスタンスの型と存続期間による分類

各インスタンスの違いを、表18-1に示します。

表18-1 インスタンスの型と存続期間

特性

永続オブジェクト

一時オブジェクト

値

型

オブジェクト型

オブジェクト型

オブジェクト型、組込み、コレクション

最長存続期間

オブジェクトが削除されるまで

セッション

セッション

参照可能性

あり

あり

なし

埋込み可能性

なし

なし

あり

用語

この章では、次の用語が使用されます。

- オブジェクトとは、一般に、永続オブジェクト、一時オブジェクト、オブジェクト型のスタンドアロン値、またはオブジェクト型の埋込み値のことです。

- 参照可能オブジェクトとは、永続オブジェクトまたは一時オブジェクトのことです。

- スタンドアロン・オブジェクトとは、永続オブジェクト、一時オブジェクト、またはオブジェクト型のスタンドアロン値のことです。

- 埋込みオブジェクトとは、オブジェクト型の埋込み値のことです。

- オブジェクトは、作成(新規作成)された場合、または更新済や削除済のマークが設定された場合に、使用済と表現されます。

関連項目:
異なるオブジェクト型を指す用語の詳細は、「永続オブジェクト、一時オブジェクトおよび値」を参照してください。

OCI関数の規則

各関数を記述する際に使用される規則は、「OCI関数の規則」を参照してください。関数ごとに次の情報が記載されている場合もあります。

戻り値

表18-3にリストされている標準コード以外の値が関数によって戻される場合の、戻り値についての説明。

ナビゲーショナル関数の戻り値

表18-2は、 OCIナビゲーショナル関数によって通常戻される値を示しています。

表18-2 ナビゲーショナル関数の戻り値

戻り値

意味

OCI_SUCCESS

操作は成功しました。

OCI_ERROR

操作は失敗しました。関数に渡されたエラー・ハンドルに対してOCIErrorGet()をコールすることで特定のエラーを取り出せます。

OCI_INVALID_HANDLE

関数に渡されたOCIハンドルが無効です。

この章では、各関数に関する記述の後で関数固有の戻り値に関する情報を説明します。各関数から戻される特定のエラー・コードに関する情報は、次の項で記述します。

関連項目:
リターン・コードおよびエラー処理の詳細は、「OCIでのエラー処理」を参照してください。

キャッシュ関数およびオブジェクト関数用のサーバー・ラウンドトリップ

個々のOCIキャッシュ関数およびオブジェクト関数に必要なサーバー・ラウンドトリップ回数を示す表は、表C-3を参照してください。

ナビゲーショナル関数エラー・コード

表18-3には、各OCIナビゲーショナル関数によって戻される外部Oracleエラー・コードがリストされています。表の後に各エラーの内容を説明します。

表18-3 OCIナビゲーショナル関数エラー・コード

関数

発生する可能性のあるORAエラー

OCICacheFlush()

24350, 21560, 21705

OCICacheFree()

24350, 21560, 21705

OCICacheRefresh()

24350, 21560, 21705

OCICacheUnmark()

24350, 21560, 21705

OCICacheUnpin()

24350, 21560, 21705

OCIObjectArrayPin()

24350, 21560

OCIObjectCopy()

24350, 21560, 21705, 21710

OCIObjectExists()

24350, 21560, 21710

OCIObjectFlush()

24350, 21560, 21701, 21703, 21708, 21710

OCIObjectFree()

24350, 21560, 21603, 21710

OCIObjectGetAttr()

21560, 21600, 22305

OCIObjectGetInd()

24350, 21560, 21710

OCIObjectGetObjectRef()

24350, 21560, 21710

OCIObjectGetTypeRef()

24350, 21560, 21710

OCIObjectIsDirty()

24350, 21560, 21710

OCIObjectIsLocked()

24350, 21560, 21710

OCIObjectLock()

24350, 21560, 21701, 21708, 21710

OCIObjectLockNoWait()

24350, 21560, 21701, 21708, 21710

OCIObjectMarkDelete()

24350, 21560, 21700, 21701, 21702, 21710

OCIObjectMarkDeleteByRef()

24350, 21560

OCIObjectMarkUpdate()

24350, 21560, 21700, 21701, 21710

OCIObjectNew()

24350, 21560, 21705, 21710

OCIObjectPin()

24350, 21560, 21700, 21702

OCIObjectPinCountReset()

24350, 21560, 21710

OCIObjectPinTable()

24350, 21560, 21705

OCIObjectRefresh()

24350, 21560, 21709, 21710

OCIObjectSetAttr()

21560, 21600, 22305, 22279, 21601

OCIObjectUnmark()

24350, 21560, 21710

OCIObjectUnmarkByRef()

24350, 21560

OCIObjectUnpin()

24350, 21560, 21710

表18-3のORAエラーは、次のとおりです。

- ORA-21560 - 引数stringがNULL、無効または範囲外です。

- ORA-21600 - パス式が長すぎます。

- ORA-21601 - 属性がオブジェクトではありません。

- ORA-21603 - プロパティID[string]は無効です。

- ORA-21700 - オブジェクトが存在しないか、削除マークが設定されています。

- ORA-21701 - 異なるサーバーにオブジェクトをフラッシュしようとしました。

- ORA-21702 - オブジェクトがインスタンス化されていないか、またはキャッシュ内でインスタンス化解除されています

- ORA-21703 - 変更されていないオブジェクトはフラッシュできません。

- ORA-21704 - フラッシュを実行しないとキャッシュまたは接続を終了できません。

- ORA-21705 - サービス・コンテキストが無効です。

- ORA-21708 - 一時オブジェクトで不適切な操作が行われました。

- ORA-21709 - 変更されたオブジェクトをリフレッシュできません。

- ORA-21710 - 引数にはオブジェクトの有効なメモリー・アドレスが必要です。

- ORA-22279 - LOBバッファリングが使用可能な状態では、操作を実行できません。

- ORA-22305 - 属性/メソッド/パラメータ"string"が見つかりません。

- ORA-24350 - OCIコールは使用できません。

OCIフラッシュまたはリフレッシュ関数

表18-4は、この項で説明しているOCIフラッシュまたはリフレッシュ関数を示しています。

表18-4 フラッシュまたはリフレッシュ関数

関数

用途

「OCICacheFlush()」

キャッシュ内の変更済永続オブジェクトをサーバーにフラッシュします。

「OCICacheRefresh()」

確保されている永続オブジェクトをリフレッシュします。

「OCIObjectFlush()」

単一の変更済永続オブジェクトをサーバーにフラッシュします。

「OCIObjectRefresh()」

永続オブジェクトをリフレッシュします。

OCICacheFlush()

用途

この関数は、変更済永続オブジェクトをサーバーにフラッシュします。

構文

sword OCICacheFlush ( OCIEnv              *env,
OCIError            *err,
const OCISvcCtx     *svc,
void                *context,
OCIRef              *(*get)
( void    *context,
ub1     *last ),
OCIRef              **ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキストです。

context (IN) [オプション]

クライアント・コールバック関数getへの引数であるユーザー・コンテキストを指定します。ユーザー・コンテキストがない場合、このパラメータはNULLに設定します。

get (IN) [オプション]

フラッシュを必要とする使用済オブジェクトのバッチを取り出すイテレータとして機能するクライアント定義関数です。関数がNULLでない場合は、使用済オブジェクトの参照を取得するために、この関数がコールされます。これは、クライアント関数によってNULL参照が戻されるか、lastパラメータがTRUEに設定されるまで繰り返されます。クライアント関数がコールされるたびにget()にcontextパラメータが渡されます。ユーザー・コールバックを指定しない場合、このパラメータはNULLにする必要があります。クライアント関数によって戻されたオブジェクトが使用済永続オブジェクトでない場合、そのオブジェクトは無視されます。

クライアント関数から戻されたすべてのオブジェクトは、同じサービス・コンテキストを使用して更新するか、または確保する必要があります。そうしない場合、エラーが発生します。キャッシュは、戻されたオブジェクトを使用済とマークを付けられた順序でフラッシュします。

このパラメータにNULLを渡すと(たとえば、クライアント定義関数が指定されていない場合)、指定されたサービス・コンテキストのすべての使用済永続オブジェクトが、使用済とマークされた順序でフラッシュされます。

ref (OUT) [オプション]

オブジェクトのフラッシュでエラーが発生すると、(*ref)はエラーの原因となったオブジェクトを指し示します。refがNULLの場合、オブジェクトは戻りません。*refがNULLの場合は、参照が割り当てられ、そのオブジェクトを指し示すように設定されます。*refがNULLでない場合は、オブジェクトの参照が指定の領域にコピーされます。エラーの原因が使用済オブジェクトでない場合は、指定のREFがNULL参照になるように初期化されます(OCIRefIsNull(*ref)がTRUEになります)。

REFはセッション継続時間(OCI_DURATION_SESSION)に対して割り当てられます。アプリケーションはOCIObjectFree()関数を使用して、割り当てられたREFを解放できます。

コメント

この関数は、オブジェクト・キャッシュの変更済永続オブジェクトをサーバーにフラッシュします。オブジェクトは、新たに作成された順序、または更新済や削除済のマークが設定された順序でフラッシュされます。

関連項目:
「OCIObjectFlush()」

この関数によるネットワーク・ラウンドトリップは大抵1回です。

関連関数

OCIObjectFlush()

OCICacheRefresh()

用途

キャッシュ内のすべての確保済永続オブジェクトをリフレッシュします。

構文

sword OCICacheRefresh ( OCIEnv            *env,
OCIError           *err,
const OCISvcCtx    *svc,
OCIRefreshOpt      option,
void               *context,
OCIRef             *(*get)(void  *context),
OCIRef             **ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキストです。

option (IN) [オプション]

OCI_REFRESH_LOADEDが指定されると、そのトランザクションの間にロードされたすべてのオブジェクトをリフレッシュします。オプションがOCI_REFRESH_LOADEDで、getパラメータがNULLでない場合、このパラメータは無視されます。

context (IN) [オプション]

クライアント・コールバック関数getへの引数であるユーザー・コンテキストを指定します。ユーザー・コンテキストがない場合、このパラメータはNULLに設定します。

get (IN) [オプション]

リフレッシュされる必要があるオブジェクトのバッチを取り出すイテレータとして機能するクライアント定義関数です。関数がNULLでない場合は、オブジェクトの参照を取得するために、この関数がコールされます。参照がNULLでない場合、オブジェクトはリフレッシュされます。このステップは、この関数からNULL参照が戻されるまで繰り返されます。クライアント関数がコールされるたびにget()にcontextパラメータが渡されます。ユーザー・コールバックを指定しない場合、このパラメータはNULLにする必要があります。

ref (OUT) [オプション]

オブジェクトのリフレッシュでエラーが発生すると、(*ref)はエラーの原因となったオブジェクトを指し示します。refがNULLの場合、オブジェクトは戻りません。*refがNULLの場合は、参照が割り当てられ、そのオブジェクトを指し示すように設定されます。*refがNULLでない場合は、オブジェクトの参照が指定の領域にコピーされます。エラーの原因がオブジェクトでない場合は、指定のrefがNULL参照になるように初期化されます(OCIRefIsNull(*ref)がTRUEになります)。

コメント

この関数は、すべての確保済永続オブジェクトをリフレッシュします。確保解除されたすべての永続オブジェクトは、オブジェクト・キャッシュから解放されます。

関連項目:

- OCIObjectRefresh()

- 「オブジェクト・コピーのリフレッシュ」。

注意:
オブジェクトがリフレッシュされると、それらのオブジェクトの2次メモリーがメモリー内の別の場所に移動することがあります。このため、このコール前に保存された属性へのポインタが無効になる可能性があります。2次メモリーを使用する属性には、OCIString *、OCIColl *、OCIRaw *などがあります。

関連関数

OCIObjectRefresh()

OCIObjectFlush()

用途

変更済永続オブジェクトをサーバーにフラッシュします。

構文

sword OCIObjectFlush ( OCIEnv        *env,
OCIError      *err,
void          *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

永続オブジェクトへのポインタです。このコールの前に、オブジェクトが確保されることが必要です。

コメント

この関数は、変更済永続オブジェクトをサーバーにフラッシュします。フラッシュ時には、オブジェクトの排他ロックが暗黙的に取得されます。この関数によってオブジェクトがサーバーに書き込まれるときに、トリガーを起動できます。この関数は、一時オブジェクトと値、および未修正の永続オブジェクトに対して、エラーを戻します。

オブジェクトは、サーバーでトリガーによって変更できます。キャッシュにあるオブジェクトとデータベースとの間の整合性を保つために、アプリケーションではキャッシュにあるオブジェクトの解放やリフレッシュを行うことができます。

フラッシュするオブジェクトに内部LOB属性があり、そのLOB属性がOCIObjectCopy()、OCILobAssign()またはOCILobLocatorAssign()操作によって変更されたり、別のLOBロケータの割当てによって変更された場合は、フラッシュによって、割当て時にソースLOB内に存在していたLOB値のコピーか、内部LOBのロケータまたはオブジェクトのコピーが生成されます。

関連項目:
「LOB関数」

関連関数

OCIObjectPin()、OCICacheFlush()

OCIObjectRefresh()

用途

カレント・データベースの最新のスナップショットから永続オブジェクトをリフレッシュします。

構文

sword OCIObjectRefresh ( OCIEnv        *env,
OCIError      *err,
void          *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

永続オブジェクトへのポインタです。すでに確保されていることが必要です。

コメント

この関数は、サーバー内の最新のスナップショットから取り出されたデータを使用して、オブジェクトをリフレッシュします。オブジェクトは、オブジェクト・キャッシュ内のオブジェクトとサーバー内のオブジェクトとの間に整合性がなくなったときにリフレッシュされる必要があります。

注意:
オブジェクトをサーバーにフラッシュすると、トリガーを起動してサーバー内のさらに多くのオブジェクトを変更できます。その場合、オブジェクト・キャッシュ内にある(トリガーによって変更したオブジェクトと)同一のオブジェクトは最新の状態ではなくなり、リフレッシュしないとロックまたはフラッシュできません。
これは、ユーザーがSQL文またはPL/SQLプロシージャを発行してサーバー内のオブジェクトを変更したときに発生します。

注意:
最後のフラッシュ以降にオブジェクト(使用済オブジェクト)に対して行われた変更は、マークされていないオブジェクトがこの関数でリフレッシュされると失われます。

表18-5は、リフレッシュの後、オブジェクトの様々なメタ属性フラグと継続時間がどのように変更されるかを示しています。

表18-5 リフレッシュ後のオブジェクトの状態

オブジェクト属性

リフレッシュ後の状態

既存

適切な値に設定

確保済

変更なし

割当て時間

変更なし

確保継続時間

変更なし

リフレッシュされたオブジェクトは、その場で置き換えられます。オブジェクトがその場で置き換えられると、オブジェクトのトップレベル・メモリーが再利用されるため、新しいデータが同じメモリー・アドレスにロードされるようになります。NULLインジケータ構造体のトップレベル・メモリーも再利用されます。トップレベル・メモリー・チャンクとは異なり、2次メモリー・チャンクは解放され、再割当てが行われます。

ポインタはオブジェクトのリフレッシュ後に無効になる場合があるため、2次メモリー・チャンクのアドレスをローカル変数に割り当てるときなど、2次メモリー・チャンクへのポインタを保持する機能の記述時には注意が必要です。

この関数は、一時オブジェクトまたは値に対して何も影響を与えません。

関連関数

OCICacheRefresh()

OCIオブジェクトおよびキャッシュへのマークまたはマーク解除関数

表18-6は、この項で説明しているOCIオブジェクトおよびキャッシュへのマークまたはマーク解除関数を示しています。

表18-6 オブジェクトおよびキャッシュへのマークまたはマーク解除関数

関数

用途

「OCICacheUnmark()」

キャッシュ内のオブジェクトのマークを解除します。

「OCIObjectMarkDelete()」

オブジェクトに削除済のマークを付けるか、または、値インスタンスを削除します。

「OCIObjectMarkDeleteByRef()」

オブジェクトへの参照の指定時に、オブジェクトに削除済のマークを付けます。

「OCIObjectMarkUpdate()」

オブジェクトに更新済または使用済のマークを付けます。

「OCIObjectUnmark()」

オブジェクトのマークを解除します。

「OCIObjectUnmarkByRef()」

オブジェクトへの参照の指定時に、オブジェクトのマークを解除します。

OCICacheUnmark()

用途

オブジェクト・キャッシュ内のすべての使用済オブジェクトのマークを解除します。

構文

sword OCICacheUnmark ( OCIEnv            *env,
OCIError          *err,
const OCISvcCtx   *svc );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキストです。

コメント

接続が指定された場合、この関数は、その接続内のすべての使用済オブジェクトのマークを解除します。それ以外の場合は、キャッシュ内のすべての使用済オブジェクトのマークを解除します。

関連項目:
オブジェクトのマーク解除の詳細は、「OCIObjectUnmark()」を参照してください。

関連関数

OCIObjectUnmark()

OCIObjectMarkDelete()

用途

スタンドアロン・インスタンスへのポインタの指定時に、そのインスタンスに削除マークを設定します。

構文

sword OCIObjectMarkDelete ( OCIEnv        *env,
OCIError      *err,
void          *instance );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

instance (IN)

インスタンスへのポインタです。これはスタンドアロン型にする必要があり、オブジェクトの場合は確保されることも必要です。

コメント

この関数は、スタンドアロン・インスタンスへのポインタを受け取り、そのオブジェクトに削除マークを設定します。オブジェクトは、次の規則に従って解放されます。

永続オブジェクト

オブジェクトに削除マークが設定されます。オブジェクトのメモリーは解放されません。オブジェクトは、そのオブジェクトがフラッシュされたときにサーバー内で削除されます。

一時オブジェクト

オブジェクトに削除マークが設定されます。オブジェクトのメモリーは解放されません。

値

この関数は、ただちに値を解放します。

関連関数

OCIObjectMarkDeleteByRef()、OCIObjectGetProperty()

OCIObjectMarkDeleteByRef()

用途

オブジェクトへの参照の指定時に、そのオブジェクトに削除マークを設定します。

構文

sword OCIObjectMarkDeleteByRef ( OCIEnv         *env,
OCIError       *err,
OCIRef         *object_ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object_ref (IN)

削除されるオブジェクトへの参照です。

コメント

この関数は、オブジェクトへの参照を受け取り、object_refによって指定されたオブジェクトに削除マークを設定します。オブジェクトはマーク付けされて、次のように解放されます。

永続オブジェクト

オブジェクトがロードされていない場合は、一時オブジェクトが作成され、それに対して削除マークが設定されます。それ以外の場合は、オブジェクトに削除マークが設定されます。

オブジェクトは、そのオブジェクトがフラッシュされたときにサーバー内で削除されます。

一時オブジェクト

オブジェクトに削除マークが設定されます。オブジェクトは、確保が解除されるまで解放されません。

関連関数

OCIObjectMarkDelete()、OCIObjectGetProperty()

OCIObjectMarkUpdate()

用途

永続オブジェクトに更新済(使用済)マークを設定します。

構文

sword OCIObjectMarkUpdate ( OCIEnv        *env,
OCIError      *err,
void          *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

永続オブジェクトへのポインタです。すでに確保されていることが必要です。

コメント

この関数は、永続オブジェクトに更新済(使用済)マークを設定します。オブジェクトの型に応じて、次の規則が適用されます。オブジェクトの使用済状態は、OCIObjectIsLocked()をコールすることによりチェックできます。

永続オブジェクト

この関数は、指定された永続オブジェクトに更新済マークを設定します。

オブジェクト・キャッシュがフラッシュされると、サーバーに永続オブジェクトを書き込みます。この関数は、オブジェクトのロックもフラッシュも行いません。削除済オブジェクトを更新しようとすると、エラーが発生します。

オブジェクトの更新済マークの設定とフラッシュが実行された後、オブジェクトがフラッシュ後も使用済になっている場合は、この関数を再度コールしてオブジェクトに更新済マークを設定する必要があります。

一時オブジェクト

この関数は、指定された一時オブジェクトに更新済マークを設定します。一時オブジェクトは、サーバーには書き込まれません。削除済オブジェクトを更新しようとすると、エラーが発生します。

値

この関数は、値に対しては何も行われません。

関連項目:
この関数の使用方法の詳細は、「オブジェクトのマークおよび変更のフラッシュ」を参照してください。

関連関数

OCIObjectPin()、OCIObjectGetProperty()、OCIObjectIsDirty()、OCIObjectUnmark()

OCIObjectUnmark()

用途

オブジェクトの使用済マークを解除します。

構文

sword OCIObjectUnmark ( OCIEnv       *env,
OCIError     *err,
void         *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

永続オブジェクトへのポインタです。確保されることが必要です。

コメント

永続オブジェクトと一時オブジェクト

この関数は、指定された永続オブジェクトの使用済マークを解除します。オブジェクトに対して行われた変更は、サーバーに書き込まれません。オブジェクトにロック・マークが設定されている場合は、ロックされたままになります。オブジェクトに対してこれまで実行された変更は、暗黙的に元に戻されません。

値

この関数は、値に対してコールしても何も影響がありません。

関連関数

OCIObjectUnmarkByRef()

OCIObjectUnmarkByRef()

用途

オブジェクトへのrefの指定時に、オブジェクトの使用済マークを解除します。

構文

sword OCIObjectUnmarkByRef ( OCIEnv      *env,
OCIError    *err,
OCIRef      *ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

ref (IN)

オブジェクトの参照です。確保されることが必要です。

コメント

この関数は、オブジェクトの使用済マークを解除します。オブジェクトへのrefを引数として取ることを除けば、この関数はOCIObjectUnmark()と同じです。

永続オブジェクトと一時オブジェクト

この関数は、指定された永続オブジェクトの使用済マークを解除します。オブジェクトに対して行われた変更は、サーバーに書き込まれません。オブジェクトにロック・マークが設定されている場合は、ロックされたままになります。オブジェクトに対してこれまで実行された変更は、暗黙的に元に戻されません。

値

この関数は、値に対しては何も行われません。

関連関数

OCIObjectUnmark()

OCIのオブジェクト・ステータス取得関数

表18-7は、この項で説明しているOCIのオブジェクト・ステータス取得関数を示しています。

表18-7 オブジェクト・ステータス取得関数

関数

用途

「OCIObjectExists()」

インスタンスの存在ステータスを取得します。

「OCIObjectGetProperty()」

特定のオブジェクト・プロパティのステータスを取得します。

「OCIObjectIsDirty()」

インスタンスの使用済ステータスを取得します。

「OCIObjectIsLocked()」

インスタンスのロック状態を取得します。

OCIObjectExists()

用途

スタンドアロン・インスタンスの存在メタ属性を戻します。

構文

sword OCIObjectExists ( OCIEnv         *env,
OCIError       *err,
void           *ins,
boolean        *exist );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

ins (IN)

インスタンスへのポインタです。オブジェクトの場合は、確保されることが必要です。

exist (OUT)

存在状況の戻り値です。

コメント

この関数は、インスタンスの存在メタ属性を戻します。インスタンスが値の場合、この関数は常にTRUEを戻します。インスタンスは、スタンドアロン型の永続または一時オブジェクトにしてください。

関連項目:
「オブジェクトのメタ属性」

関連関数

OCIObjectPin()

OCIObjectGetProperty()

用途

オブジェクトの指定されたプロパティを取り出します。

構文

sword OCIObjectGetProperty ( OCIEnv              *envh,
OCIError            *errh,
const void          *obj,
OCIObjectPropId     propertyId,
void                *property,
ub4                 *size );

パラメータ

envh (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

errh (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

obj (IN)

そのプロパティが戻されるオブジェクトです。

propertyId (IN)

プロパティを指定する識別子です。

property (OUT)

指定したプロパティがコピーされるバッファです。

size (IN/OUT)

入力の際は、コール元から渡されるプロパティ・バッファのサイズがこのパラメータによって指定されます。

出力の際は、戻されるプロパティのサイズがバイト単位でここに格納されます。このパラメータは、OCI_OBJECTPROP_SCHEMA、OCI_OBJECTPROP_TABLEなどの文字列型のプロパティのみに必要です。非文字列型のプロパティの場合は、サイズが固定しているため、このパラメータは無視されます。

コメント

この関数によりオブジェクトの指定されたプロパティが戻されます。このプロパティはpropertyIdで識別されます。プロパティの値はpropertyにコピーされ、文字列型プロパティの場合は、文字列のサイズがsizeによって戻されます。

オブジェクトは、その存続期間と参照可能性に基づいて永続、一時および値に分類されます。プロパティのいくつかは永続オブジェクトのみに適用され、また他のプロパティは永続オブジェクトと一時オブジェクト(の両方)に適用されます。指定したオブジェクトに適用されないプロパティを取得しようとすると、エラーが戻されます。このようなエラーを回避するには、最初にそのオブジェクト(のOCI_OBJECTPROP_LIFETIMEプロパティ)が永続、一時、値のどれであるかをチェックしてから、他のプロパティを適切に問い合せるようにします。

様々なプロパティIDとそれに対応するproperty引数の型を次に示します。

OCI_OBJECTPROP_LIFETIME

このプロパティによって、指定されたオブジェクトが永続オブジェクト、一時オブジェクト、または値のインスタンスかのいずれであるかが識別されます。property引数はOCIObjectLifetime型の変数へのポインタにしてください。可能な値は、次のとおりです。

- OCI_OBJECT_PERSISTENT

- OCI_OBJECT_TRANSIENT

- OCI_OBJECT_VALUE

OCI_OBJECTPROP_SCHEMA

このプロパティによって、オブジェクトが存在する表のスキーマ名が戻されます。指定されたオブジェクトが一時インスタンスまたは値を指し示している場合は、エラーが戻されます。スキーマ名の保持に入力バッファのサイズが足りない場合は、エラーが戻され、エラー・メッセージで必要なサイズが表示されます。成功した場合は、sizeによって、戻されたスキーマ名のサイズがバイト単位で戻されます。property引数はtext型の配列にして、コール元は、sizeをバイト単位で配列のサイズに設定する必要があります。

OCI_OBJECTPROP_TABLE

このプロパティによってそのオブジェクトが存在する表名が戻されます。指定されたオブジェクトが一時インスタンスまたは値を指し示している場合は、エラーが戻されます。表名の保持に入力バッファのサイズが足りない場合は、エラーが戻され、エラー・メッセージで必要なサイズが表示されます。成功した場合は、sizeによって、戻された表名のサイズがバイト単位で戻されます。property引数はtext型の配列にして、コール元は、sizeをバイト単位で配列のサイズに設定する必要があります。

OCI_OBJECTPROP_PIN_DURATION

このプロパティによってオブジェクトの確保継続時間が戻されます。指定されたオブジェクトが値のインスタンスを指し示している場合は、エラーが戻されます。property引数はOCIDuration型の変数へのポインタにしてください。次の値が有効です。

- OCI_DURATION_SESSION

- OCI_DURATION_TRANS

継続時間については、「オブジェクト継続時間」を参照してください。

OCI_OBJECTPROP_ALLOC_DURATION

このプロパティによって、オブジェクトの割当て時間が戻されます。property引数はOCIDuration型の変数へのポインタにしてください。次の値が有効です。

- OCI_DURATION_SESSION

- OCI_DURATION_TRANS

継続時間については、「オブジェクト継続時間」を参照してください。

OCI_OBJECTPROP_LOCK

このプロパティによってオブジェクトのロック状況が戻されます。可能なロック状況はOCILockOptによって列挙されます。指定されたオブジェクトが一時インスタンスまたは値インスタンスを指し示している場合は、エラーが戻されます。property引数はOCILockOpt型の変数へのポインタにしてください。オブジェクトのロック状況は、OCIObjectIsLocked()関数をコールしても取り出せます。次の値が有効です。

- OCI_LOCK_NONE (ロックなし)

- OCI_LOCK_X (排他ロック)

- OCI_LOCK_X_NOWAIT (NOWAITオプションを使用した排他ロック)

関連項目:
「NOWAITオプションを使用したロック」

OCI_OBJECTPROP_MARKSTATUS

これによって使用済ステータスが戻され、オブジェクトが新規のオブジェクトであるか、更新されたオブジェクトであるか、削除されたオブジェクトであるかが示されます。指定されたオブジェクトが一時インスタンスまたは値インスタンスを指し示している場合は、エラーが戻されます。property引数はOCIObjectMarkStatus型にしてください。次の値が有効です。

- OCI_OBJECT_NEW

- OCI_OBJECT_DELETED

- OCI_OBJECT_UPDATED

次のマクロを使用してマーク状態をテストすることが可能です。

- OCI_OBJECT_IS_UPDATED (flag)

- OCI_OBJECT_IS_DELETED (flag)

- OCI_OBJECT_IS_NEW (flag)

- OCI_OBJECT_IS_DIRTY (flag)

OCI_OBJECTPROP_VIEW

このプロパティによって指定されたオブジェクトがビュー・オブジェクトであるかどうかが識別されます。戻されたプロパティ値がTRUEの場合、そのオブジェクトはビューであり、そうでない場合はビューではありません。指定されたオブジェクトが一時インスタンスまたは値インスタンスを指し示している場合は、エラーが戻されます。property引数はboolean型にしてください。

関連関数

OCIObjectLock()、OCIObjectMarkDelete()、OCIObjectMarkUpdate()、OCIObjectPin()、OCIObjectPin()

OCIObjectIsDirty()

用途

オブジェクトに使用済とマークが付けられているかどうかを確認します。

構文

sword OCIObjectIsDirty ( OCIEnv       *env,
OCIError     *err,
void         *ins,
boolean      *dirty );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

ins (IN)

インスタンスへのポインタです。

dirty (OUT)

使用済ステータスに対する値を戻します。

コメント

この関数に渡すインスタンスはスタンドアロンにしてください。インスタンスがオブジェクトの場合、そのインスタンスは確保されることが必要です。

この関数は、インスタンスの使用済ステータスを戻します。インスタンスが値の場合、この関数は使用済ステータスに対して常にFALSEを戻します。

関連関数

OCIObjectMarkUpdate()、OCIObjectGetProperty()

OCIObjectIsLocked()

用途

オブジェクトのロック状況を取得します。

構文

sword OCIObjectIsLocked ( OCIEnv       *env,
OCIError     *err,
void         *ins,
boolean      *lock );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

ins (IN)

インスタンスへのポインタです。インスタンスはスタンドアロンであることが必要で、インスタンスがオブジェクトの場合は確保されることも必要です。

lock (OUT)

ロック状況に対する値を戻します。

コメント

この関数は、インスタンスのロック状況を戻します。インスタンスが値の場合、この関数は常にFALSEを戻します。

関連関数

OCIObjectLock()、OCIObjectGetProperty()

その他のOCIオブジェクト関数

表18-8は、この項で説明しているその他のオブジェクト関数を示しています。

表18-8 その他のオブジェクト関数

関数

用途

「OCIObjectCopy()」

1つのインスタンスを別のインスタンスにコピーします。

「OCIObjectGetAttr()」

オブジェクト属性を取得します。

「OCIObjectGetInd()」

インスタンスのNULLインジケータ構造体を取得します。

「OCIObjectGetObjectRef()」

指定のオブジェクトへの参照を戻します。

「OCIObjectGetTypeRef()」

インスタンスのTDOへの参照を取得します。

「OCIObjectLock()」

永続オブジェクトをロックします。

「OCIObjectLockNoWait()」

永続オブジェクトをロックしますが、ロック待機は行いません。

「OCIObjectNew()」

新規インスタンスを作成します。

「OCIObjectSetAttr()」

オブジェクト属性を設定します。

OCIObjectCopy()

用途

ソース・インスタンスを宛先インスタンスにコピーします。

構文

sword OCIObjectCopy ( OCIEnv              *env,
OCIError            *err,
const OCISvcCtx     *svc,
void                *source,
void                *null_source,
void                *target,
void                *null_target,
OCIType             *tdo,
OCIDuration         duration,
ub1                 option );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキスト・ハンドルで、コピー処理が発生するサービス・コンテキストを指定します。

source (IN)

ソース・インスタンスへのポインタです。ポインタがオブジェクトの場合は、確保する必要があります。

関連項目:
「OCIObjectPin()」

null_source (IN)

ソース・オブジェクトのNULLインジケータ構造体へのポインタです。

target (IN)

ターゲット・インスタンスへのポインタです。ポインタがオブジェクトの場合は、確保する必要があります。

null_target (IN)

ターゲット・オブジェクトのNULLインジケータ構造体へのポインタです。

tdo (IN)

ソースとターゲットの両方に対するTDOです。OCIDescribeAny()で取り出せます。

duration (IN)

ターゲット・メモリーの割当て時間です。

option (IN)

このパラメータは使用されていません。0 (ゼロ)またはOCI_DEFAULTを渡します。

コメント

この関数は、sourceインスタンスの内容をtargetインスタンスにコピーします。この関数は、次の情報すべてがコピーされるディープ・コピーを実行します。

- すべての最上位属性(後述の例外参照)

- 最上位属性から到達可能な(ソースの)すべての2次メモリー

- インスタンスのNULL構造体

メモリーは、durationパラメータに指定された継続時間の間、割り当てられます。

次のデータ項目はコピーされません。

- optionパラメータにオプションOCI_OBJECTCOPY_NOREFが指定されている場合、ソース内のすべての参照はコピーされません。ターゲット内の参照はNULLに設定されます。

- 属性が内部LOBの場合は、ソース・オブジェクトのLOBロケータのみがコピーされます。LOBデータのコピーはOCIObjectFlush()がコールされるまで作成されません。ターゲット・オブジェクトがフラッシュされるまで、ソースとターゲットのロケータはともに同じLOB値を参照します。

ターゲットまたはターゲットの格納インスタンスは、作成されている必要があります。これは、ターゲット・オブジェクトの存在の有無に応じて、OCIObjectNew()またはOCIObjectPin()を使用して実行できます。

sourceインスタンスとtargetインスタンスは、同じ型にしてください。ソースとターゲットが別々のデータベースに置かれている場合は、両方のデータベースに同じ型が存在することが必要です。

関連関数

OCIObjectPin()

OCIObjectGetAttr()

用途

オブジェクト属性を取り出します。

構文

sword OCIObjectGetAttr ( OCIEnv             *env,
OCIError           *err,
void               *instance,
void               *null_struct,
struct OCIType     *tdo,
const OraText      **names,
const ub4          *lengths,
const ub4          name_count,
const ub4          *indexes,
const ub4          index_count,
OCIInd             *attr_null_status,
void               **attr_null_struct,
void               **attr_value,
struct OCIType     **attr_tdo );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

instance (IN)

オブジェクトへのポインタです。

null_struct (IN)

オブジェクトまたは配列のNULLインジケータ構造体です。

tdo (IN)

型記述子オブジェクト(TDO)へのポインタです。

names (IN)

属性名の配列です。パス式に属性名を指定します。

lengths (IN)

属性名長(バイト単位)の配列です。

name_count (IN)

配列namesの要素数です。

indexes (IN) [オプション]

現行ではサポートされていません。(ub4 *)0で渡します。

index_count (IN) [オプション]

現行ではサポートされていません。(ub4)0で渡します。

attr_null_status (OUT)

属性タイプが基本形の場合、属性はNULLステータスです。

attr_null_struct (OUT)

このパラメータは、オブジェクト属性および不透明な属性に対してのみ指定され、コレクションに対しては指定されません。コレクションの場合(OCICollGetElemを渡します)、attr_null_structはNULLです。また、コレクションの場合、このパラメータは全コレクションがNULLであるかどうかを示します。

attr_value (OUT)

属性値へのポインタです。

attr_tdo (OUT)

属性のTDOへのポインタです。

コメント

この関数は、オブジェクトまたは配列から値を取得します。パラメータinstanceがオブジェクトを指し示している場合は、パス式によってそのオブジェクトの属性の位置が指定されます。オブジェクトが確保され、戻された値はオブジェクトの確保が解除されるまで有効であるとみなされます。

attr_null_statusとattr_null_structの両方がともにNULLである場合、NULL情報は戻されません。

関連関数

OCIObjectSetAttr()

OCIObjectGetInd()

用途

スタンドアロン・インスタンスのNULLインジケータ構造体を取得します。

構文

sword OCIObjectGetInd ( OCIEnv        *env,
OCIError      *err,
void          *instance,
void          **null_struct );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

instance (IN)

NULLインジケータ構造体が取り出されるインスタンスへのポインタです。インスタンスは、スタンドアロン型にしてください。instanceがオブジェクトの場合は、事前に確保されることが必要です。

null_struct (OUT)

インスタンスのNULLインジケータ構造体です。

関連項目:
NULLインジケータ構造体の詳細とその使用例は、「NULLインジケータ構造体」を参照してください。

コメント

なし。

関連関数

OCIObjectPin()

OCIObjectGetObjectRef()

用途

指定された永続オブジェクトへの参照を戻します。

構文

sword OCIObjectGetObjectRef ( OCIEnv        *env,
OCIError      *err,
void          *object,
OCIRef        *object_ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

永続オブジェクトへのポインタです。事前に確保されることが必要です。

object_ref (OUT)

objectに指定されているオブジェクトへの参照です。参照は、事前に割り当てられることが必要です。これは、OCIObjectNew()によって実行できます。

コメント

この関数は、オブジェクトへのポインタの指定時に、特定の永続オブジェクトへの参照を戻します。(オブジェクトではなく)値をこの関数に渡すと、エラーになります。

関連項目:
「オブジェクトのメタ属性」

関連関数

OCIObjectPin()

OCIObjectGetTypeRef()

用途

スタンドアロン・インスタンスの型記述子オブジェクト(TDO)への参照を戻します。

構文

sword OCIObjectGetTypeRef ( OCIEnv        *env,
OCIError      *err,
void          *instance,
OCIRef        *type_ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

instance (IN)

スタンドアロン・インスタンスへのポインタです。これはスタンドアロン型であることが必要で、インスタンスがオブジェクトの場合は、事前に確保されていることも必要です。

type_ref (OUT)

オブジェクトの型に対する参照です。参照は、事前に割り当てられることが必要です。これは、OCIObjectNew()によって実行できます。

コメント

なし。

関連関数

OCIObjectPin()

OCIObjectLock()

用途

永続オブジェクトをサーバー側でロックします。

構文

sword OCIObjectLock ( OCIEnv        *env,
OCIError      *err,
void          *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

ロックされている永続オブジェクトへのポインタです。事前に確保されることが必要です。

コメント

この関数は、一時オブジェクトと値ではエラーを戻します。また、オブジェクトが存在しない場合にもエラーを戻します。

関連項目:
「更新するためのオブジェクトのロック」

関連関数

OCIObjectPin()、OCIObjectIsLocked()、OCIObjectGetProperty()、OCIObjectLockNoWait()

OCIObjectLockNoWait()

用途

永続オブジェクトをサーバー側でロックしますが、ロック待機は行いません。ロックが使用不可能である場合は、エラーを戻します。

構文

sword OCIObjectLockNoWait ( OCIEnv        *env,
OCIError      *err,
void          *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

ロックされている永続オブジェクトへのポインタです。事前に確保されることが必要です。

コメント

この関数は、永続オブジェクトをサーバーでロックします。ただし、OCIObjectLock()とは異なり、この関数は別のユーザーがオブジェクトでロックを保持している場合でも待機せず、オブジェクトが現在別のユーザーによってロックされている場合はエラーが戻されます。この関数は、一時オブジェクトと値、または存在しない永続オブジェクトに対して、エラーを戻します。

オブジェクトのロックは、トランザクションの終了時に解除されます。

関連項目:
「更新するためのオブジェクトのロック」

OCIObjectLockNoWait()は、次の値を戻します。

- OCI_INVALID_HANDLE (環境ハンドルまたはエラー・ハンドルがNULLである場合)

- OCI_SUCCESS (操作が成功した場合)

- OCI_ERROR (操作が失敗した場合)

関連関数

OCIObjectPin()、OCIObjectIsLocked()、OCIObjectGetProperty()、OCIObjectLock()

OCIObjectNew()

用途

スタンドアロン・インスタンスを作成します。

構文

sword OCIObjectNew ( OCIEnv            *env,
OCIError          *err,
const OCISvcCtx   *svc,
OCITypeCode       typecode,
OCIType           *tdo,
void              *table,
OCIDuration       duration,
boolean           value,
void              **instance );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。ハンドルはUTF-16 (Unicode)モードで初期化することができます。OCIEnvNlsCreate()の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・ハンドルです。

typecode (IN)

インスタンスの型のコードです。

関連項目:
「型コード」

tdo (IN) [オプション]

記述子オブジェクト型へのポインタです。TDOは、作成されるインスタンスの型を記述します。TDOの取得の詳細は、「OCITypeByName()」を参照してください。TDOは、オブジェクトやコレクションなどの名前付き型の作成に必要です。

table (IN) [オプション]

表をサーバーに指定している表オブジェクトへのポインタです。表が指定されていない場合、このパラメータはNULLに設定されます。作成するインスタンスの種類(永続、一時、値)を判断するための表オブジェクトとTDOの使用方法は、次の説明を参照してください。表オブジェクトの取出しについては、「OCIObjectPinTable()」も参照してください。

duration (IN)

これはオーバーロードされたパラメータです。このパラメータの使用方法は、作成されるインスタンスの種類によって決まります。詳細は、表18-9を参照してください。

- インスタンスの永続オブジェクト型の場合、このパラメータは確保継続時間を指定します。

- インスタンスの一時オブジェクト型の場合、このパラメータは割当て時間および確保継続時間を指定します。

- インスタンスの値型の場合、このパラメータは割当て時間を指定します。

value (IN)

作成されたオブジェクトが値かどうかを指定します。TRUEの場合は、値が作成されます。それ以外の場合は、参照可能オブジェクトが作成されます。インスタンスがオブジェクトではない場合、このパラメータは無視されます。

instance (OUT)

新規に作成されたインスタンスのアドレスです。環境ハンドルが適切に設定され、オブジェクトがOCIStringの場合、インスタンスはUTF-16 (Unicode)の文字列であることが可能です。

コメント

この関数は、型コードまたはTDOによって指定された型のインスタンスを新たに作成します。型コードによって、作成するオブジェクトがOCIStringであることが示されている場合は、Unicodeバッファを使用してOCIStringオブジェクトを作成できます。

関連項目:
「型コード」

表18-9は、パラメータtypecode (またはtdo)、valueおよびtableに基づいて、異なる種類のインスタンスが作成されることを示しています。

表18-9 作成されるインスタンス

インスタンスの型

Table != NULL

Table == NULL

オブジェクト型(value＝TRUE)

値

値

オブジェクト型(value＝FALSE)

永続オブジェクト

一時オブジェクト

組込み型

値

値

コレクション型

値

値

この関数は、インスタンスのトップレベルのメモリー・チャンクを割り当てます。トップレベルのメモリー内の属性は初期化されます。つまり、VARCHAR2の属性は、長さが0 (ゼロ)のOCIStringに初期化されます。インスタンスがオブジェクトである場合、オブジェクトは存在するとマークが付けられますが、アトミックにはNULLです。

関連項目:
オブジェクト・ビューまたはユーザー作成OIDに基づいた新規オブジェクト作成の詳細は、「オブジェクト・ビューおよび主キー・ベースのOIDを備えたオブジェクト表に基づくオブジェクトの作成」を参照してください。

永続オブジェクト

オブジェクトに使用済および存在マークが設定されます。オブジェクトの割当て時間はセッションです。オブジェクトは、durationパラメータに指定された確保継続時間の間、確保されます。永続オブジェクトが作成されても、そのオブジェクトがサーバーにフラッシュされるまで、データベース表へのエントリは行われません。

一時オブジェクト

オブジェクトが確保されます。割当て時間および確保継続時間は、durationパラメータによって指定されます。

値

割当て時間は、durationパラメータによって指定されます。

新規オブジェクトの属性値

デフォルトでは、新規作成されたオブジェクトのすべての属性に NULL値があります。属性データを初期化した後で、対応する各属性のNULLステータスをNULL以外に変更する必要があります。

オブジェクトの作成時に、属性をNULL以外の値に設定できます。これは、OCIAttrSet()を使用して環境ハンドルのOCI_ATTR_OBJECT_NEWNOTNULL属性をTRUEに設定することによって実行できます。その後、この属性をFALSEに設定すると、このモードを無効にできます。OCI_ATTR_OBJECT_NEWNOTNULLがTRUEに設定されている場合は、OCIObjectNew()によってNULL以外のオブジェクトが作成されます。

関連項目:
「新規オブジェクトの属性値」

LOB属性を持つオブジェクト

オブジェクトに内部LOB属性がある場合、LOBはEmpty値に設定されます。LOBへのデータ書込みを開始する前には、そのオブジェクトに使用済マークを設定して(オブジェクトを表に挿入するために)フラッシュし、再確保する必要があります。作成後にオブジェクトを確保するときは、新しく更新されたLOBロケータをサーバーから取り出すために、OCI_PIN_LATEST PINオプションを使用する必要があります。

オブジェクトに外部LOB属性(FILE)がある場合は、FILEロケータが割り当てられますが、初期化はされません。オブジェクトをデータベースにフラッシュする前に、OCILobFileSetName()をコールしてFILE属性を初期化する必要があります。最初にディレクトリ・オブジェクトおよびファイル名を指定せずにFILEのINSERTまたはUPDATE操作を実行すると、エラーが発生します。ファイル名を設定すると、ユーザーはFILEから読取りを開始できるようになります。

注意:
Oracle Databaseでは、バイナリ・ファイル(BFILE)のみをサポートしています。

関連関数

OCIObjectPinTable()、OCIObjectFree()

OCIObjectSetAttr()

用途

オブジェクト属性を設定します。

構文

sword OCIObjectSetAttr ( OCIEnv              *env,
OCIError            *err,
void                *instance,
void                *null_struct,
struct OCIType      *tdo,
const OraText       **names,
const ub4           *lengths,
const ub4           name_count,
const ub4           *indexes,
const ub4           index_count,
const OCIInd        *attr_null_status,
const void          *attr_null_struct,
const void          *attr_value );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

instance (IN)

オブジェクト・インスタンスへのポインタです。

null_struct (IN)

オブジェクト・インスタンスまたは配列のNULLインジケータ構造体です。

tdo (IN)

TDOへのポインタです。

names (IN)

属性名の配列です。パス式に属性名を指定します。

lengths (IN)

属性名長(バイト単位)の配列です。

name_count (IN)

配列namesの要素数です。

indexes (IN) [オプション]

現行ではサポートされていません。(ub4 *)0で渡します。

index_count (IN) [オプション]

現行ではサポートされていません。(ub4)0で渡します。

attr_null_status (IN)

属性タイプが基本形の場合、属性はNULLステータスです。

attr_null_struct (IN)

オブジェクトまたはコレクション属性のNULLインジケータ構造体です。

attr_value (IN)

属性値へのポインタです。

コメント

この関数は、所定のオブジェクトの属性に所定の値を設定します。属性の位置は名前配列および索引配列であるパス式で指定されます。

例

パス式stanford.cs.stu[5].addrの場合、配列は次のようになります。

names = {"stanford", "cs", "stu", "addr"}

lengths = {8, 2, 3, 4}

indexes = {5}

関連関数

OCIObjectGetAttr()

OCIの確保関数、確保解除関数および解放関数

表18-10は、この項で説明しているOCIの確保関数、確保解除関数および解放関数を示しています。

表18-10 確保関数、確保解除関数および解放関数

関数

用途

「OCICacheFree()」

キャッシュ内のオブジェクトを解放します。

「OCICacheUnpin()」

キャッシュまたは接続で永続オブジェクトの確保を解除します。

「OCIObjectArrayPin()」

参照の配列を確保します。

「OCIObjectFree()」

割当て済のオブジェクトを解放します。

「OCIObjectPin()」

オブジェクトを確保します。

「OCIObjectPinCountReset()」

オブジェクトの確保を解除して確保カウントを0 (ゼロ)にします。

「OCIObjectPinTable()」

継続時間を指定して表オブジェクトを確保します。

「OCIObjectUnpin()」

オブジェクトの確保を解除します。

OCICacheFree()

用途

指定された接続に対してキャッシュ内のオブジェクトと値をすべて解放します。

構文

sword OCICacheFree ( OCIEnv              *env,
OCIError            *err,
const OCISvcCtx     *svc );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキストです。

コメント

接続が指定された場合、この関数は、その接続に対して割り当てられている永続オブジェクト、一時オブジェクトおよび値を解放します。それ以外の場合は、オブジェクト・キャッシュ内の永続オブジェクト、一時オブジェクトおよび値をすべて解放します。オブジェクトは、確保カウントに関係なく解放されます。

関連項目:
インスタンスの解放の詳細は、「OCIObjectFree()」を参照してください。

関連関数

OCIObjectFree()

OCICacheUnpin()

用途

永続オブジェクトの確保を解除します。

構文

sword OCICacheUnpin ( OCIEnv              *env,
OCIError            *err,
const OCISvcCtx     *svc );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキスト・ハンドルです。指定された接続のオブジェクトの確保が解除されます。

コメント

この関数は、所定の接続に対するすべての永続オブジェクトの確保を完全に解除します。オブジェクトの確保カウントは0 (ゼロ)にリセットされます。

関連項目:

- 「オブジェクトの確保」

- 「確保カウントおよび確保解除」

関連関数

OCIObjectUnpin()

OCIObjectArrayPin()

用途

参照配列を確保します。

構文

sword OCIObjectArrayPin ( OCIEnv            *env,
OCIError          *err,
OCIRef            **ref_array,
ub4               array_size,
OCIComplexObject  **cor_array,
ub4               cor_array_size,
OCIPinOpt         pin_option,
OCIDuration       pin_duration,
OCILockOpt        lock,
void              **obj_array,
ub4               *pos );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

ref_array (IN)

確保される参照の配列です。

array_size (IN)

参照の配列にある要素の数です。

cor_array

確保されるオブジェクトに対応するCORハンドルの配列です。

cor_array_size

cor_arrayにある要素の数です。

pin_option (IN)

PINオプションです。

関連項目:
「OCIObjectPin()」

pin_duration (IN)

確保継続時間です。「OCIObjectPin()」を参照してください。

lock (IN)

ロック・オプションです。「OCIObjectPin()」を参照してください。

obj_array (OUT)

この引数がNULLでない場合は、確保されたオブジェクトをこの配列に戻します。void *型の要素をこの配列に割り当てる必要があります。この配列のサイズはarray_sizeと同じです。

pos (OUT)

エラーが発生すると、この引数によってエラーの原因となった要素が示されます。この引数には、ref_arrayの第1要素に対して、1が設定されます。

コメント

確保されたすべてのオブジェクトが1回のネットワーク・ラウンドトリップでデータベースから取り出されます。ユーザーが出力配列(obj_array)を指定した場合は、確保されたオブジェクトのアドレスが配列内の各要素に割り当てられます。

関連関数

OCIObjectPin()

OCIObjectFree()

用途

オブジェクト・インスタンスの解放と確保解除を行います。

構文

sword OCIObjectFree ( OCIEnv          *env,
OCIError        *err,
void            *instance,
ub2             flags );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

instance (IN)

スタンドアロン・インスタンスへのポインタです。オブジェクトの場合は、確保されることが必要です。

flags (IN)

OCI_OBJECTFREE_FORCEが渡された場合は、オブジェクトが確保済または使用済である場合も解放します。OCI_OBJECTFREE_NONULLが渡されると、NULLインジケータ構造体は解放されません。

コメント

この関数は、オブジェクト・インスタンスのために割り当てられたすべてのメモリーの割当てを解除します(NULLインジケータ構造体も含まれます)。インスタンスの型に応じて、次の規則が適用されます。

永続オブジェクト

この関数は、フラッシュされていない使用済永続オブジェクトをクライアントが解放しようとした場合、エラーを戻します。クライアントは、永続オブジェクトをフラッシュするか、マークを解除するか、またはflagsパラメータにOCI_OBJECTFREE_FORCEを設定する必要があります。

この関数は、オブジェクトの確保を完全に解除できるかどうかを調べるためにOCIObjectUnpin()を1回コールします。成功した場合は、関数の残りを続行してオブジェクトを解放します。失敗した場合は、flagsパラメータにOCI_OBJECTFREE_FORCEが設定されていないかぎり、エラーが戻ります。

メモリー内の永続オブジェクトを解放しても、そのオブジェクトのサーバー側での永続状態が変化することはありません。たとえば、オブジェクトが解放された後でも、そのオブジェクトはロックされたままになります。

一時オブジェクト

この関数は、オブジェクトの確保を完全に解除できるかどうかを調べるためにOCIObjectUnpin()を1回コールします。成功した場合は、関数の残りを続行してオブジェクトを解放します。失敗した場合は、flagsパラメータにOCI_OBJECTFREE_FORCEが設定されていないかぎり、エラーが戻ります。

値

オブジェクトのメモリーが即時に解放されます。

関連関数

OCICacheFree()

OCIObjectPin()

用途

参照可能オブジェクトを確保します。

構文

sword OCIObjectPin ( OCIEnv              *env,
OCIError            *err,
OCIRef              *object_ref,
OCIComplexObject    *corhdl,
OCIPinOpt           pin_option,
OCIDuration         pin_duration,
OCILockOpt          lock_option,
void                **object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object_ref (IN)

オブジェクトに対する参照です。

corhdl (IN)

複合オブジェクト検索に対するハンドルです。

pin_option (IN)

取り出されるオブジェクトのコピーの指定に使用します。

pin_duration (IN)

オブジェクトがクライアントによってアクセスされる継続時間です。オブジェクトの確保は、確保継続時間の終了時点で暗黙的に解除されます。OCI_DURATION_NULLが渡された場合、オブジェクトがすでにキャッシュ内にロードされているときは、確保の促進はありません。オブジェクトが未ロードの場合、OCI_DURATION_NULLに対して、確保継続時間にはOCI_DURATION_DEFAULTが設定されます。

lock_option (IN)

ロック・オプション(たとえば、排他的ロック)です。ロック・オプションが指定された場合、オブジェクトはサーバー内でロックされます。オブジェクトのロック状況は、OCIObjectIsLocked()関数をコールしても取り出せます。次の値が有効です。

- OCI_LOCK_NONE (ロックなし)

- OCI_LOCK_X (排他ロック)

- OCI_LOCK_X_NOWAIT (NOWAITオプションを使用した排他ロック)

関連項目:
「NOWAITオプションを使用したロック」

object (OUT)

確保されたオブジェクトへのポインタです。

コメント

この関数は、オブジェクト参照の指定時に参照可能オブジェクト・インスタンスを確保します。この確保のプロセスで、次の2つの目的を達成します。

- 参照を指定されたオブジェクトの場所を特定します。これは、オブジェクト・キャッシュ内のオブジェクトを追跡し記録するオブジェクト・キャッシュによって実行されます。

- 永続オブジェクトは使用中のため、エージ・アウトが不可であることをオブジェクト・キャッシュに通知します。永続オブジェクトは必要に応じていつでもサーバーからロードできるため、割当て時間の経過前であっても、確保が完全に解除された永続オブジェクトを解放する(エージ・アウトさせる)ことができる場合は、利用できるメモリーを増やすことができます。オブジェクトは複数回確保できます。確保されたオブジェクトは、確保が完全に解除されるまでメモリー内に残ります。

関連項目:
「OCIObjectUnpin()」

永続オブジェクト

永続オブジェクトを確保したときにそのオブジェクトがキャッシュ内に存在しない場合は、永続ストアからフェッチされます。オブジェクトの割当て時間はセッションです。オブジェクトがキャッシュ内に存在する場合は、そのオブジェクトがクライアントに戻されます。ロック・オプションが指定されている場合、オブジェクトは、サーバー内でロックされます。

この関数は存在しないオブジェクトに対してはエラーを戻します。

確保オプションを使用して、取り出されるオブジェクトのコピーを指定します。

- pin_optionがOCI_PIN_ANY (任意のオブジェクトを確保)であり、オブジェクトがすでにオブジェクト・キャッシュ内にある場合は、そのオブジェクトが戻されます。それ以外の場合、オブジェクトはデータベースから取り出されます。これは、OCI_PIN_LATESTである場合と同じです。このオプションは、クライアントがセッションのデータに排他的アクセス権を持っていることを認識しているときに役立ちます。

- pin_optionがOCI_PIN_LATEST (最新のオブジェクトを確保)の場合は、オブジェクトがロックされていなければデータベースから取り出されます。オブジェクトがキャッシュ処理されている場合は、最新バージョンによってリフレッシュされます。リフレッシュの詳細は、「OCIObjectRefresh()」を参照してください。オブジェクトがすでにキャッシュ内に確保され、使用済マークが設定されている場合は、そのオブジェクトへのポインタが戻ります。オブジェクトは、データベースからリフレッシュされません。

- pin_optionがOCI_PIN_RECENT (最近のオブジェクトを確保)であり、オプションがカレント・トランザクションでキャッシュにロードされた場合は、そのオブジェクトが戻されます。オブジェクトがカレント・トランザクション中にロードされていない場合、オブジェクトはサーバーからリフレッシュされます。

一時オブジェクト

一時オブジェクトがすでに解放されている場合、この関数はエラーを戻します。ロック・オプションに排他ロックが指定されている場合は、エラーを戻しません。

関連関数

OCIObjectUnpin()、OCIObjectPinCountReset()

OCIObjectPinCountReset()

用途

オブジェクトの確保を完全に解除し、その確保カウントを0 (ゼロ)に設定します。

構文

sword OCIObjectPinCountReset ( OCIEnv        *env,
OCIError      *err,
void          *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

オブジェクトへのポインタで、すでに確保されていることが必要です。

コメント

この関数は、オブジェクトの確保を完全に解除し、その確保カウントに0 (ゼロ)を設定します。オブジェクトの確保が完全に解除されると、OCIは、そのオブジェクトをエラーなしにいつでも暗黙的に解放します。オブジェクトの型に応じて、次の規則が適用されます。

永続オブジェクト

永続オブジェクトの確保が完全に解除された場合、そのオブジェクトはエージ・アウトの対象になります。オブジェクトのメモリーは、オブジェクトのエージ・アウトが終了したときに解放されます。エージ・アウトは、メモリーを最大限に利用するために行われます。使用済オブジェクトは、フラッシュされるまでエージ・アウトされません。

一時オブジェクト

オブジェクトの確保カウントが減分されます。一時オブジェクトは、その割当て時間の終了時、またはOCIObjectFree()をコールすることで明示的に解放された場合にかぎり解放できます。

値

この関数は値に対してはエラーを戻します。

関連項目:
「確保カウントおよび確保解除」

関連関数

OCIObjectPin()、OCIObjectUnpin()

OCIObjectPinTable()

用途

表オブジェクトを指定された継続時間の間、確保します。

構文

sword OCIObjectPinTable ( OCIEnv             *env,
OCIError           *err,
const OCISvcCtx    *svc,
const OraText      *schema_name,
ub4                s_n_length,
const OraText      *object_name,
ub4                o_n_length,
const OCIRef       *scope_obj_ref,
OCIDuration        pin_duration,
void               **object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキスト・ハンドルです。

schema_name (IN) [オプション]

表のスキーマ名です。

s_n_length (IN) [オプション]

schema_nameに示されているスキーマ名の長さ(バイト単位)です。

object_name (IN)

表の名前です。

o_n_length (IN)

object_nameに示されている表名の長さ(バイト単位)です。

scope_obj_ref (IN) [オプション]

スコーピング・オブジェクトの参照です。

pin_duration (IN)

確保継続時間です。

関連項目:
「OCIObjectPin()」

object (OUT)

確保された表オブジェクトです。

コメント

この関数は、表オブジェクトを指定の確保継続時間の間、確保します。クライアントは、OCIObjectUnpin()をコールしてこのオブジェクトの確保を解除できます。

このコールによって確保される表オブジェクトは、スタンドアロン型の永続オブジェクトを作成するために、パラメータとしてOCIObjectNew()に渡すことができます。

注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。

関連関数

OCIObjectPin()、OCIObjectUnpin()

OCIObjectUnpin()

用途

オブジェクトの確保を解除します。

構文

sword OCIObjectUnpin ( OCIEnv        *env,
OCIError      *err,
void          *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

オブジェクトへのポインタで、すでに確保されていることが必要です。

コメント

各オブジェクトには、そのオブジェクトが確保されるたびに増分される確保カウントが対応付けられています。オブジェクトの確保カウントが0 (ゼロ)になったとき、そのオブジェクトの確保は完全に解除されたことになります。確保が解除されたオブジェクトは、OCIによって、エラーなしにいつでも暗黙的に解放されます。

この関数は、オブジェクトの確保を解除します。次のいずれかがTRUEであるとき、オブジェクトの確保は完全に解除されています。

- オブジェクトの確保カウントが0 (ゼロ)に達しています(つまり、全部でn回確保された後に全部でn回確保解除されています)。

- オブジェクトの確保継続時間が終了しています。

- オブジェクトに対してOCIObjectPinCountReset()関数がコールされました。

オブジェクトの確保が完全に解除されると、OCIは、そのオブジェクトをエラーなしにいつでも暗黙的に解放します。

確保解除しているオブジェクトの型に応じて、次の規則が適用されます。

永続オブジェクト

永続オブジェクトの確保が完全に解除された場合、そのオブジェクトはエージ・アウトの対象になります。オブジェクトのメモリーは、オブジェクトのエージ・アウトが終了したときに解放されます。エージ・アウトは、メモリーを最大限に利用するために行われます。使用済オブジェクトは、フラッシュされるまでエージ・アウトされません。

一時オブジェクト

オブジェクトの確保カウントが減分されます。一時オブジェクトは、その割当て時間の終了時、またはOCIObjectFree()をコールすることで明示的に削除したときにかぎり解放できます。

値

この関数は値に対してはエラーを戻します。

関連関数

OCIObjectPin()、OCIObjectPinCountReset()

OCIの型情報アクセッサ関数

表18-11は、この項で説明しているOCIの型情報アクセッサ関数を示しています。

表18-11 型情報アクセッサ関数

関数

用途

「OCITypeArrayByName()」

オブジェクト名配列の指定時にTDO配列を取得します。

「OCITypeArrayByRef()」

オブジェクト参照配列の指定時にTDO配列を取得します。

「OCITypeByName()」

オブジェクト名の指定時にTDOを取得します。

「OCITypeByRef()」

オブジェクト参照の指定時にTDOを取得します。

OCITypeArrayByName()

用途

名前配列の指定時に型配列を取得します。

構文

sword OCITypeArrayByName ( OCIEnv             *envhp,
OCIError           *errhp,
const OCISvcCtx    *svc,
ub4                array_len,
const OraText      *schema_name[],
ub4                s_length[],
const OraText      *type_name[],
ub4                t_length[],
const OraText      *version_name[],
ub4                v_length[],
OCIDuration        pin_duration,
OCITypeGetOpt      get_option,
OCIType            *tdo[] );

パラメータ

envhp (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・ハンドルです。

array_len (IN)

取り出されるschema_name、type_nameまたはversion_nameエントリの数です。

schema_name (IN、オプション)

取得される型に関連付けられているスキーマ名の配列です。この配列を指定する場合は、array_len個の要素が必要です。0 (ゼロ)を指定すると、デフォルト・スキーマが想定されます。指定しない場合、schema_nameの要素数をarray_lenにする必要があります。1つ以上のエントリでデフォルト・スキーマが必要であることを示す場合は、これらのエントリに対してゼロ(0)を指定します。

s_length (IN)

schema_name配列の対応するschema_nameエントリの長さに対応する各エントリを持つschema_nameの配列の長さです(バイト単位)。配列の要素数はarray_lenまたは0 (ゼロ) (schema_nameが指定されていない場合)のいずれかにする必要があります。

type_name (IN)

取り出される型の名前の配列です。array_len個の要素が必要です。

t_length (IN)

type_name配列にある型名のバイト単位の長さの配列です。

version_name (IN)

バージョン名は無視され、要求された型の最新バージョンが戻されます。リリース9.0以上は型の変更が可能であったため、それより前のリリースのアプリケーションで変更された型にアクセスすると、エラーが発生します。この場合は、最新の型定義を使用して、アプリケーションの変更、再コンパイルおよび再リンクを行う必要があります。

取り出される型に対応するバージョン名の配列です。この配列は、最新バージョンの取出しを示す0 (ゼロ)にするか、またはarray_len個の要素が必要です。

0 (ゼロ)を指定すると、最新のバージョンが想定されます。指定しない場合、要素数をarray_lenにする必要があります。1つ以上のエントリで最新のバージョンが必要であることを示す場合は、これらのエントリに対してゼロ(0)を指定します。

v_length (IN)

version_name配列にあるバージョン名のバイト単位の長さの配列です。

pin_duration (IN)

取り出された型用の確保継続時間(たとえば、カレント・トランザクションの終わりまで)です。各オプションの説明は、oro.hを参照してください。

get_option (IN)

型をロードする場合のオプションです。値は次の2つのうちのいずれかです。

- OCI_TYPEGET_HEADER (ヘッダーのみがロードされる)

- OCI_TYPEGET_ALL (TDOおよびすべてのADOとMDOがロードされる)

tdo (OUT)

オブジェクト・キャッシュに確保された各型へのポインタ用出力配列です。これには、array_lenポインタ用の領域が必要です。OCIObjectGetObjectRef()を使用して、確保された各型記述子に対するCREFを取得します。

コメント

スキーマまたは型名配列に対応付けられている既存の型のポインタを取得します。

get_optionパラメータを使用すると、各ラウンドトリップごとにロードされるTDOの部分を制御できます。

この関数は、必須パラメータにNULLがある場合、あるいはスキーマ名または型名に対応付けられたオブジェクト型が存在しない場合はエラーを戻します。

配列ではなく単一の型を取り出すには、OCITypeByName()を使用します。

注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。

関連関数

OCITypeArrayByRef()、OCITypeByName()、OCITypeByRef()

OCITypeArrayByRef()

用途

参照配列の指定時に型配列を取得します。

構文

sword OCITypeArrayByRef ( OCIEnv           *envhp,
OCIError         *errhp,
ub4              array_len,
const OCIRef     *type_ref[],
OCIDuration      pin_duration,
OCITypeGetOpt    get_option,
OCIType          *tdo[] );

パラメータ

envhp (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

array_len (IN)

取り出されるschema_name、type_nameまたはversion_nameエントリの数です。

type_ref (IN)

取り出される型記述子オブジェクトの特定のバージョンを指し示すOCIRef*の配列です。この配列を指定する場合は、array_len個の要素が必要です。

pin_duration (IN)

取り出された型用の確保継続時間(たとえば、カレント・トランザクションの終わりまで)です。各オプションの説明は、oro.hを参照してください。

get_option (IN)

型をロードする場合のオプションです。値は次の2つのうちのいずれかです。

- OCI_TYPEGET_HEADER (ヘッダーのみがロードされる)

- OCI_TYPEGET_ALL (TDOおよびすべてのADOとMDOがロードされる)

tdo (OUT)

オブジェクト・キャッシュに確保された各型へのポインタ用出力配列です。これには、array_lenポインタ用の領域が必要です。OCIObjectGetObjectRef()を使用して、確保された各型記述子に対するCREFを取得します。

コメント

スキーマまたは型名配列に対応付けられている既存の型のポインタを取得します。

この関数は、次の場合にエラーを戻します。

- 必須パラメータにNULLがある場合

- スキーマまたは型名エントリに対応付けられている1つ以上のオブジェクト型が存在しない場合

型の配列ではなく、単一の型を取り出すには、OCITypeByRef()を使用します。

注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。

関連関数

OCITypeArrayByName()、OCITypeByRef()、OCITypeByName()

OCITypeByName()

用途

既存の型の最新バージョンを名前を指定して取得します。

構文

sword OCITypeByName ( OCIEnv               *env,
OCIError             *err,
const OCISvcCtx      *svc,
const OraText        *schema_name,
ub4                  s_length,
const OraText        *type_name,
ub4                  t_length,
const OraText        *version_name,
ub4                  v_length,
OCIDuration          pin_duration,
OCITypeGetOpt        get_option
OCIType              **tdo );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・ハンドルです。

schema_name (IN、オプション)

型に関連付けられているスキーマの名前です。デフォルトでは、ユーザーのスキーマ名が使用されます。この文字列はすべて大文字であることが必要です。それ以外の場合は、OCIで内部エラーが発生してプログラムが停止します。

s_length (IN)

schema_name パラメータの長さ(バイト単位)です。

type_name (IN)

取得する型の名前です。この文字列はすべて大文字であることが必要です。それ以外の場合は、OCIで内部エラーが発生してプログラムが停止します。

t_length (IN)

type_name パラメータの長さ(バイト単位)です。

version_name (IN)

バージョン名は無視され、要求された型の最新バージョンが戻されます。リリース9.0以上は型の変更が可能であったため、それより前のリリースのアプリケーションで変更された型にアクセスすると、エラーが発生します。この場合は、最新の型定義を使用して、アプリケーションの変更、再コンパイルおよび再リンクを行う必要があります。

ユーザーが読取り可能な、型のバージョンです。最新のバージョンを取り出すには、(text *) 0を渡します。

v_length (IN)

version_nameのバイト単位の長さです。

pin_duration (IN)

確保継続時間です。

関連項目:
「オブジェクト継続時間」

get_option (IN)

型をロードする場合のオプションです。値は次の2つのうちのいずれかです。

- OCI_TYPEGET_HEADER (ヘッダーのみがロードされる)

- OCI_TYPEGET_ALL (TDOおよびすべてのADOとMDOがロードされる)

tdo (OUT)

オブジェクト・キャッシュに確保された型へのポインタです。

コメント

この関数は、スキーマまたは型名に関連付けられている既存の型へのポインタを取得します。必須パラメータにNULLがある場合、スキーマまたは型名に関連付けられたオブジェクト型が存在しない場合、またはversion_nameが存在しない場合はエラーを戻します。

注意:
スキーマおよび型名は大/小文字の区別があります。SQLを使用して作成されている場合は、すべて大文字の文字列を使用する必要があります。すべて大文字でない場合、プログラムは停止します。

この関数では、常にサーバーへのラウンドトリップが発生します。そのため、この関数を繰り返しコールして型を取得すると、パフォーマンスが大幅に低下する可能性があります。ラウンドトリップを最小限にするため、アプリケーションでは、型ごとにこの関数をコールし、型オブジェクトをキャッシュできます。

この関数によって取得した型を解放するには、OCIObjectUnpin()またはOCIObjectPinCountReset()をコールします。

OCITypeArrayByName()またはOCITypeArrayByRef()をコールすることにより、アプリケーションでTDOの配列を取り出せます。

注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。

関連関数

OCITypeByRef()、OCITypeArrayByName()、OCITypeArrayByRef()

OCITypeByRef()

用途

参照の指定時に型を取得します。

構文

sword OCITypeByRef ( OCIEnv          *env,
OCIError        *err,
const OCIRef    *type_ref,
OCIDuration     pin_duration,
OCITypeGetOpt   get_option,
OCIType         **tdo );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

type_ref (IN)

取得する型記述子オブジェクトのバージョンを指し示すOCIRef*です。

pin_duration (IN)

取り出す型に対する、カレント・トランザクションの終了までの確保継続時間です。各オプションの説明は、oro.hを参照してください。

get_option (IN)

型をロードする場合のオプションです。値は次の2つのうちのいずれかです。

- OCI_TYPEGET_HEADER (ヘッダーのみがロードされる)

- OCI_TYPEGET_ALL (TDOおよびすべてのADOとMDOがロードされる)

tdo (OUT)

オブジェクト・キャッシュに確保された型へのポインタです。

コメント

OCITypeByRef()関数は、必須パラメータにNULLがある場合、エラーを戻します。

注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。

関連関数

OCITypeByName()、OCITypeArrayByName()、OCITypeArrayByRef()

19 OCIのデータ型マッピング関数および操作関数

この章では、OCIデータ型マッピング関数および操作関数について説明します。これらの関数は、Oracle Database事前定義型に対する、Oracleの外部C言語インタフェースです。

関連項目:
コード例は、Oracle Databaseのインストールに含まれているデモ・プログラムを参照してください。詳細は、付録Bを参照してください。

この章は、次の項目で構成されています。

- データ型マッピング関数および操作関数の概要

- OCIコレクションおよびイテレータ関数

- OCIの日付関数、日時関数および時間隔関数

- OCI NUMBER関数

- OCIロー関数

- OCI REF関数

- OCI文字列関数

- OCI表関数

データ型マッピング関数および操作関数の概要

この章では、OCIデータ型マッピング関数および操作関数の詳細を説明します。

関連項目:
この章にリストされている関数の詳細は、第12章 を参照してください。

OCI関数の規則

各関数を記述する際に使用される規則は、「OCI関数の規則」を参照してください。関数ごとに次の情報が記載されている場合もあります。

戻り値

「関数戻り値」にリストされている標準リターン・コード以外の値が関数によって戻される場合の、戻り値についての説明。

データ型マッピング関数および操作関数の戻り値

OCIのデータ型マッピング関数および操作関数は、通常、表19-1に示す値のいずれかを戻します。

表19-1 関数戻り値

戻り値

意味

OCI_SUCCESS

操作は成功しました。

OCI_ERROR

操作は失敗しました。関数に渡されたエラー・ハンドルに対してOCIErrorGet()をコールすることで特定のエラーを取り出せます。

OCI_INVALID_HANDLE

関数に渡されたOCIハンドルが無効です。

関連項目:
リターン・コードおよびエラー処理の詳細は、「OCIでのエラー処理」を参照してください。

その他の値を戻す関数

一部の関数は、表19-1にリストされていない値を戻します。これらの関数を使用する場合、OUTパラメータからではなく、関数コールから直接値が戻ります。

- OCICollMax()

- OCIRawPtr()

- OCIRawSize()

- OCIRefHexSize()

- OCIRefIsEqual()

- OCIRefIsNull()

- OCIStringPtr()

- OCIStringSize()

データ型マッピング関数および操作関数のサーバー・ラウンドトリップ回数

個々のOCIデータ型マッピング関数および操作関数に必要なサーバー・ラウンドトリップ回数を示す表は、表C-5を参照してください。

例

コード例など、これらの関数の詳細は、第12章を参照してください。

OCIコレクションおよびイテレータ関数

表19-2は、この項で説明しているコレクションおよびイテレータ関数を示しています。

表19-2 コレクションおよびイテレータ関数

関数

用途

「OCICollAppend()」

コレクションの最後に要素を追加します。

「OCICollAssign()」

あるコレクションを別のコレクションに割り当てます(ディープ・コピーします)。

「OCICollAssignElem()」

指定の要素値elemをcoll[index]の要素に割り当てます。

「OCICollGetElem()」

要素へのポインタを取得します。

「OCICollGetElemArray()」

コレクションから要素の配列を取得します。

「OCICollIsLocator()」

コレクションがロケータベースであるかどうかを示します。

「OCICollMax()」

コレクションの最大要素数を戻します。

「OCICollSize()」

コレクションのカレント・サイズ(要素数単位)を取得します。

「OCICollTrim()」

コレクションから要素を切り捨てます。

「OCIIterCreate()」

VARRAY要素をスキャンするためのイテレータを作成します。

「OCIIterDelete()」

イテレータを削除します。

「OCIIterGetCurrent()」

カレント・コレクション要素を取得します。

「OCIIterInit()」

イテレータを初期化して指定のコレクションをスキャンします。

「OCIIterNext()」

次のコレクション要素を取得します。

「OCIIterPrev()」

前のコレクション要素を取得します。

OCICollAppend()

用途

コレクションの最後に要素を追加します。

構文

sword OCICollAppend ( OCIEnv              *env,
OCIError            *err,
const void          *elem,
const void          *elemind,
OCIColl             *coll );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

elem (IN)

与えられたコレクションの最後に追加される要素へのポインタです。

elemind (IN) [オプション]

要素のNULLインジケータ情報へのポインタです。elemind == NULLの場合、追加された要素のNULLインジケータ情報は、NULL以外に設定されます。

coll (IN/OUT)

更新されたコレクションです。

コメント

要素を追加することは、要素ごとにコレクションのサイズを増加させて、最後の要素のデータを指定した要素のデータで更新(ディープ・コピー)することと同等です。この関数では、指定した要素elemへのポインタは保存されません。つまり、elemは厳密に入力パラメータになります。

戻り値

この関数は、コレクションのカレント・サイズが、要素を追加する前のコレクションの最大サイズ(上限)と等しい場合、エラーを戻します。また、この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()

OCICollAssign()

用途

あるコレクションを別のコレクションに割り当てます(ディープ・コピーします)。

構文

sword OCICollAssign ( OCIEnv              *env,
OCIError            *err,
const OCIColl       *rhs,
OCIColl             *lhs );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

rhs (IN)

割当て元となる右側(ソース)コレクションです。

lhs (OUT)

割当て先となる左側(ターゲット)コレクションです。

コメント

rhs (ソース)をlhs (ターゲット)に割り当てます。lhsコレクションは、rhsのサイズに応じて変更されます。lhsコレクションに要素が格納されている場合は、割当てに先立ってその要素が削除されます。この関数はディープ・コピーを実行します。要素用のメモリーはオブジェクト・キャッシュから取られます。

戻り値

lhsコレクションとrhsコレクションの要素の型が一致しない場合はエラーが戻ります。lhsコレクションの上限がrhsコレクション内の現行の要素数より小さい場合もエラーが戻ります。次の場合にもエラーが戻されます。

- 入力パラメータがNULLである場合

- lhsコレクションとrhsコレクションの型が一致しない場合

- lhsコレクションの上限がrhsコレクション内の現行の要素数より小さい場合

関連関数

OCIErrorGet()、OCICollAssignElem()

OCICollAssignElem()

用途

指定の要素値elemをcoll[index]の要素に割り当てます。

構文

sword OCICollAssignElem ( OCIEnv           *env,
OCIError         *err,
sb4              index,
const void       *elem,
const void       *elemind,
OCIColl          *coll );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

index (IN)

要素の割当て先となる要素の索引です。

elem (IN)

要素の割当て元となるソース要素です。

elemind (IN) [オプション]

要素のNULLインジケータ情報へのポインタです。elemind == NULLの場合、割り当てられた要素のNULLインジケータ情報は、NULL以外に設定されます。

coll (IN/OUT)

更新されるコレクションです。

コメント

コレクションの型がNESTED TABLEである場合は、要素が削除されているときと同様に、指定の索引位置に要素が存在しない場合があります。このような場合は、indexの位置に指定の要素が挿入されます。それ以外の場合は、indexの位置にある要素がelemの値で更新されます。

指定の要素はディープ・コピーされること、およびelemは厳密に入力パラメータであることに注意してください。

戻り値

この関数は、入力パラメータがNULLであるか、または指定の索引が指定のコレクションの上限を超えている場合にエラーを戻します。

関連関数

OCIErrorGet()、OCICollAssign()

OCICollGetElem()

用途

指定の索引位置にある要素へのポインタを取得します。

構文

sword OCICollGetElem ( OCIEnv           *env,
OCIError         *err,
const OCIColl    *coll,
sb4              index,
boolean          *exists,
void             **elem,
void             **elemind );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

このコレクション内の要素へのポインタが戻されます。

index (IN)

ポインタが戻される要素の索引です。

exists (OUT)

指定した索引の要素が存在しない場合はFALSEに設定されます。それ以外の場合はTRUEに設定されます。

elem (OUT)

要素のアドレスが戻されます。

elemind (OUT) [オプション]

NULLインジケータ情報のアドレスが戻されます。elemind == NULLの場合、NULLインジケータ情報は戻されません。

コメント

指定の位置にある要素のアドレスを取得します。また、この関数は、オプションで要素のNULLインジケータ情報のアドレスを戻します。

表19-3に、コレクションの各要素型と対応する要素ポインタの型を示します。要素ポインタはOCICollGetElem()のelemパラメータによって戻されます。

表19-3 要素ポインタ

要素型

*elemの設定

Oracle NUMBER(OCINumber)

OCINumber*

日付(OCIDate)

OCIDate*

日時(OCIDateTime)

OCIDateTime *

時間隔(OCIInterval)

OCIInterval *

可変長文字列(OCIString*)

OCIString **

可変長RAW (OCIRaw*)

OCIRaw**

オブジェクト参照(OCIRef*)

OCIRef**

LOBロケータ(OCILobLocator*)

OCILobLocator**

オブジェクト型(personなど)

person*

OCICollGetElem()で戻される要素ポインタは、要素データにアクセスするためだけでなく、代入文のターゲット(左側)として機能するために使用できる書式です。

たとえば、要素型がオブジェクト参照(OCIRef*)であるコレクションの要素を反復するとします。OCICollGetElem()のコールにより、参照ハンドル(OCIRef**)へのポインタが戻ります。コレクション要素へのポインタを取得した後、新しい参照を割り当てることでそれを修正できます。

例19-1に、OCIRefAssign()関数を使用してこれを実行する方法を示します。

例19-1 コレクション要素へのポインタへの新しい参照の割当て

sword OCIRefAssign( OCIEnv       *env,
OCIError     *err,
const OCIRef *source,
OCIRef       **target );

OCIRefAssign()のtargetパラメータの型はOCIRef**であることに注意してください。したがってOCICollGetElem()は、OCIRef**を戻します。*targetがNULLの場合は、OCIRefAssign()によって新しいREFが割り当てられ、targetパラメータに戻されます。

同様に、コレクション要素がタイプ文字列(OCIString*)のものである場合、OCICollGetElem()は文字列ハンドル(つまり、OCIString**)へのポインタを戻します。OCIStringAssign()またはOCIStringAssignText()を介して新しい文字列を割り当てる場合、ターゲットの型はOCIString **にしてください。

コレクションの要素型がOracle NUMBERの場合、OCICollGetElem()はOCINumber*を戻します。例19-2に、OCINumberAssign()コールのプロトタイプを示します。

例19-2 OCINumberAssign()コールのプロトタイプ

sword OCINumberAssign(OCIError        *err,
const OCINumber *from,
OCINumber       *to);

戻り値

OCICollGetElem()関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCICollAssignElem()

OCICollGetElemArray()

用途

開始索引の指定時にコレクションから要素の配列を取得します。

構文

sword OCICollGetElemArray ( OCIEnv              *env,
OCIError            *err,
const OCIColl       *coll,
sb4                 index,
boolean             *exists,
void                **elem,
void                **elemind,
uword               *nelems );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

このコレクション内の要素へのポインタが戻されます。

index (IN)

この要素の開始索引です。

exists (OUT)

指定した索引の要素が存在しない場合はFALSEに設定されます。それ以外の場合はTRUEに設定されます。

elem (OUT)

要求する要素のアドレスが戻されます。

elemind (OUT) [オプション]

NULLインジケータ情報のアドレスが戻されます。elemind == NULLの場合、NULLインジケータ情報は戻されません。

nelems (IN)

elemおよびelemind両方に対するポインタの最大数です。

コメント

指定の位置から要素のアドレスを取得します。

戻り値

また、この関数は、オプションで要素のNULLインジケータ情報のアドレスを戻します。

関連関数

OCIErrorGet()、OCICollGetElem()

OCICollIsLocator()

用途

コレクションがロケータベースであるかどうかを示します。

構文

sword OCICollIsLocator ( OCIEnv *env,
OCIError *err,
const OCIColl *coll,
boolean *result );

パラメータ

env (IN)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

コレクション項目です。

result (OUT)

コレクション項目がロケータベースである場合はTRUEを戻します。それ以外の場合はFALSEを戻します。

コメント

この関数は、コレクションがロケータベースであるかどうかを確認するためのテストを行います。

戻り値

コレクション項目がロケータベースである場合はresultパラメータにTRUEを戻します。それ以外の場合はFALSEを戻します。

関連関数

OCIErrorGet()

OCICollMax()

用途

指定のコレクションの最大サイズを要素数単位で取得します。

構文

sb4 OCICollMax ( OCIEnv           *env,
const OCIColl    *coll );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

coll (IN)

要素の数が戻されるコレクションです。collパラメータは、有効なコレクション識別子を指し示している必要があります。

コメント

指定されたコレクションが保持できる要素の最大数を戻します。値0 (ゼロ)は、そのコレクションには上限がないことを示します。

戻り値

指定のコレクションの上限。

関連関数

OCIErrorGet()、OCICollSize()

OCICollSize()

用途

指定のコレクションのカレント・サイズを要素数単位で取得します。

構文

sword OCICollSize ( OCIEnv           *env,
OCIError         *err,
const OCIColl    *coll
sb4              *size );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

要素の数が戻されるコレクションです。有効なコレクション識別子を指し示している必要があります。

size (OUT)

コレクション内の現行の要素数です。

コメント

指定されたコレクションの現行の要素数を戻します。ネストした表の場合、要素を削除してもこのカウントは減分されません。したがって、このカウントには要素を削除した際に作成された穴が含まれています。切捨て操作(OCICollTrim())は、切り捨てられた要素の数のみこのカウントを減分します。削除済の要素を差し引いたカウントを取得するには、OCITableSize()を使用します。

次の疑似コードで例をいくつか示します。

OCICollSize(...);
// assume 'size' returned is equal to 5
OCITableDelete(...); // delete one element
OCICollSize(...);
// 'size' returned is still 5

削除済の要素を差し引いたカウントを取得するには、OCITableSize()を使用します。前述の例を続けます。

OCITableSize(...)
// 'size' returned is equal to 4

切捨て操作(OCICollTrim())は、切り捨てられた要素の数のみこのカウントを減分します。前述の例を続けます。

OCICollTrim(..,1..); // trim one element
OCICollSize(...);
// 'size' returned is equal to 4

戻り値

OCICollSize()関数は、コレクションのオブジェクト・キャッシュへのロード中にエラーが発生した場合、または入力パラメータがNULLである場合にエラーを戻します。

関連関数

OCIErrorGet()、OCICollMax()

OCICollTrim()

用途

指定数の要素をコレクションの最後から切り捨てます。

構文

sword OCICollTrim ( OCIEnv         *env,
OCIError       *err,
sb4            trim_num,
OCIColl        *coll );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

trim_num (IN)

切り捨てる要素数です。

coll (IN/OUT)

trim_num要素をコレクションcollの最後から削除(解放)します。

コメント

要素は、コレクションの末尾から削除されます。

戻り値

trim_numがコレクションのカレント・サイズよりも大きい場合はエラーを戻します。

関連関数

OCIErrorGet()、OCICollSize()

OCIIterCreate()

用途

要素またはコレクションをスキャンするためのイテレータを作成します。

構文

sword OCIIterCreate ( OCIEnv               *env,
OCIError             *err,
const OCIColl        *coll,
OCIIter              **itr );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

スキャンするコレクションです。Oracle8i以上では、有効なコレクション型としてVARRAYとNESTED TABLEが含まれています。

itr (OUT)

割り当てられたコレクション・イテレータのアドレスは、この関数で戻されます。

コメント

イテレータは、オブジェクト・キャッシュの中に作成されます。イテレータは、コレクションの先頭を指し示すように初期化されます。

イテレータの作成直後にOCIIterNext()をコールした場合は、コレクションの最初の要素が戻ります。イテレータの作成直後にOCIIterPrev()をコールした場合は、「コレクションの先頭にいる」ことを示すエラーが戻ります。

戻り値

この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIIterDelete()

OCIIterDelete()

用途

コレクション・イテレータを削除します。

構文

sword OCIIterDelete ( OCIEnv           *env,
OCIError         *err,
OCIIter          **itr );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

itr (IN/OUT)

割り当てられたコレクション・イテレータです。これは戻す前に破棄されNULLに設定されます。

コメント

OCIIterCreate()のコールによって以前に作成されたイテレータを削除します。

戻り値

この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIIterCreate()

OCIIterGetCurrent()

用途

カレント・イテレータ・コレクション要素へのポインタを取得します。

構文

sword OCIIterGetCurrent ( OCIEnv            *env,
OCIError          *err,
const OCIIter     *itr,
void              **elem,
void              **elemind );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

itr (IN)

現在の要素を指し示すイテレータです。

elem (OUT)

イテレータが指し示した要素のアドレスが戻されます。

elemind (OUT) [オプション]

要素のNULLインジケータ情報のアドレスが戻されます。elem_ind == NULLの場合、NULLインジケータ情報は戻されません。

コメント

カレント・イテレータ・コレクション要素へのポインタとそれに対応するNULL情報を戻します。

戻り値

この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIIterNext()、OCIIterPrev()

OCIIterInit()

用途

コレクションをスキャンするためのイテレータを初期化します。

構文

sword OCIIterInit ( OCIEnv              *env,
OCIError            *err,
const OCIColl       *coll,
OCIIter             *itr );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

スキャンするコレクションです。Oracle8i以上では、有効なコレクション型としてVARRAYとNESTED TABLEが含まれています。

itr (IN/OUT)

割り当てられたコレクション・イテレータへのポインタです。

コメント

指定したイテレータが、指定したコレクションの先頭を指し示すように初期化します。この関数を使用して、次のいずれかのタスクを実行できます。

- コレクションの先頭を指し示すようにイテレータをリセットします。

- 割当て済のイテレータを再利用して別のコレクションをスキャンします。

戻り値

入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()

OCIIterNext()

用途

次のイテレータ・コレクション要素へのポインタを取得します。

構文

sword OCIIterNext ( OCIEnv            *env,
OCIError          *err,
OCIIter           *itr,
void              **elem,
void              **elemind,
boolean           *eoc);

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

itr (IN/OUT)

次の要素を指し示すように更新されるイテレータです。

elem (OUT)

イテレータが次の要素を指し示すように更新された後に戻される、次の要素のアドレスです。

elemind (OUT) [オプション]

要素のNULLインジケータ情報のアドレスが戻されます。elem_ind == NULLの場合、NULLインジケータ情報は戻されません。

eoc (OUT)

イテレータがコレクションの最後にある(つまり、次の要素が存在しない)場合はTRUE、それ以外の場合はFALSEとなります。

コメント

この関数は、次のイテレータ・コレクション要素へのポインタおよびそれに対応するNULL情報を戻します。また、次の要素を指し示すようにイテレータを更新します。

この関数の実行前にイテレータがコレクションの最後の要素を指し示している場合は、この関数をコールするとeocフラグにTRUEが設定されます。この場合、イテレータは更新されません。

戻り値

この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIIterGetCurrent()、OCIIterPrev()

OCIIterPrev()

用途

直前のイテレータ・コレクション要素へのポインタを取得します。

構文

sword OCIIterPrev ( OCIEnv            *env,
OCIError          *err,
OCIIter           *itr,
void              **elem,
void              **elemind,
boolean           *boc );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

itr (IN/OUT)

前の要素を指し示すように更新されるイテレータです。

elem (OUT)

イテレータが前の要素を指し示すように更新された後に戻される、前の要素のアドレスです。

elemind (OUT) [オプション]

要素のNULLインジケータ情報のアドレスが戻されます。elemind == NULLの場合、NULLインジケータ情報は戻されません。

boc (OUT)

イテレータがコレクションの先頭にある(つまり、前の要素が存在しない)場合はTRUE、それ以外の場合はFALSEとなります。

コメント

この関数は、前のイテレータ・コレクション要素へのポインタおよびそれに対応するNULL情報を戻します。イテレータは、前の要素を指し示すように更新されます。

この関数の実行前にイテレータがコレクションの最初の要素を指し示している場合は、この関数をコールするとbocにTRUEが設定されます。この場合、イテレータは更新されません。

戻り値

この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIIterGetCurrent()、OCIIterNext()

OCIの日付関数、日時関数および時間隔関数

表19-4は、この項で説明しているOCIの日付関数および時間隔関数を示しています。

表19-4 日付関数

関数

用途

「OCIDateAddDays()」

日数の加算または減算を行います。

「OCIDateAddMonths()」

月の加算または減算を行います。

「OCIDateAssign()」

日付を割り当てます。

「OCIDateCheck()」

指定の日付が有効かどうかをチェックします。

「OCIDateCompare()」

日付を比較します。

「OCIDateDaysBetween()」

2つの日付の間にある日数を取得します。

「OCIDateFromText()」

文字列を日付に変換します。

「OCIDateGetDate()」

日付の日付部分を取得します。

「OCIDateGetTime()」

日付の時刻部分を取得します。

「OCIDateLastDay()」

月末の日付を取得します。

「OCIDateNextDay()」

次の日の日付を取得します。

「OCIDateSetDate()」

日付の日付部分を設定します。

「OCIDateSetTime()」

日付の時刻部分を設定します。

「OCIDateSysDate()」

現行のシステム日付および時刻を取得します。

「OCIDateTimeAssign()」

日付の割当てを実行します。

「OCIDateTimeCheck()」

指定の日付が有効かどうかをチェックします。

「OCIDateTimeCompare()」

2つの日時値を比較します。

「OCIDateTimeConstruct()」

日時記述子を作成します。

「OCIDateTimeConvert()」

ある日時型を別の日時型に変換します。

「OCIDateTimeFromArray()」

サイズOCI_DT_ARRAYLENの配列をOCIDateTime記述子に変換します。

「OCIDateTimeFromText()」

指定された書式に従って、指定の文字列をOCIDateTime記述子のOracle日時型に変換します。

「OCIDateTimeGetDate()」

日時値の日付部分(年、月、日)を取得します。

「OCIDateTimeGetTime()」

日時値の時刻部分(時間、分、秒、小数秒)を取得します。

「OCIDateTimeGetTimeZoneName()」

日時値のタイム・ゾーン名部分を取得します。

「OCIDateTimeGetTimeZoneOffset()」

日時値のタイム・ゾーン(時間、分)部分を取得します。

「OCIDateTimeIntervalAdd()」

日時に時間隔を加算して、結果の日時を生成します。

「OCIDateTimeIntervalSub()」

日時から時間隔を減算して、その結果を日時に格納します。

「OCIDateTimeSubtract()」

2つの日時を入力値にして、その差異を時間隔に格納します。

「OCIDateTimeSysTimeStamp()」

現行のシステム日付および時刻を、タイム・ゾーン付きタイムスタンプとして取得します。

「OCIDateTimeToArray()」

OCIDateTime記述子を配列に変換します。

「OCIDateTimeToText()」

指定された日付を指定の書式の文字列に変換します。

「OCIDateToText()」

日付を文字列に変換します。

「OCIDateZoneToZone()」

あるタイム・ゾーンの日付を別のゾーンの日付に変換します。

「OCIIntervalAdd()」

2つの時間隔を加算して、その結果の時間隔を生成します。

「OCIIntervalAssign()」

ある時間隔を別の時間隔にコピーします。

「OCIIntervalCheck()」

時間隔の妥当性をチェックします。

「OCIIntervalCompare()」

2つの時間隔を比較します。

「OCIIntervalDivide()」

時間隔をOracle NUMBERで除算して、時間隔を生成します。

「OCIIntervalFromNumber()」

Oracle NUMBERを時間隔に変換します。

「OCIIntervalFromText()」

時間隔文字列が指定されている場合、その文字列で表現される時間隔を戻します。

「OCIIntervalFromTZ()」

OCI_DTYPE_INTERVAL_DSを戻します。

「OCIIntervalGetDaySecond()」

時間隔から日、時、分、秒の値を取得します。

「OCIIntervalGetYearMonth()」

時間隔から年と月を取得します。

「OCIIntervalMultiply()」

時間隔をOracle NUMBERで乗算して、時間隔を生成します。

「OCIIntervalSetDaySecond()」

時間隔に日、時、分、秒を設定します。

「OCIIntervalSetYearMonth()」

時間隔に年と月を設定します。

「OCIIntervalSubtract()」

2つの時間隔を減算し、その結果を時間隔に格納します。

「OCIIntervalToNumber()」

時間隔をOracle NUMBERに変換します。

「OCIIntervalToText()」

時間隔が指定されている場合、その時間隔を表現する文字列を生成します。

OCIDateAddDays()

用途

指定の日付に日数を加算または減算します。

構文

sword OCIDateAddDays ( OCIError          *err,
const OCIDate     *date,
sb4               num_days,
OCIDate           *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date (IN)

加算または減算の対象となる指定の日付です。

num_days (IN)

加算または減算される日数です。マイナス値の場合は減算となります。

result (IN/OUT)

dateに対して日数を加算または減算した結果です。

戻り値

この関数は、無効な日付が渡された場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIDateAddMonths()

OCIDateAddMonths()

用途

指定の日付に月数を加算または減算します。

構文

sword OCIDateAddMonths ( OCIError            *err,
const OCIDate       *date,
sb4                 num_months,
OCIDate             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date (IN)

加算または減算の対象となる指定の日付です。

num_months (IN)

加算または減算される月数です。マイナス値の場合は減算となります。

result (IN/OUT)

dateに対して日数を加算または減算した結果です。

コメント

入力されたdateが月末の場合は、出力される日付も月末になるように適切な調整が行われます。たとえば、2月28日＋1か月＝3月31日、11月30日 – 3か月＝8月31日となります。それ以外の場合、resultの日付はdateの日付コンポーネントと同じになります。

戻り値

この関数は、無効な日付が渡された場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIDateAddDays()

OCIDateAssign()

用途

日付の割当てを実行します。

構文

sword OCIDateAssign ( OCIError         *err,
const OCIDate    *from,
OCIDate          *to );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

from (IN)

割り当てる日付です。

to (OUT)

割当てのターゲットです。

コメント

この関数は、あるOCIDate変数の値を別の変数に割り当てます。

関連関数

OCIErrorGet()、OCIDateCheck()

OCIDateCheck()

用途

指定の日付が有効かどうかをチェックします。

構文

sword OCIDateCheck ( OCIError          *err,
const OCIDate     *date,
uword             *valid );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date (IN)

チェックする日付です。

valid (OUT)

有効な日付の場合は0 (ゼロ)を戻します。それ以外の場合は、表19-5に指定されたすべてのエラー・ビットの論理演算子ORによる組合せを戻します。

表19-5 OCIDateCheck()の有効なパラメータによって戻されるエラー・ビット

マクロ名

ビット数

エラー

OCI_DATE_INVALID_DAY

0x1

無効な日。

OCI_DATE_DAY_BELOW_VALID

0x2

無効な日の、有効な日に対する大/小を示すビット(1=小)。

OCI_DATE_INVALID_MONTH

0x4

無効な月。

OCI_DATE_MONTH_BELOW_VALID

0x8

無効な月の、有効な月に対する大/小を示すビット(1=小)。

OCI_DATE_INVALID_YEAR

0x10

無効な年。

OCI_DATE_YEAR_BELOW_VALID

0x20

無効な年の、有効な年に対する大/小を示すビット(1=小)。

OCI_DATE_INVALID_HOUR

0x40

無効な時刻(時)。

OCI_DATE_HOUR_BELOW_VALID

0x80

無効な時刻(時)の、有効な時刻(時)に対する大/小を示すビット(1=小)。

OCI_DATE_INVALID_MINUTE

0x100

無効な時刻(分)。

OCI_DATE_MINUTE_BELOW_VALID

0x200

無効な時刻(分)の、有効な時刻(分)に対する大/小を示すビット(1=小)。

OCI_DATE_INVALID_SECOND

0x400

無効な時刻(秒)。

OCI_DATE_SECOND_BELOW_VALID

0x800

無効な時刻(秒)の、有効な時刻(秒)に対する大/小を示すビット(1=小)。

OCI_DATE_DAY_MISSING_FROM_1582

0x1000

日が1582から欠落しています。

OCI_DATE_YEAR_ZERO

0x2000

年が0 (ゼロ)に等しくありません。

OCI_DATE_INVALID_FORMAT

0x8000

無効な日付書式入力。

たとえば、渡された日付が2/0/1990 25:61:10 (月/日/年 時:分:秒書式)の場合は、次のエラーが戻されます。

OCI_DATE_INVALID_DAY | OCI_DATE_DAY_BELOW_VALID | OCI_DATE_INVALID_HOUR |
OCI_DATE_INVALID_MINUTE.

戻り値

この関数は、dateまたはvalidポインタがNULLの場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIDateCompare()

OCIDateCompare()

用途

2つの日付を比較します。

構文

sword OCIDateCompare ( OCIError           *err,
const OCIDate      *date1,
const OCIDate      *date2,
sword              *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date1、date2 (IN)

比較する日付です。

result (OUT)

表19-6に示したような比較結果です。

表19-6 比較結果

比較結果

resultパラメータの出力

date1 < date2

-1

date1 = date2

0

date1 > date2

1

戻り値

この関数は、無効な日付が渡された場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIDateCheck()

OCIDateDaysBetween()

用途

2つの日付間の日数を取得します。

構文

sword OCIDateDaysBetween ( OCIError            *err,
const OCIDate       *date1,
const OCIDate       *date2,
sb4                 *num_days );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date1 (IN)

入力日付です。

date2 (IN)

入力日付です。

num_days (OUT)

date1とdate2の間の日数です。

コメント

date1とdate2の間の日数の計算時には、時刻は無視されます。

戻り値

この関数は、無効な日付が渡された場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIDateCheck()

OCIDateFromText()

用途

指定された書式に従って、文字列を日付型に変換します。

構文

sword OCIDateFromText ( OCIError           *err,
const OraText      *date_str,
ub4                d_str_length,
const OraText      *fmt,
ub1                fmt_length,
const OraText      *lang_name,
ub4                lang_length,
OCIDate            *date );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date_str (IN)

Oracle日付に変換される入力文字列です。

d_str_length (IN)

入力文字列のサイズです。長さが–1の場合、date_strはNULLで終了する文字列として処理されます。

fmt (IN)

変換書式です。fmtがNULLポインタの場合、文字列は"DD-MON-YY"書式になります。

fmt_length (IN)

fmtパラメータの長さです。

lang_name (IN)

日および月の名前と省略が指定される言語です。lang_nameがNULL文字列(text *)0の場合は、そのセッションのデフォルト言語が使用されます。

lang_length (IN)

lang_nameパラメータの長さです。

date (OUT)

日付に変換された指定文字列です。

コメント

書式および多言語引数の詳細は、『Oracle Database SQL言語リファレンス』のTO_DATE変換関数の説明を参照してください。

戻り値

この関数は、無効な書式、言語または入力文字列を受け取った場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIDateToText()

OCIDateGetDate()

用途

Oracle日付に格納されている年月日を取得します。

構文

void OCIDateGetDate ( const OCIDate    *date,
sb2              *year,
ub1              *month,
ub1              *day );

パラメータ

date (IN)

年、月、日データの取出し元となるOracle日付です。

year (OUT)

戻される年の値です。

month (OUT)

戻される月の値です。

day (OUT)

戻される日の値です。

コメント

なし。

関連関数

OCIDateSetDate()、OCIDateGetTime()

OCIDateGetTime()

用途

Oracle日付に格納されている時刻を取得します。

構文

void OCIDateGetTime ( const OCIDate    *date,
ub1              *hour,
ub1              *min,
ub1              *sec );

パラメータ

date (IN)

時間データの取出し元となるOracle日付です。

hour (OUT)

戻される時間の値です。

min (OUT)

戻される分の値です。

sec (OUT)

戻される秒の値です。

戻り値

時、分、秒の時刻情報を戻します。

関連関数

OCIDateSetTime()、OCIDateGetDate()

OCIDateLastDay()

用途

指定された日付の月の最後の日の日付を取得します。

構文

sword OCIDateLastDay ( OCIError            *err,
const OCIDate       *date,
OCIDate             *last_day );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date (IN)

入力日付です。

last_day (OUT)

dateの月の最後の日付です。

戻り値

この関数は、無効な日付が渡された場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIDateGetDate()

OCIDateNextDay()

用途

指定した日付以降で、指定した曜日の最初の日付を取得します。

構文

sword OCIDateNextDay ( OCIError            *err,
const OCIDate       *date,
const OraText       *day,
ub4                 day_length,
OCIDate             *next_day );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date (IN)

戻される日付は、この日付よりも後になります。

day (IN)

これによって指定された週の最初の日が戻されます。

day_length (IN)

文字列dayのバイト長です。

next_day (OUT)

date以降で、dayによって指定された週の最初の日付です。

戻り値

date以降で、dayによって指定された週の最初の曜日の日付を戻します。

例

例19-3は、1996年4月18日(木曜日)の次の月曜日の日付の取得方法を示しています。

例19-3 指定した日付以降の指定した曜日の日付の取得

OCIDate one_day, next_day;
/* Add code here to set one_day to be '18-APR-96' */
OCIDateNextDay(err, &one_day, "MONDAY", strlen("MONDAY"), &next_day);

OCIDateNextDay()は"22-APR-96"を戻します。

この関数は、無効な日付または曜日が渡された場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIDateGetDate()

OCIDateSetDate()

用途

Oracle日付に値を設定します。

構文

void OCIDateSetDate ( OCIDate    *date,
sb2        year,
ub1        month,
ub1        day );

パラメータ

date (OUT)

時間データ設定の対象となるOracle日付です。

year (IN)

設定する年の値です。

month (IN)

設定する月の値です。

day (IN)

設定する日の値です。

コメント

なし。

関連関数

OCIDateGetDate()

OCIDateSetTime()

用途

Oracle日付に時刻情報を設定します。

構文

void OCIDateSetTime ( OCIDate    *date,
ub1        hour,
ub1        min,
ub1        sec );

パラメータ

date (OUT)

時間データ設定の対象となるOracle日付です。

hour (IN)

設定する時間の値です。

min (IN)

設定する分の値です。

sec (IN)

設定する秒の値です。

コメント

なし。

関連関数

OCIDateGetTime()

OCIDateSysDate()

用途

クライアントの現行のシステム日付およびシステム時刻を取得します。

構文

sword OCIDateSysDate ( OCIError       *err,
OCIDate        *sys_date );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sys_date (OUT)

クライアントの現行日付およびシステム時刻です。

コメント

なし。

関連関数

OCIErrorGet()

OCIDateTimeAssign()

用途

日時の割当てを実行します。

構文

sword OCIDateTimeAssign ( void                *hndl,
OCIError            *err,
const OCIDateTime   *from,
OCIDateTime         *to );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。ユーザー・セッション・ハンドルが渡されると、セッションのNLS_LANGUAGEおよびセッションのNLS_CALENDARで変換が行われます。渡されない場合は、デフォルトが使用されます。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

from (IN)

ソース、割当て先となる右側(rhs)日時です。

to (OUT)

ターゲット、割当ての左側(lhs)です。

コメント

この関数は、typeパラメータの説明にリストされている日時型に関して、from日時からto日時への割当てを実行します。

出力のtypeは入力と同じです。

戻り値

OCI_SUCCESSまたはOCI_ERROR。

関連関数

OCIDateTimeCheck()、OCIDateTimeConstruct()

OCIDateTimeCheck()

用途

指定の日付が有効かどうかをチェックします。

構文

sword OCIDateTimeCheck ( void                *hndl,
OCIError            *err,
const OCIDateTime   *date,
ub4                 *valid );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。ユーザー・セッション・ハンドルが渡されると、セッションのNLS_LANGUAGEおよびセッションのNLS_CALENDARで変換が行われます。渡されない場合は、デフォルトが使用されます。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date (IN)

チェックする日付です。

valid (OUT)

有効な日付の場合は0 (ゼロ)を戻します。それ以外の場合は、表19-7に指定されたすべてのエラー・ビットの論理演算子ORによる組合せを戻します。

表19-7 OCIDateTimeCheck()の有効なパラメータによって戻されるエラー・ビット

マクロ名

ビット数

エラー

OCI_DT_INVALID_DAY

0x1

無効な日。

OCI_DT_DAY_BELOW_VALID

0x2

無効な日の、有効な日に対する大/小を示すビット(1=小)。

OCI_DT_INVALID_MONTH

0x4

無効な月。

OCI_DT_MONTH_BELOW_VALID

0x8

無効な月の、有効な月に対する大/小を示すビット(1=小)。

OCI_DT_INVALID_YEAR

0x10

無効な年。

OCI_DT_YEAR_BELOW_VALID

0x20

無効な年の、有効な年に対する大/小を示すビット(1=小)。

OCI_DT_INVALID_HOUR

0x40

無効な時刻(時)。

OCI_DT_HOUR_BELOW_VALID

0x80

無効な時刻(時)の、有効な時刻(時)に対する大/小を示すビット(1=小)。

OCI_DT_INVALID_MINUTE

0x100

無効な時刻(分)。

OCI_DT_MINUTE_BELOW_VALID

0x200

無効な時刻(分)の、有効な時刻(分)に対する大/小を示すビット(1=小)。

OCI_DT_INVALID_SECOND

0x400

無効な時刻(秒)。

OCI_DT_SECOND_BELOW_VALID

0x800

無効な時刻(秒)の、有効な時刻(秒)に対する大/小を示すビット(1=小)。

OCI_DT_DAY_MISSING_FROM_1582

0x1000

日が1582から欠落しています。

OCI_DT_YEAR_ZERO

0x2000

年が0 (ゼロ)に等しくありません。

OCI_DT_INVALID_TIMEZONE

0x4000

無効なタイム・ゾーン。

OCI_DT_INVALID_FORMAT

0x8000

無効な日付書式入力。

たとえば渡された日付が2/0/1990 25:61:10 (月/日/年 時:分:秒書式)の場合は、次のエラーが戻されます。

OCI_DT_INVALID_DAY | OCI_DT_DAY_BELOW_VALID |
OCI_DT_INVALID_HOUR | OCI_DT_INVALID_MINUTE.

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (dateまたはvalidがNULLポインタの場合)。

関連関数

OCIDateTimeAssign()

OCIDateTimeCompare()

用途

2つの日時値を比較します。

構文

sword OCIDateTimeCompare ( void               *hndl,
OCIError           *err,
const OCIDateTime  *date1,
const OCIDateTime  *date2,
sword              *result );

パラメータ

hndl (IN/OUT)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date1、date2 (IN)

比較する日付です。

result (OUT)

表19-8に示したような比較結果です。

表19-8 OCIDateTimeCompare()のresultパラメータによって戻される比較結果

比較結果

resultパラメータの出力

date1 < date2

-1

date1 = date2

0

date1 > date2

1

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (無効な日付が使用されている場合または入力日付引数が相互に比較可能な型でない場合)。

関連関数

OCIDateTimeConstruct()

OCIDateTimeConstruct()

用途

日時記述子を作成します。

構文

sword OCIDateTimeConstruct ( void          *hndl,
OCIError      *err,
OCIDateTime   *datetime,
sb2           year,
ub1           month,
ub1           day,
ub1           hour,
ub1           min,
ub1           sec,
ub4           fsec,
OraText       *timezone,
size_t        timezone_length );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

datetime (IN)

OCIDateTime記述子へのポインタです。

year (IN)

年の値です。

month (IN)

月の値です。

day (IN)

日の値です。

hour (IN)

時間の値です。

min (IN)

分の値です。

sec (IN)

秒の値です。

fsec (IN)

小数秒の値です。

timezone (IN)

タイム・ゾーン文字列です。タイム・ゾーン置換の文字列表現は、[+|-][HH:MM]という書式での、現地時間とUTC (協定世界時、以前はグリニッジ平均時)との差異(時分による)です。たとえば、「-08:00」。

timezone_length (IN)

タイム・ゾーン文字列の長さです。

コメント

日時の型は、OCIDateTime記述子の型です。型に基づいた関連フィールドのみを使用します。タイム・ゾーンを持つ型の場合、日付フィールドと時刻フィールドは、指定されたタイム・ゾーンのローカル・タイムとみなされます。

タイム・ゾーンが指定されていない場合は、セッションのデフォルト・タイム・ゾーンが使用されます。

戻り値

OCI_SUCCESS、OCI_ERROR (日時が無効な場合)。

関連関数

OCIDateTimeAssign()、OCIDateTimeConvert()

OCIDateTimeConvert()

用途

ある日時型を別の日時型に変換します。

構文

sword OCIDateTimeConvert ( void         *hndl,
OCIError     *err,
OCIDateTime  *indate,
OCIDateTime  *outdate );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

indate (IN)

入力日付へのポインタです。

outdate (OUT)

出力日時へのポインタです。

コメント

この関数は、ある日時型を別の日時型に変換します。結果タイプは、outdate記述子の型になります。タイム・ゾーンを持たない日時をタイム・ゾーンを持つ日時に変換する場合は、セッションのデフォルト・タイム・ゾーン(ORA_SDTZ)が使用されます。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLの場合)、OCI_ERROR (指定の入力値では変換が不可能な場合)。

関連関数

OCIDateTimeCheck()

OCIDateTimeFromArray()

用途

日付が含まれている配列をOCIDateTime 記述子に変換します。

構文

sword OCIDateTimeFromArray ( void               *hndl,
OCIError           *err,
const ub1          *inarray,
ub4                *len
ub1                type,
OCIDateTime        *datetime,
const OCIInterval  *reftz,
ub1                fsprec );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

inarray (IN)

日付が含まれるub1の配列です。

len (IN)

inarrayの長さです。

type (IN)

結果の日時の型です。配列は、特定のSQLT型に変換されます。

datetime (OUT)

OCIDateTime記述子へのポインタです。

reftz (IN)

SQLT_TIMESTAMP_LTZ型の変換時に参照として使用するOCIIntervalの記述子です。

fsprec (IN)

結果の日時の小数秒の精度です。

戻り値

OCI_SUCCESS、OCI_ERROR (typeが無効な場合)。

関連関数

OCIDateTimeFromText()、OCIDateTimeToArray()

OCIDateTimeFromText()

用途

指定された書式に従って、指定の文字列をOCIDateTime記述子のOracle日時型に変換します。

構文

sword OCIDateTimeFromText ( void               *hndl,
OCIError           *err,
const OraText      *date_str,
size_t             dstr_length,
const OraText      *fmt,
ub1                fmt_length,
const OraText      *lang_name,
size_t             lang_length,
OCIDateTime        *datetime );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。ユーザー・セッション・ハンドルが渡されると、セッションのNLS_LANGUAGEおよびセッションのNLS_CALENDARで変換が行われます。渡されない場合は、デフォルトが使用されます。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date_str (IN)

Oracle日時に変換される入力文字列です。

dstr_length (IN)

入力文字列のサイズです。長さが–1の場合、date_strはNULLで終了する文字列として処理されます。

fmt (IN)

変換書式です。fmtがNULLポインタの場合、文字列は日時型のデフォルトの書式になります。

fmt_length (IN)

fmtパラメータの長さです。

lang_name (IN)

日および月の名前と略称が指定される際の言語を指定します。lang_nameがNULL (lang_name = (text *)0)の場合は、セッションのデフォルト言語が使用されます。

lang_length (IN)

lang_nameパラメータの長さです。

datetime (OUT)

日付に変換された指定文字列です。

コメント

書式引数の詳細は、『Oracle Database SQL言語リファレンス』のTO_DATE変換関数の説明を参照してください。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLの場合)、OCI_ERROR (次のいずれかの場合)。

- 無効な書式が使用されている場合。

- 不明な言語が使用されている場合。

- 無効な入力文字列が使用されている場合。

関連関数

OCIDateTimeToText()、OCIDateTimeFromArray()。

OCIDateTimeGetDate()

用途

日時値の日付部分(年、月、日)を取得します。

構文

void OCIDateTimeGetDate ( void               *hndl,
OCIError           *err,
const OCIDateTime  *datetime,
sb2                *year,
ub1                *month,
ub1                *day );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

datetime (IN)

日付情報が取り出されるOCIDateTime記述子へのポインタです。

year (OUT)

month (OUT)

day (OUT)

取り出された年、月および日の値です。

コメント

この関数は、日時値の日付部分(年、月、日)を取得します。

戻り値

OCI_SUCCESS、OCI_ERROR (入力型がSQLT_TIMEまたはOCI_TIME_TZの場合)。

関連関数

OCIDateTimeGetTime()

OCIDateTimeGetTime()

用途

日時値の時刻部分(時間、分、秒、小数秒)を取得します。

構文

void OCIDateTimeGetTime ( void          *hndl,
OCIError      *err,
OCIDateTime   *datetime,
ub1           *hour,
ub1           *min,
ub1           *sec,
ub4           *fsec );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

datetime (IN)

時刻情報が取り出されるOCIDateTime記述子へのポインタです。

hour (OUT)

取り出される時間の値です。

min (OUT)

取り出される分の値です。

sec (OUT)

取り出される秒の値です。

fsec (OUT)

取り出される小数秒の値です。

コメント

この関数は、指定の日時値から時刻部分(時間、分、秒、小数秒)を取得します。

この関数は、指定の日時に時間情報が含まれていない場合はエラーを戻します。

戻り値

OCI_SUCCESS、OCI_ERROR (日時に時間(SQLT_DATE)が含まれていない場合)。

関連関数

OCIDateTimeGetDate()

OCIDateTimeGetTimeZoneName()

用途

日時のタイム・ゾーン名部分を取得します。

構文

void OCIDateTimeGetTimeZoneName ( void               *hndl,
OCIError           *err,
const OCIDateTime  *datetime,
ub1                *buf,
ub4                *buflen, );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

datetime (IN)

OCIDateTime記述子へのポインタです。

buf (OUT)

取り出されたタイム・ゾーン名を格納するバッファです。

buflen (IN/OUT)

(IN)はバッファのサイズです。(OUT)は名前フィールドのサイズです。

コメント

この関数は、指定の日時値から時刻部分(時間、分、秒、小数秒)を取得します。

この関数は、指定の日時に時間情報が含まれていない場合はエラーを戻します。

戻り値

OCI_SUCCESS、OCI_ERROR (日時にタイム・ゾーン(SQLT_DATE、SQLT_TIMESTAMP)が含まれていない場合)。

関連関数

OCIDateTimeGetDate()、OCIDateTimeGetTimeZoneOffset()

OCIDateTimeGetTimeZoneOffset()

用途

日時値のタイム・ゾーン(時間、分)部分を取得します。

構文

void OCIDateTimeGetTimeZoneOffset ( void               *hndl,
OCIError           *err,
const OCIDateTime  *datetime,
sb1                *hour,
sb1                *min, );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

datetime (IN)

OCIDateTime記述子へのポインタです。

hour (OUT)

取り出されるタイム・ゾーンの時間の値です。

min (OUT)

取り出されるタイム・ゾーンの分の値です。

コメント

この関数は、指定の日時値からタイム・ゾーンの時間と分の部分を取得します。

この関数は、指定の日時に時間情報が含まれていない場合はエラーを戻します。

戻り値

OCI_SUCCESS、OCI_ERROR (日時にタイム・ゾーン(SQLT_DATE、SQLT_TIMESTAMP)が含まれていない場合)。

関連関数

OCIDateTimeGetDate()、OCIDateTimeGetTimeZoneName()

OCIDateTimeIntervalAdd()

用途

時間隔を日時に加算して、結果の日時を生成します。

構文

sword OCIDateTimeIntervalAdd ( void         *hndl,
OCIError     *err,
OCIDateTime  *datetime,
OCIInterval  *inter,
OCIDateTime  *outdatetime );

パラメータ

hndl (IN)

ユーザー・セッション・ハンドルまたは環境ハンドルです。セッション・ハンドルが渡されると、セッションのデフォルト・カレンダで加算が行われます。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

datetime (IN)

入力日時へのポインタです。

inter (IN)

入力時間隔へのポインタです。

outdatetime (OUT)

出力日時へのポインタです。出力日時と入力日時の型は同じになります。

戻り値

OCI_SUCCESS (関数が正常に完了した場合)、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (結果の日付が紀元前4713年1月1日より前、または9999年12月31日より後の場合)。

関連関数

OCIDateTimeIntervalSub()

OCIDateTimeIntervalSub()

用途

日時から時間隔を減算して、その結果を日時に格納します。

構文

sword OCIDateTimeIntervalSub ( void         *hndl,
OCIError     *err,
OCIDateTime  *datetime,
OCIInterval  *inter,
OCIDateTime  *outdatetime );

パラメータ

hndl (IN)

ユーザー・セッション・ハンドルまたは環境ハンドルです。セッション・ハンドルが渡されると、セッションのデフォルト・カレンダで減算が行われます。時間隔は、セッション・カレンダ内であるとみなされます。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

datetime (IN)

入力日時値へのポインタです。

inter (IN)

入力時間隔へのポインタです。

outdatetime (OUT)

出力日時へのポインタです。出力日時と入力日時の型は同じになります。

戻り値

OCI_SUCCESS (関数が正常に完了した場合)、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (結果の日付が紀元前4713年1月1日より前、または9999年12月31日より後の場合)。

関連関数

OCIDateTimeIntervalAdd()

OCIDateTimeSubtract()

用途

2つの日時を入力値にして、その差異を時間隔に格納します。

構文

sword OCIDateTimeSubtract ( void         *hndl,
OCIError     *err,
OCIDateTime  *indate1,
OCIDateTime  *indate2,
OCIInterval  *inter );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

indate1(IN)

減数(減算する数)へのポインタです。

indate2(IN)

被減数(減算される数)へのポインタです。

inter (OUT)

出力時間隔へのポインタです。

戻り値

OCI_SUCCESS (関数が正常に完了した場合)、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (入力日時が比較可能な型でない場合)。

関連関数

OCIDateTimeCompare()

OCIDateTimeSysTimeStamp()

用途

現行のシステム日付および時刻を、タイム・ゾーン付きタイムスタンプとして取得します。

構文

sword OCIDateTimeSysTimeStamp ( void           *hndl,
OCIError       *err,
OCIDateTime    *sys_date );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sys_date (OUT)

出力タイムスタンプへのポインタです。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)。

関連関数

OCIDateSysDate()

OCIDateTimeToArray()

用途

OCIDateTime記述子を配列に変換します。

構文

sword OCIDateTimeToArray ( void               *hndl,
OCIError           *err,
const OCIDateTime  *datetime,
const OCIInterval  *reftz,
ub1                *outarray,
ub4                *len
ub1                fsprec );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

datetime (IN)

OCIDateTime記述子へのポインタです。

reftz (IN)

SQL_TIMESTAMP_LTZ型の変換時に参照として使用するOCIIntervalの記述子です。

outarray (OUT)

日付が含まれるバイトの配列です。

len (OUT)

outarrayの長さです。

fsprec (IN)

配列の小数秒の精度です。

コメント

OCIによって配列が割り当てられ、その長さが戻されます。

戻り値

OCI_SUCCESS、OCI_ERROR (日時が無効な場合)。

関連関数

OCIDateTimeToText()、OCIDateTimeFromArray()

OCIDateTimeToText()

用途

指定された日付を指定の書式の文字列に変換します。

構文

sword OCIDateTimeToText ( void                *hndl,
OCIError            *err,
const OCIDateTime   *date,
const OraText       *fmt,
ub1                 fmt_length,
ub1                 fsprec,
const OraText       *lang_name,
size_t              lang_length,
ub4                 *buf_size,
OraText             *buf );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。ユーザー・セッション・ハンドルが渡されると、セッションのNLS_LANGUAGEおよびセッションのNLS_CALENDARで変換が行われます。渡されない場合は、デフォルトが使用されます。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date (IN)

変換するOracle日時値です。

fmt (IN)

変換書式です。NULL文字列ポインタ(text*)0の場合、日付は、その型に対するデフォルトの書式で文字列に変換されます。

fmt_length (IN)

fmtパラメータの長さです。

fsprec (IN)

戻される小数秒値の精度を指定します。

lang_name (IN)

日および月の名前と略称が戻される際の言語を指定します。lang_nameがNULL (lang_name = (OraText *)0)の場合は、セッションのデフォルト言語が使用されます。

lang_length (IN)

lang_nameパラメータの長さです。

buf_size (IN/OUT)

(IN)はbufバッファのサイズです。

(OUT)は変換結果の文字列のサイズです。

buf (OUT)

変換された文字列が配置されるバッファです。

コメント

書式および多言語引数の詳細は、『Oracle Database SQL言語リファレンス』のTO_DATE変換関数の説明を参照してください。変換されてNULL文字で終了する日付文字列は、bufバッファに格納されます。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLの場合)、OCI_ERROR (次のいずれかの場合)。

- バッファが小さすぎる場合。

- 無効な書式が使用されている場合。

- 不明な言語が使用されている場合。

- オーバーフロー・エラーがある場合。

関連関数

OCIDateTimeFromText()

OCIDateToText()

用途

日付型を文字列に変換します。

構文

sword OCIDateToText ( OCIError                  *err,
const OCIDate             *date,
const OraText             *fmt,
ub1                       fmt_length,
const OraText             *lang_name,
ub4                       lang_length,
ub4                       *buf_size,
OraText                   *buf );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date (IN)

変換するOracle日付です。

fmt (IN)

変換書式です。NULL、つまり(text *)0の場合、日付はデフォルトの日付書式DD-MON-YYの文字列に変換されます。

fmt_length (IN)

fmtパラメータの長さです。

lang_name (IN)

月および日の名前と略称が戻される際の言語を指定します。lang_nameがNULL ((text *)0)の場合は、セッションのデフォルト言語が使用されます。

lang_length (IN)

lang_nameパラメータの長さです。

buf_size (IN/OUT)

バッファのサイズです(IN)。このパラメータ(OUT)に、結果の文字列のサイズが戻されます。

buf (OUT)

変換された文字列が配置されるバッファです。

コメント

指定された日付を指定の書式の文字列に変換します。変換されてNULLで終了する日付文字列は、bufに格納されます。

書式および多言語引数の詳細は、『Oracle Database SQL言語リファレンス』のTO_DATE変換関数の説明を参照してください。

戻り値

この関数は、バッファが小さすぎる場合または無効な書式や認識できない言語が渡された場合はエラーを戻します。オーバーフローもエラーの原因となります。たとえば、値10を書式9に変換すると、エラーが発生します。

関連関数

OCIErrorGet()、OCIDateFromText()

OCIDateZoneToZone()

用途

あるタイム・ゾーンの日付を別のタイム・ゾーンの日付に変換します。

構文

sword OCIDateZoneToZone ( OCIError           *err,
const OCIDate      *date1,
const OraText      *zon1,
ub4                zon1_length,
const OraText      *zon2,
ub4                zon2_length,
OCIDate            *date2 );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

date1 (IN)

変換する日付です。

zon1 (IN)

入力日付のゾーンです。

zon1_length (IN)

zon1のバイト長です。

zon2 (IN)

変換先のゾーンです。

zon2_length (IN)

zon2のバイト長です。

date2 (OUT)

zon2での変換日付です。

コメント

タイム・ゾーンzon1の指定の日付date1を、タイム・ゾーンzon2の日付date2に変換します。北米のタイム・ゾーンのみが対象です。

有効なゾーン文字列のリストは、『Oracle Database SQL言語リファレンス』のNEW_TIME関数の説明を参照してください。有効なゾーン文字列の例を次に示します。

- AST (大西洋標準時)

- ADT (大西洋夏時間)

- BST (ベーリング標準時)

- BDT (ベーリング夏時間)

戻り値

この関数は、無効な日付またはタイム・ゾーンが渡された場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIDateCheck()

OCIIntervalAdd()

用途

2つの時間隔を加算して、結果の時間隔を生成します。

構文

sword OCIIntervalAdd ( void         *hndl,
OCIError     *err,
OCIInterval  *addend1,
OCIInterval  *addend2,
OCIInterval  *result );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

addend1 (IN)

加算する時間隔です。

addend2 (IN)

加算する時間隔です。

result (OUT)

加算結果の時間隔(addend1 + addend2)です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (次のいずれかの場合)。

- 入力された2つの時間隔が相互に比較可能でない場合。

- 結果の年がSB4MAXVALを超える場合。

- 結果の年がSB4MINVALを下回る場合。

関連関数

OCIIntervalSubtract()

OCIIntervalAssign()

用途

ある時間隔を別の時間隔にコピーします。

構文

void OCIIntervalAssign ( void              *hndl,
OCIError          *err,
const OCIInterval *inpinter,
OCIInterval       *outinter );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

inpinter (IN)

入力時間隔です。

outinter (OUT)

出力時間隔です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)。

関連関数

OCIIntervalCompare()

OCIIntervalCheck()

用途

時間隔の妥当性をチェックします。

構文

sword OCIIntervalCheck ( void               *hndl,
OCIError            *err,
const OCIInterval   *interval,
ub4                 *valid );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

interval (IN)

チェックする時間隔です。

valid (OUT)

時間隔が有効な場合は0 (ゼロ)を戻します。それ以外の場合は、表19-9に指定されたコードの論理演算子ORによる組合せを戻します。

表19-9 OCIIntervalCheck()の有効なパラメータによって戻されるエラー・ビット

マクロ名

ビット数

エラー

OCI_INTER_INVALID_DAY

0x1

無効な日。

OCI_INTER_DAY_BELOW_VALID

0x2

無効な日の、有効な日に対する大/小を示すビット(1=小)。

OCI_INTER_INVALID_MONTH

0x4

無効な月。

OCI_INTER_MONTH_BELOW_VALID

0x8

無効な月の、有効な月に対する大/小を示すビット(1=小)。

OCI_INTER_INVALID_YEAR

0x10

無効な年。

OCI_INTER_YEAR_BELOW_VALID

0x20

無効な年の、有効な年に対する大/小を示すビット(1=小)。

OCI_INTER_INVALID_HOUR

0x40

無効な時刻(時)。

OCI_INTER_HOUR_BELOW_VALID

0x80

無効な時刻(時)の、有効な時刻(時)に対する大/小を示すビット(1=小)。

OCI_INTER_INVALID_MINUTE

0x100

無効な時刻(分)。

OCI_INTER_MINUTE_BELOW_VALID

0x200

無効な時刻(分)の、有効な時刻(分)に対する大/小を示すビット(1=小)。

OCI_INTER_INVALID_SECOND

0x400

無効な時刻(秒)。

OCI_INTER_SECOND_BELOW_VALID

0x800

無効な時刻(秒)の、有効な時刻(秒)に対する大/小を示すビット(1=小)。

OCI_INTER_INVALID_FRACSEC

0x1000

無効な小数秒。

OCI_INTER_FRACSEC_BELOW_VALID

0x2000

無効な時刻(小数秒)の、有効な時刻(小数秒)に対する大/小を示すビット(1=小)

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (エラーの場合)。

関連関数

OCIIntervalCompare()

OCIIntervalCompare()

用途

2つの時間隔を比較します。

構文

sword OCIIntervalCompare (void          *hndl,
OCIError      *err,
OCIInterval   *inter1,
OCIInterval   *inter2,
sword         *result );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

inter1 (IN)

比較する時間隔です。

inter2 (IN)

比較する時間隔です。

result (OUT)

表19-10に指定したような比較結果です。

表19-10 OCIIntervalCompare()のresultパラメータによって戻される比較結果

比較結果

resultパラメータの出力

inter1 < inter2

-1

inter1 = inter2

0

inter1 > inter2

1

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (入力値が相互に比較可能でない場合)。

関連関数

OCIIntervalAssign()

OCIIntervalDivide()

用途

時間隔をOracle NUMBERで除算して、時間隔を生成します。

構文

sword OCIIntervalDivide ( void         *hndl,
OCIError     *err,
OCIInterval  *dividend,
OCINumber    *divisor,
OCIInterval  *result );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

dividend (IN)

除算する時間隔です。

divisor (IN)

dividendを除算するOracle NUMBERです。

result (OUT)

除算結果の時間隔(dividend / divisor)です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)。

関連関数

OCIIntervalMultiply()

OCIIntervalFromNumber()

用途

Oracle NUMBERを時間隔に変換します。

構文

sword OCIIntervalFromNumber ( void               *hndl,
OCIError           *err,
OCIInterval        *interval,
OCINumber          *number );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

interval (OUT)

結果の時間隔です。

number (IN)

変換するOracle NUMBER (YEAR TO MONTH時間隔の場合は年数、DAY TO SECOND時間隔の場合は日数)です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)。

関連関数

OCIIntervalToNumber()

OCIIntervalFromText()

用途

時間隔文字列が指定されている場合、その文字列で表現される時間隔を戻します。時間隔の型は、result記述子の型です。

構文

sword OCIIntervalFromText ( void           *hndl,
OCIError       *err,
const OraText  *inpstring,
size_t         str_len,
OCIInterval    *result );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

inpstring (IN)

入力文字列です。

str_len (IN)

入力文字列の長さです。

result (OUT)

結果の時間隔です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (次のいずれかの場合)。

- リテラル文字列のフィールドが多すぎる場合。

- 年が範囲(–4713から9999)外の場合。

- 月が範囲(1から12)外の場合。

- 1か月の日が範囲(1から28...31)外の場合。

- 時間が範囲(0から23)外の場合。

- 時間が範囲(0から11)外の場合。

- 分が範囲(0から59)外の場合。

- 1分の秒が範囲(0から59)外の場合。

- 1日の秒が範囲(0から86399)外の場合。

- 時間隔が無効な場合。

関連関数

OCIIntervalToText()

OCIIntervalFromTZ()

用途

OCIIntervalデータ型のOCI_DTYPE_INTERVAL_DSを、設定されているリージョンID (入力文字列にリージョンが指定されている場合)と現行の絶対オフセット、またはリージョンIDが0 (ゼロ)に設定されている絶対オフセットとともに戻します。

構文

sword OCIIntervalFromTZ ( void           *hndl,
OCIError       *err,
const oratext  *inpstring,
size_t         str_len,
OCIInterval    *result ) ;

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

inpstring (IN)

入力文字列へのポインタです。

str_len (IN)

inpstringの長さです。

result (OUT)

出力時間隔です。

戻り値

OCI_SUCCESS (成功した場合)、OCI_INVALID_HANDLE (errがNULLの場合)、OCI_ERROR (無効な時間隔型、またはタイム・ゾーン・エラーがある場合)。

コメント

入力文字列は、[+/-]TZH:TZMまたは'TZR [TZD]'の形式であることが必要です。

関連関数

OCIIntervalFromText()

OCIIntervalGetDaySecond()

用途

時間隔から日、時、分、秒の値を取得します。

構文

sword OCIIntervalGetDaySecond (void               *hndl,
OCIError           *err,
sb4                *dy,
sb4                *hr,
sb4                *mm,
sb4                *ss,
sb4                *fsec,
const OCIInterval  *interval );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

dy (OUT)

日数です。

hr (OUT)

時間数です。

mm (OUT)

分数です。

ss (OUT)

秒数です。

fsec (OUT)

小数秒の数です。

interval (IN)

入力時間隔です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)。

関連関数

OCIIntervalSetDaySecond()

OCIIntervalGetYearMonth()

用途

時間隔から年と月を取得します。

構文

sword OCIIntervalGetYearMonth ( void               *hndl,
OCIError           *err,
sb4                *yr,
sb4                *mnth,
const OCIInterval  *interval );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

yr (OUT)

年の値です。

mnth (OUT)

月の値です。

interval (IN)

入力時間隔です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)。

関連関数

OCIIntervalSetYearMonth()

OCIIntervalMultiply()

用途

時間隔をOracle NUMBERで乗算して、時間隔を生成します。

構文

sword OCIIntervalMultiply ( void               *hndl,
OCIError           *err,
const OCIInterval  *inter,
OCINumber          *nfactor,
OCIInterval        *result );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

inter (IN)

乗算する時間隔です。

nfactor (IN)

乗算するOracle NUMBERです。

result (OUT)

乗算結果の時間隔(inter * nfactor)です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (次のいずれかの場合)。

- 結果の年がSB4MAXVALを超える場合。

- 結果の年がSB4MINVALを下回る場合。

関連関数

OCIIntervalDivide()

OCIIntervalSetDaySecond()

用途

時間隔に日、時、分、秒を設定します。

構文

sword OCIIntervalSetDaySecond ( void               *hndl,
OCIError           *err,
sb4                dy,
sb4                hr,
sb4                mm,
sb4                ss,
sb4                fsec,
OCIInterval        *result );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

dy (IN)

日数です。

hr (IN)

時間数です。

mm (IN)

分数です。

ss (IN)

秒数です。

fsec (IN)

小数秒の数です。

result (OUT)

結果の時間隔です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)。

関連関数

OCIIntervalGetDaySecond()

OCIIntervalSetYearMonth()

用途

時間隔に年と月を設定します。

構文

sword OCIIntervalSetYearMonth ( void               *hndl,
OCIError           *err,
sb4                yr,
sb4                mnth,
OCIInterval        *result );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

yr (IN)

年の値です。

mnth (IN)

月の値です。

result (OUT)

結果の時間隔です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (次のいずれかの場合)。

- 結果の年がSB4MAXVALを超える場合。

- 結果の年がSB4MINVALを下回る場合。

関連関数

OCIIntervalGetYearMonth()

OCIIntervalSubtract()

用途

2つの時間隔を減算し、その結果を時間隔に格納します。

構文

sword OCIIntervalSubtract ( void         *hndl,
OCIError     *err,
OCIInterval  *minuend,
OCIInterval  *subtrahend,
OCIInterval  *result );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

minuend (IN)

減算される時間隔です。

subtrahend (IN)

minuendから減算する時間隔です。

result (OUT)

減算結果の時間隔(minuend - subtrahend)です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (次のいずれかの場合)。

- 結果の年がSB4MAXVALを超える場合。

- 結果の年がSB4MINVALを下回る場合。

- 入力された2つの時間隔が相互に比較可能でない場合。

関連関数

OCIIntervalAdd()

OCIIntervalToNumber()

用途

時間隔をOracle NUMBERに変換します。

構文

sword OCIIntervalToNumber ( void               *hndl,
OCIError           *err,
OCIInterval        *interval,
OCINumber          *number );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

interval (IN)

変換する時間隔です。

number (OUT)

Oracle NUMBERの変換結果(YEARMONTH時間隔の年、およびDAYSECONDの日)です。

コメント

変換されたOracle NUMBERには、日付の小数部分(たとえば、選択した単位が時間の場合は分と秒)が含まれます。精度を超える部分は切り捨てられます。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)。

関連関数

OCIIntervalFromNumber()

OCIIntervalToText()

用途

時間隔が指定されている場合、その時間隔を表現する文字列を生成します。

構文

sword OCIIntervalToText ( void               *hndl,
OCIError           *err,
const OCIInterval  *interval,
ub1                lfprec,
ub1                fsprec,
OraText            *buffer,
size_t             buflen,
size_t             *resultlen );

パラメータ

hndl (IN)

OCIユーザー・セッション・ハンドルまたは環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

interval (IN)

変換する時間隔です。

lfprec (IN)

先行フィールド精度を指定します。(先行フィールドを表すのに使用される桁数です)。

fsprec (IN)

時間隔の小数秒精度(小数秒を表すのに使用される桁数)です。

buffer (OUT)

結果を保持するバッファです。

buflen (IN)

bufferの長さです。

resultlen (OUT)

bufferに格納された結果の長さです。

コメント

時間隔リテラルは、INTERVAL YEAR TO MONTH時間隔の'年'または'[年-]月'、およびINTERVAL DAY TO SECOND時間隔の'秒'、'分[:秒]'、'時間[:分[:秒]]'または'日[ 時間[:分[:秒]]]'として出力されます(大カッコで囲まれているフィールドはオプションです)。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE (errがNULLポインタの場合)、OCI_ERROR (バッファ領域が不足しているため結果を保持できない場合)。

関連関数

OCIIntervalFromText()

OCI NUMBER関数

表19-11は、この項で説明しているOCI NUMBER関数を示しています。

関連項目:
「OCINumberの例」

表19-11 NUMBER関数

関数

用途

「OCINumberAbs()」

絶対値を計算します。

「OCINumberAdd()」

NUMBERを加算します。

「OCINumberArcCos()」

アーク・コサインを計算します。

「OCINumberArcSin()」

アーク・サインを計算します。

「OCINumberArcTan()」

アーク・タンジェントを計算します。

「OCINumberArcTan2()」

2つのNUMBERのアーク・タンジェントを計算します。

「OCINumberAssign()」

1つのNUMBERを別のNUMBERに代入します。

「OCINumberCeil()」

NUMBERの上限値を計算します。

「OCINumberCmp()」

NUMBERを比較します。

「OCINumberCos()」

コサインを計算します。

「OCINumberDec()」

NUMBERを減分します。

「OCINumberDiv()」

2つのNUMBERを除算します。

「OCINumberExp()」

eを指定のOracle NUMBERで累乗します。

「OCINumberFloor()」

NUMBERの下限値を計算します。

「OCINumberFromInt()」

整数をOracle NUMBERに変換します。

「OCINumberFromReal()」

実数型をOracle NUMBERに変換します。

「OCINumberFromText()」

文字列をOracle NUMBERに変換します。

「OCINumberHypCos()」

双曲線コサインを計算します。

「OCINumberHypSin()」

双曲線サインを計算します。

「OCINumberHypTan()」

双曲線タンジェントを計算します。

「OCINumberInc()」

Oracle NUMBERを増分します。

「OCINumberIntPower()」

指定の基数を整数で累乗します。

「OCINumberIsInt()」

NUMBERが整数かどうかをテストします。

「OCINumberIsZero()」

NUMBERが0 (ゼロ)かどうかを確認します。

「OCINumberLn()」

自然対数を計算します。

「OCINumberLog()」

任意の基数に対する対数を計算します。

「OCINumberMod()」

2つのOracle NUMBERの除算の余り(剰余)を取得します。

「OCINumberMul()」

2つのOracle NUMBERを乗算します。

「OCINumberNeg()」

Oracle NUMBERを負の数にします。

「OCINumberPower()」

指定の基数を指定の指数で累乗します。

「OCINumberPrec()」

NUMBERを指定の小数点以下の桁数に丸めます。

「OCINumberRound()」

Oracle NUMBERを指定の小数点以下の桁数に丸めます。

「OCINumberSetPi()」

NUMBERをpiに初期化します。

「OCINumberSetZero()」

NUMBERを0 (ゼロ)に初期化します。

「OCINumberShift()」

10の累乗を乗算し、小数点以下を指定の桁数にします。

「OCINumberSign()」

Oracle NUMBERの符号を取得します。

「OCINumberSin()」

サインを計算します。

「OCINumberSqrt()」

NUMBERの平方根を計算します。

「OCINumberSub()」

NUMBERを減算します。

「OCINumberTan()」

タンジェントを計算します。

「OCINumberToInt()」

Oracle NUMBERを整数に変換します。

「OCINumberToReal()」

Oracle NUMBERを実数型に変換します。

「OCINumberToRealArray()」

NUMBERの配列を実際の配列に変換します。

「OCINumberToText()」

Oracle NUMBERを文字列に変換します。

「OCINumberTrunc()」

Oracle NUMBERを指定の小数点以下の桁数で切り捨てます。

OCINumberAbs()

用途

Oracle NUMBERの絶対値を計算します。

構文

sword OCINumberAbs ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

入力NUMBERです。

result (OUT)

入力NUMBERの絶対値です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()

OCINumberAdd()

用途

2つのOracle NUMBERを加算します。

構文

sword OCINumberAdd ( OCIError              *err,
const OCINumber       *number1,
const OCINumber       *number2,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number1、number2 (IN)

加算されるNUMBERです。

result (OUT)

number1をnumber2に加算した結果です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberSub()

OCINumberArcCos()

用途

Oracle NUMBERのアーク・コサインをラジアン単位で求めます。

構文

sword OCINumberArcCos ( OCIError            *err,
const OCINumber     *number,
OCINumber           *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

アーク・コサインの引数です。

result (OUT)

ラジアンのアーク・コサインの結果です。

戻り値

この関数は、NULLのNUMBER引数がある場合、またはnumberが–1より小さいか–numberが1より大きい場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberCos()

OCINumberArcSin()

用途

Oracle NUMBERのアーク・サインをラジアン単位で求めます。

構文

sword OCINumberArcSin ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

アーク・サインの引数です。

result (OUT)

ラジアンのアーク・サインの結果です。

戻り値

この関数は、NULLのNUMBER引数がある場合、またはnumberが–1より小さいか–numberが1より大きい場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberSin()

OCINumberArcTan()

用途

Oracle NUMBERのアーク・タンジェントをラジアン単位で求めます。

構文

sword OCINumberArcTan ( OCIError             *err,
const OCINumber      *number,
OCINumber            *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

アーク・タンジェントの引数です。

result (OUT)

ラジアンのアーク・タンジェントの結果です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberTan()

OCINumberArcTan2()

用途

2つのOracle NUMBERのアーク・タンジェントを求めます。

構文

sword OCINumberArcTan2 ( OCIError              *err,
const OCINumber       *number1,
const OCINumber       *number2,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number1 (IN)

アーク・タンジェントの引数1です。

number2 (IN)

アーク・タンジェントの引数2です。

result (OUT)

ラジアンのアーク・タンジェントの結果です。

戻り値

この関数は、NULLのNUMBER引数がある場合、またはnumber2が0 (ゼロ)の場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberTan()

OCINumberAssign()

用途

1つのOracle NUMBERを別のOracle NUMBERに代入します。

構文

sword OCINumberAssign ( OCIError              *err,
const OCINumber       *from,
OCINumber             *to );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

from (IN)

割当て対象のNUMBERです。

to (OUT)

コピー先のNUMBERです。

コメント

fromによって識別されたNUMBERをtoによって識別されたNUMBERに代入します。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberCmp()

OCINumberCeil()

用途

Oracle NUMBERの上限値を計算します。

構文

sword OCINumberCeil ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

入力NUMBERです。

result (OUT)

入力NUMBERの上限値を含む出力です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberFloor()

OCINumberCmp()

用途

2つのOracle NUMBERを比較します。

構文

sword OCINumberCmp ( OCIError            *err,
const OCINumber     *number1,
const OCINumber     *number2,
sword               *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number1、number2 (IN)

比較するNUMBERです。

result (OUT)

表19-12に指定したような比較結果です。

表19-12 OCINumberCmp()のresultパラメータによって戻される比較結果

比較結果

resultパラメータの出力

number1 < number2

負数

number1 = number2

0

number1 > number2

正数

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberAssign()

OCINumberCos()

用途

Oracle NUMBERのコサインをラジアン単位で計算します。

構文

sword OCINumberCos ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

ラジアンのコサインの引数です。

result (OUT)

コサインの結果です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberArcCos()

OCINumberDec()

用途

Oracle NUMBERを適切に減分します。

構文

sword OCINumberDec ( OCIError  *err,
OCINumber *number );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN/OUT)

減分される正数のOracle NUMBERです。

コメント

Oracle NUMBERを適切に減分します。入力値は0から100^21-2の整数であるとみなされます。入力値が大きすぎる場合は0 (ゼロ)として扱われ、その結果、Oracle NUMBERは1になります。入力値が正の整数でない場合は、予想できない結果になります。

戻り値

この関数は、入力NUMBERにNULLがある場合はエラーを戻します。

関連関数

OCINumberInc()

OCINumberDiv()

用途

2つのOracle NUMBERを除算します。

構文

sword OCINumberDiv ( OCIError               *err,
const OCINumber        *number1,
const OCINumber        *number2,
OCINumber              *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number1 (IN)

分子へのポインタです。

number2 (IN)

分母へのポインタです。

result (OUT)

除算結果です。

コメント

number1をnumber2で除算し、その結果をresultに戻します。

戻り値

この関数は、次のいずれかの文がTRUEである場合はエラーを戻します。

- NUMBER引数にNULLがある場合。

- アンダーフロー・エラーがある場合。

- ゼロによる除算エラーがある場合。

関連関数

OCIErrorGet()、OCINumberMul()

OCINumberExp()

用途

eを指定のOracle NUMBERで累乗します。

構文

sword OCINumberExp ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

この関数は、eをこのOracle NUMBERで累乗します。

result (OUT)

指数の出力です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberLn()

OCINumberFloor()

用途

Oracle NUMBERの下限(切捨て)値を計算します。

構文

sword OCINumberFloor ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

入力NUMBERです。

result (OUT)

入力NUMBERの下限(切捨て)値です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberCeil()

OCINumberFromInt()

用途

整数をOracle NUMBERに変換します。

構文

sword OCINumberFromInt ( OCIError            *err,
const void          *inum,
uword               inum_length,
uword               inum_s_flag,
OCINumber           *number );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

inum (IN)

変換する整数へのポインタです。

inum_length (IN)

整数のサイズです。

inum_s_flag (IN)

整数の符号を指定するフラグで、可能な値は次のとおりです。

- OCI_NUMBER_UNSIGNED－ 符号なしの値

- OCI_NUMBER_SIGNED－ 符号付きの値

number (OUT)

Oracle NUMBERに変換される指定の整数です。

コメント

これは、システム固有な型変換関数です。ub4やsb2などのOracle標準システム固有の整数型をOracle NUMBERに変換します。

戻り値

この関数は、数値が大きすぎてOracle NUMBERに適合しない場合、numberまたはinumがNULLの場合、あるいはinum_s_flagに無効な符号フラグの値が渡された場合は、エラーを戻します。

関連関数

OCIErrorGet()、OCINumberToInt()

OCINumberFromReal()

用途

実数(浮動小数点数)型をOracle NUMBERに変換します。

構文

sword OCINumberFromReal ( OCIError           *err,
const void         *rnum,
uword              rnum_length,
OCINumber          *number );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

rnum (IN)

変換する浮動小数点数へのポインタです。

rnum_length (IN)

目的の結果のサイズです。sizeof({float | double | long double})に等しくなります。

number (OUT)

Oracle NUMBERに変換される指定のfloatです。

コメント

これは、システム固有な型変換関数です。システム固有の浮動小数点型をOracle NUMBERに変換します。

戻り値

この関数は、numberまたはrnumがNULLであるか、rnum_lengthが0 (ゼロ)である場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberToReal()

OCINumberFromText()

用途

文字列をOracle NUMBERに変換します。

構文

sword OCINumberFromText ( OCIError           *err,
const OraText      *str,
ub4                str_length,
const OraText      *fmt,
ub4                fmt_length,
const OraText      *nls_params,
ub4                nls_p_length,
OCINumber          *number );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

str (IN)

Oracle NUMBERに変換する入力文字列です。

str_length (IN)

入力文字列のサイズです。

fmt (IN)

変換書式です。

fmt_length (IN)

fmtパラメータの長さです。

nls_params (IN)

グローバリゼーション・サポートのフォーマット指定です。NULL文字列("")の場合は、セッションのデフォルト・パラメータが使用されます。

nls_p_length (IN)

nls_paramsパラメータの長さです。

number (OUT)

NUMBERに変換される指定の文字列です。

コメント

指定された文字列を指定の書式のNUMBERに変換します。書式および多言語パラメータの詳細は、『Oracle Database SQL言語リファレンス』のTO_NUMBER変換関数の説明を参照してください。

戻り値

この関数は、無効な書式、マルチバイト書式または入力文字列がある場合、numberまたはstrがNULLである場合、あるいはstr_lengthが0 (ゼロ)である場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberToText()

OCINumberHypCos()

用途

Oracle NUMBERの双曲線コサインを計算します。

構文

sword OCINumberHypCos ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

コサイン双曲線の引数です。

result (OUT)

コサイン双曲線の結果です。

戻り値

この関数は、number引数のいずれかにNULLがある場合はエラーを戻します。

注意:
Oracle NUMBERのオーバーフローは、予想できない結果値が出力される原因となります。

関連関数

OCIErrorGet()、OCINumberHypSin()、OCINumberHypTan()

OCINumberHypSin()

用途

Oracle NUMBERの双曲線サインを計算します。

構文

sword OCINumberHypSin ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

サイン双曲線の引数です。

result (OUT)

サイン双曲線の結果です。

戻り値

この関数は、NUMBER引数のいずれかにNULLがある場合はエラーを戻します。

注意:
Oracle NUMBERのオーバーフローは、予想できない結果値が出力される原因となります。

関連関数

OCIErrorGet()、OCINumberHypCos()、OCINumberHypTan()

OCINumberHypTan()

用途

Oracle NUMBERの双曲線タンジェントを計算します。

構文

sword OCINumberHypTan ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

タンジェント双曲線の引数です。

result (OUT)

タンジェント双曲線の結果です。

戻り値

この関数は、NUMBER引数のいずれかにNULLがある場合はエラーを戻します。

注意:
Oracle NUMBERのオーバーフローは、予想できない結果値が出力される原因となります。

関連関数

OCIErrorGet()、OCINumberHypCos()、OCINumberHypSin()

OCINumberInc()

用途

Oracle NUMBERを増分します。

構文

sword OCINumberInc ( OCIError   *err,
OCINumber  *number );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN/OUT)

増分される正数のOracle NUMBERです。

コメント

Oracle NUMBERを適切に増分します。入力値は0から100^21-2の整数であるとみなされます。入力値が大きすぎる場合は0 (ゼロ)として扱われ、その結果、Oracle NUMBERは1になります。入力値が正の整数でない場合は、予想できない結果になります。

戻り値

この関数は、入力NUMBERにNULLがある場合はエラーを戻します。

関連関数

OCINumberDec()

OCINumberIntPower()

用途

指定の基数を指定の整数で累乗します。

構文

sword OCINumberIntPower ( OCIError             *err,
const OCINumber      *base,
const sword          exp,
OCINumber            *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

base (IN)

指数の基数です。

exp (IN)

基数が累乗される指数です。

result (OUT)

指数の出力です。

戻り値

この関数は、NUMBER引数のいずれかにNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberPower()

OCINumberIsInt()

用途

OCINumberが整数かどうかをテストします。

構文

sword OCINumberIsInt ( OCIError         *err,
const OCINumber  *number,
boolean          *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

テストされるNUMBERです。

result (OUT)

整数値の場合はTRUE、それ以外の場合はFALSEに設定されます。

戻り値

この関数は、numberまたはresultがNULLの場合にエラーを戻します。

関連関数

OCIErrorGet()、OCINumberRound()、OCINumberTrunc()

OCINumberIsZero()

用途

指定のNUMBERが0 (ゼロ)に等しいかどうかをテストします。

構文

sword OCINumberIsZero ( OCIError            *err,
const OCINumber     *number,
boolean             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

比較するNUMBERです。

result (OUT)

0 (ゼロ)の場合はTRUE、それ以外の場合はFALSEが設定されます。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberSetZero()

OCINumberLn()

用途

Oracle NUMBERの自然対数(基数e)を求めます。

構文

sword OCINumberLn ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

このNUMBERの対数を計算します。

result (OUT)

対数結果です。

戻り値

この関数は、NUMBER引数がNULLのいずれかである場合、またはnumberが0 (ゼロ)以下の場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberExp()、OCINumberLog()

OCINumberLog()

用途

Oracle NUMBERの任意の基数に対する対数を求めます。

構文

sword OCINumberLog ( OCIError              *err,
const OCINumber       *base,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

base (IN)

対数の基数です。

number (IN)

演算子です。

result (OUT)

対数結果です。

戻り値

この関数は、次の場合にエラーを戻します。

- NUMBER引数にNULLがある場合

- numberの値 <= 0の場合

- baseの値 <= 0の場合

関連関数

OCIErrorGet()、OCINumberLn()

OCINumberMod()

用途

2つのOracle NUMBERの除算の余り(剰余)を取得します。

構文

sword OCINumberMod ( OCIError              *err,
const OCINumber       *number1,
const OCINumber       *number2,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number1 (IN)

分子へのポインタです。

number2 (IN)

分母へのポインタです。

result (OUT)

結果の剰余です。

戻り値

この関数は、number1またはnumber2がNULLか、0 (ゼロ)による除算エラーがある場合にエラーを戻します。

関連関数

OCIErrorGet()、OCINumberDiv()

OCINumberMul()

用途

2つのOracle NUMBERを乗算します。

構文

sword OCINumberMul ( OCIError              *err,
const OCINumber       *number1,
const OCINumber       *number2,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number1 (IN)

乗算するNUMBERです。

number2 (IN)

乗算するNUMBERです。

result (OUT)

乗算結果です。

コメント

number1にnumber2を乗算し、その結果をresultに戻します。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberDiv()

OCINumberNeg()

用途

Oracle NUMBERを負の数にします。

構文

sword OCINumberNeg ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

負の数にするNUMBERです。

result (OUT)

numberの負の値が入ります。

戻り値

この関数は、NUMBER引数のいずれかにNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberAbs()、OCINumberSign()

OCINumberPower()

用途

指定の基数を指定の指数で累乗します。

構文

sword OCINumberPower ( OCIError              *err,
const OCINumber       *base,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

base (IN)

指数の基数です。

number (IN)

基数が累乗される指数です。

result (OUT)

指数の出力です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberExp()

OCINumberPrec()

用途

OCINumberを指定の小数点以下の桁数に丸めます。

構文

sword OCINumberPrec ( OCIError *err,
const OCINumber *number,
eword nDigs,
OCINumber *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

精度を設定する数値です。

nDigs (IN)

目的の結果の小数点以下の桁数です。

result (OUT)

結果です。

コメント

桁数に基づいて、浮動小数点を丸めます。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberRound()

OCINumberRound()

用途

Oracle NUMBERを指定の小数点以下の桁数に丸めます。

構文

sword OCINumberRound ( OCIError              *err,
const OCINumber       *number,
sword                 decplace,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

丸めるNUMBERです。

decplace (IN)

丸める小数点以下の桁数です。負数も可能です。

result (OUT)

丸めた結果の出力です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberTrunc()

OCINumberSetPi()

用途

OCINumberをpiに設定します。

構文

void OCINumberSetPi ( OCIError *err,
OCINumber *num );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

num (OUT)

piの値に設定されるNUMBERです。

コメント

指定のNUMBERをpiの値に初期化します。

関連関数

OCIErrorGet()

OCINumberSetZero()

用途

Oracle NUMBERを0 (ゼロ)に初期化します。

構文

void OCINumberSetZero ( OCIError      *err
OCINumber     *num );

パラメータ

err (IN)

有効なOCIエラー・ハンドルです。関数がエラーを生成しないため、この関数はエラーをチェックしません。

num (IN/OUT)

0 (ゼロ)値に初期化するOracle NUMBERです。

コメント

なし。

関連関数

OCIErrorGet()

OCINumberShift()

用途

NUMBERを10の累乗で乗算し、小数点を指定の桁に移動します。

構文

sword OCINumberShift ( OCIError         *err,
const OCINumber  *number,
const sword      nDig,
OCINumber        *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

桁を移動するOracle NUMBERです。

nDig (IN)

移動する小数点以下の桁数です。

result (OUT)

桁を移動した結果です。

コメント

numberを10^nDigで乗算し、productに結果を設定します。

戻り値

この関数は、入力numberにNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()

OCINumberSign()

用途

Oracle NUMBERの符号を取得します。

構文

sword OCINumberSign ( OCIError             *err,
const OCINumber      *number,
sword                *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

符号が戻されるOracle NUMBERです。

result (OUT)

表19-13は、可能な戻り値を示しています。

表19-13 結果の値

numberの値

resultパラメータの出力

number < 0

-1

number == 0

0

number > 0

1

戻り値

この関数は、numberまたはresultがNULLの場合にエラーを戻します。

関連関数

OCIErrorGet()、OCINumberAbs()

OCINumberSin()

用途

Oracle NUMBERのサインをラジアン単位で計算します。

構文

sword OCINumberSin ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

ラジアン単位でのサインの引数です。

result (OUT)

サインの結果です。

戻り値

この関数は、number引数のいずれかにNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberArcSin()

OCINumberSqrt()

用途

Oracle NUMBERの平方根を計算します。

構文

sword OCINumberSqrt ( OCIError           *err,
const OCINumber     *number,
OCINumber           *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

入力NUMBERです。

result (OUT)

入力NUMBERの平方根を含む出力です。

戻り値

この関数は、numberがNULLまたは負のnumberの場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberPower()

OCINumberSub()

用途

2つのOracle NUMBERを減算します。

構文

sword OCINumberSub ( OCIError             *err,
const OCINumber      *number1,
const OCINumber      *number2,
OCINumber            *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number1、number2 (IN)

この関数は、number1からnumber2を減算します。

result (OUT)

減算結果です。

コメント

number1からnumber2を減算し、その結果をresultに戻します。

戻り値

この関数は、number引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberAdd()

OCINumberTan()

用途

Oracle NUMBERのタンジェントをラジアン単位で計算します。

構文

sword OCINumberTan ( OCIError              *err,
const OCINumber       *number,
OCINumber             *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

ラジアン単位でのタンジェントの引数です。

result (OUT)

タンジェントの結果です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberArcTan()、OCINumberArcTan2()

OCINumberToInt()

用途

Oracle NUMBER型を整数に変換します。

構文

sword OCINumberToInt ( OCIError              *err,
const OCINumber       *number,
uword                 rsl_length,
uword                 rsl_flag,
void                  *rsl );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

変換するOracle NUMBERです。

rsl_length (IN)

適切な結果のサイズです。

rsl_flag (IN)

出力値の符号を指定するフラグで、可能な値は次のとおりです。

- OCI_NUMBER_UNSIGNED－ 符号なしの値

- OCI_NUMBER_SIGNED－ 符号付きの値

rsl (OUT)

結果を保存する領域へのポインタです。

コメント

これは、システム固有な型変換関数です。指定のOracle NUMBERをub2、ub4、sb2など、xbnという書式の整数に変換します。

戻り値

この関数は、numberまたはrslがNULLの場合、numberが大きすぎる(オーバーフロー)か小さすぎる(アンダーフロー)場合、または無効な符号フラグの値がrsl_flagに渡された場合にエラーを戻します。

関連関数

OCIErrorGet()、OCINumberFromInt()

OCINumberToReal()

用途

Oracle NUMBER型を実数型に変換します。

構文

sword OCINumberToReal ( OCIError            *err,
const OCINumber     *number,
uword               rsl_length,
void                *rsl );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

変換するOracle NUMBERです。

rsl_length (IN)

目的の結果のサイズです。sizeof({float | double | long double})に等しくなります。

rsl (OUT)

結果を保存する領域へのポインタです。

コメント

これは、システム固有な型変換関数です。Oracle NUMBERをシステム固有の実数型に変換します。この関数は、最大LDBL_DIG、DBL_DIGまたはFLT_DIG桁の精度のNUMBERを変換し、後続の0 (ゼロ)を削除するだけです。これらの定数は、float.hに定義されます。

この関数に有効なOCINumberの値を渡す必要があります。それ以外の場合は、結果は保証されません。

関連関数

OCIErrorGet()、OCINumberFromReal()

OCINumberToRealArray()

用途

NUMBERの配列を実数型の配列に変換します。

構文

sword OCINumberToRealArray ( OCIError         *err,
const OCINumber  **number,
uword            elems,
uword            rsl_length,
void             *rsl );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

変換対象のNUMBERの配列へのポインタです。

elems (IN)

NUMBERポインタの最大数です。

rsl_length (IN)

目的の結果のサイズです。sizeof({ float | double | long double })に等しくなります。

rsl (OUT)

結果を保存する領域の配列へのポインタです。

コメント

Oracle NUMBERをマシン固有の実数型に変換するシステム固有な型変換関数です。この関数は、最大LDBL_DIG、DBL_DIGまたはFLT_DIG桁の精度のNUMBERを変換し、後続の0 (ゼロ)を削除するだけです。この定数は、float.hヘッダー・ファイルに定義されます。

この関数に有効なOCINumberの値を渡す必要があります。それ以外の場合は、結果は保証されません。

戻り値

OCI_SUCCESS (関数が正常に完了した場合)、OCI_INVALID_HANDLE (errがNULLの場合)、OCI_ERROR (numberまたはrslがNULLの場合、あるいはrsl_lengthが0の場合)。

関連関数

OCIErrorGet()、OCINumberToReal()

OCINumberToText()

用途

指定された書式に従って、Oracle NUMBERを文字列に変換します。

構文

sword OCINumberToText ( OCIError             *err,
const OCINumber      *number,
const OraText        *fmt,
ub4                  fmt_length,
const OraText        *nls_params,
ub4                  nls_p_length,
ub4                  *buf_size,
OraText              *buf );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

変換するOracle NUMBERです。

fmt (IN)

変換書式です。

fmt_length (IN)

fmtパラメータの長さです。

nls_params (IN)

グローバリゼーション・サポートのフォーマット指定です。NULL文字列((text *)0)の場合は、そのセッションのデフォルト・パラメータが使用されます。

nls_p_length (IN)

nls_paramsパラメータの長さです。

buf_size (IN)

バッファのサイズです。

buf (OUT)

変換された文字列が配置されるバッファです。

コメント

書式およびグローバリゼーション・サポート・パラメータの詳細は、『Oracle Database SQL言語リファレンス』のTO_NUMBER変換関数の説明を参照してください。

変換された数字文字列は、最大buf_sizeバイトまでbufに格納されます。

戻り値

この関数は、次の場合にエラーを戻します。

- numberまたはbufの値がNULLである場合

- バッファが小さすぎる場合

- 書式またはマルチバイト・フォーマットが無効である場合

- 数値を指定の書式のテキストに翻訳するときにオーバーフローが発生した場合

関連関数

OCIErrorGet()、OCINumberFromText()

OCINumberTrunc()

用途

Oracle NUMBERを指定の小数点以下の桁数で切り捨てます。

構文

sword OCINumberTrunc ( OCIError             *err,
const OCINumber      *number,
sword                decplace,
OCINumber            *result );

パラメータ

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

number (IN)

入力NUMBERです。

decplace (IN)

切り捨てる小数点以下の桁数です。負数も可能です。

result (OUT)

切捨ての出力です。

戻り値

この関数は、NUMBER引数にNULLがある場合はエラーを戻します。

関連関数

OCIErrorGet()、OCINumberRound()

OCIロー関数

表19-14は、この項で説明しているOCIロー関数を示しています。

表19-14 ロー関数

関数

用途

「OCIRawAllocSize()」

ロー・メモリーに割り当てられたサイズをバイト単位で取得します。

「OCIRawAssignBytes()」

ローにロー・バイトを割り当てます。

「OCIRawAssignRaw()」

ローにローを割り当てます。

「OCIRawPtr()」

ロー・データのポインタを取得します。

「OCIRawResize()」

可変長ローのメモリー・サイズを変更します。

「OCIRawSize()」

ローのサイズを取得します。

OCIRawAllocSize()

用途

ロー・メモリーの割り当てられたサイズ(バイト単位)を取得します。

構文

sword OCIRawAllocSize ( OCIEnv             *env,
OCIError           *err,
const OCIRaw       *raw,
ub4                *allocsize );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

raw (IN)

割り当てられたサイズがバイト単位で戻されるロー・データです。これは、NULL以外のポインタにしてください。

allocsize (OUT)

戻されるロー・メモリーの割当てサイズ(バイト単位)。

コメント

割り当てられるサイズは、実際のロー・サイズより大きいかそれに等しくなります。

関連関数

OCIErrorGet()、OCIRawResize()、OCIRawSize()

OCIRawAssignBytes()

用途

ub1*型のロー・バイトをOracleのOCIRaw*データ型に割り当てます。

構文

sword OCIRawAssignBytes ( OCIEnv             *env,
OCIError           *err,
const ub1          *rhs,
ub4                rhs_len,
OCIRaw             **lhs );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

rhs (IN)

割当ての右側(ソース)となるub1データ型です。

rhs_len (IN)

rhsロー・バイトの長さです。

lhs (IN/OUT)

割当ての左側(ターゲット)となるOCIRawデータです。

コメント

rhsロー・バイトをlhsロー・データ型に割り当てます。lhsローのサイズは、rhsのサイズに応じて変更されます。割り当てられたロー・バイトの型はub1になります。

関連関数

OCIErrorGet()、OCIRawAssignRaw()

OCIRawAssignRaw()

用途

あるOracle RAWデータ型を別のOracle RAWデータ型に割り当てます。

構文

sword OCIRawAssignRaw ( OCIEnv             *env,
OCIError           *err,
const OCIRaw       *rhs,
OCIRaw             **lhs );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

rhs (IN)

割当ての右側(rhs) (ソース)となるOCIRawデータです。

lhs (IN/OUT)

割当ての左側(lhs) (ターゲット)となるOCIRawデータです。

コメント

rhs OCIRawをlhs OCIRawに割り当てます。lhs OCIRawのサイズは、rhsのサイズに応じて変更されます。

関連関数

OCIErrorGet()、OCIRawAssignBytes()

OCIRawPtr()

用途

ロー・データへのポインタを取得します。

構文

ub1 *OCIRawPtr ( OCIEnv             *env,
const OCIRaw       *raw );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

raw (IN)

指定されたrawのデータへのポインタ。

コメント

なし。

関連関数

OCIErrorGet()、OCIRawAssignRaw()

OCIRawResize()

用途

指定の可変長rawのメモリー・サイズを変更します。

構文

sword OCIRawResize ( OCIEnv          *env,
OCIError        *err,
ub2             new_size,
OCIRaw          **raw );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

new_size (IN)

バイト単位での新規ロー・データのサイズです。

raw (IN)

可変長rawポインタです。rawのサイズはnew_sizeに変更されます。

コメント

この関数は、オブジェクト・キャッシュ内の指定した可変長rawのメモリーをサイズ変更します。rawの以前の内容は保存されません。また、指定したrawで占有されている元のメモリーが解放された場合に、新しいメモリー領域にrawを割り当てることがあります。入力raw値がNULLの場合(raw == NULL)、この関数はrawデータにメモリーを割り当てます。

new_sizeが0 (ゼロ)の場合、この関数はrawが占有していたメモリーを解放し、NULLポインタ値を戻します。

関連関数

OCIErrorGet()、OCIRawAllocSize()、OCIRawSize()

OCIRawSize()

用途

指定のローのサイズをバイト単位で戻します。

構文

ub4 OCIRawSize ( OCIEnv             *env,
const OCIRaw       *raw );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

raw (IN/OUT)

サイズが戻されるローです。

コメント

なし。

関連関数

OCIErrorGet()、OCIRawAllocSize()、OCIRawResize()

OCI REF関数

表19-15は、この項で説明しているOCI参照(REF)関数を示しています。

表19-15 REF関数

関数

用途

「OCIRefAssign()」

1つのREFを別のREFに代入します。

「OCIRefClear()」

REFを消去またはNULL化します。

「OCIRefFromHex()」

16進文字列をREFに変換します。

「OCIRefHexSize()」

REFの16進表現のサイズを戻します。

「OCIRefIsEqual()」

2つのREFが等しいかどうかを比較します。

「OCIRefIsNull()」

REFがNULLかどうかをテストします。

「OCIRefToHex()」

REFを16進文字列に変換します。

OCIRefAssign()

用途

あるREFを別のREFに割り当て、両方が同じオブジェクトを参照するようにします。

構文

sword OCIRefAssign ( OCIEnv             *env,
OCIError           *err,
const OCIRef       *source,
OCIRef             **target );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

source (IN)

コピー元のREFです。

target (IN/OUT)

コピー先のREFです。

コメント

source REFをtarget REFにコピーし、両方が同じオブジェクトを参照するようにします。target REFポインタがNULL (*target == NULL)の場合、OCIRefAssign()は、コピー操作を実行する前にOCIオブジェクト・キャッシュ内にtarget REF用のメモリーを割り当てます。

関連関数

OCIErrorGet()、OCIRefIsEqual()

OCIRefClear()

用途

指定のREFを消去またはNULLにします。

構文

void OCIRefClear ( OCIEnv        *env,
OCIRef        *ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

ref (IN/OUT)

消去するREFです。

コメント

オブジェクトを指し示さないREFは、NULLのREFとみなされます。論理的には、NULLのREFは参照先がないREFになります。

NULLのREFは依然として有効なSQL値であり、SQLのNULLではないことに注意してください。これは、表内のNOT NULL列または行属性用の有効な非NULL定数REF値として使用できます。

REFとしてNULLポインタ値が渡されると、この関数による操作は実行されません。

関連関数

OCIErrorGet()、OCIRefIsNull()

OCIRefFromHex()

用途

指定の16進文字列をREFに変換します。

構文

sword OCIRefFromHex ( OCIEnv              *env,
OCIError            *err,
const OCISvcCtx     *svc,
const OraText       *hex,
ub4                 length,
OCIRef              **ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキスト・ハンドルです(結果のREFがこのサービス・コンテキストで初期化される場合)。

hex (IN)

REFに変換する16進テキスト文字列で、以前にOCIRefToHex()によって出力されたものです。

length (IN)

16進文字列の長さです。

ref (IN/OUT)

16進文字列が変換先となるREFです。入力時に*refがNULLの場合は、そのREF用の領域がオブジェクト・キャッシュ内に割り当てられます。それ以外の場合は、指定のREFによって占有されているメモリーが再利用されます。

コメント

この関数は、変換後のREFの書式が正しいことを保証します。生成されたREFで指し示されるオブジェクトが存在することは保証されません。

関連関数

OCIErrorGet()、OCIRefToHex()

OCIRefHexSize()

用途

REFの16進表現のサイズを戻します。

構文

ub4 OCIRefHexSize ( OCIEnv            *env,
const OCIRef      *ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

ref (IN)

16進表現のサイズがバイト単位で戻されるREFです。

コメント

REFの16進表現のために必要なバッファ・サイズをバイト単位で戻します。最低このサイズのバッファを、REFから16進への変換関数(OCIRefToHex())に渡す必要があります。

戻り値

REFの16進表現のサイズです。

関連関数

OCIErrorGet()、OCIRefFromHex()

OCIRefIsEqual()

用途

2つのREFを比較してそれらが同等であるかどうかを判断します。

構文

boolean OCIRefIsEqual ( OCIEnv              *env,
const OCIRef        *x,
const OCIRef        *y );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

x (IN)

比較するREFです。

y (IN)

比較するREFです。

コメント

2つのREFは、オブジェクトの種類(永続または一時)に関係なく同じオブジェクトを参照している場合のみ同等になります。

注意:
この関数では、2つのNULLのREFは等価とみなされません。

戻り値

2つのREFが同等な場合はTRUEです。

2つのREFが等しくない場合、xがNULLの場合、またはyがNULLの場合はFALSEです。

関連関数

OCIErrorGet()、OCIRefAssign()

OCIRefIsNull()

用途

REFがNULLかどうかをテストします。

構文

boolean OCIRefIsNull ( OCIEnv           *env,
const OCIRef     *ref );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

ref (IN)

NULLであるかどうかをテストするREFです。

コメント

REFは、次に該当する場合のみNULLになります。

- 永続オブジェクトを参照するが、オブジェクトの識別子がNULLである場合

- 一時オブジェクトを参照するが、現時点ではオブジェクトを指し示していない場合

注意:
指し示しているオブジェクトが存在しない場合、このREFは不確定なREFです。

戻り値

指定されたREFがNULLの場合はTRUEを戻します。それ以外の場合はFALSEを戻します。

関連関数

OCIErrorGet()、OCIRefClear()

OCIRefToHex()

用途

REFを16進文字列に変換します。

構文

sword OCIRefToHex ( OCIEnv            *env,
OCIError          *err,
const OCIRef      *ref,
OraText           *hex,
ub4               *hex_length );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

ref (IN)

16進文字列に変換するREFです。refがNULLのREF (つまり、OCIRefIsNull(ref) == TRUE)の場合は、0(ゼロ)のhex_length値が戻されます。

hex (OUT)

結果の16進文字列を格納するのに十分なバッファです。文字列の内容は、コール元にとっては不透明になります。

hex_length (IN/OUT)

入力ではhexバッファのサイズを指定し、出力ではhexで戻される16進文字列の実際のサイズを指定します。

コメント

指定されたREFを16進文字列に変換し、その文字列の長さを戻します。変換された文字列は、コール元にとっては不透明になります。

戻り値

この関数は、指定されたバッファが変換後の文字列を保持できるだけの大きさがない場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIRefFromHex()、OCIRefHexSize()、OCIRefIsNull()

OCI文字列関数

表19-16は、この項で説明しているOCI文字列関数を示しています。

表19-16 文字列関数

関数

用途

「OCIStringAllocSize()」

文字列メモリーの割り当てられたサイズ(バイト単位)を取得します。

「OCIStringAssign()」

文字列に文字列を割り当てます。

「OCIStringAssignText()」

文字列にテキスト文字列を割り当てます。

「OCIStringPtr()」

文字列ポインタを取得します。

「OCIStringResize()」

文字列メモリーをサイズ変更します。

「OCIStringSize()」

文字列サイズを取得します。

OCIStringAllocSize()

用途

文字列の割当てメモリー・サイズをコード・ポイント(Unicode)またはバイト単位で取得します。

構文

sword OCIStringAllocSize ( OCIEnv              *env,
OCIError            *err,
const OCIString     *vs,
ub4                 *allocsize );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

vs (IN)

割り当てられたサイズがバイト単位で戻される文字列です。vsパラメータは、NULL以外のポインタにしてください。

allocsize (OUT)

文字列メモリーの割当てサイズをバイト単位で戻します。

コメント

割り当てられるサイズは、実際の文字列サイズより大きいかそれに等しくなります。

関連関数

OCIErrorGet()、OCIStringResize()、OCIStringSize()

OCIStringAssign()

用途

文字列を別の文字列に割り当てます。

構文

sword OCIStringAssign ( OCIEnv               *env,
OCIError             *err,
const OCIString      *rhs,
OCIString            **lhs );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

rhs (IN)

割当ての右側(ソース)です。UTF-16形式が可能です。

lhs (IN/OUT)

割当ての左側(ターゲット)です。rhsがUTF-16の場合、バッファはUTF-16形式になります。

コメント

rhs文字列をlhs文字列に割り当てます。lhs文字列のサイズは、rhsのサイズに応じて変更されます。割り当てられる文字列は、NULLで終了します。長さのフィールドには、NULLによる終了に必要な余分なコード・ポイントやバイトは含まれません。

戻り値

この関数は、割当て操作で領域が足りなくなった場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIStringAssignText()

OCIStringAssignText()

用途

ソース・テキスト文字列をターゲット文字列に割り当てます。

構文

sword OCIStringAssignText ( OCIEnv           *env,
OCIError         *err,
const OraText    *rhs,
ub4              rhs_len,
OCIString        **lhs );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

rhs (IN)

割当ての右側(ソース)となるテキスト文字列またはUTF-16 Unicode文字列です。

rhs_len (IN)

rhs文字列のバイト単位の長さです。

lhs (IN/OUT)

割当ての左側(ターゲット)です。rhsがUnicodeの場合、バッファはUnicodeになります。

コメント

rhs文字列をlhs文字列に割り当てます。lhs文字列のサイズは、rhsのサイズに応じて変更されます。割り当てられる文字列は、NULLで終了します。長さのフィールドには、NULLによる終了に必要な余分なバイトやコード・ポイントは含まれません。

関連関数

OCIErrorGet()、OCIStringAssign()

OCIStringPtr()

用途

指定の文字列のテキストへのポインタを取得します。

構文

text *OCIStringPtr ( OCIEnv               *env,
const OCIString      *vs );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

vs (IN)

文字列を戻すOCIStringオブジェクトへのポインタです。vsがUTF-16形式の場合、戻されるバッファもUTF-16形式です。戻されるバッファのエンコーディングを判別するには、OCIStringのvs自体でUTF-16に関する情報を確認します。この場合、特定のOCIStringがenvと同じ設定であることは保証されません。オブジェクト内でメンバー・フィールドを確認するためのオブジェクトOCI関数をチェックします。

コメント

なし。

関連関数

OCIErrorGet()、OCIStringAssign()

OCIStringResize()

用途

指定の文字列のメモリー・サイズを変更します。

構文

sword OCIStringResize ( OCIEnv          *env,
OCIError        *err,
ub4             new_size,
OCIString       **str );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

new_size (IN)

文字列の新規メモリー・サイズ(バイト単位)です。new_sizeパラメータには、文字列終了記号のNULL文字用の領域を含める必要があります。

str (IN/OUT)

OCIオブジェクト・キャッシュから解放された文字列の割当てメモリーです。

コメント

この関数は、オブジェクト・キャッシュ内の指定した可変長文字列のメモリーをサイズ変更します。文字列の内容は保存されません。また、指定した文字列で占有されている元のメモリーが解放された場合に、新しいメモリー領域に文字列を割り当てることがあります。strがNULLの場合、この関数は文字列にメモリーを割り当てます。new_sizeが0 (ゼロ)の場合、この関数はstrが占有していたメモリーを解放し、NULLポインタ値を戻します。

関連関数

OCIErrorGet()、OCIStringAllocSize()、OCIStringSize()

OCIStringSize()

用途

指定の文字列vsのサイズを取得します。

構文

ub4 OCIStringSize ( OCIEnv              *env,
const OCIString     *vs );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

vs (IN)

サイズがバイト単位で戻される文字列です。

コメント

戻されたサイズには、NULLによる終了用の余分なバイトは含まれていません。

関連関数

OCIErrorGet()、OCIStringResize()

OCI表関数

表19-17は、この項で説明しているOCI表関数を示しています。

表19-17 表関数

関数

用途

「OCITableDelete()」

要素を削除します。

「OCITableExists()」

要素が存在するかどうかをテストします。

「OCITableFirst()」

表の先頭の索引を戻します。

「OCITableLast()」

表の最後の索引を戻します。

「OCITableNext()」

使用可能な次の表索引を戻します。

「OCITablePrev()」

使用可能な1つ前の表索引を戻します。

「OCITableSize()」

表のカレント・サイズを戻します。

OCITableDelete()

用途

指定の索引位置にある要素を削除します。

構文

sword OCITableDelete ( OCIEnv          *env,
OCIError        *err,
sb4             index,
OCITable        *tbl );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

index (IN)

削除する必要のある要素の索引です。

tbl (IN)

要素を削除する表です。

コメント

この関数は、指定した索引の要素がすでに削除されている場合、または指定した索引が表に対して無効の場合は、エラーを戻します。

注意:
表の残りの要素の位置序数は、OCITableDelete()で変更されません。削除操作により、表に穴が作成されます。

戻り値

入力パラメータがNULLである場合はエラーも戻されます。

関連関数

OCIErrorGet()、OCITableExists()

OCITableExists()

用途

指定の索引位置に要素が存在するかどうかをテストします。

構文

sword OCITableExists ( OCIEnv              *env,
OCIError            *err,
const OCITable      *tbl,
sb4                 index,
boolean             *exists );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

tbl (IN)

指定の索引をチェックする表です。

index (IN)

要素の存在をチェックする索引です。

exists (OUT)

指定するindexに要素が存在する場合はTRUEです。それ以外の場合は、FALSEです。

戻り値

この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCITableDelete()

OCITableFirst()

用途

指定の表の先頭の既存要素の索引を戻します。

構文

sword OCITableFirst ( OCIEnv             *env,
OCIError           *err,
const OCITable     *tbl,
sb4                *index  );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

tbl (IN)

スキャンする表です。

index (OUT)

戻される指定の表に存在する最初の要素の索引です。

コメント

OCITableDelete()によって表の先頭の5つの要素が削除されている場合、OCITableFirst()は値6を戻します。

関連項目:
表内のデータのない空き(削除された要素)に関する情報は、「OCITableDelete()」を参照してください。

戻り値

この関数は、表が空の場合はエラーを戻します。

関連関数

OCIErrorGet()、OCITableDelete()、OCITableLast()

OCITableLast()

用途

表の最後の既存要素の索引を戻します。

構文

sword OCITableLast ( OCIEnv              *env,
OCIError            *err,
const OCITable      *tbl,
sb4                 *index );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

tbl (IN)

スキャンする表です。

index (OUT)

表の最後の既存要素の索引です。

戻り値

この関数は、表が空の場合はエラーを戻します。

関連関数

OCIErrorGet()、OCITableFirst()、OCITableNext()、OCITablePrev()

OCITableNext()

用途

表の次の既存要素の索引を戻します。

構文

sword OCITableNext ( OCIEnv             *env,
OCIError           *err,
sb4                index,
const OCITable     *tbl,
sb4                *next_index
boolean            *exists );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

index (IN)

スキャンの開始位置の索引です。

tbl (IN)

スキャンする表です。

next_index (OUT)

tbl(index)の次の既存要素の索引です。

exists (OUT)

次の索引が存在しない場合はFALSEで、存在する場合はTRUEです。

戻り値

indexよりも大きく、exists(j)がTRUEになるような最小位置jを戻します。

関連項目:
表内のデータのない空き(削除された要素)の存在に関する情報は、「OCITableSize()」の説明を参照してください。

関連関数

OCIErrorGet()、OCITablePrev()

OCITablePrev()

用途

表の直前の既存要素の索引を戻します。

構文

sword OCITablePrev ( OCIEnv             *env,
OCIError           *err,
sb4                index,
const OCITable     *tbl,
sb4                *prev_index
boolean            *exists );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

index (IN)

スキャンの開始位置の索引です。

tbl (IN)

スキャンする表です。

prev_index (OUT)

tbl(index)の直前の既存要素の索引です。

exists (OUT)

前の索引が存在しない場合はFALSEで、存在する場合はTRUEです。

戻り値

indexよりも小さく、exists(j)がTRUEになるような最大位置jを戻します。

関連項目:
表内のデータのない空き(削除された要素)の存在に関する情報は、「OCITableSize()」の説明を参照してください。

関連関数

OCIErrorGet()、OCITableNext()

OCITableSize()

用途

指定の表のサイズを戻します。削除済の要素によって生成された空きは含まれません。

構文

sword OCITableSize ( OCIEnv             *env,
OCIError           *err,
const OCITable     *tbl
sb4                *size );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:
, 「OCIEnvNlsCreate()」、「OCIEnvCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

tbl (IN)

要素の数を戻す対象のネストした表です。

size (OUT)

ネストした表内の現行の要素数です。削除された要素はカウントに含まれません。

コメント

カウントは、ネストした表から要素を削除すると減分されます。したがって、このカウントには要素を削除した際に作成された穴は含まれていません。削除済の要素によって生成された空きを含むカウントを取得するには、OCICollSize()を使用します。

例19-4 は、ネストした表から要素を削除するコード・フラグメントを示しています。

例19-4 ネストした表からの要素の削除

OCITableSize(...);
// assume 'size' returned is equal to 5
OCITableDelete(...); // delete one element
OCITableSize(...);
// 'size' returned is equal to 4

例19-5に示すように、削除された要素を含めたカウントを取得するには、OCICollSize()を使用します。例19-4を続けます。

例19-5 ネストした表から削除された要素を含めたすべての要素のカウントの取得

OCICollSize(...)
// 'size' returned is still equal to 5

戻り値

この関数は、ネストした表のオブジェクト・キャッシュへのロード中にエラーが発生した場合、または入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCICollSize()

20 OCIカートリッジ関数

この章では、カートリッジ関数について説明します。コード例は、Oracle Databaseのインストールに含まれているデモ・プログラムを参照してください。詳細は、付録Bを参照してください。

この章は、次の項目で構成されています。

- 外部プロシージャ関数およびカートリッジ・サービス関数の概要

- カートリッジ・サービス: OCI外部プロシージャ

- カートリッジ・サービス: メモリー・サービス

- カートリッジ・サービス: コンテキストのメンテナンス

- カートリッジ・サービス: パラメータ・マネージャ・インタフェース

- カートリッジ・サービス: ファイルI/Oインタフェース

- カートリッジ・サービス: 文字列のフォーマット・インタフェース

外部プロシージャ関数およびカートリッジ・サービス関数の概要

この章では、最初にOCI外部プロシージャ関数について説明します。これらの関数により、外部プロシージャのユーザーは、エラーの通知、メモリーの割当ておよびOCIコンテキスト情報の取得ができます。これらの関数を外部プロシージャで使用する方法の詳細は、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』を参照してください。

次に、カートリッジ・サービスについて説明します。これらの関数の使用方法の詳細は、『Oracle Databaseデータ・カートリッジ開発者ガイド』を参照してください。

OCI関数の規則

各関数を記述する際に使用される規則は、「OCI関数の規則」を参照してください。関数ごとに次の情報が記載されている場合もあります。

リターン・コード

成功とエラーのリターン・コードは、特定の外部プロシージャ・インタフェース関数に対して定義されます。特定のインタフェース・ファンクションがOCIEXTPROC_SUCCESSまたはOCIEXTPROC_ERRORを戻した場合、アプリケーションはこれらのマクロを使用して戻り値をチェックする必要があります。

- OCIEXTPROC_SUCCESS－ 外部プロシージャの成功した場合のリターン・コード

- OCIEXTPROC_ERROR－ 外部プロシージャの失敗した場合のリターン・コード

With_Context型

C言語におけるPL/SQL外部プロシージャへのコール可能なインタフェースでは、with_contextパラメータを渡す必要があります。この構造体の型はOCIExtProcContextで、ユーザーには認識されません。

ユーザーは、with_contextパラメータをアプリケーションで次のように宣言できます。

OCIExtProcContext *with_context;

カートリッジ・サービス — OCI外部プロシージャ

表20-1は、この項で説明しているCのOCI外部プロシージャ関数を示しています。

表20-1 外部プロシージャ関数

関数

用途

「OCIExtProcAllocCallMemory()」

外部プロシージャの継続時間にメモリーを割り当てます。

「OCIExtProcGetEnv()」

OCI環境ハンドル、サービス・コンテキスト・ハンドルおよびエラー・ハンドルを取得します。

「OCIExtProcRaiseExcp()」

PL/SQLに例外を呼び出します。

「OCIExtProcRaiseExcpWithMsg()」

例外をメッセージ付きで呼び出します。

OCIExtProcAllocCallMemory()

用途

外部プロシージャの継続時間にNバイトのメモリーを割り当てます。

構文

void  * OCIExtProcAllocCallMemory ( OCIExtProcContext    *with_context,
size_t                amount );

パラメータ

with_context (IN)

C外部プロシージャに渡されるwith_contextポインタです。

関連項目:
「With_Context型」

amount (IN)

割り当てるバイト数です。

コメント

このコールは、外部プロシージャのコール継続時間にamountバイトのメモリーを割り当てます。

このコールで割り当てられたメモリーは、外部プロシージャから戻るとすぐにPL/SQLによって解放されます。アプリケーションでは、OCIExtProcAllocCallMemory()で割り当てたメモリーにfree()関数を使用しないでください。この関数を使用して、関数の戻り値用のメモリーを割り当ててください。

0 (ゼロ)の戻り値はエラーとして扱われます。

戻り値

割り当てたメモリーを指し示す未定義の型(不透明な)ポインタを戻します。

例

例20-1 OCIExtProcAllocCallMemory()を使用した1024バイトのメモリーの割当て

text *ptr = (text *)OCIExtProcAllocCallMemory(wctx, 1024)

関連関数

OCIErrorGet()およびOCIMemoryAlloc()

OCIExtProcGetEnv()

用途

OCI環境、サービス・コンテキストおよびエラー・ハンドルを取得します。

構文

sword OCIExtProcGetEnv ( OCIExtProcContext    *with_context,
OCIEnv               **envh,
OCISvcCtx            **svch,
OCIError             **errh );

パラメータ

with_context (IN)

C外部プロシージャに渡されるwith_contextポインタです。「With_Context型」を参照してください。

envh (OUT)

OCI環境ハンドルを格納する変数のポインタです。

svch (OUT)

OCIサービス・ハンドルを格納する変数のポインタです。

errh (OUT)

OCIエラー・ハンドルを格納する変数のポインタです。

コメント

この関数の主な目的は、OCIコールバックで同じトランザクションのデータベースを使用可能にすることです。この関数で取得するOCIハンドルは、データベースに対するOCIコールバックで使用する必要があります。これらのハンドルを標準のOCIコールを介して取得した場合、これらのハンドルはデータベースへの新規接続を使用するので、同一トランザクション内のコールバックには使用できません。1つの外部プロシージャで使用できるのは、コールバックと新規接続のどちらか一方で、両方は使用できません。

コールの例:

OCIEnv    *envh;
OCISvcCtx *svch;
OCIError  *errh;
...
OCIExtProcGetEnv(ctx,&envh,&svch,&errh);

戻り値

この関数は、コールが成功した場合は、OCI_SUCCESSを戻します。コールが失敗した場合は、OCI_ERRORを戻します。

関連関数

OCIEnvCreate()、OCIArrayDescriptorAlloc()、OCIHandleAlloc()

OCIExtProcRaiseExcp()

用途

PL/SQLに例外を呼び出します。

構文

size_t OCIExtProcRaiseExcp ( OCIExtProcContext    *with_context,
int                   errnum );

パラメータ

with_context (IN)

C外部プロシージャに渡されるwith_contextポインタです。

関連項目:
「With_Context型」

errnum (IN)

PL/SQLへシグナルを送るOracle Databaseエラー番号です。errnumの値は、1から32767の正数にしてください。

コメント

この関数をコールすると、例外がPL/SQLに通知されます。この関数が問題なく戻されると、外部プロシージャは終了処理を開始し、PL/SQLに戻ります。いったん例外がPL/SQLに通知されると、IN/OUT引数とOUT引数(ある場合)は処理されません。

戻り値

この関数は、コールが正常に行われるとOCIEXTPROC_SUCCESSを戻します。コールに失敗するとOCIEXTPROC_ERRORを戻します。

関連関数

OCIExtProcRaiseExcpWithMsg()

OCIExtProcRaiseExcpWithMsg()

用途

例外をメッセージ付きで呼び出します。

構文

size_t OCIExtProcRaiseExcpWithMsg ( OCIExtProcContext   *with_context,
int                  errnum,
char                 *errmsg,
size_t               msglen );

パラメータ

with_context (IN)

C外部プロシージャに渡されるwith_contextポインタです。

関連項目:
「With_Context型」

errnum (IN)

PL/SQLへシグナルを送るOracle Databaseエラー番号です。errnumは、1から32767の正数にしてください。

errmsg (IN)

errnumに対応付けられたエラー・メッセージです。

msglen (IN)

エラー・メッセージの長さです。errmsgがNULLで終了する文字列の場合は、0 (ゼロ)が渡されます。

コメント

このコールによってPL/SQLに例外が呼び出されます。さらに、後続のエラー・メッセージ文字列を標準のOracle Databaseエラー・メッセージ文字列内で代入します。

関連項目:
OCIExtProcRaiseExcp()の説明

戻り値

この関数は、コールが正常に行われるとOCIEXTPROC_SUCCESSを戻します。コールに失敗するとOCIEXTPROC_ERRORを戻します。

関連関数

OCIExtProcRaiseExcp()

カートリッジ・サービス — メモリー・サービス

表20-2は、この項で説明しているメモリー・サービス関数を示しています。

表20-2 メモリー・サービス関数

関数

用途

「OCIDurationBegin()」

ユーザー期間を開始します。

「OCIDurationEnd()」

ユーザー期間を終了します。

「OCIMemoryAlloc()」

指定の継続時間から指定サイズのメモリーを割り当てます。

「OCIMemoryFree()」

メモリー・チャンクを解放します。

「OCIMemoryResize()」

メモリー・チャンクをサイズ変更します。

関連項目:
これらの関数の使用方法の詳細は、『Oracle Database データ・カートリッジ開発者ガイド』を参照してください。

OCIDurationBegin()

用途

ユーザー期間を開始します。

構文

sword OCIDurationBegin ( OCIEnv              *env,
OCIError            *err,
const OCISvcCtx     *svc,
OCIDuration         parent,
OCIDuration         *duration );

パラメータ

env (IN/OUT)

OCI環境ハンドルです。これは、カートリッジ・サービスに対してNULLとして渡されます。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

svc (IN)

OCIサービス・コンテキスト・ハンドルです。

parent (IN)

親の継続時間の時間番号です。次のいずれかです。

- 以前に作成されたユーザー期間

- OCI_DURATION_STATEMENT

- OCI_DURATION_SESSION

duration (OUT)

新しく作成されたユーザー期間固有の識別子です。

コメント

この関数によってユーザー期間が開始されます。ユーザーは複数のアクティブなユーザー期間を同時に利用できます。ユーザー期間をネストする必要はありません。durationパラメータは、このコールによって作成された期間を識別するための一意の番号を戻すために使用します。

環境パラメータとサービス・コンテキスト・パラメータの両方をNULLにすることはできません。

関連関数

OCIDurationEnd()

OCIDurationEnd()

用途

ユーザー期間を終了します。

構文

sword OCIDurationEnd ( OCIEnv             *env,
OCIError           *err,
const OCISvcCtx    *svc,
OCIDuration        duration );

パラメータ

env (IN/OUT)

OCI環境ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

svc (IN)

OCIサービス・コンテキストです(カートリッジ・サービスの場合はNULLとして渡しますが、それ以外の場合は非NULLとして渡します)。

duration (IN)

OCIDurationBegin()によって以前作成されたユーザー期間です。

コメント

この関数によってユーザー期間が終了します。

環境パラメータとサービス・コンテキスト・パラメータの両方をNULLにすることはできません。

関連関数

OCIDurationBegin()

OCIMemoryAlloc()

用途

指定の継続時間から指定サイズのメモリーを割り当てます。

構文

sword OCIMemoryAlloc( void         *hndl,
OCIError     *err,
void         **mem,
OCIDuration  dur,
ub4          size,
ub4          flags );

パラメータ

hndl (IN)

durがOCI_DURATION_PROCESSの場合、OCI環境ハンドル(OCIEnv *)で、それ以外の場合はユーザー・セッション・ハンドル(OCISession *)です。

err (IN)

エラー・ハンドルです。

mem (OUT)

割り当てられたメモリーです。

dur (IN)

以前に作成されたユーザー期間または次の値のいずれかです。

OCI_DURATION_CALLOUT

OCI_DURATION_STATEMENT

OCI_DURATION_SESSION

OCI_DURATION_PROCESS

size (IN)

割り当てられるメモリーのサイズです。

flags (IN)

OCI_MEMORY_CLEAREDビットを設定して、消去されたメモリーを取得します。

コメント

エージェントのコールアウトの継続時間(外部プロシージャ継続時間)にメモリーを割り当てるには、OCIExtProcAllocCallMemory()またはdurをOCI_DURATION_CALLOUTとして指定するOCIMemoryAlloc()を使用します。

戻り値

エラー・コードを戻します。

OCIMemoryFree()

用途

メモリー・チャンクを解放します。

構文

sword OCIMemoryFree ( void     *hndl,
OCIError *err,
void     *mem );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

mem (IN/OUT)

OCIMemoryAlloc()を使用して以前割り当てたメモリーへのポインタです。

戻り値

エラー・コードを戻します。

OCIMemoryResize()

用途

メモリー・チャンクを新規サイズに変更します。

構文

sword OCIMemoryResize( void         *hndl,
OCIError     *err,
void         **mem,
ub4          newsize,
ub4          flags );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

mem (IN/OUT)

OCIMemoryAlloc()を使用して以前割り当てたメモリーへのポインタです。

newsize (IN)

要求されたメモリーのサイズです。

flags (IN)

OCI_MEMORY_CLEAREDビットを設定して、消去されたメモリーを取得します。

コメント

メモリーを割り当ててからこの関数をコールしてサイズ変更する必要があります。

戻り値

エラー・コードを戻します。

カートリッジ・サービス — コンテキストのメンテナンス

表20-3は、この項で説明しているコンテキストのメンテナンス関数を示しています。

表20-3 コンテキストのメンテナンス関数

関数

用途

「OCIContextClearValue()」

コンテキストに格納されている値を削除します。

「OCIContextGenerateKey()」

コールが実行されるたびに一意の4バイト値を戻します。

「OCIContextGetValue()」

コンテキストに格納されている値を戻します。

「OCIContextSetValue()」

特定の継続時間に対する値(アドレス)を保存します。

関連項目:
これらの関数の使用方法の詳細は、『Oracle Databaseデータ・カートリッジ開発者ガイド』を参照してください。

OCIContextClearValue()

用途

OCIContextSetValue()をコールして指定キーに対応付けられたコンテキストに格納されている値を削除します。

構文

sword OCIContextClearValue( void     *hndl,
OCIError *err,
ub1      *key,
ub1      keylen );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

key (IN)

一意のキー値です。

keylen (IN)

キーの長さです。最大の長さは64ビットです。

コメント

存在しないキーが渡されるとエラーが戻されます。

戻り値

- 操作が成功した場合は、OCI_SUCCESSが戻されます。

- 操作が失敗した場合は、OCI_ERRORが戻されます。

OCIContextGenerateKey()

用途

コールが実行されるたびに一意の4バイト値を戻します。

構文

sword OCIContextGenerateKey( void     *hndl,
OCIError *err,
ub4      *key );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

key (IN)

一意のキー値です。

コメント

この値はセッションごとに一意です。

戻り値

- 操作が成功した場合は、OCI_SUCCESSが戻されます。

- 操作が失敗した場合は、OCI_ERRORが戻されます。

OCIContextGetValue()

用途

OCIContextSetValue()をコールして指定キーに対応付けられたコンテキストに格納されている値を戻します。

構文

sword OCIContextGetValue( void       *hndl,
OCIError   *err,
ub1        *key,
ub1        keylen,
void       **ctx_value );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

key (IN)

一意のキー値です。

keylen (IN)

キーの長さです。最大の長さは64ビットです。

ctx_value (IN)

コンテキストに格納されている値へのポインタです(値が格納されていない場合はNULL)。

コメント

ctx_valueの場合は、戻される格納済コンテキストに対する事前割当てポインタへのポインタが必要です。

戻り値

- 操作が成功した場合は、OCI_SUCCESSが戻されます。

- 操作が失敗した場合は、OCI_ERRORが戻されます。

OCIContextSetValue()

用途

特定の継続時間に対する値(アドレス)を保存します。

構文

sword OCIContextSetValue( void        *hndl,
OCIError    *err,
OCIDuration duration,
ub1         *key,
ub1         keylen,
void        *ctx_value );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

duration (IN)

次の値のいずれかになります(以前作成されたユーザー期間)。

OCI_DURATION_STATEMENT

OCI_DURATION_SESSION

key (IN)

一意のキー値です。

keylen (IN)

キーの長さです。最大の長さは64ビットです。

ctx_value (IN)

コンテキストに保存されるポインタです。

コメント

格納されているコンテキスト値は、渡される期間以上の期間でメモリーから割り当てる必要があります。渡されるキーは、このセッションで一意的である必要があります。同じキーと期間で再度コンテキスト値を保存しようとすると、以前のコンテキスト値が新しいコンテキスト値で上書きされます。通常、クライアントは、このコールを使用して構造体を割り当て、そのアドレスをコンテキストに格納し、OCIContextGetValue()を使用して別のコールでこのアドレスを取得します。(キー、値の)対応付けは、OCIContextClearValue()をコールして明示的に削除できます。削除しない場合は、期間の最後で消滅します。

戻り値

- 操作が成功した場合は、OCI_SUCCESSが戻されます。

- 操作が失敗した場合は、OCI_ERRORが戻されます。

カートリッジ・サービス — パラメータ・マネージャ・インタフェース

表20-4は、この項で説明しているパラメータ・マネージャ・インタフェース関数を示しています。

表20-4 パラメータ・マネージャ・インタフェース関数

関数

用途

「OCIExtractFromFile()」

指定したファイルのキーおよびそのキーの値を処理します。

「OCIExtractFromList()」

パラメータ・リストのindexに示されるパラメータの値のリストを生成します。

「OCIExtractFromStr()」

指定した文字列のキーおよびそのキーの値を処理します。

「OCIExtractInit()」

パラメータ・マネージャを初期化します。

「OCIExtractReset()」

メモリーを再初期化します。

「OCIExtractSetKey()」

キーに関する情報をパラメータ・マネージャに登録します。

「OCIExtractSetNumKeys()」

登録されるキー数をパラメータ・マネージャに通知します。

「OCIExtractTerm()」

動的に割り当てたすべての記憶域を解放します。

「OCIExtractToBool()」

指定されたキーのブール値を取得します。

「OCIExtractToInt()」

指定されたキーの整数値を取得します。

「OCIExtractToList()」

メモリーに格納されているパラメータ構造からパラメータのリストを生成します。

「OCIExtractToOCINum()」

指定されたキーの数値を取得します。

「OCIExtractToStr()」

指定されたキーの文字列値を取得します。

関連項目:
これらの関数の使用方法の詳細は、『Oracle Database データ・カートリッジ開発者ガイド』を参照してください。

OCIExtractFromFile()

用途

指定したファイルのキーおよびそのキーの値を処理します。

構文

sword OCIExtractFromFile( void     *hndl,
OCIError *err,
ub4      flag,
OraText  *filename );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

flag (IN)

0 (ゼロ)または次の1つ以上のビットを設定します。

OCI_EXTRACT_CASE_SENSITIVE

OCI_EXTRACT_UNIQUE_ABBREVS

OCI_EXTRACT_APPEND_VALUES

filename (IN)

NULLで終了するファイル名文字列です。

コメント

このルーチンをコールする前に、OCIExtractSetNumKeys()およびOCIExtractSetKey()関数をコールしてすべてのキーを定義する必要があります。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIExtractFromList()

用途

パラメータ・リストの索引で示されるパラメータの値のリストを生成します。

構文

sword OCIExtractFromList( void        *hndl,
OCIError    *err,
uword       index,
OraText     **name,
ub1         *type,
uword       *numvals,
void        ***values );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

index (IN)

パラメータ・リストから取り出すパラメータを示します。

name (OUT)

現行のパラメータのキー名です。

type (OUT)

現行のパラメータの型です。

OCI_EXTRACT_TYPE_STRING

OCI_EXTRACT_TYPE_INTEGER

OCI_EXTRACT_TYPE_OCINUM

OCI_EXTRACT_TYPE_BOOLEAN

numvals (OUT)

このパラメータの値の数です。

values (OUT)

このパラメータの値です。

コメント

OCIExtractToList()は、このルーチンのコールの前にコールして、メモリーに格納されているパラメータ構造からパラメータ・リストを生成する必要があります。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIExtractFromStr()

用途

指定した文字列のキーおよびそのキーの値を処理します。

構文

sword OCIExtractFromStr( void     *hndl,
OCIError *err,
ub4      flag,
OraText  *input );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

flag (IN)

0 (ゼロ)または次の1つ以上のビットを設定します。

OCI_EXTRACT_CASE_SENSITIVE

OCI_EXTRACT_UNIQUE_ABBREVS

OCI_EXTRACT_APPEND_VALUES

input (IN)

NULLで終了する入力文字列です。

コメント

このルーチンをコールする前に、OCIExtractSetNumKeys()およびOCIExtractSetKey()関数をコールしてすべてのキーを定義する必要があります。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIExtractInit()

用途

パラメータ・マネージャを初期化します。

構文

sword OCIExtractInit( void      *hndl,
OCIError  *err);

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

コメント

この関数は、他のパラメータ・マネージャ・ルーチンをコールする前にコールする必要があります。また、コールは1度しか実行できません。グローバリゼーション・サポート情報はパラメータ・マネージャ・コンテキストの内部に格納されており、OCIExtract関数の後続のコールで使用されます。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIExtractReset()

用途

パラメータ・ストレージ、キー定義ストレージおよびパラメータ値リスト用に現在使用されているメモリーを解放して構造を再初期化します。

構文

sword OCIExtractReset( void      *hndl,
OCIError  *err );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR

OCIExtractSetKey()

用途

キーに関する情報をパラメータ・マネージャに登録します。

構文

sword OCIExtractSetKey( void        *hndl,
OCIError    *err,
const text  *name,
ub1         type,
ub4         flag,
const void  *defval,
const sb4   *intrange,
const text  *strlist );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

name (IN)

キーの名前です。

type (IN)

次のキーの型です。

OCI_EXTRACT_TYPE_INTEGER

OCI_EXTRACT_TYPE_OCINUM

OCI_EXTRACT_TYPE_STRING

OCI_EXTRACT_TYPE_BOOLEAN

flag (IN)

キーに複数の値を使用できる場合はOCI_EXTRACT_MULTIPLEに設定し、それ以外の場合は0 (ゼロ)に設定します。

defval (IN)

キーにデフォルト値を設定します。デフォルト値がない場合はNULLです。文字列のデフォルト値は(text*)型、整数のデフォルト値は(sb4*)型およびブール・デフォルト値は(ub1*)型にする必要があります。

intrange (IN)

許容範囲の整数値の開始値および終了値です。キーが整数型でない場合、またはすべての整数値が受け入れ可能な場合はNULLになります。

strlist (IN)

0 (ゼロ) (またはNULL)で終了するキーで受け入れ可能なすべてのテキスト文字列のリストです。キーが文字列型でない場合またはすべてのテキスト値が受け入れ可能である場合はNULLになります。

コメント

このルーチンはOCIExtractSetNumKeys()をコールしてからコールし、その後にOCIExtractFromFile()またはOCIExtractFromStr()をコールする必要があります。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIExtractSetNumKeys()

用途

登録されるキー数をパラメータ・マネージャに通知します。

構文

sword OCIExtractSetNumKeys( void    *hndl,
CIError *err,
uword   numkeys );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

numkeys (IN)

OCIExtractSetKey()で登録されるキー数です。

コメント

このルーチンはOCIExtractSetKey()の最初のコールの前にコールする必要があります。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIExtractTerm()

用途

動的に割り当てたすべての記憶域を解放します。

構文

sword OCIExtractTerm( void      *hndl,
OCIError  *err );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

コメント

この関数は、他の内部ブックキーピング関数を実行する場合があります。また、パラメータ・マネージャが使用されなくなったときにコールする必要があります。また、コールは1度しか実行できません。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIExtractToBool()

用途

指定されたキーのブール値を取得します。valno値(0から開始)が戻されます。

構文

sword OCIExtractToBool( void      *hndl,
OCIError  *err,
OraText   *keyname,
uword     valno,
ub1       *retval );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

keyname (IN)

キー名です。

valno (IN)

このキーで取得する値です。

retval (OUT)

実際のブール値です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE、OCI_NO_DATAまたはOCI_ERROR。

OCI_NO_DATAは、このキーにはvalno値がないことを意味します。

OCIExtractToInt()

用途

指定されたキーの整数値を取得します。valno値(0から開始)が戻されます。

構文

sword OCIExtractToInt( void      *hndl,
OCIError  *err,
OraText   *keyname,
uword     valno,
sb4       *retval );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

keyname (IN)

キー名(IN)です。

valno (IN)

このキーで取得する値です。

retval (OUT)

実際の整数値です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE、OCI_NO_DATAまたはOCI_ERROR。

OCI_NO_DATAは、このキーにはvalno値がないことを意味します。

OCIExtractToList()

用途

メモリーに格納されているパラメータ構造からパラメータのリストを生成します。OCIExtractValues()をコールする前にコールする必要があります。

構文

sword OCIExtractToList( void      *hndl,
OCIError  *err,
uword     *numkeys );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

numkeys (OUT)

メモリーに格納されている個別キーの数です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIExtractToOCINum()

用途

指定されたキーのOCINumber値を取得します。valno値(0から開始)が戻されます。

構文

sword OCIExtractToOCINum( void      *hndl,
OCIError  *err,
OraText   *keyname,
uword     valno,
OCINumber *retval );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

keyname (IN)

キー名です。

valno (IN)

このキーで取得する値です。

retval (OUT)

実際のOCINumber値です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE、OCI_NO_DATAまたはOCI_ERROR。

OCI_NO_DATAは、このキーにはvalno値がないことを意味します。

OCIExtractToStr()

用途

指定されたキーの文字列値を取得します。valno値(0から開始)が戻されます。

構文

sword OCIExtractToStr( void       *hndl,
OCIError   *err,
OraText    *keyname,
uword      valno,
OraText    *retval,
uword      buflen );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

keyname (IN)

キー名です。

valno (IN)

このキーで取得する値です。

retval (OUT)

NULLで終了する実際の文字列値です。

buflen

retvalのバッファの長さです。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLE、OCI_NO_DATAまたはOCI_ERROR。

OCI_NO_DATAは、このキーにはvalno値がないことを意味します。

カートリッジ・サービス — ファイルI/Oインタフェース

表20-5は、この項で説明しているファイルI/Oインタフェース関数を示しています。

表20-5 ファイルI/Oインタフェース関数

関数

用途

「OCIFileClose()」

オープンされているファイルをクローズします。

「OCIFileExists()」

ファイルの存在を確認するためにテストします。

「OCIFileFlush()」

バッファ・データをファイルに書き込みます。

「OCIFileGetLength()」

ファイルの長さを取得します。

「OCIFileInit()」

OCIFileパッケージを初期化します。

「OCIFileOpen()」

ファイルをオープンします。

「OCIFileRead()」

ファイルからバッファにデータを読み取ります。

「OCIFileSeek()」

ファイルの現行の位置を変更します。

「OCIFileTerm()」

OCIFileパッケージを終了します。

「OCIFileWrite()」

buflenバイトをファイルに書き込みます。

関連項目:
これらの関数の使用方法の詳細は、『Oracle Database データ・カートリッジ開発者ガイド』を参照してください。

OCIFileObject

OCIFileObjectデータ構造には、ファイルのオープン方法およびオープンしてからそのファイルへアクセスする方法に関する情報が保持されています。この構造をOCIFileOpen()で初期化すると、ファイルで実行可能な操作によって識別子となります。このパラメータは、オープンされているファイルで実行するすべての機能に必要です。このデータ構造はOCIFileクライアントには不透明です。これはOCIFileOpen()で初期化し、OCIFileClose()で終了します。

OCIFileClose()

用途

オープンされているファイルをクローズします。

構文

sword OCIFileClose( void          *hndl,
OCIError      *err,
OCIFileObject *filep );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

クローズされるファイル識別子へのポインタです。

コメント

この関数によってOCI_SUCCESSが戻されると、filepによって指し示されたOCIFileObject構造は破棄されます。したがって、この関数によってOCI_SUCCESSが戻されてからこの構造にはアクセスしないでください。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileExists()

用途

ファイルの存在を確認するためにテストします。

構文

sword OCIFileExists( void     *hndl,
OCIError *err,
OraText  *filename,
OraText  *path,
ub1      *flag );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filename (IN)

NULLで終了する文字列のファイル名です。

path (IN)

NULLで終了する文字列のファイルのパスです。

flag (OUT)

ファイルが存在する場合はTRUEに設定し、それ以外の場合はFALSEに設定します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileFlush()

用途

バッファ・データをファイルに書き込みます。

構文

sword OCIFileFlush( void          *hndl
OCIError      *err,
OCIFileObject *filep );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイルを参照する一意のファイル識別子です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileGetLength()

用途

ファイルの長さを取得します。

構文

sword OCIFileGetLength( void     *hndl,
OCIError *err,
OraText  *filename,
OraText  *path,
ubig_ora *lenp );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filename (IN)

NULLで終了する文字列のファイル名です。

path (IN)

NULLで終了する文字列のファイルのパスです。

lenp (OUT)

バイトで示したバッファの長さに設定します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileInit()

用途

OCIFileパッケージを初期化します。この関数をコールしてから、他のOCIFileルーチンをコールする必要があります。

構文

sword OCIFileInit( void     *hndl,
OCIError *err );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileOpen()

用途

ファイルをオープンします。

構文

sword OCIFileOpen( void           *hndl,
OCIError       *err,
OCIFileObject  **filep,
OraText        *filename,
OraText        *path,
ub4            mode,
ub4            create,
ub4            type );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイル識別子です。

filename (IN)

NULLで終了する文字列のファイル名です。

path (IN)

NULLで終了する文字列のファイルのパスです。

mode (IN)

ファイルをオープンするモードです。次のモードが有効です。

OCI_FILE_READ_ONLY

OCI_FILE_WRITE_ONLY

OCI_FILE_READ_WRITE

create (IN)

ファイルが存在しない場合に作成するかどうか指定します。次の値が有効です。

OCI_FILE_TRUNCATE — ファイルをその存在の有無に関係なく作成します。ファイルが存在する場合は、既存のファイルが上書きされます。

OCI_FILE_EXCL — ファイルが存在する場合は失敗し、存在しない場合はファイルが作成されます。

OCI_FILE_CREATE — ファイルが存在する場合はそのファイルをオープンし、存在しない場合はファイルが作成されます。

OCI_FILE_APPEND — 書込みの前にファイルの終わりへのファイル・ポインタを設定します。このフラグは、OCI_FILE_CREATEで論理演算子ORとともに使用できます。

type (IN)

ファイルの型。次の値が有効です。

OCI_FILE_TEXT

OCI_FILE_BIN

OCI_FILE_STDIN

OCI_FILE_STDOUT

OCI_FILE_STDERR

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileRead()

用途

ファイルからバッファにデータを読み取ります。

構文

sword OCIFileRead( void          *hndl,
OCIError      *err,
OCIFileObject *filep,
void          *bufp,
ub4           bufl,
ub4           *bytesread );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイルを参照する一意のファイル識別子です。

bufp(IN)

データの読取り先バッファへのポインタです。buflのメモリー長が割り当てられるとみなされます。

bufl (IN)

バイトで示したバッファの長さです。

bytesread (OUT)

読取りバイト数です。

コメント

可能なバイト数をユーザー・バッファに読み取ります。読取りはユーザー・バッファが一杯になった場合、またはEOFに達すると終了します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileSeek()

用途

ファイルの現行の位置を変更します。

構文

sword OCIFileSeek( void          *hndl,
OCIError      *err,
OCIFileObject *filep,
uword         origin,
ubig_ora      offset,
sb1           dir );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイルを参照する一意のファイル識別子です。

origin (IN)

検索の開始地点です。次のいずれかの値を使用します。

OCI_FILE_SEEK_BEGINNING (先頭)

OCI_FILE_SEEK_CURRENT (現行の位置)

OCI_FILE_SEEK_END (EOF)

offset (IN)

読取り開始地点からのバイト数です。

dir (IN)

開始地点から移動する方向です。

注意:
方向はOCIFILE_FORWARDまたはOCIFILE_BACKWARDのいずれかです。

コメント

この関数では、ファイルの終わりを超えて検索できます。このような位置から読取りを実行すると、EOF条件がレポートされます。そのような位置への書込みは一部のファイル・システムでしか機能しません。これは、ファイルの動的成長が許可されていないシステムがあるためです。このようなシステムでは、ファイルを固定サイズで事前割当てする必要があります。この関数はバイト位置に対して検索を実行するということに注意してください。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileTerm()

用途

OCIFileパッケージを終了します。この関数は、OCIFileパッケージを使用しなくなってからコールする必要があります。

構文

sword OCIFileTerm( void     *hndl,
OCIError *err );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFileWrite()

用途

buflenバイトをファイルに書き込みます。

構文

sword OCIFileWrite( void          *hndl,
OCIError      *err,
OCIFileObject *filep,
void          *bufp,
ub4           buflen,
ub4           *byteswritten );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

filep (IN/OUT)

ファイルを参照する一意のファイル識別子です。

bufp (IN)

データの書込み元バッファへのポインタです。buflenのメモリー長が割り当てられるとみなされます。

buflen (IN)

バイトで示したバッファの長さです。

byteswritten (OUT)

書込みバイト数です。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

カートリッジ・サービス — 文字列のフォーマット・インタフェース

表20-6は、この項で説明している文字列のフォーマット関数を示しています。

表20-6 文字列のフォーマット関数

関数

用途

「OCIFormatInit()」

OCIFormatパッケージを初期化します。

「OCIFormatString()」

テキスト文字列を指定されたテキスト・バッファに書き込みます。

「OCIFormatTerm()」

OCIFormatパッケージを終了します。

関連項目:
これらの関数の使用方法の詳細は、『Oracle Database データ・カートリッジ開発者ガイド』を参照してください。

OCIFormatInit()

用途

OCIFormatパッケージを初期化します。

構文

sword OCIFormatInit( void      *hndl,
OCIError  *err);

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

コメント

このルーチンをコールしてから、他のOCIFormatルーチンをコールする必要があります。またこのルーチンは1度しかコールできません。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFormatString()

用途

送られた引数リストを使用し、指定のフォーマット文字列に従って、指定されたテキスト・バッファにテキスト文字列を書き込みます。

構文

sword OCIFormatString( void          *hndl,
OCIError      *err,
OraText       *buffer,
sbig_ora      bufferLength,
sbig_ora      *returnLength,
const OraText *formatString,... );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

buffer (OUT)

文字列を含むバッファです。

bufferLength (IN)

バイトで示したバッファの長さです。

returnLength (OUT)

バッファに書き込むバイト数です(終了のNULLを除く)。

formatString (IN)

リテラル・テキストとフォーマット指定の任意の組合せを指定できるフォーマット文字列です。フォーマット指定はパーセント文字(%)で区切られ、任意の数(ない場合もあります)のオプションのフォーマット修飾子が続き、必須の書式コードで終了します。フォーマット文字列が%で終わる場合、つまり、後続のフォーマット修飾子やフォーマット指定がない場合、アクションは実行されません。使用可能なフォーマット修飾子および書式コードについては、表20-7および表20-8で説明します。

... ...(IN)

OCIFormat型ラッパー形式の引数の可変数(variable)です。ここで、variableは使用される値を含む変数にする必要があります。OCIFormat型ラッパーへの引数として、定数の値または式は使用できません。使用可能なOCIFormat型ラッパーを次に示します。引数のリストは、OCIFormatEndで終了する必要があります。

OCIFormatUb1(ub1 variable);

OCIFormatUb2(ub2 variable);

OCIFormatUb4(ub4 variable);

OCIFormatUword(uword variable);

OCIFormatUbig_ora(ubig_ora variable);

OCIFormatSb1(sb1 variable);

OCIFormatSb2(sb2 variable);

OCIFormatSb4(sb4 variable);

OCIFormatSword(sword variable);

OCIFormatSbig_ora(sbig_ora variable);

OCIFormatEb1(eb1 variable);

OCIFormatEb2(eb2 variable);

OCIFormatEb4(eb4 variable);

OCIFormatEword(eword variable);

OCIFormatChar (text variable);

OCIFormatText(const text *variable);

OCIFormatDouble(double variable);

OCIFormatDvoid(const dvoid *variable);

OCIFormatEnd

コメント

このルーチンの最初のコールを実行する前に、OCIFormatInit()ルーチンのコールを実行してOCIFormatパッケージを使用できるように初期化する必要があります。このルーチンが必要なくなった場合は、OCIFormatTerm()ルーチンをコールしてOCIFormatパッケージを終了します。

フォーマット修飾子

フォーマット修飾子は、より詳細な出力が可能になるようにフォーマット指定を変更または拡張します。表20-7で説明するように、フォーマット修飾子は任意の順序で指定でき、すべてオプションです。

表20-7 フォーマット修飾子フラグ

フラグ

操作

'-'

フィールド内の出力を左揃えにします。

'+'

数値型の符号('+'または'–')を常に出力します。

' '

数値の符号が出力されない場合は、符号の位置が空白で出力されます。

'0'

数値出力に空白ではなく0 (ゼロ)を埋め込みます。

- '+'および' 'の両方のフラグが同じフォーマット指定で使用されている場合、' 'フラグは無視されます。

- '-'および'0'の両方のフラグが同じフォーマット指定で使用されている場合、'-'フラグは無視されます。

代替出力:

- 8進書式コードの場合は、先行0 (ゼロ)を追加します。

- 16進書式コードの場合は、先行'0x'を追加します。

- 浮動小数点書式コードの場合は、出力で常に基数文字が利用されます。

フィールド幅

<w>です。ここで、<w>は最小フィールド幅を指定する数値です。変換後の引数は、最低この幅で、必要に応じてさらに広い幅でフィールドに出力されます。変換後の引数の表示幅がフィールド幅より小さい場合、左側(左寄せの場合は右側)に埋込み文字が挿入され、フィールド幅を一定にします。通常、埋込み文字はスペースですが、ゼロ埋込みフラグが指定されている場合はゼロになります。<w>では特殊文字'*'が使用される場合があり、これはフィールド幅値に対して現在の引数が使用されていることを示します。実際のフィールドまたは精度は、後続の引数に従います。

精度

.<p> (ピリオドとそれに続く数値<p>)は、文字列から出力する表示位置の最大数、または10進数値の小数点の後の桁、あるいは整数型で出力する場合の最小桁数を指定します(相違を補うために先行0 (ゼロ)が追加されます)。特殊文字'*'は、<p>のかわりに使用され、現行の引数に精度値があることを示します。

引数索引

(<n>)です。ここで、<n>は最初の引数が1である引数リストへの整数の索引です。フォーマット情報として引数索引が指定されていない場合は、最初の引数が選択されます。次回もフォーマット情報として引数索引が指定されていない場合は、2番目の引数が選択され、以降同様に続きます。引数索引を持つまたは持たないフォーマット情報はともに任意の順序で指定でき、操作においてはお互いが独立しています。

たとえば、フォーマット文字列"%u %(4)u %u %(2)u %u"では、OCIFormatString()に指定された1番目、4番目、2番目、2番目および3番目の引数が選択されます。

書式コード

書式コードは文字列中の引数のフォーマット方法を指定します。

表20-8で説明するように、これらの書式コードは、大文字にすると、テキスト文字列を除くすべてのアルファベット文字が大文字で出力されます。テキスト文字列には、この変換は行われません。

表20-8 文字列中の引数のフォーマット方法を指定する書式コード

コード

操作

'c'

コンパイラ・キャラクタ・セット内のシングルバイト文字。

'd'

符号付き10進整数。

'e'

形式[-]<d><r>[<d>...]e+[<d>]<d><d>の指数(科学的)表記法。ここで、<r>は現在の言語の基数文字、<d>は任意の1桁を示します。デフォルトの精度は、定数OCIFormatDPで指定されます。精度は、必要に応じてフォーマット修飾子として指定できます。精度として0 (ゼロ)を指定すると、基数文字が表示されません。また、指数は常に最低2桁で出力され、最大3桁まで指定できます(たとえば、1e+01、1e+10、1e+100など)。

'f'

形式[-]<d>[<d>...]<r>[<d>...]の固定小数点表記法。ここで、<r>は現在の言語に適切な基数文字、<d>は任意の1桁を示します。精度は、必要に応じてフォーマット修飾子として指定できます。精度として0 (ゼロ)を指定すると、基数文字が表示されません。デフォルトの精度は、定数OCIFormatDPで指定されます。

'g'

変数浮動小数点表記法。'e'または'f'を選択します。数値が指定された精度に適合する場合は'f'を選択します(指定されていない場合はデフォルトの精度)。指数フォーマットでより多くの桁を出力できる場合のみ'e'を選択します。数値に分数部分がない場合は基数文字は出力されません。

'i'

'd'と同一。

'o'

符号なし8進整数。

'p'

オペレーティング・システム固有のポインタ印刷出力。

's'

次の型ではデフォルトの書式コードを使用して引数を出力します。

ociformatub<n>、ociformatuword、ociformatubig_ora、ociformateb<n>およびociformateword。

使用される書式コードは'u'です。

ociformatsb<n>、ociformatswordおよびociformatsbig_ora。

使用される書式コードは'd'です。

ociformatchar

使用される書式コードは'c'です。

ociformattext

後続のNULLが検出されるまでテキストを出力します。

ociformatdouble

使用される書式コードは'g'です。

ociformatdvoid

使用される書式コードは'p'です。

' %' - print a '%'。

'u'

符号なし10進整数。

'x'

符号なし16進整数。

例

例20-2 OCIFormatString()を使用した、2つの方法での2つの国の日付のフォーマット

/* This example shows the power of arbitrary argument    */
/* selection in the context of internationalization.  A  */
/* date is formatted in two different ways for two different */
/* countries according to the format string, yet the      */
/* argument list submitted to OCIFormatString remains    */
/* invariant.                                            */

text      buffer[255];
ub1       day, month, year;
OCIError *err;
void     *hndl;
sbig_ora  returnLen;

/* Set the date. */

day   = 10;
month = 3;
year  = 97;

/* Work out the date in United States style: mm/dd/yy */
OCIFormatString(hndl, err,
buffer, (sbig_ora)sizeof(buffer), &returnLen
(const text *)"%(2)02u/%(1)02u/%(3)02u",
OCIFormatUb1(day),
OCIFormatUb1(month),
OCIFormatUb1(year),
OCIFormatEnd);    /* Buffer is "03/10/97". */

/* Work out the date in New Zealand style: dd/mm/yy */
OCIFormatString(hndl, err,
buffer, (sbig_ora)sizeof(buffer), &returnLen
(const text *)"%(1)02u/%(2)02u/%(3)02u",
OCIFormatUb1(day),
OCIFormatUb1(month),
OCIFormatUb1(year),
OCIFormatEnd);    /* Buffer is "10/03/97". */

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIFormatTerm()

用途

OCIFormatパッケージを終了します。

構文

sword OCIFormatTerm( void     *hndl,
OCIError *err);

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

コメント

この関数は、OCIFormatパッケージを使用しなくなってからコールする必要があります。また、コールは1度しか実行できません。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

21 OCIの任意型関数および任意データ関数

この章では、OCIの任意型関数および任意データ関数について説明します。

関連項目:
コード例は、Oracle Databaseのインストールに含まれているデモ・プログラムを参照してください。詳細は、付録Bを参照してください。

この章は、次の項目で構成されています。

- 任意型インタフェースおよび任意データ・インタフェースの概要

- OCIの型インタフェース関数

- OCI任意データ・インタフェース関数

- OCI任意データ・セット・インタフェース関数

任意型インタフェースおよび任意データ・インタフェースの概要

この章では、OCIの任意型関数および任意データ関数の詳細について説明します。

関連項目:
「AnyTypeインタフェース、AnyDataインタフェースおよびAnyDataSetインタフェース」

OCI関数の規則

各関数を記述する際に使用される規則は、「OCI関数の規則」を参照してください。関数ごとに次の情報が記載されている場合もあります。

関数戻り値

OCIの任意型関数および任意データ関数は、通常、表21-1で説明する値のいずれかを戻します。

表21-1 関数戻り値

戻り値

意味

OCI_SUCCESS

操作は成功しました。

OCI_ERROR

操作は失敗しました。関数に渡されたエラー・ハンドルに対してOCIErrorGet()をコールすることで特定のエラーを取り出せます。

OCI_INVALID_HANDLE

関数に渡されたOCIハンドルが無効です。

関連項目:
リターン・コードおよびエラー処理の詳細は、「OCIでのエラー処理」を参照してください。

OCIの型インタフェース関数

表21-2は、この項で説明している型インタフェース関数を示しています。

表21-2 型インタフェース関数

関数

用途

「OCITypeAddAttr()」

型コードOCI_TYPECODE_OBJECTを使用して以前作成したオブジェクト型に属性を追加します。

「OCITypeBeginCreate()」

一時的な型に対する構成プロセスを開始します。この型は無名(名前なし)です。

「OCITypeEndCreate()」

型の記述の構成を終了します。終了後は、アクセスのみ可能です。

「OCITypeSetBuiltin()」

組込みの型情報を設定します。このコールは、型が組込みの型コード(OCI_TYPECODE_NUMBERなど)を使用して構成されている場合のみ実行されます。

「OCITypeSetCollection()」

コレクション型情報を設定します。このコールは、型がコレクション型コードを使用して構成されている場合のみ実行されます。

OCITypeAddAttr()

用途

型コードOCI_TYPECODE_OBJECTを使用して以前作成したオブジェクト型に属性を追加します。

構文

sword OCITypeAddAttr ( OCISvcCtx   *svchp,
OCIError    *errhp,
OCIType     *type,
const text  *a_name,
ub4         a_length,
OCIParam    *attr_info );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

type (IN/OUT)

構成される型の記述です。

a_name (IN) [オプション]

属性の名前です。

a_length (IN) [オプション]

属性名の長さ(バイト単位)です。

attr_info (IN)

属性に関する情報です。この情報は、OCIParamパラメータ・ハンドルを割り当て、OCIAttrSet()コールを使用して型情報をOCIParamに設定して取得します。

OCITypeBeginCreate()

用途

一時的な型に対する構成プロセスを開始します。この型は無名(名前なし)です。

構文

sword OCITypeBeginCreate ( OCISvcCtx    *svchp,
OCIError     *errhp,
OCITypeCode  tc,
OCIDuration  dur,
OCIType      **type );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

tc (IN)

型に対する型コードです。この型コードは、オブジェクト型または組込みの型に対応している場合があります。

現在、ユーザー定義型に対して可能な値は次のとおりです。

- OCI_TYPECODE_OBJECT (構成済のオブジェクト型の場合)

- OCI_TYPECODE_VARRAY (VARRAYコレクション型の場合)

- OCI_TYPECODE_TABLE (NESTED TABLEコレクション型の場合)

オブジェクト型の場合は、OCITypeAddAttr()をコールして、各属性型を追加します。コレクション型の場合は、OCITypeSetCollection()をコールします。次に、OCITypeEndCreate()をコールして、作成プロセスを終了します。

組込みの型コードに対して可能な値は、「型コード」で指定されています。組込みの型に関する追加情報(精度、数値のスケール、VARCHAR2のキャラクタ・セット情報など)がある場合は、後続のOCITypeSetBuiltin()コールで設定してください。最後に、OCITypeEndCreate()を使用して、作成プロセスを終了します。

dur (IN)

型に対する割当て時間です。次のいずれかです。

- 以前に作成されたユーザー期間。これは、OCIDurationBegin()を使用して作成できます。

- OCI_DURATION_SESSIONなどの事前定義の期間。

type (OUT)

構成されるOCIType (型の記述子)です。

コメント

永続的な名前付きの型を作成するには、SQL文CREATE TYPEを使用してください。一時的な型には識別情報がありません。これらは純粋な値です。

OCITypeEndCreate()

用途

型の記述の構成を終了します。終了後は、アクセスのみ可能です。

構文

sword OCITypeEndCreate ( OCISvcCtx  *svchp,
OCIError   *errhp,
OCIType    *type );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

type (IN/OUT)

構成される型の記述です。

OCITypeSetBuiltin()

用途

組込みの型情報を設定します。このコールは、型が組込みの型コード(OCI_TYPECODE_NUMBERなど)を使用して構成されている場合のみ実行されます。

構文

sword OCITypeSetBuiltin ( OCISvcCtx   *svchp,
OCIError    *errhp,
OCIType     *type,
OCIParam    *builtin_info );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

type (IN/OUT)

構成される型の記述です。

builtin_info (IN)

組込みの型に関する情報(精度、スケール、キャラクタ・セットなど)を提供します。この情報は、OCIParamパラメータ・ハンドルを割り当て、OCIAttrSet()コールを使用して型情報をOCIParamに設定して取得します。

OCITypeSetCollection()

用途

コレクション型情報を設定します。このコールは、型がコレクション型コードを使用して構成されている場合のみ実行されます。

構文

sword OCITypeSetCollection ( OCISvcCtx   *svchp,
OCIError    *errhp,
OCIType     *type,
OCIParam    *collelem_info,
ub4         coll_count );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

type (IN/OUT)

構成される型の記述子です。

collelem_info (IN)

collelem_infoによって、コレクション要素に関する情報が提供されます。この情報は、OCIParamパラメータ・ハンドルを割り当て、OCIAttrSet()コールを使用して型情報をOCIParamに設定して取得します。

coll_count (IN)

コレクション内の要素数です。ネストした表(非有界)の場合は、0 (ゼロ)が渡されます。

OCI任意データ・インタフェース関数

表21-3は、この項で説明している任意データ・インタフェース関数を示しています。

表21-3 任意データ関数

関数

用途

「OCIAnyDataAccess()」

OCIAnyDataのデータ値を取り出します。

「OCIAnyDataAttrGet()」

OCIAnyDataの現行の位置にある属性の値を取得します。

「OCIAnyDataAttrSet()」

現行の位置にある属性に指定の値を設定します。

「OCIAnyDataBeginCreate()」

指定の継続時間に対してOCIAnyDataを割り当て、型情報を使用して初期化します。

「OCIAnyDataCollAddElem()」

現行の属性位置にあるOCIAnyDataのコレクション属性に、次のコレクション要素を追加します。

「OCIAnyDataCollGetElem()」

現行の位置にあるOCIAnyDataのコレクション属性内の要素に順次アクセスします。

「OCIAnyDataConvert()」

指定の型の指定のデータ値を使用してOCIAnyDataを構成します。

「OCIAnyDataDestroy()」

AnyDataを解放します。

「OCIAnyDataEndCreate()」

OCIAnyData作成の終わりをマークします。

「OCIAnyDataGetCurrAttrNum()」

OCIAnyDataの現行の属性番号を戻します。

「OCIAnyDataGetType()」

AnyData値に対応する型を取得します。

「"OCIAnyDataIsNull()」

OCIAnyDataがNULLかどうかをチェックします。

「OCIAnyDataTypeCodeToSqlt()」

AnyData値のOCITypeCodeをOCIAnyData APIが戻す値の表現に対応するSQLTコードに変換します。

OCIAnyDataAccess()

用途

OCIAnyDataのデータ値を取り出します。データ値は、OCIAnyDataの初期化で使用された型になります。このコールを使用すると、OCI_TYPECODE_OBJECT型、任意のコレクション型または任意の組込みの型など、OCIAnyData全体にアクセスできます。

構文

sword OCIAnyDataAccess ( OCISvcCtx    *svchp,
OCIError     *errhp,
OCIAnyData   *sdata,
OCITypeCode  tc,
OCIType      *inst_type,
void         *null_ind,
void         *data_value,
ub4          *length );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sdata (IN)

OCIAnyDataへの初期化済ポインタです。

tc (IN)

データ値の型コードです。この型コードを使用して型をチェックします(OCIAnyDataが初期化された型)。

inst_type (IN)

データ値のOCITypeです(基本形でない場合)。tcパラメータが次のいずれかの型の場合、このパラメータはNULLにしないでください。

- OCI_TYPECODE_OBJECT

- OCI_TYPECODE_REF

- OCI_TYPECODE_VARRAY

- OCI_TYPECODE_TABLE

これ以外のパラメータの場合は、NULLでもかまいません。

null_ind (OUT)

data_valueがNULLかどうかを示します。OCI_TYPECODE_OBJECT以外のすべての型コードについて、(OCIInd *)を渡します。戻される値は、値がNULL以外の場合はOCI_IND_NOTNULLに、値がNULLの場合はOCI_IND_NULLになります。型コードがOCI_TYPECODE_OBJECTの場合は、data_valueのインジケータ構造体へのポインタがここの引数として渡されます。詳細は、「OCIAnyDataAttrGet()」を参照してください。

data_value (OUT)

データ値です(OCIAnyDataの初期化で使用された型になります)。可能な各型コードに対応する適切なC型とこのパラメータに渡される値に応じたメモリー割当て動作については、「OCIAnyDataAttrGet()」を参照してください。

length (OUT)

現在、このパラメータは無視されます。今後、このパラメータは、データ表現自体が長さ(バイト単位)を暗黙的に渡さないような特定の型コードに使用される予定です。

OCIAnyDataAttrGet()

用途

OCIAnyDataの現行の位置にある属性の値を取得します。属性値には順次アクセスできます。

構文

sword OCIAnyDataAttrGet ( OCISvcCtx    *svchp,
OCIError     *errhp,
OCIAnyData   *sdata,
OCITypeCode  tc,
OCIType      *attr_type,
void         *null_ind,
void         *attr_value,
ub4          *length,
boolean      is_any );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sdata (IN/OUT)

初期化済のOCIAnyData型へのポインタです。

tc (IN)

属性の型コードです。型のチェックは、tc、attr_typeおよびOCIAnyDataの型情報に基づいて行われます。

attr_type (IN) [オプション]

attr_typeパラメータは、参照先の型(OCI_TYPECODE_REFの場合)、コレクション型(OCI_TYPECODE_VARRAY、OCI_TYPECODE_TABLEの場合)またはオブジェクト(OCI_TYPECODE_OBJECTの場合)の型の記述を指定します。組込みの型コードの場合、このパラメータは必要ありません。

null_ind (OUT)

attr_valueがNULLかどうかを示します。OCI_TYPECODE_OBJECT以外のすべての型コードについて、(OCIInd *)をnull_indで渡します。

型コードがOCI_TYPECODE_OBJECTの場合は、ポインタ (void **)をnull_indで渡します。

戻されるインジケータは、値がNULL以外の場合はOCI_IND_NOTNULLに、値がNULLの場合はOCI_IND_NULLになります。

attr_value (IN/OUT)

属性の値です。

length (IN/OUT)

現在、このパラメータは無視されます。ここでは、0 (ゼロ)を渡してください。今後、このパラメータは、データ表現自体が長さ(バイト単位)を暗黙的に渡さないような特定の型コードに使用される予定です。

is_any (IN)

属性がOCIAnyDataの形式で戻されるかどうかを示します。

コメント

このコールは、型コードがOCI_TYPECODE_OBJECTのOCIAnyDataでのみ使用できます。

- このコールは、OCIAnyDataの現行の位置にある属性の値を取得します。

- tcパラメータは、現行の位置にある属性の型と一致する必要があります。一致しない場合はエラーが戻されます。

- is_anyパラメータは、属性の型コードが次のいずれかの値の場合のみ適用できます。

- OCI_TYPECODE_OBJECT

- OCI_TYPECODE_VARRAY

- OCI_TYPECODE_TABLE

is_anyがTRUEの場合、attr_valueはOCIAnyData *の形式で戻されます。

- 関数をコールする前に、属性に対してメモリーを割り当てる必要があります。メモリーはOCIObjectNew()を使用して割り当てることができます。NUMBER、VARCHARなどの組込みの型の場合、属性は単なるスタック変数へのポインタである場合があります。表21-4 には、オブジェクトの属性型として使用できるOracleデータ型、およびそれに対応して渡される属性値の型が示されています。

表21-4 データ型および属性値

データ型

attr_value

VARCHAR2、VARCHAR、CHAR

OCIString **

NUMBER、REAL、INT、FLOAT、DECIMAL

OCINumber **

DATE

OCIDate **

TIMESTAMP

OCIDateTime **

TIMESTAMPWITHTIMEZONE

OCIDateTime **

TIMESTAMPWITHLOCALTIMEZONE

OCIDateTime **

INTERVALYEARTOMONTH

OCIInterval **

INTERVALDAYTOSECOND

OCIInterval **

BLOB

OCILobLocator **またはOCIBlobLocator **

CLOB

OCILobLocator **またはOCIClobLocator *

BFILE

OCILobLocator**

REF

OCIRef**

RAW

OCIRaw**

VARRAY

OCIArray ** (is_anyがTRUEの場合はOCIAnyData *)

TABLE

OCITable ** (is_anyがTRUEの場合はOCIAnyData *)

OBJECT

void ** (is_anyがTRUEの場合はOCIAnyData *)

OCIAnyDataAttrSet()

用途

現行の位置にある属性に指定の値を設定します。

構文

sword OCIAnyDataAttrSet ( OCISvcCtx    *svchp,
OCIError     *errhp,
OCIAnyData   *sdata,
OCITypeCode  tc,
OCIType      *attr_type,
void         *null_ind,
void         *attr_value,
ub4          length,
boolean      is_any );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sdata (IN/OUT)

初期化済のOCIAnyDataです。

tc (IN)

属性の型コードです。型のチェックは、tc、attr_typeおよびOCIAnyDataの型情報に基づいて行われます。

attr_type (IN) [オプション]

attr_typeパラメータは、参照先の型(OCI_TYPECODE_REFの場合)、コレクション型(OCI_TYPECODE_VARRAY、OCI_TYPECODE_TABLEの場合)およびオブジェクト(OCI_TYPECODE_OBJECTの場合)の型の記述を指定します。組込みの型コードの場合、またはOCI_TYPECODE_NONEが指定されている場合、このパラメータは必要ありません。

null_ind (IN)

attr_valueがNULLかどうかを示します。OCI_TYPECODE_OBJECT以外のすべての型コードについて、(OCIInd *)を渡します。インジケータは、値がNULL以外の場合はOCI_IND_NOTNULLに、値がNULLの場合はOCI_IND_NULLになります。

型コードがOCI_TYPECODE_OBJECTの場合は、attr_valueのインジケータ構造体へのポインタがここの引数として渡されます。

attr_value (IN)

属性の値です。

length (IN)

現在、このパラメータは無視されます。ここでは、0 (ゼロ)を渡してください。今後、このパラメータは、データ表現自体が長さを暗黙的に渡さないような特定の型コードに使用される予定です。

is_any (IN)

属性がOCIAnyDataの形式かどうかを示します。

コメント

OCIAnyDataBeginCreate()によって、空のスケルトン・インスタンスを持つOCIAnyDataが作成されます。属性値を入力するには、OCIAnyDataAttrSet() (OCI_TYPECODE_OBJECTの場合)またはOCIAnyDataCollAddElem() (コレクション型コードの場合)を使用します。

属性値は、最初の属性から最後の属性まで順に設定する必要があります。現行の属性番号は、OCIAnyData内部のメンテナンス状態として記憶されています。埋込み属性およびコレクション要素のピース単位の構成はサポートされていません。

このコールによって、現行の位置にある属性にattr_valueが設定されます。OCIAnyDataインスタンスに対するピース単位の構成を開始すると、OCIAnyDataConstruct()はコールできなくなります。

tcパラメータは、現行の位置にある属性の型と一致する必要があります。それ以外の場合はエラーが戻されます。

is_anyがTRUEの場合、属性はOCIAnyData*の形式であることが必要で、変換されずに、囲まれたOCIAnyData (データ)にコピーされます。

表21-5 には、オブジェクトの属性型として使用できるデータ型、およびそれに対応して渡される属性値の型が示されています。

表21-5 データ型および属性値

データ型

attr_value

VARCHAR2、VARCHAR、CHAR

OCIString *

NUMBER、REAL、INT、FLOAT、DECIMAL

OCINumber*

DATE

OCIDate*

TIMESTAMP

OCIDateTime *

TIMESTAMPWITHTIMEZONE

OCIDateTime *

TIMESTAMPWITHLOCALTIMEZONE

OCIDateTime *

INTERVALYEARTOMONTH

OCIInterval *

INTERVALDAYTOSECOND

OCIInterval *

BLOB

OCILobLocator *またはOCIBlobLocator *

CLOB

OCILobLocator *またはOCIClobLocator *

BFILE

OCILobLocator *

REF

OCIRef *

RAW

OCIRaw *

VARRAY

OCIArray * (is_anyがTRUEの場合はOCIAnyData *)

TABLE

OCITable * (is_anyがTRUEの場合はOCIAnyData *)

OBJECT

void * (is_anyがTRUEの場合はOCIAnyData *)

OCIAnyDataBeginCreate()

用途

指定の継続時間に対してOCIAnyDataを割り当て、型情報を使用して初期化します。

構文

sword OCIAnyDataBeginCreate ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCITypeCode    tc,
OCIType        *type,
OCIDuration    dur,
OCIAnyData     **sdata );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

tc (IN)

OCIAnyDataに対応する型コードす。組込みの型コード、または次のようなユーザー定義型の型コードが可能です。

- OCI_TYPECODE_OBJECT

- OCI_TYPECODE_REF

- OCI_TYPECODE_VARRAY

type (IN)

OCIAnyDataに対応する型です。型コードが組込みの型(OCI_TYPECODE_NUMBERなど)に対応している場合、このパラメータはNULLにできます。また、ユーザー定義型(OCI_TYPECODE_OBJECT、OCI_TYPECODE_REF、コレクション型など)の場合は、NULL以外になります。

dur (IN)

OCIAnyDataが割り当てられる継続時間です。次のいずれかです。

- 以前に作成されたユーザー期間。これは、OCIDurationBegin()を使用して作成できます。

- OCI_DURATION_SESSIONなどの事前定義の期間。

sdata (OUT)

初期化済のOCIAnyDataです。コールの開始時に(*sdata)がNULLでない場合は、OCIAnyDataに領域を再割当てするかわりにメモリーを再使用できます。

したがって、初期化していないポインタをここで渡さないでください。

コメント

OCIAnyDataBeginCreate()によって、空のスケルトン・インスタンスを持つOCIAnyDataが作成されます。属性値を入力するには、OCIAnyDataAttrSet() (OCI_TYPECODE_OBJECTの場合)またはOCIAnyDataCollAddElem() (コレクション型コードの場合)を使用します。

属性値は順に設定する必要があります。最初の属性から最後の属性に順に設定してください。現行の属性番号は、OCIAnyData内部のメンテナンス状態として記憶されています。埋込み属性およびコレクション要素のピース単位の構成はサポートされていません。

パフォーマンス向上のために、OCIAnyDataは最終的に、渡されたOCITypeパラメータを指し示します。OCITypeの継続時間が延長されていることを確認する必要があります(OCITypeが一時パラメータの場合は割当て時間 >= OCIAnyDataの継続時間、OCITypeが永続パラメータの場合は割当てまたは確保継続時間 >= OCIAnyDataの継続時間)。

OCIAnyDataCollAddElem()

用途

現行の属性位置にあるOCIAnyDataのコレクション属性に、次のコレクション要素を追加します。OCIAnyDataがコレクション型の場合は、属性位置の概念がなく、このコールでは次のコレクション要素が追加されます。

構文

sword OCIAnyDataCollAddElem ( OCISvcCtx    *svchp,
OCIError     *errhp,
OCIAnyData   *sdata,
OCITypeCode  collelem_tc,
OCIType      *collelem_type,
void         *null_ind,
void         *elem_value,
ub4          length,
boolean      is_any,
boolean      last_elem );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sdata (IN/OUT)

初期化済のOCIAnyDataです。

collelem_tc (IN)

追加するコレクション要素の型コードです。型のチェックは、collelem_tc、collelem_typeおよびOCIAnyDataの型情報に基づいて行われます。

collelem_type (IN) [オプション]

collelem_typeパラメータは、参照先の型(OCI_TYPECODE_REFの場合)、コレクション型(OCI_TYPECODE_NAMEDCOLLECTIONの場合)およびオブジェクト(OCI_TYPECODE_OBJECTの場合)の型の記述を指定します。

組込みの型コードの場合、このパラメータは必要ありません。

null_ind (IN)

elem_valueがNULLかどうかを示します。OCI_TYPECODE_OBJECT以外のすべての型コードについて、(OCIInd *)を渡します。インジケータは、値がNULL以外の場合はOCI_IND_NOTNULLに、値がNULLの場合はOCI_IND_NULLになります。

型コードがOCI_TYPECODE_OBJECTの場合は、elem_valueのインジケータ構造体へのポインタがここの引数として渡されます。

elem_value (IN)

コレクション要素の値です。

length (IN)

コレクション要素の長さです。

is_any (IN)

属性がOCIAnyDataの形式かどうかを示します。

last_elem (IN)

追加する要素がコレクション内で最後の要素かどうかを示します。

コメント

このコールは、OCI_TYPECODE_OBJECT型または任意のコレクション型のOCIAnyDataに対して呼び出すことができます。OCIAnyDataインスタンスに対するピース単位の構成を開始すると、OCIAnyDataConstruct()はコールできなくなります。

OCIAnyDataAttrSet()と同様に、is_anyは、collelem_tcの型コードがOCI_TYPECODE_OBJECTまたはコレクション型コードの場合のみ適用できます。is_anyがTRUEの場合、属性はOCIAnyData*の形式であることが必要です。

追加する要素がコレクション内で最後の要素の場合は、last_elemをTRUEに設定する必要があります。

NULL要素を追加するには、NULLインジケータ(null_ind)をOCI_IND_NULLに設定します。この場合、他のすべての引数は無視されます。それ以外の場合、null_indはOCI_IND_NOTNULLに設定する必要があります。

可能なすべての型のコレクション要素に渡される属性の型については、「OCIAnyDataAttrSet()」を参照してください。

OCIAnyDataCollGetElem()

用途

現行の位置にあるOCIAnyDataのコレクション属性内の要素に順次アクセスします。

構文

sword OCIAnyDataCollGetElem ( OCISvcCtx    *svchp,
OCIError     *errhp,
OCIAnyData   *sdata,
OCITypeCode  collelem_tc,
OCIType      *collelem_type,
void         *null_ind,
void         *collelem_value,
ub4          *length,
boolean      is_any );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sdata (IN/OUT)

初期化済のOCIAnyDataです。

collelem_tc (IN)

取り出すコレクション要素の型コードです。型のチェックは、collelem_tc、collelem_typeおよびOCIAnyDataの型情報に基づいて行われます。

collelem_type (IN) [オプション]

collelem_typeパラメータは、参照先の型(OCI_TYPECODE_REFの場合)、コレクション型(OCI_TYPECODE_NAMEDCOLLECTIONの場合)およびオブジェクト(OCI_TYPECODE_OBJECTの場合)の型の記述を指定します。

組込みの型コードの場合、このパラメータは必要ありません。

null_ind (OUT)

collelem_valueがNULLかどうかを示します。OCI_TYPECODE_OBJECT以外のすべての型コードについて、(OCIInd *)を渡します。インジケータは、値がNULL以外の場合はOCI_IND_NOTNULLに、値がNULLの場合はOCI_IND_NULLになります。

型コードがOCI_TYPECODE_OBJECTの場合は、collelem_valueのインジケータ構造体へのポインタ(void **)がここの引数として渡されます。

collelem_value (IN/OUT)

コレクション要素の値です。

length (IN/OUT)

コレクション要素の長さです。現在は無視されます。入力時には、0 (ゼロ)を設定してください。

is_any (IN)

attr_valueがOCIAnyDataの形式で戻されるかどうかを示します。

コメント

OCIAnyDataデータは、トップレベルのコレクションに対応させることもできます。OCIAnyDataがOCI_TYPECODE_OBJECT型の場合、現行の位置の属性は適切な型のコレクションであることが必要です。それ以外の場合はエラーが戻されます。

OCIAnyDataAttrGet()と同様に、is_anyパラメータは、collelem_tcの型コードがOCI_TYPECODE_OBJECTである場合のみ適用されます。is_anyがTRUEの場合、attr_valueはOCIAnyData *の形式になります。

このコールは、コレクションの終わりに達するとOCI_NO_DATAを戻します。成功時にはOCI_SUCCESSを戻し、エラーが発生した場合はOCI_ERRORを戻します。

可能なすべての型のコレクション要素に渡される属性の型については、「OCIAnyDataAttrGet()」を参照してください。

OCIAnyDataConvert()

用途

指定の型の指定のデータ値を使用してOCIAnyDataを構成します。このコールを使用すると、OCI_TYPECODE_OBJECT型、任意のコレクション型または任意の組込みの型など、OCIAnyData全体を構成できます。

構文

sword OCIAnyDataConvert ( OCISvcCtx    *svchp,
OCIError     *errhp,
OCITypeCode  tc,
OCIType      *inst_type,
OCIDuration  dur,
void         *null_ind,
void         *data_value,
ub4          length,
OCIAnyData   **sdata );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

tc (IN)

データ値の型コードです。組込みの型コードまたはユーザー定義型の型コード(OCI_TYPECODE_OBJECT、OCI_TYPECODE_REF、OCI_TYPECODE_VARRAYなど)が可能です。

(*sdata)がNULL以外で、OCIAnyDataSetAddInstance()のコール時に戻されたスケルトン・インスタンスを表す場合、tcパラメータおよびinst_typeパラメータは、ここのオプションになります。これは、このようなスケルトン・インスタンスの型情報は認識されているためです。この状況で、tcパラメータとinst_typeパラメータが指定されると、これらのパラメータは型のチェックにのみ使用されます。

inst_type (IN)

OCIAnyDataに対応する型です。型コードが組込みの型(OCI_TYPECODE_NUMBERなど)に対応している場合、このパラメータはNULLにできます。ユーザー定義型(OCI_TYPECODE_OBJECT、OCI_TYPECODE_REF、コレクション型など)の場合は、NULL以外になります。

dur (IN)

OCIAnyDataが割り当てられる継続時間です。次のいずれかです。

- 以前に作成されたユーザー期間。これは、OCIDurationBegin()を使用して作成できます。

- OCI_DURATION_SESSIONなどの事前定義の期間。

null_ind

data_valueがNULLかどうかを示します。OCI_TYPECODE_OBJECT以外のすべての型コードについて、(OCIInd *)を渡します。インジケータは、値がNULL以外の場合はOCI_IND_NOTNULLに、値がNULLの場合はOCI_IND_NULLになります。

型コードがOCI_TYPECODE_OBJECTの場合は、data_valueのインジケータ構造体へのポインタがここの引数として渡されます。

data_value (IN)

データ値です(OCIAnyDataの初期化で使用された型になります)。使用できる各型コードに対応する適切なC言語の型の詳細は、OCIAnyDataAttrSet()に関する説明を参照してください。

length (IN)

現在、このパラメータは無視されます。ここでは、0 (ゼロ)を渡してください。今後、このパラメータは、データ表現自体が長さを暗黙的に渡さないような特定の型コードに使用される予定です。

sdata (IN/OUT)

初期化済のOCIAnyDataです。コールの開始時に(*sdata)がNULLでない場合は、OCIAnyDataに領域を再割当てするかわりにメモリーを再使用できます。

したがって、初期化していないポインタをここで渡さないでください。

(*sdata)がOCIAnyDataSetAddInstance()のコール時に戻されたスケルトン・インスタンスを表す場合、tcパラメータおよびinst_typeパラメータは、必要に応じて型のチェックに使用されます。

コメント

パフォーマンス向上のため、OCIAnyDataポインタは最終的に、渡されたOCITypeパラメータを指し示します。OCITypeの継続時間が延長されていることを確認する必要があります(OCITypeが一時パラメータの場合は割当て時間 >= OCIAnyDataの継続時間、OCITypeが永続パラメータの場合は割当てまたは確保継続時間 >= OCIAnyDataの継続時間)。

OCIAnyDataDestroy()

用途

OCIAnyDataを解放します。

構文

sword OCIAnyDataDestroy ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyData     *sdata );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sdata (IN/OUT)

解放するOCIAnyDataの型へのポインタです。

OCIAnyDataEndCreate()

用途

OCIAnyData作成の終わりをマークします。この関数は、インスタンスのすべての属性を適切な値で初期化してからコールしてください。このコールは、OCIAnyDataに対してOCIAnyDataBeginCreate()がすでにコールされている場合にのみ有効です。

構文

sword OCIAnyDataEndCreate ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyData     *data );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

data (IN/OUT)

初期化済のOCIAnyDataです。

OCIAnyDataGetCurrAttrNum()

用途

OCIAnyDataの現行の属性番号を戻します。OCIAnyDataを構成する場合、この関数は設定する現行の属性を参照します。また、OCIAnyDataにアクセスする場合は、この関数はアクセスする属性を参照します。

構文

sword OCIAnyDataGetCurrAttrNum( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyData     *sdata,
ub4            *attrnum );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sdata (IN)

初期化済のOCIAnyDataです。

attrnum (OUT)

属性番号です。

OCIAnyDataGetType()

用途

OCIAnyData値に対応する型を取得します。この関数は、OCIAnyDataの内部でメンテナンスされている型への実際のポインタを戻します。パフォーマンス向上のため、コピーは行われません。OCIAnyDataを解放した後(または継続時間が終了した後)は、この型を使用しないでください。

構文

sword OCIAnyDataGetType( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyData     *data,
OCITypeCode    *tc,
OCIType        **type );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

data (IN)

初期化済のOCIAnyDataです。

tc (OUT)

OCIAnyDataに対応する型コードです。

type (OUT)

OCIAnyDataに対応する型です。OCIAnyDataが組込みの型に対応している場合は、NULLになります。

OCIAnyDataIsNull()

用途

OCIAnyData内の型の内容がNULLかどうかをチェックします。

構文

sword OCIAnyDataIsNull ( OCISvcCtx         *svchp,
OCIError          *errhp,
const OCIAnyData  *sdata,
boolean           *isNull) ;

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

sdata (IN)

チェックするOCIAnyDataです。

isNull (IN/OUT)

NULLの場合はTRUE、それ以外の場合はFALSEです。

OCIAnyDataTypeCodeToSqlt()

用途

OCIAnyData値のOCITypeCodeをOCIAnyData APIが戻す値の表現に対応するSQLTコードに変換します。

構文

sword  OCIAnyDataTypeCodeToSqlt ( OCIError       *errhp,
OCITypeCode    tc,
ub1            *sqltcode,
ub1            *csfrm) ;

パラメータ

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errhpに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

tc (IN)

AnyData値に対応するOCITypeCodeです。

sqltcode (OUT)

型コードのユーザー・フォーマットに対応するSQLTコードです。

csfrm (OUT)

型コードのユーザー・フォーマットに対応するキャラクタ・セット・フォームです。キャラクタ・タイプの場合のみ有効です。(NCHAR型の) SQLCS_IMPLICITまたはSQLCS_NCHARを戻します。

コメント

この関数は、OCI_TYPECODE_CHARおよびOCI_TYPECODE_VARCHAR2を、SQLCS_IMPLICITのキャラクタ・セット・フォームでSQLT_VST (OCIStringマッピングに相当する)に変換します。また、OCI_TYPECODE_NVARCHAR2は、キャラクタ・セット・フォームがSQLCS_NCHARのSQLT_VST (OCIStringマッピングはOCIAnyData APIで使用されます)を戻します。

関連項目:
「OCIAnyData関数のNCHAR型コード」

OCI任意データ・セット・インタフェース関数

表21-6は、この項で説明している任意データ・セット・インタフェース関数を示しています。

表21-6 任意データ・セット関数

関数

用途

「OCIAnyDataSetAddInstance()」

新規のスケルトン・インスタンスをOCIAnyDataSetに追加し、そのインスタンスのすべての属性をNULLに設定します。

「OCIAnyDataSetBeginCreate()」

指定の継続時間に対してOCIAnyDataSetを割り当て、型情報を使用して初期化します。

「OCIAnyDataSetDestroy()」

OCIAnyDataSetを解放します。

「OCIAnyDataSetEndCreate()」

OCIAnyDataSet作成の終わりをマークします。

「OCIAnyDataSetGetCount()」

OCIAnyDataSetのインスタンス数を取得します。

「OCIAnyDataSetGetInstance()」

現行の位置にあるインスタンスに対応するOCIAnyDataを戻し、現行の位置を更新します。

「OCIAnyDataSetGetType()」

OCIAnyDataSetに対応する型を取得します。

OCIAnyDataSetAddInstance()

用途

新規のスケルトン・インスタンスをOCIAnyDataSetに追加し、そのインスタンスのすべての属性をNULLに設定します。

構文

sword OCIAnyDataSetAddInstance ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyDataSet  *data_set,
OCIAnyData     **data );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

data_set (IN/OUT)

新規インスタンスを追加するOCIAnyDataSetです。

data (IN/OUT)

新規に追加するインスタンスに対応するOCIAnyDataです。(*data)がNULLの場合、新規のOCIAnyDataはOCIAnyDataSetと同じ継続時間の間割り当てられます。(*data)がNULL以外の場合は再使用されます。このOCIAnyDataは、後でOCIAnyDataConvert()コールを使用して構成したり、OCIAnyDataAttrSet()コールまたはOCIAnyDataCollAddElem()コールを使用してピース単位で構成することができます。

コメント

このコールは、このスケルトン・インスタンスをOCIAnyDataパラメータを介して戻します。このインスタンスは、後でOCIAnyData APIを呼び出して構成できます。

注意:
古い値は破棄されません。一連のコールを開始する前に、(*data)が指し示す古い値を破棄し、(*data)をNULLポインタに設定する必要があります。戻されたOCIAnyDataでは、(OCIType情報またはデータ部分の)ディープ・コピーは行われません。このOCIAnyDataは、OCIAnyDataSetの割当て時間を超えて使用することはできません(OCIAnyDataSetへの参照と同様です)。戻されたOCIAnyDataをこの関数に対する後続のコールで再使用すると、新規のデータ・インスタンスをOCIAnyDataSetに後で追加できます。

OCIAnyDataSetBeginCreate()

用途

指定の継続時間に対してOCIAnyDataSetを割り当て、型情報を使用して初期化します。OCIAnyDataSetは、指定の型のインスタンスを複数保持できます。

構文

sword OCIAnyDataSetBeginCreate ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCITypeCode    typecode,
const OCIType  *type,
OCIDuration    dur,
OCIAnyDataSet  **data_set );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

typecode (IN)

OCIAnyDataSetに対応する型コードです。

type (IN)

OCIAnyDataSetに対応する型です。型コードが組込みの型(OCI_TYPECODE_NUMBERなど)に対応している場合、このパラメータはNULLにできます。また、ユーザー定義型(OCI_TYPECODE_OBJECT、OCI_TYPECODE_REF、コレクション型など)の場合は、NULL以外になります。

dur (IN)

OCIAnyDataSetが割り当てられる継続時間です。次のいずれかです。

- 以前に作成されたユーザー期間。これは、OCIDurationBegin()を使用して作成できます。

- OCI_DURATION_SESSIONなどの事前定義の期間。

data_set (OUT)

初期化済のOCIAnyDataSetです。

コメント

パフォーマンス向上のために、OCIAnyDataSetは最終的に、渡されたOCITypeパラメータを指し示します。OCITypeの継続時間が延長されていることを確認する必要があります(OCITypeが一時パラメータの場合は割当て時間 >= OCIAnyDataの継続時間、OCITypeが永続パラメータの場合は割当てまたは確保継続時間 >= OCIAnyDataの継続時間)。

OCIAnyDataSetDestroy()

用途

OCIAnyDataSetを解放します。

構文

sword OCIAnyDataSetDestroy ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyDataSet  *data_set );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

data_set (IN/OUT)

解放されるOCIAnyDataSetです。

OCIAnyDataSetEndCreate()

用途

OCIAnyDataSet作成の終わりをマークします。この関数は、すべてのインスタンスを構成した後にコールしてください。

構文

sword OCIAnyDataSetEndCreate ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyDataSet  *data_set );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

data_set (IN/OUT)

初期化済のOCIAnyDataSetです。

OCIAnyDataSetGetCount()

用途

OCIAnyDataSetのインスタンス数を取得します。

構文

sword OCIAnyDataSetGetCount( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyDataSet  *data_set,
ub4            *count );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

data_set (IN/OUT)

正しい形式のOCIAnyDataSetです。

count (OUT)

OCIAnyDataSet内のインスタンス数です。

OCIAnyDataSetGetInstance()

用途

現行の位置にあるインスタンスに対応するOCIAnyDataを戻し、現行の位置を更新します。

構文

sword OCIAnyDataSetGetInstance ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyDataSet  *data_set,
OCIAnyData     **data );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

data_set (IN/OUT)

正しい形式のOCIAnyDataSetです。

data (IN/OUT)

インスタンスに対応するOCIAnyDataです。(*data)がNULLの場合、新規のOCIAnyDataはOCIAnyDataSetと同じ継続時間の間割り当てられます。(*data)がNULL以外の場合は再使用されます。

コメント

OCIAnyDataSet内のインスタンスには、順次アクセスのみ可能です。このコールは、現行の位置にあるインスタンスに対応するOCIAnyDataを戻し、現行の位置を更新します。後で、OCIAnyDataアクセス・ルーチンを使用して、インスタンスにアクセスできます。

OCIAnyDataSetGetType()

用途

OCIAnyDataSetに対応する型を取得します。

構文

sword OCIAnyDataSetGetType ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAnyDataSet  *data_set,
OCITypeCode    *tc,
OCIType        **type );

パラメータ

svchp (IN)

OCIサービス・コンテキストです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

data_set (IN)

初期化済のOCIAnyDataSetです。

tc (OUT)

OCIAnyDataSetの型に対応する型コードです。

type (OUT)

OCIAnyDataSetに対応する型です。OCIAnyDataが組込みの型に対応している場合は、NULLになります。

22 OCIグローバリゼーション・サポート関数

この章では、OCIグローバリゼーション・サポート関数について説明します。

この章は、次の項目で構成されています。

- OCIにおけるグローバリゼーション・サポートの概要

- OCIロケール関数

- OCIロケールマッピング関数

- OCI文字列操作関数

- OCI文字分類関数

- OCIキャラクタ・セット変換関数

- OCIメッセージ関数

OCIにおけるグローバリゼーション・サポートの概要

この章では、グローバリゼーション・サポート関数について詳細に説明します。

関連項目:
『Oracle Databaseグローバリゼーション・サポート・ガイド』

OCI関数の規則

各関数を記述する際に使用される規則は、「OCI関数の規則」を参照してください。関数ごとに次の情報が記載されている場合もあります。

戻り値

戻される値。標準の戻り値には、表22-1で説明するように、次の意味があります。

表22-1 関数戻り値

戻り値

意味

OCI_SUCCESS

操作は成功しました。

OCI_ERROR

操作は失敗しました。関数に渡されたエラー・ハンドルに対してOCIErrorGet()をコールすることで特定のエラーを取り出せます。

OCI_INVALID_HANDLE

関数に渡されたOCIハンドルが無効です。

関連項目:
リターン・コードおよびエラー処理の詳細は、「OCIでのエラー処理」を参照してください。

OCIロケール関数

表22-2は、この項で説明しているOCIロケール関数を示しています。

Oracleロケールは、言語、地域およびキャラクタ・セット定義で構成されます。ロケールは、曜日と月の名前、および日付、時刻、数値、通貨の書式などの表記規則を決定します。グローバライズされたアプリケーションは、ユーザーのロケール設定および文化的規則に従います。たとえば、ロケールをドイツに設定すると、月日の名前がドイツ語で表示されます。

表22-2 OCIロケール関数

関数

用途

「OCINlsCharSetIdToName()」

指定されたキャラクタ・セットIDからOracle Databaseキャラクタ・セット名を戻します。

「OCINlsCharSetNameToId()」

指定されたOracle Databaseキャラクタ・セット名のOracle Databaseキャラクタ・セットIDを戻します。

「OCINlsEnvironmentVariableGet()」

NLS_LANGからキャラクタ・セットIDを、またはNLS_NCHARから各国語キャラクタ・セットIDを戻します。

「OCINlsGetInfo()」

OCI環境またはユーザー・セッション・ハンドルから、宛先バッファによってポイントされた配列に、指定サイズ内でロケール情報をコピーします。

「OCINlsNumericInfoGet()」

OCI環境ハンドルまたはユーザー・セッション・ハンドルから出力数値変数に、数値言語情報をコピーします。

OCINlsCharSetIdToName()

用途

指定されたキャラクタ・セットIDからOracle Databaseキャラクタ・セット名を戻します。

構文

sword OCINlsCharSetIdToName ( void      *hndl,
OraText   *buf,
size_t    buflen
ub2       id );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。ハンドルが無効の場合、関数はOCI_INVALID_HANDLEを戻します。

buf (OUT)

宛先バッファを指します。関数がOCI_SUCCESSを戻す場合、パラメータにはキャラクタ・セット名にNULLで終了する文字列が含まれています。

buflen (IN)

宛先バッファのサイズです。Oracle Databaseキャラクタ・セット名の格納を保証するには、OCI_NLS_MAXBUFSZのサイズをお薦めします。宛先バッファのサイズがキャラクタ・セット名の長さより小さい場合、関数はOCI_ERRORを戻します。

id (IN)

Oracle Databaseキャラクタ・セットID。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCINlsCharSetNameToId()

用途

指定されたOracle Databaseキャラクタ・セット名のOracle Databaseキャラクタ・セットIDを戻します。

構文

ub2 OCINlsCharSetNameToId ( void            *hndl,
const OraText   *name );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。ハンドルが無効の場合、0 (ゼロ)が戻されます。

name (IN)

NULLで終了するOracle Databaseキャラクタ・セット名へのポインタ。キャラクタ・セット名が無効の場合、0 (ゼロ)が戻されます。

戻り値

指定されたキャラクタ・セット名およびOCIハンドルが有効の場合、キャラクタ・セットID。それ以外の場合は、0が戻されます。

OCINlsEnvironmentVariableGet()

用途

NLS_LANGからキャラクタ・セットIDを、またはNLS_NCHARから各国語キャラクタ・セットIDを戻します。

構文

sword OCINlsEnvironmentVariableGet ( void       *val,
size_t     size,
ub2        item,
ub2        charset,
size_t     *rsize );

パラメータ

val (IN/OUT)

NLS_LANGキャラクタ・セットIDやNLS_NCHARキャラクタ・セットIDなどのグローバリゼーション・サポート環境変数の値を戻します。

size (IN)

指定した出力値のサイズを指定します。文字列データのみに適用できます。情報の各ピースの最大長は、OCI_NLS_MAXBUFSZバイトです。数値データの場合、この引数は無視されます。

item (IN)

グローバリゼーション・サポート環境変数から取得する値を指定します。次のいずれかの値です。

- OCI_NLS_CHARSET_ID: ub2データ型のNLS_LANGキャラクタ・セットID。

- OCI_NLS_NCHARSET_ID: ub2データ型のNLS_NCHARキャラクタ・セットID。

charset (IN)

取得する文字列データのキャラクタ・セットIDを指定します。0 (ゼロ)の場合は、NLS_LANG値が使用されます。OCI_UTF16IDはこの引数に対する有効な値です。数値データの場合、この引数は無視されます。

rsize (OUT)

バイトで示した戻り値の長さです。

コメント

NLS_NCHARが設定されていない場合、各国語キャラクタ・セットIDは、グローバリゼーション・サポート規則に従ってキャラクタ・セットIDと同じになります。NLS_LANGが設定されていない場合は、デフォルトのキャラクタ・セットIDが戻されます。

この関数の今後の機能拡張(他の値を環境変数から取得する)を考慮に入れ、出力valのデータ型は、voidへのポインタになっています。文字列データはNULLで終了しません。

この関数は環境ハンドルを受け入れないため、戻されるキャラクタ・セットIDおよび各国語キャラクタ・セットは、OCI環境ハンドルに保存されている値ではなく、NLS_LANGおよびNLS_NCHARで指定した値です。OCI環境ハンドルで使用されているキャラクタ・セットを取得するには、OCI_ATTR_ENV_CHARSETおよびOCI_ATTR_ENV_NCHARSETのそれぞれに対してOCIAttrGet()をコールします。

戻り値

OCI_SUCCESSまたはOCI_ERROR。

関連関数

OCIEnvNlsCreate()

OCINlsGetInfo()

用途

OCI環境またはユーザー・セッション・ハンドルから、宛先バッファによってポイントされた配列に、指定サイズ内でロケール情報を取得します。

構文

sword OCINlsGetInfo ( void        *hndl,
OCIError    *errhp,
OraText     *buf,
size_t      buflen,
ub2         item );

パラメータ

hndl (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errhpに記録され、NULLポインタが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

buf (OUT)

宛先バッファへのポインタです。戻される文字列はNULL文字で終了します。

buflen (IN)

宛先バッファのサイズです。情報の各ピースの最大長は、OCI_NLS_MAXBUFSZバイトです。

OCI_NLS_MAXBUFSIZE: OCINlsGetInfo()をコールする際、戻された情報を格納するためにバッファを割り当てる必要があります。バッファ・サイズは、問合せ対象の項目、および情報格納時に使用するエンコーディングによって異なります。開発者は、JA16SJISエンコーディングを使用して日本語でJanuaryを格納するために必要なバイト数を知っている必要はありません。OCINlsGetInfo()によって戻される最大の項目をバッファが格納できるだけの大きさがあることが、OCI_NLS_MAXBUFSZ属性によって保証されます。

item (IN)

OCI環境ハンドル内のどの項目を戻すかを指定します。これは次の値のいずれかです。

OCI_NLS_DAYNAME1: 月曜日のネイティブの名前
OCI_NLS_DAYNAME2: 火曜日のネイティブの名前
OCI_NLS_DAYNAME3: 水曜日のネイティブの名前
OCI_NLS_DAYNAME4: 木曜日のネイティブの名前
OCI_NLS_DAYNAME5: 金曜日のネイティブの名前
OCI_NLS_DAYNAME6: 土曜日のネイティブの名前
OCI_NLS_DAYNAME7: 日曜日のネイティブの名前
OCI_NLS_ABDAYNAME1: 月曜日のネイティブの略称
OCI_NLS_ABDAYNAME2: 火曜日のネイティブの略称
OCI_NLS_ABDAYNAME3: 水曜日のネイティブの略称
OCI_NLS_ABDAYNAME4: 木曜日のネイティブの略称
OCI_NLS_ABDAYNAME5: 金曜日のネイティブの略称
OCI_NLS_ABDAYNAME6: 土曜日のネイティブの略称
OCI_NLS_ABDAYNAME7: 日曜日のネイティブの略称
OCI_NLS_MONTHNAME1: 1月のネイティブの名前
OCI_NLS_MONTHNAME2: 2月のネイティブの名前
OCI_NLS_MONTHNAME3: 3月のネイティブの名前
OCI_NLS_MONTHNAME4: 4月のネイティブの名前
OCI_NLS_MONTHNAME5: 5月のネイティブの名前
OCI_NLS_MONTHNAME6: 6月のネイティブの名前
OCI_NLS_MONTHNAME7: 7月のネイティブの名前
OCI_NLS_MONTHNAME8: 8月のネイティブの名前
OCI_NLS_MONTHNAME9: 9月のネイティブの名前
OCI_NLS_MONTHNAME10: 10月のネイティブの名前
OCI_NLS_MONTHNAME11: 11月のネイティブの名前
OCI_NLS_MONTHNAME12: 12月のネイティブの名前
OCI_NLS_ABMONTHNAME1: 1月のネイティブの略称
OCI_NLS_ABMONTHNAME2: 2月のネイティブの略称
OCI_NLS_ABMONTHNAME3: 3月のネイティブの略称
OCI_NLS_ABMONTHNAME4: 4月のネイティブの略称
OCI_NLS_ABMONTHNAME5: 5月のネイティブの略称
OCI_NLS_ABMONTHNAME6: 6月のネイティブの略称
OCI_NLS_ABMONTHNAME7: 7月のネイティブの略称
OCI_NLS_ABMONTHNAME8: 8月のネイティブの略称
OCI_NLS_ABMONTHNAME9: 9月のネイティブの略称
OCI_NLS_ABMONTHNAME10: 10月のネイティブの略称
OCI_NLS_ABMONTHNAME11: 11月のネイティブの略称
OCI_NLS_ABMONTHNAME12: 12月のネイティブの略称
OCI_NLS_YES: 肯定的な応答のネイティブの文字列
OCI_NLS_NO: ネイティブの否定的な応答
OCI_NLS_AM: AMに相当するネイティブの文字列
OCI_NLS_PM: PMに相当するネイティブの文字列
OCI_NLS_AD: ADに相当するネイティブの文字列
OCI_NLS_BC: BCに相当するネイティブの文字列
OCI_NLS_DECIMAL: 小数点文字
OCI_NLS_GROUP: グループ・セパレータ
OCI_NLS_DEBIT: ネイティブの借方記号
OCI_NLS_CREDIT: ネイティブの貸方記号
OCI_NLS_DATEFORMAT: Oracle Databaseの日付書式
OCI_NLS_INT_CURRENCY: 国際通貨記号
OCI_NLS_DUAL_CURRENCY: 二重通貨記号
OCI_NLS_LOC_CURRENCY: 各国通貨記号
OCI_NLS_LANGUAGE: 言語名
OCI_NLS_ABLANGUAGE: 言語名の略称
OCI_NLS_TERRITORY: 地域名
OCI_NLS_CHARACTER_SET: キャラクタ・セット名
OCI_NLS_LINGUISTIC_NAME: 言語ソート名
OCI_NLS_CALENDAR: カレンダ名
OCI_NLS_WRITING_DIR: 言語の書込み方向
OCI_NLS_ABTERRITORY: 地域の略称
OCI_NLS_DDATEFORMAT: Oracle Databaseのデフォルト日付書式
OCI_NLS_DTIMEFORMAT: Oracle Databaseのデフォルト時刻書式
OCI_NLS_SFDATEFORMAT: ローカルの日付書式
OCI_NLS_SFTIMEFORMAT: ローカルの時刻書式
OCI_NLS_NUMGROUPING: 数値のグループ・フィールド
OCI_NLS_LISTSEP: リスト・セパレータ
OCI_NLS_MONDECIMAL: 通貨の小数点文字
OCI_NLS_MONGROUP: 通貨のグループ・セパレータ
OCI_NLS_MONGROUPING: 通貨のグループ・フィールド
OCI_NLS_INT_CURRENCYSEP: 国際通貨セパレータ

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCINlsNumericInfoGet()

用途

OCI環境ハンドルまたはユーザー・セッション・ハンドルから数値言語情報を取得し、出力数値変数に格納します。

構文

sword OCINlsNumericInfoGet ( void        *hndl,
OCIError    *errhp,
sb4         *val,
ub2         item );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。ハンドルが無効の場合、OCI_INVALID_HANDLEが戻されます。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errhpに記録され、NULLポインタが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

val (OUT)

出力数値変数へのポインタです。関数がOCI_SUCCESSを戻す場合、パラメータには要求されたグローバリゼーション・サポート数値情報が含まれています。

item (IN)

OCI環境ハンドルから取得する項目を指定します。次のいずれかの値です。

- OCI_NLS_CHARSET_MAXBYTESZ: OCI環境ハンドルまたはセッション・ハンドルのキャラクタ・セットの最大文字バイト・サイズ。

- OCI_NLS_CHARSET_FIXEDWIDTH: 固定幅キャラクタ・セットの場合は文字バイト・サイズ。可変幅キャラクタ・セットの場合は0。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIロケールマッピング関数

表22-3 は、この項で説明しているOCIロケールマッピング関数を示しています。

OCIロケールマッピング関数は、キャラクタ・セット名、言語名および地域名に対して、Oracle Database、Internet Assigned Numbers Authority (IANA)および国際標準化機構(ISO)の名前との間で、名前マッピングを実行します。

表22-3 OCIロケールマッピング関数

関数

用途

「OCINlsNameMap()」

Oracle Databaseキャラクタ・セット名、言語名および地域名をInternet Assigned Numbers Authority (IANA)および国際標準化機構(ISO)の名前との間でマップします。

OCINlsNameMap()

用途

Oracle Databaseキャラクタ・セット名、言語名および地域名をInternet Assigned Numbers Authority (IANA)および国際標準化機構(ISO)の名前との間でマップします。

構文

sword OCINlsNameMap ( void             *hndl,
OraText          *buf,
size_t           buflen,
const OraText    *srcbuf,
uword            flag );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。ハンドルが無効の場合、関数はOCI_INVALID_HANDLEを戻します。

buf (OUT)

宛先バッファを指します。関数がOCI_SUCCESSを戻す場合、パラメータには要求された名前にNULLで終了する文字列が含まれています。

buflen (IN)

宛先バッファのサイズです。グローバリゼーション・サポート名の格納を保証するには、OCI_NLS_MAXBUFSZのサイズをお薦めします。宛先バッファのサイズが名前の長さより小さい場合、関数はOCI_ERRORを戻します。

srcbuf (IN)

NULLで終了するグローバリゼーション・サポート名へのポインタ。無効な名前の場合、OCI_ERRORが戻されます。

flag (IN)

名前マッピングの方向を指定します。次のいずれかの値です。

OCI_NLS_CS_IANA_TO_ORA: キャラクタ・セット名をIANAからOracle Databaseにマップします。
OCI_NLS_CS_ORA_TO_IANA: キャラクタ・セット名をOracle DatabaseからIANAにマップします。
OCI_NLS_LANG_ISO_TO_ORA: 言語名をISOからOracle Databaseにマップします。
OCI_NLS_LANG_ORA_TO_ISO: 言語名をOracle DatabaseからISOにマップします。
OCI_NLS_LOCALE_A2_ISO_TO_ORA: ロケール名をA2 ISOからOracle Databaseにマップします。
OCI_NLS_LOCALE_ORA_TO_A2_ISO: ロケール名をOracle DatabaseからA2 ISOにマップします。
OCI_NLS_TERR_ISO_TO_ORA: 地域名をISOからOracle Databaseにマップします。
OCI_NLS_TERR_ORA_TO_ISO: 地域名をOracle DatabaseからISOにマップします。
OCI_NLS_TERR_ISO3_TO_ORA: 地域名を3文字のISO略称からOracle Databaseにマップします。
OCI_NLS_TERR_ORA_TO_ISO3: 地域名をOracle Databaseから3文字のISO略称にマップします。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCI文字列操作関数

文字列の操作用に、2種類のデータ構造がサポートされています。

- マルチバイト文字列

- ワイドキャラクタ文字列

マルチバイト文字列は、システム固有のOracleキャラクタ・セットでエンコードされています。マルチバイト文字列で動作する関数は、バイト単位で計算された文字列の長さを使用して、文字列全体を1つの単位として使用します。ワイドキャラクタ(wchar)文字列関数を使用すると、より柔軟に文字列を操作できます。文字に基づいた操作および文字列に基づいた操作をサポートし、長さは文字列の長さを文字で計算した数値です。

ワイドキャラクタ・データ型はOracle固有のもので、ANSI/ISO C標準で定義されているwchar_tデータ型と混同しないでください。Oracleのワイドキャラクタ・データ型はすべてのオペレーティング・システムで常に4バイトですが、wchar_tのサイズは実装およびオペレーティング・システムによって異なります。Oracleワイドキャラクタ・データ型は、マルチバイト文字を正規化するため、統一された固定幅になり、処理が簡単になります。これにより、Oracleのワイドキャラクタ・セットとシステム固有のキャラクタ・セット間でのラウンドトリップ変換の際、データが失われません。

文字列操作は、次のカテゴリに分類できます。

- マルチバイト・キャラクタとワイド・キャラクタ間の文字列変換

- 文字の分類

- 大/小文字の変換

- 表示長の計算

- 比較、連結、検索などの一般的な文字列操作

表22-4は、この項で説明しているOCI文字列操作関数のサマリーを示しています。

表22-4 OCI文字列操作関数

関数

用途

「OCIMultiByteInSizeToWideChar()」

マルチバイト文字列の一部をワイドキャラクタ文字列に変換します。

「OCIMultiByteStrCaseConversion()」

マルチバイト文字列を指定された大/小文字に変換し、結果を宛先配列にコピーします。

「OCIMultiByteStrcat()」

マルチバイト文字列を宛先文字列に追加します。

「OCIMultiByteStrcmp()」

2つのマルチバイト文字列を、バイナリ、言語または大/小文字を区別しない比較メソッドを使用して比較します。

「OCIMultiByteStrcpy()」

マルチバイト文字列を宛先配列にコピーします。これは、コピーされたバイト数を戻します。

「OCIMultiByteStrlen()」

マルチバイト文字列のバイト数を戻します。

「OCIMultiByteStrncat()」

マルチバイト文字列を宛先文字列にnバイト以内で追加します。

「OCIMultiByteStrncmp()」

2つのマルチバイト文字列を、バイナリ、言語または大/小文字を区別しない比較メソッドを使用して比較します。各文字列は指定された長さの範囲内です。

「OCIMultiByteStrncpy()」

指定されたバイト数のマルチバイト文字列を宛先配列にコピーします。

「OCIMultiByteStrnDisplayLength()」

マルチバイト文字列が占める表示位置のバイト数を、nバイト以内で戻します。

「OCIMultiByteToWideChar()」

NULLで終了するマルチバイト文字列をワイドキャラクタ形式に変換します。

「OCIWideCharInSizeToMultiByte()」

ワイドキャラクタ文字列の一部をマルチバイト文字列に変換します。

「OCIWideCharMultiByteLength()」

マルチバイト・エンコーディングの際、ワイドキャラクタで必要なバイト数を判断します。

「OCIWideCharStrCaseConversion()」

ワイドキャラクタ文字列を指定された大/小文字に変換し、結果を宛先配列にコピーします。

「OCIWideCharStrcat()」

ワイドキャラクタ文字列を宛先文字列に追加します。

「OCIWideCharStrchr()」

文字列内にある最初のワイド・キャラクタを検索します。検索が正常終了すると、ワイド・キャラクタへのポインタを戻します。

「OCIWideCharStrcmp()」

2つのワイドキャラクタ文字列を、バイナリ、言語または大/小文字を区別しない比較メソッドを使用して比較します。

「OCIWideCharStrcpy()」

ワイドキャラクタ文字列を宛先配列にコピーします。次に、コピーされた文字数を戻します。

「OCIWideCharStrlen()」

ワイドキャラクタ文字列の文字数を戻します。

「OCIWideCharStrncat()」

ワイドキャラクタ文字列を宛先文字列にn文字以内で追加します。

「OCIWideCharStrncmp()」

2つのワイドキャラクタ文字列を、バイナリ、言語または大/小文字を区別しないメソッドを使用して比較します。各文字列は指定された長さです。

「OCIWideCharStrncpy()」

ワイドキャラクタ文字列を宛先配列にn文字以内でコピーします。

「OCIWideCharStrrchr()」

ワイドキャラクタ文字列内にある最後の文字を検索します。

「OCIWideCharToLower()」

指定されたワイド・キャラクタを対応する小文字に変換します。

「OCIWideCharToMultiByte()」

NULLで終了するワイドキャラクタ文字列をマルチバイト文字列に変換します。

「OCIWideCharToUpper()」

指定されたワイド・キャラクタを対応する大文字に変換します。

OCIMultiByteInSizeToWideChar()

用途

マルチバイト文字列の一部をワイドキャラクタ文字列に変換します。

構文

sword OCIMultiByteInSizeToWideChar ( void          *hndl,
OCIWchar      *dst,
size_t        dstsz,
const OraText *src,
size_t        srcsz,
size_t        *rsize );

パラメータ

hndl (IN/OUT)

文字列のキャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

dst (OUT)

宛先バッファへのwcharのポインタです。dstszが0 (ゼロ)の場合、NULLポインタを使用できます。

dstsz (IN)

文字数単位で示した宛先バッファ・サイズです。0 (ゼロ)の場合、変換に必要な文字数が戻されます。

src (IN)

変換対象のソース文字列です。

srcsz (IN)

バイトで示したソース文字列の長さです。

rsize (OUT)

宛先バッファに書き込まれる文字数です。または、dstszが0 (ゼロ)の場合、変換された文字列の文字数です。NULLポインタの場合、何も戻されません。

コメント

このルーチンは、マルチバイト文字列の一部をワイドキャラクタ文字列に変換します。出力バッファ・サイズの制限か入力バッファ・サイズの制限に達するまで、またはソース文字列でNULL終端文字が出現するまで、何文字でも文字をすべて変換します。出力バッファは、領域に余裕がある場合、NULLで終了します。dstszが0(ゼロ)の場合、NULL終端文字を含まない、変換文字列に必要な文字数のみ戻されます。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

関連関数

OCIMultiByteToWideChar()

OCIMultiByteStrCaseConversion()

用途

srcstrが指し示すマルチバイト文字列を大文字または小文字(フラグによって指定)に変換し、その結果を、dststrが指し示す配列にコピーします。

構文

size_t OCIMultiByteStrCaseConversion ( void           *hndl,
OraText        *dststr,
const OraText  *srcstr,
ub4            flag );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

dststr (OUT)

宛先配列へのポインタです。結果の文字列は、NULLで終了します。

srcstr (IN)

ソース文字列へのポインタです。

flag (IN)

大文字または小文字のいずれに変換するかを指定します。

- OCI_NLS_UPPERCASE: 大文字に変換します。

- OCI_NLS_LOWERCASE: 小文字に変換します。

このフラグをOCI_NLS_LINGUISTICとともに使用すると、ロケールの言語設定を大/小文字の変換に使用するよう指定できます。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない結果文字列のバイト数。

OCIMultiByteStrcat()

用途

srcstrが指し示すマルチバイト文字列のコピーを、dststrが指し示す文字列の最後に追加します。

構文

size_t OCIMultiByteStrcat ( void            *hndl,
OraText         *dststr,
const OraText   *srcstr );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

dststr (IN/OUT)

追加先のマルチバイト文字列へのポインタです。出力バッファは、NULLで終了します。

srcstr (IN)

追加するソース文字列へのポインタです。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない結果文字列のバイト数。

関連関数

OCIMultiByteStrncat()

OCIMultiByteStrcmp()

用途

2つのマルチバイト文字列を、バイナリ、言語または大/小文字を区別しない比較メソッドを使用して比較します。

構文

int OCIMultiByteStrcmp ( void            *hndl,
const OraText   *str1,
const OraText   *str2,
int             flag );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

str1 (IN)

NULLで終了する文字列へのポインタです。

str2 (IN)

NULLで終了する文字列へのポインタです。

flag (IN)

比較メソッドを決定するために使用されます。次のいずれかの値です。

- OCI_NLS_BINARY: バイナリ比較。これがデフォルト値です。

- OCI_NLS_LINGUISTIC: ロケールで指定された言語比較。

このフラグをOCI_NLS_CASE_INSENSITIVEとともに使用することにより、大/小文字を区別しない比較を実行できます。たとえば、大/小文字を区別せずに文字列の言語を比較するには、OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVEを使用します。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

関数の戻り値は次のとおりです。

- 0 (str1 = str2の場合)

- 正(str1 > str2の場合)

- 負(str1 < str2の場合)

関連関数

OCIMultiByteStrncmp()

OCIMultiByteStrcpy()

用途

srcstrが指し示すマルチバイト文字列を、dststrが指し示す配列にコピーします。

構文

size_t OCIMultiByteStrcpy ( void            *hndl,
OraText         *dststr,
const OraText   *srcstr );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

dststr (OUT)

宛先バッファへのポインタです。出力バッファは、NULLで終了します。

srcstr (IN)

ソース・マルチバイト文字列へのポインタです。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない、コピーされるバイト数。

関連関数

OCIMultiByteStrncpy()

OCIMultiByteStrlen()

用途

strが指し示すマルチバイト文字列のバイト数(NULL終端文字を含まない)を戻します。

構文

size_t OCIMultiByteStrlen ( void           *hndl,
const OraText  *str );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

str (IN)

ソース・マルチバイト文字列へのポインタです。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まないバイト数。

関連関数

OCIWideCharStrlen()

OCIMultiByteStrncat()

用途

指定されたバイト数をマルチバイト文字列から宛先文字列に追加します。

構文

size_t OCIMultiByteStrncat ( void            *hndl,
OraText         *dststr,
const OraText   *srcstr,
size_t          n );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

dststr (IN/OUT)

追加先のマルチバイト文字列へのポインタです。

srcstr (IN)

追加するソース・マルチバイト文字列へのポインタです。

n (IN)

追加するsrcstrのバイト数です。

コメント

この関数は、OCIMultiByteStrcat()と類似しています。srcstrから最大nバイトがdststrに追加されます。srcstrのNULL終端文字によって追加が終了され、nバイト以内で関数は可能な数の文字を追加します。dststrパラメータはNULLで終了します。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない結果文字列のバイト数。

関連関数

OCIMultiByteStrcat()

OCIMultiByteStrncmp()

用途

2つのマルチバイト文字列を、バイナリ、言語または大/小文字を区別しない比較メソッドを使用して比較します。各文字列の長さは指定されています。

構文

int OCIMultiByteStrncmp ( void           *hndl,
const OraText  *str1,
size_t         len1,
OraText        *str2,
size_t         len2,
int            flag );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

str1 (IN)

最初の文字列へのポインタです。

len1 (IN)

比較する最初の文字列の長さです。

str2 (IN)

2番目の文字列へのポインタです。

len2 (IN)

比較する2番目の文字列の長さです。

flag (IN)

比較メソッドを決定するために使用されます。次のいずれかの値です。

- OCI_NLS_BINARY: バイナリ比較。これがデフォルト値です。

- OCI_NLS_LINGUISTIC: ロケールで指定された言語比較。

このフラグをOCI_NLS_CASE_INSENSITIVEとともに使用することにより、大/小文字を区別しない比較を実行できます。たとえば、大/小文字を区別せずに文字列の言語を比較するには、OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVEを使用します。

コメント

この関数はOCIMultiByteStrcmp()と類似していますが、最大str1からlen1バイト、str2からlen2バイトが比較される点が異なります。比較では、NULL終端文字が使用されます。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

関数の戻り値は次のとおりです。

- 0 (str1 = str2の場合)

- 正(str1 > str2の場合)

- 負(str1 < str2の場合)

関連関数

OCIMultiByteStrcpy()、OCIMultiByteStrncpy()

OCIMultiByteStrncpy()

用途

マルチバイト文字列を配列にコピーします。

構文

size_t OCIMultiByteStrncpy ( void            *hndl,
OraText         *dststr,
const OraText   *srcstr,
size_t           n );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

dststr (IN)

ソース・マルチバイト文字列へのポインタです。

srcstr (OUT)

宛先バッファへのポインタです。

n (IN)

コピーするsrcstrのバイト数です。

コメント

この関数は、OCIMultiByteStrcpy()と類似しています。ただし、srcstrが指し示す配列からdststrが指し示す配列にコピーされるのは、最大nバイトです。srcstrのNULL終端文字によってコピーが終了され、nバイト以内で関数は可能な数の文字をコピーします。結果の文字列は、NULLで終了します。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない結果文字列のバイト数。

関連関数

OCIMultiByteStrcpy()

OCIMultiByteStrnDisplayLength()

用途

マルチバイト文字列が占める表示位置のバイト数を、nバイト以内で戻します。

構文

size_t OCIMultiByteStrnDisplayLength ( void            *hndl,
const OraText   *str1,
size_t          n );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

str1 (IN)

マルチバイト文字列へのポインタです。

n (IN)

検査するバイト数です。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

表示位置の数です。

OCIMultiByteToWideChar()

用途

NULLで終了する文字列全体をワイドキャラクタ文字列に変換します。

構文

sword OCIMultiByteToWideChar ( void            *hndl,
OCIWchar        *dst,
const OraText   *src,
size_t          *rsize );

パラメータ

hndl (IN/OUT)

文字列のキャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

dst (OUT)

wcharの宛先バッファです。

src (IN)

変換対象のソース文字列です。

rsize (OUT)

NULL終端文字を含めた変換された文字数です。NULLポインタの場合、何も戻されません。

コメント

wchar出力バッファは、NULLで終了します。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

関連関数

OCIWideCharToMultiByte()

OCIWideCharInSizeToMultiByte()

用途

ワイドキャラクタ文字列の一部をマルチバイト形式に変換します。

構文

sword OCIWideCharInSizeToMultiByte ( void             *hndl,
OraText          *dst,
size_t           dstsz,
const OCIWchar   *src,
size_t           srcsz,
size_t           *rsize );

パラメータ

hndl (IN/OUT)

文字列のキャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

dst (OUT)

マルチバイトの宛先バッファです。dstszが0(ゼロ)の場合、NULLポインタを使用できます。

dstsz (IN)

バイト単位で示した宛先バッファ・サイズです。0 (ゼロ)の場合、変換文字列に必要なサイズがバイト単位で戻されます。

src (IN)

変換対象のソースwchar文字列です。

srcsz (IN)

文字で示したソース文字列の長さです。

rsize (OUT)

宛先バッファに書き込まれるバイト数です。または、dstszが0 (ゼロ)の場合、変換された文字列を格納するのに必要なバイト数です。NULLポインタの場合、何も戻されません。

コメント

ワイドキャラクタ文字列の一部をマルチバイト形式に変換します。出力バッファ・サイズか入力バッファ・サイズに達するまで、またはソース文字列でNULL終端文字が出現するまで、何文字でも文字をすべて変換します。出力バッファは、領域に余裕がある場合、NULLで終了します。dstszが0 (ゼロ)の場合、NULL終端文字を含まない、変換された文字列の格納に必要なサイズがバイト単位で戻されます。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIWideCharMultibyteLength()

用途

マルチバイト・エンコーディングの際、ワイドキャラクタで必要なバイト数を判断します。

構文

size_t OCIWideCharMultiByteLength ( void      *hndl,
OCIWchar  wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

wchar文字です。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

ワイドキャラクタに必要なバイト数です。

OCIWideCharStrCaseConversion()

用途

ワイドキャラクタ文字列を指定された大/小文字に変換し、結果を宛先配列にコピーします。

構文

size_t OCIWideCharStrCaseConversion ( void              *hndl,
OraText           *dststr,
const OraText     *srcstr,
ub4               flag );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

dststr (OUT)

宛先配列へのポインタです。結果の文字列は、NULLで終了します。

srcstr (IN)

ソース文字列へのポインタです。

flag (IN)

大文字または小文字のいずれに変換するかを指定します。

- OCI_NLS_UPPERCASE: 大文字に変換します。

- OCI_NLS_LOWERCASE: 小文字に変換します。

このフラグをOCI_NLS_LINGUISTICとともに使用すると、ロケールの言語設定を大/小文字の変換に使用するよう指定できます。

コメント

srcstrが指し示すワイドキャラクタ文字列を大文字または小文字(フラグによって指定)に変換し、その結果を、dststrが指し示す配列にコピーします。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない結果文字列のバイト数。

OCIWideCharStrcat()

用途

wsrcstrが指し示すワイドキャラクタ文字列を、wdststrが指し示すワイドキャラクタ文字列に追加します。

構文

size_t OCIWideCharStrcat ( void             *hndl,
OCIWchar         *wdststr,
const OCIWchar   *wsrcstr );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wdststr (IN/OUT)

宛先wchar文字列へのポインタです。出力バッファは、NULLで終了します。

wsrcstr (IN)

追加するソース・ワイドキャラクタ文字列へのポインタです。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない結果文字列の文字数。

関連関数

OCIWideCharStrncat()

OCIWideCharStrchr()

用途

ワイドキャラクタ文字列内にある最初の指定された文字を検索します。

構文

OCIWchar *OCIWideCharStrchr ( void             *hndl,
const OCIWchar   *wstr,
OCIWchar         wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wstr (IN)

検索するwchar文字列へのポインタです。

wc (IN)

検索対象のwcharです。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

成功した場合はwcharポインタ、そうでない場合はNULLポインタです。

関連関数

OCIWideCharStrrchr()

OCIWideCharStrcmp()

用途

2つのワイドキャラクタ文字列を、バイナリ(wcharエンコーディング値に基づく)、言語または大/小文字を区別しない比較メソッドを使用して比較します。

構文

int OCIWideCharStrcmp ( void             *hndl,
const OCIWchar   *wstr1,
const OCIWchar   *wstr2,
int              flag );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wstr1 (IN)

NULLで終了するwchar文字列へのポインタ。

wstr2 (IN)

NULLで終了するwchar文字列へのポインタ。

flag (IN)

比較メソッドを決定するために使用されます。次のいずれかの値です。

- OCI_NLS_BINARY: バイナリ比較。これがデフォルト値です。

- OCI_NLS_LINGUISTIC: ロケール定義で指定された言語比較。

このフラグをOCI_NLS_CASE_INSENSITIVEとともに使用することにより、大/小文字を区別しない比較を実行できます。たとえば、大/小文字を区別せずに文字列の言語を比較するには、OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVEを使用します。

OCIWideCharStrcmp()では、指定されたワイドキャラクタ引数の言語比較を実行するためにUNICODE_BINARYソート方法は使用できません。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

関数の戻り値は次のとおりです。

- 0 (wstr1 = wstr2の場合)

- 正(wstr1 > wstr2の場合)

- 負(wstr1 < wstr2の場合)

関連関数

OCIWideCharStrncmp()

OCIWideCharStrcpy()

用途

ワイドキャラクタ文字列を配列にコピーします。

構文

size_t OCIWideCharStrcpy ( void             *hndl,
OCIWchar         *wdststr,
const OCIWchar   *wsrcstr );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wdststr (OUT)

宛先wcharバッファへのポインタです。結果の文字列は、NULLで終了します。

wsrcstr (IN)

ソースwchar文字列へのポインタです。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない、コピーされる文字数。

関連関数

OCIWideCharStrncpy()

OCIWideCharStrlen()

用途

ワイドキャラクタ文字列の文字数を戻します。

構文

size_t OCIWideCharStrlen ( void             *hndl,
const OCIWchar   *wstr );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wstr (IN)

ソースwchar文字列へのポインタです。

コメント

wstrが指し示すwchar文字列の文字数(NULL終端文字を含まない)を戻します。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない文字数。

OCIWideCharStrncat()

用途

ワイドキャラクタ文字列を宛先にn文字以内で追加します。

構文

size_t OCIWideCharStrncat ( void             *hndl,
OCIWchar         *wdststr,
const OCIWchar   *wsrcstr,
size_t           n );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wdststr (IN/OUT)

宛先wchar文字列へのポインタです。

wsrcstr (IN)

ソースwchar文字列へのポインタです。

n (IN)

追加するwsrcstrの文字数です。

コメント

この関数は、OCIWideCharStrcat()と類似しています。wsrcstrから最大n文字がwdststrに追加されます。wsrcstrのNULL終端文字によって追加が終了されます。wdststrパラメータはNULLで終了します。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない結果文字列の文字数。

関連関数

OCIWideCharStrcat()

OCIWideCharStrncmp()

用途

2つのワイドキャラクタ文字列を、バイナリ、言語または大/小文字を区別するメソッドを使用して比較します。各文字列は長さが指定されています。

構文

int OCIWideCharStrncmp ( void                *hndl,
const OCIWchar      *wstr1,
size_t              len1,
const OCIWchar      *wstr2,
size_t              len2,
int                 flag );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wstr1 (IN)

最初のwchar文字列へのポインタです。

len1 (IN)

比較する最初の文字列の長さです。

wstr2 (IN)

2番目のwchar文字列へのポインタです。

len2 (IN)

比較する2番目の文字列の長さです。

flag (IN)

比較メソッドを決定するために使用されます。次のいずれかの値です。

- OCI_NLS_BINARY: バイナリ比較の場合。これがデフォルト値です。

- OCI_NLS_LINGUISTIC: ロケールで指定された言語比較の場合。

このフラグをOCI_NLS_CASE_INSENSITIVEとともに使用することにより、大/小文字を区別しない比較を実行できます。たとえば、大/小文字を区別せずに文字列の言語を比較するには、OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVEを使用します。

コメント

この関数は、OCIWideCharStrcmp()と類似しています。2つのワイドキャラクタ文字列を、バイナリ、言語または大/小文字を区別しない比較メソッドを使用して比較します。wstr1から最大len1バイト、wstr2から最大len2バイトが比較されます。比較では、NULL終端文字が使用されます。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

OCIWideCharStrncmp()では、指定されたワイドキャラクタ引数の言語比較を実行するためにUNICODE_BINARYソート方法は使用できません。

戻り値

関数の戻り値は次のとおりです。

- 0 (wstr1 = wstr2の場合)

- 正(wstr1 > wstr2の場合)

- 負(wstr1 < wstr2の場合)

関連関数

OCIWideCharStrcmp()

OCIWideCharStrncpy()

用途

ワイドキャラクタ文字列を宛先にn文字以内でコピーします。

構文

size_t OCIWideCharStrncpy ( void             *hndl,
OCIWchar         *wdststr,
const OCIWchar   *wsrcstr,
size_t           n );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wdststr (OUT)

宛先wcharバッファへのポインタです。

wsrcstr (IN)

ソースwchar文字列へのポインタです。

n (IN)

コピーするwsrcstrの文字数です。

コメント

この関数は、OCIWideCharStrcpy()と類似しています。ただし、wsrcstrが指し示す配列からwdststrが指し示す配列にコピーされるのは、最大n文字です。wdststr内のNULL終端文字に達するとコピーが停止され、生成される文字列の最後はNULLです。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

NULL終端文字を含まない、コピーされる文字数。

関連関数

OCIWideCharStrcpy()

OCIWideCharStrrchr()

用途

ワイドキャラクタ文字列内にある最後の文字を検索します。

構文

OCIWchar *OCIWideCharStrrchr ( void              *hndl,
const OCIWchar    *wstr,
OCIWchar          wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wstr (IN)

検索するwchar文字列へのポインタです。

wc (IN)

検索対象のwcharです。

コメント

wstrが指し示すwchar文字列内にある最後のwcを検索します。OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

成功した場合はwcharポインタ、そうでない場合はNULLポインタです。

関連関数

OCIWideCharStrchr()

OCIWideCharToLower()

用途

wcによって指定されたワイドキャラクタ文字列を、指定されたロケールの対応する小文字(存在する場合)に変換します。対応する小文字が存在しない場合、wcそのものが戻されます。

構文

OCIWchar OCIWideCharToLower ( void        *hndl,
OCIWchar    wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

小文字に変換するwcharです。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

wcharです。

関連関数

OCIWideCharToUpper()

OCIWideCharToMultiByte()

用途

NULLで終了するワイドキャラクタ文字列全体をマルチバイト文字列に変換します。

構文

sword OCIWideCharToMultiByte ( void             *hndl,
OraText          *dst,
const OCIWchar   *src,
size_t           *rsize );

パラメータ

hndl (IN/OUT)

文字列のキャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

dst (OUT)

マルチバイト文字列の宛先バッファです。出力バッファは、NULLで終了します。

src (IN)

変換対象のソースwchar文字列です。

rsize (OUT)

宛先バッファに書き込まれるバイト数です。NULLポインタの場合、何も戻されません。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

関連関数

OCIMultiByteToWideChar()

OCIWideCharToUpper()

用途

wcによって指定されたワイドキャラクタ文字列を、指定されたロケールの対応する大文字(存在する場合)に変換します。対応する大文字が存在しない場合、wcそのものが戻されます。

構文

OCIWchar OCIWideCharToUpper ( void      *hndl,
OCIWchar  wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

大文字に変換するwcharです。

コメント

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

wcharです。

関連関数

OCIWideCharToLower()

OCI文字分類関数

表22-5は、この項で説明しているOCI文字分類関数を示しています。

表22-5 OCI文字分類関数

関数

用途

「OCIWideCharIsAlnum()」

ワイド・キャラクタが文字か10進数値かをテストします。

「OCIWideCharIsAlpha()」

ワイド・キャラクタが文字かどうかをテストします。

「OCIWideCharIsCntrl()」

ワイド・キャラクタが制御文字かどうかをテストします。

「OCIWideCharIsDigit()」

ワイド・キャラクタが10進数値かどうかをテストします。

「OCIWideCharIsGraph()」

ワイド・キャラクタがグラフ文字かどうかをテストします。

「OCIWideCharIsLower()」

ワイド・キャラクタが小文字かどうかをテストします。

「OCIWideCharIsPrint()」

ワイド・キャラクタが印字可能文字かどうかをテストします。

「OCIWideCharIsPunct()」

ワイド・キャラクタが句読点文字かどうかをテストします。

「OCIWideCharIsSingleByte()」

マルチバイトへの変換時に、ワイド・キャラクタがシングルバイト文字かどうかをテストします。

「OCIWideCharIsSpace()」

ワイド・キャラクタがスペース文字かどうかをテストします。

「OCIWideCharIsUpper()」

ワイド・キャラクタが大文字かどうかをテストします。

「OCIWideCharIsXdigit()」

ワイド・キャラクタが16進数値かどうかをテストします。

OCIWideCharIsAlnum()

用途

ワイド・キャラクタが文字か10進数値かをテストします。

構文

boolean OCIWideCharIsAlnum ( void       *hndl,
OCIWchar   wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsAlpha()

用途

ワイド・キャラクタが文字かどうかをテストします。

構文

boolean OCIWideCharIsAlpha ( void      *hndl,
OCIWchar  wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsCntrl()

用途

ワイド・キャラクタが制御文字かどうかをテストします。

構文

boolean OCIWideCharIsCntrl ( void        *hndl,
OCIWchar    wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsDigit()

用途

ワイド・キャラクタが10進数値かどうかをテストします。

構文

boolean OCIWideCharIsDigit ( void       *hndl,
OCIWchar   wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsGraph()

用途

ワイド・キャラクタがグラフ文字かどうかをテストします。グラフ文字とは、表示される文字で、通常はアルファベット文字、小数点および句読点記号を含みます。

構文

boolean OCIWideCharIsGraph ( void      *hndl,
OCIWchar   wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsLower()

用途

ワイド・キャラクタが小文字かどうかをテストします。

構文

boolean OCIWideCharIsLower ( void       *hndl,
OCIWchar    wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsPrint()

用途

ワイド・キャラクタが印字可能文字かどうかをテストします。

構文

boolean OCIWideCharIsPrint ( void      *hndl,
OCIWchar  wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsPunct()

用途

ワイド・キャラクタが句読点文字かどうかをテストします。

構文

boolean OCIWideCharIsPunct ( void       *hndl,
OCIWchar   wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsSingleByte()

用途

マルチバイトへの変換時に、ワイド・キャラクタがシングルバイト文字かどうかをテストします。

構文

boolean OCIWideCharIsSingleByte ( void      *hndl,
OCIWchar  wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsSpace()

用途

ワイド・キャラクタがスペース文字かどうかをテストします。スペース文字は、表示テキストに空白のみを表示させます(たとえば、空白、タブ、改行、新規行、縦方向タブまたは改ページなど)。

構文

boolean OCIWideCharIsSpace ( void     *hndl,
OCIWchar wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsUpper()

用途

ワイド・キャラクタが大文字かどうかをテストします。

構文

boolean OCIWideCharIsUpper ( void      *hndl,
OCIWchar  wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIWideCharIsXdigit()

用途

ワイド・キャラクタが16進数値(0から9、AからF、aからf)かどうかをテストします。

構文

boolean OCIWideCharIsXdigit ( void      *hndl,
OCIWchar  wc );

パラメータ

hndl (IN/OUT)

キャラクタ・セットを判断するOCI環境ハンドルまたはユーザー・セッション・ハンドルです。

wc (IN)

テストするwcharです。

戻り値

TRUEまたはFALSEです。

OCIキャラクタ・セット変換関数

Oracle Databaseキャラクタ・セットとUnicode (16ビット、固定幅のUnicodeエンコーディング)間の変換がサポートされています。UnicodeからOracle Databaseキャラクタ・セットへの文字のマッピングが存在しない場合、置換文字が使用されます。したがって、変換して元のキャラクタ・セットに戻す場合、データが失われる可能性があります。

表22-6に、OCIキャラクタ・セット変換関数を示します。

表22-6 OCIキャラクタ・セット変換関数

関数

用途

「OCICharSetConversionIsReplacementUsed()」

最後に起動されたOCINlsCharSetConvert()またはOCICharSetToUnicode()で、変換不可の文字に対して置換文字が使用されたかどうかを示します。

「OCICharSetToUnicode()」

マルチバイト文字列をUnicodeに変換します。

「OCINlsCharSetConvert()」

文字列を別のキャラクタ・セットに変換します。

「OCIUnicodeToCharSet()」

Unicode文字列をマルチバイトに変換します。

OCICharSetConversionIsReplacementUsed()

用途

最後に起動されたOCICharSetToUnicode()またはOCINlsCharSetConvert()で、変換不可の文字に対して置換文字が使用されたかどうかを示します。

構文

boolean OCICharSetConversionIsReplacementUsed ( void *hndl );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

コメント

Oracle Databaseキャラクタ・セットとUnicode (16ビット、固定幅のUnicodeエンコーディング)間の変換がサポートされています。UnicodeからOracle Databaseキャラクタ・セットへの文字のマッピングが存在しない場合、置換文字が使用されます。したがって、元の文字へのラウンドトリップ変換を実行できない文字も存在します。一部の文字ではデータが失われます。

戻り値

OCINlsCharSetConvert()またはOCICharSetToUnicode()が最後に起動された際、置換文字が使用されていればTRUEが戻されます。それ以外の場合は、FALSEが戻されます。

OCICharSetToUnicode()

用途

srcが指し示すマルチバイト文字列をUnicodeに変換し、dstが指し示す配列に追加します。

構文

sword OCICharSetToUnicode ( void              *hndl,
ub2               *dst,
size_t            dstlen,
const OraText     *src,
size_t            srclen,
size_t            *rsize );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

dst (OUT)

宛先バッファへのポインタです。

dstlen (IN)

文字で示した宛先バッファのサイズです。

src (IN)

マルチバイト・ソース文字列へのポインタです。

srclen (IN)

バイトで示したソース文字列のサイズです。

rsize (OUT)

変換された文字数。NULLポインタの場合、何も戻されません。

コメント

ソースの制限または宛先の制限に達すると、変換は終了します。Unicode文字列に変換された文字数が戻されます。dstlenが0の場合、関数は文字列をスキャンし、文字数を数え、文字数をrsizeに戻しますが、文字列を変換しません。

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR

OCINlsCharSetConvert()

用途

srcが指し示すsrcidによって指定されたキャラクタ・セットの文字列を、dstidで指定されたキャラクタ・セットに変換し、dstが指し示す配列に追加します。ソースまたは宛先のデータ・サイズの制限に達すると、変換は終了します。宛先バッファに変換されたバイト数が戻されます。

構文

sword OCINlsCharSetConvert ( void          *hndl,
OCIError      *errhp,
ub2           dstid,
void          *dstp,
size_t        dstlen,
ub2           srcid,
const void    *srcp,
size_t        srclen,
size_t        *rsize );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errhpに記録され、NULLポインタが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

dstid (IN)

宛先バッファのキャラクタ・セットIDです。

dstp (OUT)

宛先バッファへのポインタです。

dstlen (IN)

バイトで示した宛先バッファの最大サイズです。

srcid (IN)

ソース・バッファのキャラクタ・セットIDです。

srcp (IN)

ソース・バッファへのポインタです。

srclen (IN)

バイトで示したソース・バッファの長さです。

rsize (OUT)

変換された文字数。ポインタがNULLの場合、何も戻されません。

コメント

ソースまたは宛先のキャラクタ・セットIDをOCI_UTF16IDで指定できますが、元のデータおよび変換されたデータの長さは文字数ではなく、バイト数で示されます。NULLデータが出現しても、変換は停止しません。キャラクタ・セット名からキャラクタ・セットIDを取得するには、OCINlsCharSetNameToId()を使用してください。宛先バッファ内の導出されたデータに置換文字が含まれているかどうかを調べるには、OCICharSetConversionIsReplacementUsed()を使用してください。バッファは、キャラクタ・セットに対して適切なバイト境界と位置が揃っている必要があります。たとえば、UTF-16の文字列を保持するには、ub2データ型が必要です。

戻り値

OCI_SUCCESSおよび変換されたバイト数、またはOCI_ERROR。

OCIUnicodeToCharSet()

用途

Unicode文字列をマルチバイト文字列に変換し、配列に追加します。

構文

sword OCIUnicodeToCharSet ( void        *hndl,
OraText     *dst,
size_t      dstlen,
const ub2   *src,
size_t      srclen,
size_t      *rsize );

パラメータ

hndl (IN/OUT)

OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

dst (OUT)

宛先バッファへのポインタです。

dstlen (IN)

バイトで示した宛先バッファの長さです。

src (IN)

Unicode文字列へのポインタです。

srclen (IN)

文字で示したソース文字列のサイズです。

rsize (OUT)

変換されたバイト数です。NULLポインタの場合、何も戻されません。

コメント

ソースの制限または宛先の制限に達すると、変換は終了します。マルチバイト文字列に変換されたバイト数が戻されます。dstlenが0 (ゼロ)の場合、変換を実行せずに、バイト数がrsizeに戻されます。

OCI環境ハンドルまたはユーザー・セッション・ハンドルで指定されたキャラクタ・セットにUnicode文字が変換できない場合、置換文字が使用されます。この場合、OCICharSetConversionIsReplacementUsed()がTRUEを戻します。

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIメッセージ関数

ユーザー・メッセージAPIは、カートリッジ開発者が、独自のメッセージおよびOracle Databaseメッセージを取得するための単純なインタフェースを提供します。

関連項目:
『Oracle Databaseデータ・カートリッジ開発者ガイド』

表22-7は、この項で説明しているOCIメッセージ関数を示しています。

表22-7 OCIメッセージ関数

関数

用途

「OCIMessageClose()」

メッセージ・ハンドルをクローズし、ハンドルに関連するすべてのメモリーを解放します。

「OCIMessageGet()」

メッセージを取り出します。バッファが0 (ゼロ)でない場合、この関数は、バッファにメッセージをコピーします。

「OCIMessageOpen()」

指定された言語でメッセージ・ハンドルをオープンします。

OCIMessageClose()

用途

メッセージ・ハンドルをクローズし、このハンドルに関連するすべてのメモリーを解放します。

構文

sword OCIMessageClose ( void      *hndl,
OCIError  *errhp,
OCIMsg    *msgh );

パラメータ

hndl (IN/OUT)

メッセージ言語のOCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errhpに記録され、NULLポインタが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

msgh (IN/OUT)

OCIMessageOpen()によってすでにオープンされているメッセージ・ハンドルへのポインタです。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

OCIMessageGet()

用途

指定されたメッセージ番号のメッセージを取り出します。

構文

OraText *OCIMessageGet ( OCIMsg      *msgh,
ub4         msgno,
OraText     *msgbuf,
size_t      buflen );

パラメータ

msgh (IN/OUT)

OCIMessageOpen()によってすでにオープンされているメッセージ・ハンドルへのポインタです。

msgno (IN)

メッセージ番号です。

msgbuf (OUT)

取り出したメッセージの宛先バッファへのポインタです。buflenが0 (ゼロ)の場合、NULLポインタを使用できます。

buflen (IN)

宛先バッファのサイズです。

コメント

buflenが0 (ゼロ)でない場合、この関数は、msgbufが指し示すバッファにメッセージをコピーします。buflenが0 (ゼロ)の場合、msghが指し示すメッセージ・ハンドル内のメッセージ・バッファにメッセージがコピーされます。

戻り値

NULLで終了するメッセージ文字列へのポインタが戻されます。翻訳されたメッセージが検出できない場合、同等の英語のメッセージが戻されます。同等の英語のメッセージが検出できない場合、NULLポインタが戻されます。

OCIMessageOpen()

用途

指定された言語でメッセージ処理機能をオープンします。

構文

sword OCIMessageOpen ( void             *hndl,
OCIError         *errhp,
OCIMsg           *msghp,
const OraText    *product,
const OraText    *facility,
OCIDuration      dur );

パラメータ

hndl (IN/OUT)

メッセージ言語のOCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

errhp (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errhpに記録され、NULLポインタが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

msghp (OUT)

戻りのためのメッセージ・ハンドルです。

product (IN)

製品名へのポインタです。製品名は、メッセージのディレクトリを検出するために使用されます。位置は、オペレーティング・システムによって異なります。たとえば、Solarisの場合、rdbms製品のメッセージ・ファイルのディレクトリは$ORACLE_HOME/rdbmsです。

facility (IN)

製品の機能名へのポインタです。メッセージ・ファイル名を構成するのに使用されます。メッセージ・ファイル名は、接頭辞としてfacility名が付く変換に従います。たとえば、英語のimg機能のメッセージ・ファイル名はimgus.msbです。ここで、usは英語の略語で、msbはメッセージ・バイナリ・ファイルの拡張子です。

dur (IN)

戻りメッセージ・ハンドルのメモリー割当ての継続期間です。次のいずれかの値です。

- OCI_DURATION_PROCESS

- OCI_DURATION_SESSION

- OCI_DURATION_STATEMENT

コメント

OCIMessageOpen()は、まず、hndlに対応するメッセージ・ファイルをオープンします。オープンに成功すると、そのファイルを使用してメッセージ・ハンドルを初期化します。言語に対応するメッセージ・ファイルが検出できない場合、代替として主要言語ファイルを検索します。たとえば、南米スペイン語のファイルが検出できない場合、スペイン語のファイルをオープンします。代替手段が失敗すると、言語がAMERICANであるデフォルトのメッセージ・ファイルを使用します。関数は、msghpパラメータにメッセージ・ハンドルへのポインタを戻します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

23 OCI XML DB関数

この章では、OCI XML DB関数について説明します。

この章は、次の項目で構成されています。

- OCIにおけるXML DBサポートの概要

- OCI XML DB関数

OCIにおけるXML DBサポートの概要

この章では、XML DB関数について詳細に説明します。

関連項目:
「OCIでのXMLのサポート」

OCI関数の規則

各関数を記述する際に使用される規則は、「OCI関数の規則」を参照してください。関数ごとに次の情報が記載されている場合もあります。

戻り値

指定がないかぎり、関数は表23-1で説明する値を戻します。

表23-1 関数戻り値

戻り値

意味

OCI_SUCCESS

操作は成功しました。

OCI_ERROR

操作は失敗しました。関数に渡されたエラー・ハンドルに対してOCIErrorGet()をコールすることで特定のエラーを取り出せます。

OCI_INVALID_HANDLE

関数に渡されたOCIハンドルが無効です。

関連項目:
リターン・コードおよびエラー処理の詳細は、「OCIでのエラー処理」を参照してください。

OCI XML DB関数

表23-2は、この章で説明しているOCI XML DB関数を示しています。

表23-2 OCI XML DB関数

関数

用途

「OCIBinXmlCreateReposCtxFromConn()」

メタデータ接続コンテキストを作成します。

「OCIBinXmlCreateReposCtxFromCPool()」

メタデータ接続コンテキストの接続プールを作成します。

「OCIBinXmlSetFormatPref()」

転送されるイメージがバイナリのXMLフォーマットであることを指定します。

「OCIBinXmlSetReposCtxForConn()」

データ接続をメタデータ接続に関連付けます。

「OCIXmlDbFreeXmlCtx()」

XMLコンテキストを解放します。

「OCIXmlDbInitXmlCtx()」

データベースからのXMLデータのXMLコンテキストを初期化します。

OCIBinXmlCreateReposCtxFromConn()

用途

指定のOCIEnv/OCISvcCtx専用OCI接続からメタデータ接続コンテキスト(OCIBinXmlReposCtx)を作成します。この接続はメタデータ専用であることに注意してください。

構文

sword OCIBinXmlCreateReposCtxFromConn (   OCIEnv             *env,
OCISvcCtx          *svcctx,
OCIError           *err,
OCIBinXmlReposCtx  **ctx);

パラメータ

env (IN)

環境ハンドルです。

svcctx (IN)

メタデータへのアクセスに使用する接続へのハンドルです。

err (IN)

エラー・ハンドルです。

ctx (OUT)

作成され戻されるメタデータ・コンテキストです。

戻り値

エラーの場合は-1、成功の場合は0 (ゼロ)が戻されます。errパラメータには、エラーの詳細情報が含まれます。

関連関数

OCIBinXmlCreateReposCtxFromCPool()

OCIBinXmlCreateReposCtxFromCPool()

用途

指定の接続プールからメタデータ接続コンテキスト(OCIBinXmlReposCtx)を作成します。トークン・リポジトリからの情報が必要になるたびに、接続プール内の接続が使用されます。

構文

sword OCIBinXmlCreateReposCtxFromCPool (   OCIEnv             *env,
OCICPool           *cpool,
OCIError           *err,
OCIBinXmlReposCtx  **ctx);

パラメータ

env (IN)

環境ハンドルです。

cpool (IN)

メタデータへのアクセスに使用する接続へのハンドルです。

err (IN)

エラー・ハンドルです。

ctx (OUT)

作成され戻されるメタデータ・コンテキストです。

戻り値

エラーの場合は-1、成功の場合は0 (ゼロ)が戻されます。errパラメータには、エラーの詳細情報が含まれます。

関連関数

OCIBinXmlCreateReposCtxFromConn()

OCIBinXmlSetFormatPref()

用途

XML文書についてクライアントとサーバーの間で転送されるイメージが、バイナリのXMLフォーマットであることを指定します。将来は、すべての通信にバイナリのXMLフォーマットが使用されます。このフォーマットを設定できるのは、バイナリXML対応アプリケーションのみです。

構文

sword OCIBinXmlSetFormatPref (   xmldomdoc   *doc,
ub4         formattype);

パラメータ

doc (IN)

プリファレンスの適用対象であるdomdocへのポインタです。

formattype (IN)

ピクルに使用するフォーマットのタイプです。現在、使用可能な値はOCIXML_FORMATTYPE_TEXTおよびOCIXML_FORMATTYPE_BINXMLのみです。

戻り値

エラーの場合は-1、成功の場合は0 (ゼロ)が戻されます。

関連関数

OCIBinXmlSetReposCtxForConn()

OCIBinXmlSetReposCtxForConn()

用途

データ接続をメタデータ接続に関連付けます。専用接続の場合、データ接続とメタデータ接続の環境ハンドルが同一である必要があることに注意してください。

構文

sword OCIBinXmlSetReposCtxForConn (   OCISvcCtx          *dataconn,
OCIBinXmlReposCtx  *reposctx);

パラメータ

dataconn (IN)

データ接続ハンドルです。

reposctx (IN)

メタデータ接続へのポインタです。

戻り値

エラーの場合は-1、成功の場合は0 (ゼロ)が戻されます。errパラメータには、エラーの詳細情報が含まれます。

関連関数

OCIBinXmlSetFormatPref()

OCIXmlDbFreeXmlCtx()

用途

OCIXmlDbInitXmlCtx()へのコールによる割当てを解放します。

構文

void OCIXmlDbFreeXmlCtx ( xmlct   *xctx );

パラメータ

xctx (IN)

終了するXMLコンテキストです。

コメント

関連項目:
使用例は、「OCI XML DB関数の使用」を参照してください。

戻り値

エラーの場合は-1、成功の場合は0 (ゼロ)が戻されます。

関連関数

OCIXmlDbInitXmlCtx()

OCIXmlDbInitXmlCtx()

用途

データベースからのXMLデータのXMLコンテキストを初期化します。

構文

xmlctx *OCIXmlDbInitXmlCtx (   OCIEnv                *envhp,
OCISvcCtx             *svchp,
OCIError              *errhp,
ocixmldbparam         *params,
ub4                   num_params );

パラメータ

envhp (IN)

OCI環境ハンドルです。

svchp (IN)

OCIサービス・ハンドルです。

errhp (IN)

OCIエラー・ハンドルです。

params (IN)

オプションで使用可能なこの配列の値は、OCIの継続時間(デフォルト値はOCI_DURATION_SESSION)または次のプロトタイプのユーザー登録コールバックであるエラー・ハンドラのいずれかに対するポインタです。

void (*err_handler) (sword errcode, (const OraText *) errmsg);

err_handlerの2つのパラメータは次のとおりです。

errcode (OUT)

数値のエラー値です。

errmsg (OUT)

エラー・メッセージ・テキストです。

num_params (IN)

paramsから読み取られるパラメータ数です。 num_paramsの値が配列paramsのサイズより大きい場合、予期しない結果が発生します。

コメント

関連項目:
使用例は、「OCI XML DB関数の使用」を参照してください。

戻り値

次のいずれかを戻します。

- エラー・ハンドラとコールバックに適切な値が移入された、xmlctx構造へのポインタ。これは、後にすべてのOCIコールに使用されます。

- データベース接続が使用できない場合、NULL。

関連関数

OCIXmlDbFreeXmlCtx()

A ハンドルおよび記述子の属性

この付録では、OCIのハンドルおよび記述子の属性について説明します。この属性はOCIAttrGet()関数で読み取り、OCIAttrSet()関数で変更することができます。

この付録では、次の項目について説明します。

- 表記規則

- 環境ハンドル属性

- エラー・ハンドル属性

- サービス・コンテキスト・ハンドル属性

- サーバー・ハンドル属性

- 認証情報ハンドル

- ユーザー・セッション・ハンドル属性

- 管理ハンドル属性

- 接続プール・ハンドル属性

- セッション・プール・ハンドル属性

- トランザクション・ハンドル属性

- 文ハンドル属性

- バインド・ハンドル属性

- 定義ハンドル属性

- 記述ハンドル属性

- パラメータ記述子属性

- LOBロケータ属性

- 複合オブジェクト属性

- 複合オブジェクト検索ハンドル属性

- 複合オブジェクト検索記述子の属性

- Streamsアドバンスト・キューイング記述子の属性

- OCIAQEnqOptions記述子の属性

- OCIAQDeqOptions記述子の属性

- OCIAQMsgProperties記述子の属性

- OCIAQAgent記述子の属性

- OCIServerDNs記述子の属性

- サブスクリプション・ハンドル属性

- 連続問合せ通知属性

- 連続問合せ通知の記述子の属性

- 通知の記述子の属性

- 無効化された問合せの属性

- ダイレクト・パス・ロード・ハンドル属性

- ダイレクト・パス・コンテキスト・ハンドル(OCIDirPathCtx)の属性

- ダイレクト・パス関数のコンテキスト・ハンドル(OCIDirPathFuncCtx)属性

- ダイレクト・パス関数の列配列ハンドル(OCIDirPathColArray)属性

- ダイレクト・パス・ストリーム・ハンドル(OCIDirPathStream)属性

- ダイレクト・パス列パラメータ属性

- プロセス・ハンドル属性

- イベント・ハンドル属性

表記規則

それぞれのハンドル・タイプで読取りまたは変更が可能な属性をリストします。各属性リストには、次の情報が含まれています。

モード

有効なモードは次のとおりです。

READ - OCIAttrGet()を使用して属性を読み取ります。

WRITE - OCIAttrSet()を使用して属性を変更します。

READ/WRITE - OCIAttrGet()を使用して属性を読み取り、OCIAttrSet()を使用して属性を変更します。

説明

これは、属性の用途の説明です。

属性のデータ型

これは、属性のデータ型です。必要に応じて、READモードとWRITEモードのデータ型が区別されます。

有効な値

一定の値のみが許可される場合には、その値を記載します。

例

一部の属性については例が記載されています。

環境ハンドル属性

環境ハンドルには、次の属性を使用します。

OCI_ATTR_ALLOC_DURATION

モード

READ/WRITE

説明

この属性は、環境ハンドルに対応付けられたアプリケーションの割当て時間にOCI_DURATION_DEFAULTの値を設定します。

属性のデータ型

OCIDuration */OCIDuration

OCI_ATTR_BIND_DN

モード

READ/WRITE

説明

LDAPサーバーへの接続時に使用するログイン名(DN)です。

属性のデータ型

oratext **/oratext *

OCI_ATTR_CACHE_ARRAYFLUSH

モード

READ/WRITE

説明

この属性がTRUEに設定されている場合は、OCICacheFlush()のコールによって、共通の表に属するオブジェクトがフラッシュされるため、パフォーマンスを大幅に向上することができます。TRUEの属性値は、オブジェクトのフラッシュの順序が重要でない場合にのみ使用します。属性値がTRUEに設定されているときは、オブジェクトが使用済としてマークされる順序の維持は保証されません。

関連項目:
「オブジェクト・キャッシュ・パラメータ」および「変更をサーバーにフラッシュ」

属性のデータ型

boolean */boolean

OCI_ATTR_CACHE_MAX_SIZE

モード

READ/WRITE

説明

最適サイズのパーセンテージとして、クライアント側オブジェクト・キャッシュの最大サイズ(最高水位標)を設定します。通常、この値を最適サイズOCI_ATTR_CACHE_OPT_SIZEの10% (デフォルト)に設定できます。この属性を0に設定すると、値10が使用されます。オブジェクト・キャッシュは最大の最適値を使用して、オブジェクト・キャッシュ内の未使用メモリーを解放します。

関連項目:
「オブジェクト・キャッシュ・パラメータ」

属性のデータ型

ub4 */ub4

OCI_ATTR_CACHE_OPT_SIZE

モード

READ/WRITE

説明

クライアント側オブジェクト・キャッシュの最適サイズをバイト数で設定します。デフォルト値は8MBです。この属性を0に設定すると、8MBの値が使用されます。

関連項目:
「オブジェクト・キャッシュ・パラメータ」

属性のデータ型

ub4 */ub4

OCI_ATTR_ENV_CHARSET_ID

モード

READ

説明

ローカル(クライアント側)キャラクタ・セットIDです。ユーザーは、環境ハンドルの作成後にこの設定を更新できますが、他のOCI関数をコールする前に行う必要があります。この制限によって、同じ環境ハンドル内のデータおよびメタデータ間の整合性が保証されます。キャラクタ・セットIDがUTF-16の場合、この属性を取得できません。

属性のデータ型

ub2 *

OCI_ATTR_ENV_NCHARSET_ID

モード

READ

説明

ローカル(クライアント側)各国語キャラクタ・セットIDです。ユーザーは、環境ハンドルの作成後にこの設定を更新できますが、他のOCI関数をコールする前に行う必要があります。この制限によって、同じ環境ハンドル内のデータおよびメタデータ間の整合性が保証されます。キャラクタ・セットIDがUTF-16の場合、この属性を取得できません。

属性のデータ型

ub2 *

OCI_ATTR_ENV_UTF16

モード

READ

説明

エンコーディング方法はUTF-16です。値1は、エンコーディング方法がUTF-16のときに環境ハンドルが作成されたことを示し、値0はそれ以外であることを示します。この属性値はOCIEnvCreate()のコールでのみ設定でき、後で変更することはできません。

属性のデータ型

ub1 *

OCI_ATTR_EVTCBK

モード

WRITE

説明

この属性は、イベント・コールバック関数を登録します。

関連項目:
「HAイベント通知」

属性のデータ型

OCIEventCallback

OCI_ATTR_EVTCTX

モード

WRITE

説明

この属性は、イベント・コールバックに渡されるコンテキストを登録します。

関連項目:
「HAイベント通知」

属性のデータ型

void *

OCI_ATTR_HEAPALLOC

モード

READ

説明

環境ハンドルから割り当てられたメモリーのカレント・サイズです。これは、アプリケーション内でメモリーが最も使用されている部分を追跡するのに役立ちます。

属性のデータ型

ub4 *

OCI_ATTR_LDAP_AUTH

モード

READ/WRITE

説明

認証モードです。次に示す値が有効です。

0x0: 認証なし。匿名のバインドです。

0x1: 簡易認証。ユーザー名およびパスワードによる認証です。

0x5: 認証なしのSSL接続。

0x6: SSL: サーバー認証のみ必要です。

0x7: SSL: サーバー認証とクライアント認証の両方が必要です。

0x8: 認証方式は実行時に判断されます。

属性のデータ型

ub2 */ub2

OCI_ATTR_LDAP_CRED

モード

READ/WRITE

説明

認証方式が簡易認証(ユーザー名およびパスワードによる認証)の場合、この属性には、LDAPサーバーへの接続時に使用するパスワードが保持されます。

属性のデータ型

oratext **/oratext *

OCI_ATTR_LDAP_CTX

モード

READ/WRITE

説明

クライアントの管理コンテキストです。通常は、LDAPサーバー内のOracle Database LDAPスキーマのルートです。

属性のデータ型

oratext **/oratext *

OCI_ATTR_LDAP_HOST

モード

READ/WRITE

説明

LDAPサーバーが実行されているホスト名です。

属性のデータ型

oratext **/oratext *

OCI_ATTR_LDAP_PORT

モード

READ/WRITE

説明

LDAPサーバーがリスニングするポートです。

属性のデータ型

ub2 */ub2

OCI_ATTR_OBJECT

モード

READ

説明

環境がオブジェクト・モードで初期化されている場合は、TRUEを戻します。

属性のデータ型

boolean *

OCI_ATTR_PINOPTION

モード

READ/WRITE

説明

この属性は、環境ハンドルに対応付けられたアプリケーションにOCI_PIN_DEFAULTの値を設定します。

たとえば、OCI_ATTR_PINOPTIONがOCI_PIN_RECENTに設定されている場合に、pin_optionパラメータがOCI_PIN_DEFAULTに設定されているOCIObjectPin()をコールすると、オブジェクトはOCI_PIN_RECENTモードで確保されます。

属性のデータ型

OCIPinOpt */OCIPinOpt

OCI_ATTR_OBJECT_NEWNOTNULL

モード

READ/WRITE

説明

この属性がTRUEに設定されている場合は、新規に作成されるオブジェクトにNULL以外の属性が設定されます。

関連項目:
「オブジェクトの作成」

属性のデータ型

boolean */boolean

OCI_ATTR_OBJECT_DETECTCHANGE

モード

READ/WRITE

説明

この属性がTRUEに設定されている場合は、コミットされた別のトランザクションによってサーバー内で変更されたオブジェクトのフラッシュを試行すると、アプリケーションがORA-08179エラーを受け取ります。

関連項目:
「コミット時ロックの実装」

属性のデータ型

boolean */boolean

OCI_ATTR_PIN_DURATION

モード

READ/WRITE

説明

この属性は、環境ハンドルに対応付けられたアプリケーションの確保継続時間にOCI_DURATION_DEFAULTの値を設定します。

属性のデータ型

OCIDuration */OCIDuration

OCI_ATTR_SHARED_HEAPALLOC

モード

READ

説明

共有プールから現在割り当てられているメモリーのサイズを戻します。この属性はどの環境ハンドルでも使用できますが、有効な値を戻すには、プロセスを共有モードで初期化する必要があります。この属性は次のように読み取られます。

ub4 heapsz = 0;
OCIAttrGet((void *)envhp, (ub4)OCI_HTYPE_ENV,
(void *) &heapsz, (ub4 *) 0,
(ub4)OCI_ATTR_SHARED_HEAPALLOC, errhp);

属性のデータ型

ub4 *

OCI_ATTR_WALL_LOC

モード

READ/WRITE

説明

認証方式がSSL認証の場合、この属性にはクライアントWalletの位置が格納されます。

属性のデータ型

oratext **/oratext *

エラー・ハンドル属性

エラー・ハンドルには、次の属性を使用します。

OCI_ATTR_DML_ROW_OFFSET

モード

READ

説明

エラーが発生した(DML配列の)オフセットを戻します。

属性のデータ型

ub4 *

サービス・コンテキスト・ハンドル属性

サービス・コンテキスト・ハンドルには、次の属性を使用します。

OCI_ATTR_ENV

モード

READ

説明

サービス・コンテキストに対応付けられた環境コンテキストを戻します。

属性のデータ型

OCIEnv **

OCI_ATTR_IN_V8_MODE

モード

READ

説明

アプリケーションが(OCISvcCtxToLda()コールなどによって)Oracleバージョン7モードに切り替えられているかどうかを判断できます。戻り値が0 (ゼロ)以外(TRUE)の場合、アプリケーションは現在Oracleバージョン8モードで実行されており、戻り値が0 (ゼロ) (FALSE)の場合、アプリケーションは現在Oracleバージョン7モードで実行されています。

属性のデータ型

ub1 *

例

次のコード例で、この属性の使用方法を示します。

in_v8_mode = 0;
OCIAttrGet ((void *)svchp, (ub4)OCI_HTYPE_SVCCTX, (ub1 *)&in_v8_mode,
(ub4) 0, OCI_ATTR_IN_V8_MODE, errhp);
if (in_v8_mode)
fprintf (stdout, "In V8 mode\n");
else
fprintf (stdout, "In V7 mode\n");

OCI_ATTR_SERVER

モード

READ/WRITE

説明

読取りモードでは、サービス・コンテキストのサーバー・コンテキスト属性へのポインタを戻します。

書込みモードでは、サービス・コンテキストのサーバー・コンテキスト属性を設定します。

属性のデータ型

OCIServer ** / OCIServer *

OCI_ATTR_SESSION

モード

READ/WRITE

説明

読取りモードでは、サービス・コンテキストの認証コンテキスト属性へのポインタを戻します。

書込みモードでは、サービス・コンテキストの認証コンテキスト属性を設定します。

属性のデータ型

OCISession **/ OCISession *

OCI_ATTR_STMTCACHE_CBK

モード

READ/WRITE

説明

OCISvcCtxハンドルでアプリケーションのコールバック関数を取得および設定するために使用します。OCISvcCtxで登録すると、この関数は、このサービス・コンテキストに属する文キャッシュ内の文が削除されたとき、またはセッションの終了時にコールされます。

コールバック関数は、次のプロトタイプのものであることが必要です。

sword (*OCICallbackStmtCache)(void *ctx, OCIStmt *stmt, ub4 mode)

ctx: IN引数。これは、アプリケーションが現行の文ハンドルで設定したコンテキストと同じです。

stmt: IN引数。これは、キャッシュから削除された文ハンドルです。

mode: IN引数。これは、コールバック関数がコールされているモードです。現在は、OCI_CBK_STMTCACHE_STMTPURGEという1つの値のみがサポートされており、これは、コールバックが、現行の文の削除中にコールされていることを意味します。

属性のデータ型

sword (*OCICallbackStmtCache)(void *ctx, OCIStmt *stmt, ub4 mode)

OCI_ATTR_STMTCACHESIZE

モード

READ/WRITE

説明

文キャッシュ対応セッションの場合、文キャッシュ・サイズのデフォルトの文数は20です。ユーザーがこの値を増加または減少させるには、サービス・コンテキスト・ハンドルでこの属性を設定します。また、この属性を使用して、プールされている、またはプールされていないセッションの文キャッシュを使用可能または使用不可にできます。文のキャッシュを有効にするには属性のサイズをゼロ以外に設定し、無効にするにはゼロに設定します。

属性のデータ型

ub4 */ ub4

OCI_ATTR_TRANS

モード

READ/WRITE

説明

読取りモードでは、サービス・コンテキストのトランザクション・コンテキスト属性へのポインタを戻します。

書込みモードでは、サービス・コンテキストのトランザクション・コンテキスト属性を設定します。

属性のデータ型

OCITrans ** / OCITrans *

サーバー・ハンドル属性

サーバー・ハンドルには、次の属性を使用します。

関連項目:
次のイベント・ハンドル属性もサーバー・ハンドルで使用できます。

- 「OCI_ATTR_DBDOMAIN」

- 「OCI_ATTR_DBNAME」

- 「OCI_ATTR_INSTNAME」

- 「OCI_ATTR_INSTSTARTTIME」

- 「OCI_ATTR_SERVICENAME」

OCI_ATTR_ACCESS_BANNER

モード

READ

説明

ファイルからの不正アクセス・バナーを表示します。

属性のデータ型

oratext **

OCI_ATTR_BREAK_ON_NET_TIMEOUT

モード

READ/WRITE

説明

この属性は、ネットワーク・タイムアウト後に、OCIがブレークを送信するかどうかを判断します。

属性のデータ型

ub1 *

OCI_ATTR_ENV

モード

READ

説明

サーバー・コンテキストに対応付けられた環境コンテキストを戻します。

属性のデータ型

OCIEnv **

OCI_ATTR_EXTERNAL_NAME

モード

READ/WRITE

説明

外部名は、sys.props$.value$に格納されているわかりやすいグローバル名です(ここで、name = 'GLOBAL_DB_NAME')。この名前は、すべてのデータベースがネットワーク・ディレクトリ・サービスで名前を登録していないかぎり、一意であることは保証されません。

分散トランザクションを調整する場合に、データベース名をサーバーと交換できます。サーバー・データベース名には、OCISessionBegin()コールの発行時、データベースがオープンされていた場合のみ、アクセスすることができます。

属性のデータ型

oratext **/ oratext *

OCI_ATTR_FOCBK

モード

READ/WRITE

説明

サーバー・コンテキスト・ハンドルでのフェイルオーバー・コールバックの登録および登録解除の一部として、型OCIFocbkStructのコールバック定義構造体へのフェイルオーバー・コールバックを設定します。

関連項目:
「OCIでの透過的アプリケーション・フェイルオーバー」

属性のデータ型

OCIFocbkStruct *

OCI_ATTR_INTERNAL_NAME

モード

READ/WRITE

説明

グローバル・トランザクションの実行時に記録されるクライアント・データベース名を設定します。この名前は、障害のために準備状態で保留になっている可能性があるトランザクションを追跡するために、DBAで使用できます。

属性のデータ型

oratext **/ oratext *

OCI_ATTR_IN_V8_MODE

モード

READ

説明

アプリケーションが(OCISvcCtxToLda()コールなどによって)Oracleバージョン7モードに切り替えられているかどうかを判断できます。戻り値が0 (ゼロ)以外(TRUE)の場合、アプリケーションは現在Oracleバージョン8モードで実行されており、戻り値が0 (ゼロ) (FALSE)の場合、アプリケーションは現在Oracleバージョン7モードで実行されています。

属性のデータ型

ub1 *

OCI_ATTR_NONBLOCKING_MODE

モード

READ/WRITE

説明

この属性は、ブロック化モードを判断します。サーバー・コンテキストが非ブロック化モードの場合、読取り時にこの属性値はTRUEを戻します。設定すると、非ブロック化モード属性が切り替えられます。この属性を設定できるのは、OCISessionBegin()またはOCILogon2()がコールされた後でのみです。それ以外の場合はエラーが戻されます。

関連項目:
「OCIでの非ブロック化モード」

属性のデータ型

ub1 */ub1

OCI_ATTR_SERVER_GROUP

モード

READ/WRITE

説明

サーバー・グループを指定する、30文字以内の英数字文字列です。この属性は、OCIServerAttach()のコール後にのみ設定できます。

関連項目:
「パスワードおよびセッションの管理」

属性のデータ型

oratext **/oratext *

OCI_ATTR_SERVER_STATUS

モード

READ

説明

サーバー・ハンドルの現行の状態を戻します。値は次のとおりです。

- OCI_SERVER_NORMAL－ サーバーへのアクティブな接続があります。接続の最後のコールが終了しました。次のコールが終了する保証はありません。

- OCI_SERVER_NOT_CONNECTED－ サーバーへの接続はありません。

属性のデータ型

ub4 *

例

次のコード例で、このパラメータの使用方法を示します。

ub4 serverStatus = 0
OCIAttrGet((void *)srvhp, OCI_HTYPE_SERVER,
(void *)&serverStatus, (ub4 *)0, OCI_ATTR_SERVER_STATUS, errhp);
if (serverStatus == OCI_SERVER_NORMAL)
printf("Connection is up.\n");
else if (serverStatus == OCI_SERVER_NOT_CONNECTED)
printf("Connection is down.\n");

OCI_ATTR_TAF_ENABLED

モード

READ

説明

サーバー・ハンドルがTAF対応の場合TRUEに、非対応の場合はFALSEに設定します。

関連項目:
「カスタム・プーリング: タグ付けされたサーバー・ハンドル」

属性のデータ型

boolean *

OCI_ATTR_USER_MEMORY

モード

READ

説明

ハンドルに追加メモリーが割り当てられている場合、ユーザー・メモリーへのポインタが戻されます。追加メモリーが割り当てられていないハンドルに関しては、NULLポインタが戻されます。

関連項目:
「カスタム・プーリング: タグ付けされたサーバー・ハンドル」

属性のデータ型

void *

認証情報ハンドル

これらの属性は、ユーザー・セッション・ハンドルにも適用されます。

関連項目:
「ユーザー・セッション・ハンドル属性」

ユーザー・セッション・ハンドル属性

これらの属性は、認証情報ハンドルにも適用されます。

OCI_ATTR_ACTION

モード

WRITE

説明

現行のモジュール内の現行アクション名です。NULLに設定できます。現行のアクションの終了後、次のアクション名、または次のアクションが存在しない場合はNULLをこの属性に設定します。32バイト以下で指定できます。

属性のデータ型

oratext *

例

OCIAttrSet(session, OCI_HTYPE_SESSION,(void *)"insert into employees",
(ub4)strlen("insert into employees"), OCI_ATTR_ACTION, error_handle);

OCI_ATTR_APPCTX_ATTR

注意:
この属性は、データベース常駐接続プーリングではサポートされません。

モード

WRITE

説明

外部で初期化されたコンテキストの属性名を指定します。

属性のデータ型

oratext *

関連項目:
「外部で初期化されたコンテキストの設定に使用するセッション・ハンドル属性」

OCI_ATTR_APPCTX_LIST

注意:
この属性は、データベース常駐接続プーリングではサポートされません。

モード

READ

説明

セッションに対するアプリケーション・コンテキスト・リスト記述子を取得します。

属性のデータ型

OCIParam* *

OCI_ATTR_APPCTX_NAME

注意:
この属性は、データベース常駐接続プーリングではサポートされません。

モード

WRITE

関連項目:
「外部で初期化されたコンテキストの設定に使用するセッション・ハンドル属性」

説明

外部で初期化されたコンテキストのネームスペースを指定します。

属性のデータ型

oratext *

OCI_ATTR_APPCTX_SIZE

注意:
この属性は、データベース常駐接続プーリングではサポートされません。

モード

WRITE

説明

外部で初期化されたコンテキストの配列サイズを、属性数を使用して初期化します。

属性のデータ型

ub4

OCI_ATTR_APPCTX_VALUE

注意:
この属性は、データベース常駐接続プーリングではサポートされません。

モード

WRITE

説明

外部で初期化されたコンテキストの値を指定します。

属性のデータ型

oratext *

関連項目:
「外部で初期化されたコンテキストの設定に使用するセッション・ハンドル属性」

OCI_ATTR_AUDIT_BANNER

モード

READ

説明

ファイルからのユーザー・アクション監査バナーを表示します。

属性のデータ型

oratext **

OCI_ATTR_CALL_TIME

モード

READ

説明

前述のコールのサーバー側の時間をマイクロ秒単位で戻します。

属性のデータ型

ub8 *

OCI_ATTR_CERTIFICATE

モード

WRITE

説明

プロキシ認証で使用するクライアントの証明書を指定します。OCI_ATTR_CERTIFICATEを使用した証明書ベースのプロキシ認証は、Oracle Databaseの今後のリリースではサポートされません。かわりに、OCI_ATTR_DISTINGUISHED_NAME属性またはOCI_ATTR_USERNAME属性を使用してください。

属性のデータ型

ub1 *

OCI_ATTR_CLIENT_IDENTIFIER

モード

WRITE

説明

セッション・ハンドルにユーザー識別子を指定します。64バイト以下で指定できます。ユーザー名を含めることはできますが、セキュリティ上の理由から、パスワードを含めることはできません。識別子の最初の文字に':'は使用できません。この文字を使用すると、予期しない動作が発生する場合があります。

属性のデータ型

oratext *

例

OCIAttrSet(session, OCI_HTYPE_SESSION,(void *)"janedoe",
(ub4)strlen("janedoe"), OCI_ATTR_CLIENT_IDENTIFIER,
error_handle);

OCI_ATTR_CLIENT_INFO

モード

WRITE

説明

クライアント・アプリケーションの追加情報です。DBMS_APPLICATION_INFOパッケージによっても設定できます。V$SESSIONビューに格納されています。64バイト以下で指定できます。

属性のデータ型

oratext *

OCI_ATTR_COLLECT_CALL_TIME

モード

READ/WRITE

説明

TRUEに設定すると、サーバーは、後続の各OCIコールのコール時間をミリ秒単位で測定します。

属性のデータ型

boolean */boolean

OCI_ATTR_CONNECTION_CLASS

モード

READ/WRITE

説明

OCIAuthInfoハンドルのこの属性では、データベース常駐接続プール用の接続クラス名(128文字以内の文字列)を明示的に指定します。

属性のデータ型

oratext **/oratext *

OCI_ATTR_CURRENT_SCHEMA

モード

READ/WRITE

説明

スキーマ名とセッションが存在する場合、この属性を使用してOCIAttrSet()をコールすることで、SQLコマンドALTER SESSION SET CURRENT_SCHEMAと同じ結果が得られます。スキーマはサーバーへのラウンドトリップを行う次のOCIコールで変更され、余分なラウンドトリップが回避されます。新しいスキーマ名が存在しない場合、ALTER SESSION SET CURRENT_SCHEMAから戻されるエラーと同じエラーが戻されます。その後入力するDMLまたはDDLコマンド内で、データベース・オブジェクトの前にこの新しいスキーマ名が入ります。

この属性を使用しているクライアントがOracle Database 10gリリース2よりも前のソフトウェア・リリースのサーバーと通信を行うと、OCIAttrSet()コールは無視されます。この属性はOCIAttrGet()でも読み取ることができます。

属性のデータ型

oratext */oratext *

例

text schema[] = "hr";
err = OCIAttrSet( (void ) mysessp, OCI_HTYPE_SESSION, (void *)schema,
(ub4)strlen( (char *)schema), OCI_ATTR_CURRENT_SCHEMA, (OCIError *)myerrhp);

OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE

モード

READ/WRITE

説明

セッション中にフェッチされる全LOBロケータをユーザーがプリフェッチできるようにします。各LOBロケータのデフォルトのプリフェッチ・バッファ・サイズを指定します。

属性のデータ型

ub4 */ub4

OCI_ATTR_DISTINGUISHED_NAME

モード

WRITE

説明

プロキシ認証で使用するクライアントの識別名を指定します。

属性のデータ型

oratext *

OCI_ATTR_DRIVER_NAME

モード

READ/WRITE

説明

JDBC、ODBC、PHP、SQL*PlusなどのOCIを使用するドライバ・レイヤーの名称を指定します。ORA$で始まる名称も予約済です。今後のアプリケーションでは、固有の名称を選択し、障害診断に役立つように設定できます。この属性は、OCISessionBegin()を実行する前に設定してください。NULL終端文字を含めて最大9個のシングルバイト文字による配列を渡します。このデータは検証されず、サーバーに直接渡されてV$SESSION_CONNECT_INFOまたはGV$SESSION_CONNECT_INFOビューに表示されます。OCIにより確認されるのは、ドライバ名の配列が30文字以内であることのみです。9文字以上が渡されると、最初の8文字のみが表示されます。

属性のデータ型

oratext **/oratext *

例

...
oratext client_driver[9];
...
checkerr(errhp, OCIAttrSet(authp, OCI_HTYPE_SESSION,
client_driver, (ub4)(strlen(client_driver)),
OCI_ATTR_DRIVER_NAME, errhp));

checkerr(errhp, OCISessionBegin(svchp, errhp, authp, OCI_CRED_RDBMS, OCI_DEFAULT);
...

OCI_ATTR_EDITION

モード

READ/WRITE

説明

このセッションで使用されるEditionを指定します。この属性の値が明示的に設定されていない場合は、環境変数ORA_EDITIONの値が戻されます。

属性のデータ型

oratext *

OCI_ATTR_INITIAL_CLIENT_ROLES

モード

WRITE

説明

アプリケーション・サーバーがクライアントにかわってOracle Databaseに接続する場合にクライアントが最初に所有する1つまたは複数のロールを指定します。

属性のデータ型

oratext **

OCI_ATTR_MIGSESSION

モード

READ/WRITE

説明

セッション・ハンドル用に識別されたセッションを指定します。同じプロセス内または複数プロセス間で、セッションをある環境から別の環境へ複製することができます。これは、同じシステム上のプロセスでも異なるシステム上のプロセスでも可能です。複製するセッションは、移行可能と認証されている必要があります。

関連項目:
「パスワードおよびセッションの管理」

属性のデータ型

ub1 *

例

次のコード例で、この属性の使用方法を示します。

OCIAttrSet ((void *) authp, (ub4)OCI_HTYPE_SESSION, (void *) mig_session,
(ub4) sz, (ub4)OCI_ATTR_MIGSESSION, errhp);

OCI_ATTR_MODULE

モード

WRITE

説明

クライアント・アプリケーションで実行中の現行モジュール名です。現行のモジュールの終了後、新しいモジュール名でコールしするか、または新しいモジュールが存在しない場合はNULLを使用します。48バイト以下で指定できます。

属性のデータ型

oratext *

例

OCIAttrSet(session, OCI_HTYPE_SESSION,(void *)"add_employee",
(ub4)strlen("add_employee"), OCI_ATTR_MODULE, error_handle);

OCI_ATTR_PASSWORD

モード

WRITE

説明

認証に使用するパスワードを指定します。

属性のデータ型

oratext *

OCI_ATTR_PROXY_CLIENT

モード

WRITE

説明

プロキシ経由でアクセスするターゲット・ユーザー名を指定します。

属性のデータ型

oratext *

OCI_ATTR_PROXY_CREDENTIALS

モード

WRITE

説明

アプリケーション・サーバーの資格証明をプロキシ認証で使用するように指定します。

属性のデータ型

OCISession

OCI_ATTR_PURITY

モード

READ/WRITE

説明

データベース常駐接続プーリング用のOCIAuthInfoハンドルの属性です。値は、OCI_ATTR_PURITY_NEW (アプリケーションでは前のセッション状態で保持されていないセッションが必要)またはOCI_ATTR_PURITY_SELF (セッションが前に使用済でも可)です。OCISessionGet()のコール時にアプリケーションで純正値が指定されていない場合、純正値OCI_ATTR_PURITY_DEFAULTが使用されます。この値は、後でアプリケーションのタイプに応じてOCI_ATTR_PURITY_NEWまたはOCI_ATTR_PURITY_SELFに変換されます。

属性のデータ型

ub4 */ub4

OCI_ATTR_SESSION_STATE

モード

READ/WRITE

説明

データベース・セッションの現在の状態を指定します。セッションがデータベース・タスクを実行する必要がある場合は、OCI_SESSION_STATEFULに設定します。後続のデータベース・アクティビティに対して、アプリケーションが現行のセッションに依存していない場合は、OCI_SESSION_STATELESSに設定します。

関連項目:
OCI_ATTR_SESSION_STATEの使用方法の詳細および例は、「ステートフルまたはステートレスとしてのセッションの明示的作成」を参照してください。

属性のデータ型

ub1 *

OCI_ATTR_TRANSACTION_IN_PROGRESS

モード

READ

説明

TRUEの場合、参照対象のセッションには、現在アクティブなトランザクションが存在します。

FALSEの場合、参照対象のセッションには、現在アクティブなトランザクションが存在しません。

属性のデータ型

boolean *

例

{  boolean txnInProgress;

OCIAttrGet(usrhp, OCI_HTYPE_SESSION,
&txnInProgress, (ub4 *)0,
OCI_ATTR_TRANSACTION_IN_PROGRESS,
errhp);
}

OCI_ATTR_USERNAME

モード

READ/WRITE

説明

認証に使用するユーザー名を指定します。

属性のデータ型

oratext **/oratext *

管理ハンドル属性

管理ハンドルには、次の属性を使用します。

OCI_ATTR_ADMIN_PFILE

モード

READ/WRITE

説明

OCIDBStartup()をコールする前にこの属性を設定し、データベースの起動に使用するクライアント側のパラメータ・ファイルの場所を指定します。この属性が設定されていない場合、サーバー側のパラメータ・ファイルが使用されます。サーバー側のパラメータ・ファイルが存在しない場合、エラーが戻されます。

属性のデータ型

oratext */oratext *

接続プール・ハンドル属性

接続プール・ハンドルには、次の属性を使用します。

OCI_ATTR_CONN_TIMEOUT

注意:
プールの縮小は、ネットワーク・ラウンドトリップがある場合にのみ発生します。操作がない場合、接続はアクティブなままになります。

モード

READ/WRITE

説明

この時間値(秒数)を超えてアイドル状態の接続は終了し、オープン接続が最適な数に維持されます。この属性は動的に設定できます。この属性を設定していない場合、接続がタイムアウトになることはありません。

属性のデータ型

ub4 */ub4

OCI_ATTR_CONN_NOWAIT

モード

READ/WRITE

説明

この属性は、プール内のすべての接続がビジーで、接続数が最大数に達しているとき、接続の再試行を行う必要があるかどうかを判断します。

この属性が設定されている場合は、すべての接続がビジーで、それ以上接続をオープンできないときにエラーが発生します。設定されていない場合、コールは接続が確立するまで待機します。

この属性が設定されている場合、読取り時には、属性値がTRUEで戻されます。

属性のデータ型

ub1 */ub1

OCI_ATTR_CONN_BUSY_COUNT

モード

READ

説明

ビジーの接続の数を戻します。

属性のデータ型

ub4 *

OCI_ATTR_CONN_OPEN_COUNT

モード

READ

説明

オープンしている接続の数を戻します。

属性のデータ型

ub4 *

OCI_ATTR_CONN_MIN

モード

READ

説明

最小接続数を戻します。

属性のデータ型

ub4 *

OCI_ATTR_CONN_MAX

モード

READ

説明

最大接続数を戻します。

属性のデータ型

ub4 *

OCI_ATTR_CONN_INCR

モード

READ

説明

接続の増分パラメータを戻します。

属性のデータ型

ub4 *

セッション・プール・ハンドル属性

セッション・プール・ハンドルには、次の属性を使用します。

OCI_ATTR_SPOOL_BUSY_COUNT

モード

READ

説明

ビジーのセッションの数を戻します。

属性のデータ型

ub4 *

OCI_ATTR_SPOOL_GETMODE

モード

READ/WRITE

説明

この属性は、プール内のすベてのセッションがビジーで、いくつかのセッションが最大に達していることが判明したときに、セッション・プールの動作を判断します。値は次のとおりです。

- OCI_SPOOL_ATTRVAL_WAIT - スレッドはセッションが解放されるまでブロックされて待機します。これがデフォルト値です。

- OCI_SPOOL_ATTRVAL_NOWAIT - エラーが戻ります。

- OCI_SPOOL_ATTRVAL_FORCEGET - すべてのセッションがビジーで、セッション数が最大に達している場合でも、新しいセッションを作成します。OCISessionGet()によって警告が戻されます。この場合、OCISessionGet()が警告を戻すのは、新規作成のセッションがセッションの最大数を超えた場合です。
この値を設定した場合は、Oracle Databaseのインスタンスでサポートできるセッション数よりも多いセッションが作成される可能性があります。この場合は、次のエラーがサーバーから戻されます。

ORA 00018 - Maximum number of sessions exceeded

このエラーは、セッション・プールのユーザーに伝播されます。

読取りの場合は、適切な属性値が戻されます。

属性のデータ型

ub1 */ub1

OCI_ATTR_SPOOL_INCR

モード

READ

説明

セッションの増分パラメータを戻します。

属性のデータ型

ub4 *

OCI_ATTR_SPOOL_MAX

モード

READ

説明

最大セッション数を戻します。

属性のデータ型

ub4 *

OCI_ATTR_SPOOL_MIN

モード

READ

説明

最小セッション数を戻します。

属性のデータ型

ub4 *

OCI_ATTR_SPOOL_OPEN_COUNT

モード

READ

説明

オープンしているセッションの数を戻します。

属性のデータ型

ub4 *

OCI_ATTR_SPOOL_AUTH

モード

WRITE

説明

セッション・プールから取得されているセッションでセッション作成前属性を有効にする場合、この属性は、セッション・プール・ハンドルで設定できます。現在、このOCIAuthInfoハンドルで設定できるのは、次の属性のみです。

OCI_ATTR_DRIVER_NAME

OCI_ATTR_EDITION

OCIAuthInfoハンドルに他の属性が設定されている場合、およびセッション・プール・ハンドルにOCIAuthInfoハンドルが設定されている場合、エラーになります。さらに、セッション・プール・ハンドルを使用したOCISessionPoolCreate()のコール前のみ、セッション・プール・ハンドルにOCIAuthInfoハンドルを設定する必要があります。OCISessionPoolCreate()の後にこれを設定すると、エラーになります。

属性のデータ型

OCIAuthInfo *

OCI_ATTR_SPOOL_STMTCACHESIZE

モード

READ/WRITE

説明

セッション・プールの各セッションのデフォルトの文キャッシュ・サイズを、この値に設定します。プールの特定のセッションの文キャッシュ・サイズは、そのセッションでOCI_ATTR_STMTCACHESIZEを使用することでいつでも上書きできます。

関連項目:
「OCIでの文キャッシュ」

属性のデータ型

ub4 */ ub4

OCI_ATTR_SPOOL_TIMEOUT

モード

READ/WRITE

説明

この時間(秒)を超えてアイドル状態のセッションは定期的に終了し、オープンしているセッション数が最適に維持されます。この属性は動的に設定できます。この属性が設定されておらず、プール内に領域が必要な場合は、最低使用頻度のセッションがタイムアウトとなります。OCIでは、プールに解放するときにのみ、タイムアウトしたセッションがチェックされます。

属性のデータ型

ub4 */ub4

トランザクション・ハンドル属性

トランザクション・ハンドルには、次の属性を使用します。

OCI_ATTR_TRANS_NAME

モード

READ/WRITE

説明

この属性を使用して、トランザクションを識別するテキスト文字列の構築または読取りができます。これは、XIDを使用してトランザクションを識別するかわりに使用される方法です。oratext文字列は、64バイトまで指定できます。

属性のデータ型

oratext ** (READ) / oratext * (WRITE)

OCI_ATTR_TRANS_TIMEOUT

モード

READ/WRITE

説明

準備時間に使用するタイムアウト時間値の設定または読取りができます。

属性のデータ型

ub4 * (READ)/ub4 (WRITE)

OCI_ATTR_XID

モード

READ/WRITE

説明

トランザクションを識別するXIDの設定または読取りができます。

属性のデータ型

XID ** (READ)/XID * (WRITE)

文ハンドル属性

文ハンドルには、次の属性を使用します。

OCI_ATTR_BIND_COUNT

モード

READ

説明

文ハンドルのバインド位置の数を戻します。

属性のデータ型

ub4 *

例

OCIHandleAlloc(env,(void **) &pStatement, OCI_HTYPE_STMT, (size_t)0, (void **)0);
OCIStmtPrepare (pStatement, err, pszQuery, (ub4)strlen(pszQuery),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
OCIAttrGet(pStatement, OCI_HTYPE_STMT, &iNbParameters, NULL, OCI_ATTR_BIND_COUNT,
err);

OCI_ATTR_CHNF_REGHANDLE

モード

WRITE

説明

この属性を該当するサブスクリプション・ハンドルに設定すると、問合せの実行時に連続問合せ通知用の問合せの登録も作成されます。

属性のデータ型

OCISubscription *

例

/* Associate the statement with the subscription handle */
OCIAttrSet (stmthp, OCI_HTYPE_STMT, subscrhp, 0,
OCI_ATTR_CHNF_REGHANDLE, errhp);

関連項目:
「連続問合せ通知属性」

OCI_ATTR_CQ_QUERYID

モード

READ

説明

OCIStmtExecute()のコールによる登録後に、登録済問合せの問合せIDを取得します。

属性のデータ型

ub8 *

OCI_ATTR_CURRENT_POSITION

モード

READ

説明

結果セット内の現行の位置を示します。この属性は読取りのみ可能です。設定はできません。

属性のデータ型

ub4 *

OCI_ATTR_ENV

モード

READ

説明

結果セット内の現行の位置を示します。この属性は読取りのみ可能です。設定はできません。

属性のデータ型

ub4 *

OCI_ATTR_FETCH_ROWID

モード

READ/WRITE

説明

position 0での定義とSELECT...FOR UPDATE文の実行後に、ROWIDがフェッチされるように指定します。

属性のデータ型

boolean */boolean

関連項目:
「ROWIDの暗黙的フェッチ」

OCI_ATTR_NUM_DML_ERRORS

モード

READ

説明

DML操作でのエラーの数を戻します。

属性のデータ型

ub4 *

OCI_ATTR_PARAM_COUNT

モード

READ

説明

文ハンドルに対応付けられた文の選択リストにある列数を取得します。

属性のデータ型

ub4 *

例

...
int i = 0;
ub4 parmcnt = 0;
ub2 type = 0;
OCIParam *colhd = (OCIParam *) 0;   /* column handle */

/* Describe of a select-list */
OraText *sqlstmt = (OraText *)"SELECT * FROM employees WHERE employee_id = 100";

checkerr(errhp, OCIStmtPrepare(stmthp, errhp, (OraText *)sqlstmt,
(ub4)strlen((char *)sqlstmt),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));

checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, 1, 0,
(OCISnapshot *)0, (OCISnapshot *)0, OCI_DESCRIBE_ONLY));

/* Get the number of columns in the select list */
checkerr(errhp, OCIAttrGet((void *)stmthp, OCI_HTYPE_STMT, (void *)&parmcnt,
(ub4 *)0, OCI_ATTR_PARAM_COUNT, errhp));

/* Go through the column list and retrieve the data type of each column. You
start from pos = 1 */
for (i = 1; i <= parmcnt; i++)
{
/* Get parameter for column i */
checkerr(errhp, OCIParamGet((void *)stmthp, OCI_HTYPE_STMT, errhp,
(void **)&colhd, i));

/* Get data-type of column i */
type = 0;
checkerr(errhp, OCIAttrGet((void *)colhd, OCI_DTYPE_PARAM,
(void *)&type, (ub4 *)0, OCI_ATTR_DATA_TYPE, errhp));

}
...

OCI_ATTR_PARSE_ERROR_OFFSET

モード

READ

説明

文の解析エラー・オフセットを戻します。

属性のデータ型

ub2 *

OCI_ATTR_PREFETCH_MEMORY

モード

WRITE

説明

プリフェッチされるトップレベル行のメモリー・レベルを設定します。メモリー・レベルが指定したメモリー使用率制限を超えない量を占有している場合、指定したトップレベル行カウントまでの行がフェッチされます。デフォルト値は0 (ゼロ)です。これは、プリフェッチする行数の計算にメモリー・サイズが含まれていないことを示します。

属性のデータ型

ub4 *

OCI_ATTR_PREFETCH_ROWS

モード

WRITE

説明

プリフェッチされるトップレベル行の数を設定します。デフォルト値は1行です。

属性のデータ型

ub4 *

OCI_ATTR_ROW_COUNT

モード

READ

説明

SELECT文の後、これまでに処理した行の数を戻します。INSERT、UPDATEおよびDELETE文の場合、最後の文によって処理された行の数を戻します。デフォルト値は1です。

スクロール不可カーソルの場合、OCI_ATTR_ROW_COUNTは、この文ハンドルの実行後にOCIStmtFetch2()コールでユーザー・バッファにフェッチされた行の合計数です。スクロール不可カーソルは前方への順次アクセスのみであるため、この属性は、アプリケーションで参照する最後の行番号を表します。

スクロール・カーソルの場合、OCI_ATTR_ROW_COUNTは、ユーザー・バッファにフェッチされた行の最大(絶対)数を表します。アプリケーションでは、任意の位置でフェッチを行うことができるため、この属性は、(スクロール可能な)文の実行後にユーザーのバッファにフェッチされた行の合計数である必要はありません。

属性のデータ型

ub4 *

OCI_ATTR_ROWID

モード

READ

説明

OCIDescriptorAlloc()によって割り当てられるROWID記述子を戻します。

関連項目:
「位置指定の更新および削除」および「ROWID記述子」

属性のデータ型

OCIRowid *

OCI_ATTR_ROWS_FETCHED

モード

READ

説明

前回のフェッチまたは1回以上の反復処理でユーザーのバッファに正常にフェッチされた行の数を示します。スクロール可能およびスクロール不可の文ハンドルの両方で使用できます。

属性のデータ型

ub4 *

例

ub4 rows;
ub4 sizep = sizeof(ub4);
OCIAttrGet((void *) stmhp, (ub4) OCI_HTYPE_STMT,
(void *)& rows, (ub4 *) &sizep, (ub4)OCI_ATTR_ROWS_FETCHED,
errhp);

OCI_ATTR_SQLFNCODE

モード

READ

説明

文に対応付けられたSQLコマンドの関数コードを戻します。

属性のデータ型

ub2 *

注意

表A-1は、SQLコマンド・コードのリストを示しています。

表A-1 SQLコマンド・コード

コード

SQL関数

コード

SQL関数

コード

SQL関数

01

CREATE TABLE

43

DROP EXTERNAL DATABASE

85

TRUNCATE TABLE

02

SET ROLE

44

CREATE DATABASE

86

TRUNCATE CLUSTER

03

INSERT

45

ALTER DATABASE

87

CREATE BITMAPFILE

04

SELECT

46

CREATE ROLLBACK SEGMENT

88

ALTER VIEW

05

UPDATE

47

ALTER ROLLBACK SEGMENT

89

DROP BITMAPFILE

06

DROP ROLE

48

DROP ROLLBACK SEGMENT

90

SET CONSTRAINTS

07

DROP VIEW

49

CREATE TABLESPACE

91

CREATE FUNCTION

08

DROP TABLE

50

ALTER TABLESPACE

92

ALTER FUNCTION

09

DELETE

51

DROP TABLESPACE

93

DROP FUNCTION

10

CREATE VIEW

52

ALTER SESSION

94

CREATE PACKAGE

11

DROP USER

53

ALTER USER

95

ALTER PACKAGE

12

CREATE ROLE

54

COMMIT (WORK)

96

DROP PACKAGE

13

CREATE SEQUENCE

55

ROLLBACK

97

CREATE PACKAGE BODY

14

ALTER SEQUENCE

56

SAVEPOINT

98

ALTER PACKAGE BODY

15

(使用されていません)

57

CREATE CONTROL FILE

99

DROP PACKAGE BODY

16

DROP SEQUENCE

58

ALTER TRACING

157

CREATE DIRECTORY

17

CREATE SCHEMA

59

CREATE TRIGGER

158

DROP DIRECTORY

18

CREATE CLUSTER

60

ALTER TRIGGER

159

CREATE LIBRARY

19

CREATE USER

61

DROP TRIGGER

160

CREATE JAVA

20

CREATE INDEX

62

ANALYZE TABLE

161

ALTER JAVA

21

DROP INDEX

63

ANALYZE INDEX

162

DROP JAVA

22

DROP CLUSTER

64

ANALYZE CLUSTER

163

CREATE OPERATOR

23

VALIDATE INDEX

65

CREATE PROFILE

164

CREATE INDEXTYPE

24

CREATE PROCEDURE

66

DROP PROFILE

165

DROP INDEXTYPE

25

ALTER PROCEDURE

67

ALTER PROFILE

166

ALTER INDEXTYPE

26

ALTER TABLE

68

DROP PROCEDURE

167

DROP OPERATOR

27

EXPLAIN

69

(使用されていません)

168

ASSOCIATE STATISTICS

28

GRANT

70

ALTER RESOURCE COST

169

DISASSOCIATE STATISTICS

29

REVOKE

71

CREATE SNAPSHOT LOG

170

CALL METHOD

30

CREATE SYNONYM

72

ALTER SNAPSHOT LOG

171

CREATE SUMMARY

31

DROP SYNONYM

73

DROP SNAPSHOT LOG

172

ALTER SUMMARY

32

ALTER SYSTEM SWITCH LOG

74

CREATE SNAPSHOT

173

DROP SUMMARY

33

SET TRANSACTION

75

ALTER SNAPSHOT

174

CREATE DIMENSION

34

PL/SQL EXECUTE

76

DROP SNAPSHOT

175

ALTER DIMENSION

35

LOCK

77

CREATE TYPE

176

DROP DIMENSION

36

NOOP

78

DROP TYPE

177

CREATE CONTEXT

37

RENAME

79

ALTER ROLE

178

DROP CONTEXT

38

COMMENT

80

ALTER TYPE

179

ALTER OUTLINE

39

AUDIT

81

CREATE TYPE BODY

180

CREATE OUTLINE

40

NO AUDIT

82

ALTER TYPE BODY

181

DROP OUTLINE

41

ALTER INDEX

83

DROP TYPE BODY

182

UPDATE INDEXES

42

CREATE EXTERNAL DATABASE

84

DROP LIBRARY

183

ALTER OPERATOR

OCI_ATTR_STATEMENT

モード

READ

説明

プリコンパイルされたSQL文のテキストを文ハンドルに戻します。UTF-16モードでは、戻された文はUTF-16エンコーディングになります。長さは、常にバイト単位です。

属性のデータ型

oratext *

OCI_ATTR_STMTCACHE_CBKCTX

モード

READ/WRITE

説明

文ハンドルでアプリケーションの不透明なコンテキストの取得および設定を行います。このコンテキストは、アプリケーションが定義する型のいずれかです。また、主にバインドを取り扱い、バッファ・アドレスを定義するのに使用します。

属性のデータ型

void *

OCI_ATTR_STMT_STATE

モード

READ

説明

文のフェッチ状態を戻します。コール元はこの属性を使用して、このセッションが別のサービス・コンテキストで使用できるかどうか、現行のデータ・アクセス・コール・セットでまだ必要かどうかを判断できます。基本的に、フェッチ実行サイクルの途中では、別の文を実行するためにセッション・ハンドルを解放することはありません。次の値が有効です。

- OCI_STMT_STATE_INITIALIZED

- OCI_STMT_STATE_EXECUTED

- OCI_STMT_STATE_END_OF_FETCH

属性のデータ型

ub4 *

OCI_ATTR_STMT_TYPE

モード

READ

説明

ハンドルに対応付けられた文のタイプです。次の値が有効です。

- OCI_STMT_SELECT

- OCI_STMT_UPDATE

- OCI_STMT_DELETE

- OCI_STMT_INSERT

- OCI_STMT_CREATE

- OCI_STMT_DROP

- OCI_STMT_ALTER

- OCI_STMT_BEGIN (PL/SQL文)

- OCI_STMT_DECLARE (PL/SQL文)

属性のデータ型

ub2 *

バインド・ハンドル属性

バインド・ハンドルには、次の属性を使用します。

OCI_ATTR_CHAR_COUNT

モード

WRITE

説明

キャラクタ・タイプ・データの文字数を設定します。

関連項目:
「OCIバインド時のバッファの拡張」

属性のデータ型

ub4 *

OCI_ATTR_CHARSET_FORM

モード

READ/WRITE

説明

バインド・ハンドルのキャラクタ・セット・フォームです。デフォルトのフォームはSQLCS_IMPLICITです。この属性を設定すると、バインド・ハンドルでクライアント側のデータベースまたは各国語キャラクタ・セットを使用できます。この属性は、各国語キャラクタ・セットの場合はSQLCS_NCHARに設定し、データベース・キャラクタ・セットの場合はSQLCS_IMPLICITに設定します。

属性のデータ型

ub1 *

OCI_ATTR_CHARSET_ID

モード

READ/WRITE

説明

バインド・ハンドルのキャラクタ・セットIDです。入力データのキャラクタ・セットがUTF-16 (下位互換性のために保持されている、非推奨になったOCI_UC2SIDの置換え)の場合、ユーザーはキャラクタ・セットIDをOCI_UTF16IDに設定する必要があります。バインド値バッファはutextバッファであるとみなされ、入力長ポインタおよび戻り値の長さセマンティクスは、キャラクタ・セマンティクス(utextの数)に変更されます。ただし、先行するOCIBindコールでは、バインド値バッファのサイズをバイト単位で指定する必要があります。

OCI_ATTR_CHARSET_IDは、OCI_ATTR_CHARSET_FORM (設定する場合)の後に設定する必要があります。OCI_ATTR_CHARSET_FORMを設定する前にOCI_ATTR_CHARSET_IDを設定すると、予想しない結果になります。

関連項目:
「OCIバインドおよび定義における文字変換」

属性のデータ型

ub2 *

OCI_ATTR_MAXCHAR_SIZE

モード

WRITE

説明

バインドするデータを格納するためにアプリケーションがサーバー上に予約する文字数を設定します。

関連項目:
「OCI_ATTR_MAXCHAR_SIZE属性の使用」

属性のデータ型

sb4 *

OCI_ATTR_MAXDATA_SIZE

モード

READ/WRITE

説明

キャラクタ・セットの変換後、クライアント側バインド・データを格納するためにサーバー側のバッファで許可される最大バイト数を設定します。

関連項目:
「OCI_ATTR_MAXDATA_SIZE属性の使用」

属性のデータ型

sb4 *

OCI_ATTR_PDPRC

モード

WRITE

説明

パック10進数の精度を指定します。SQLT_PDN値の場合、精度は2*(value_sz-1)に等しくしてください。SQLT_SLS値の場合、精度は(value_sz-1)に等しくしてください。

バインドまたは定義後に、この値は0 (ゼロ)に初期化されます。最初にOCI_ATTR_PDPRC属性を設定して、次にOCI_ATTR_PDSCLを設定します。これらの値のどちらかを変更する必要がある場合は、最初に再バインドまたは再定義の操作を実行して、次にこれらの属性を適切に再設定する必要があります。

属性のデータ型

ub2 *

OCI_ATTR_PDSCL

モード

WRITE

説明

パック10進値のスケールを指定します。

バインドまたは定義後に、この値は0 (ゼロ)に初期化されます。最初にOCI_ATTR_PDPRC属性を設定して、次にOCI_ATTR_PDSCLを設定します。これらの値のどちらかを変更する必要がある場合は、最初に再バインドまたは再定義の操作を実行して、次にこれらの属性を適切に再設定する必要があります。

属性のデータ型

sb2 *

OCI_ATTR_ROWS_RETURNED

モード

READ

説明

この属性は、RETURNING句でDML文をバインドするOUTのコールバック関数を実行しているとき、現行の反復で戻される行数を戻します。

属性のデータ型

ub4 *

定義ハンドル属性

定義ハンドルには、次の属性を使用します。

OCI_ATTR_CHAR_COUNT

モード

WRITE

説明

この属性は非推奨です。

キャラクタ・タイプ・データの文字数を設定します。この属性は、定義バッファに必要な文字数を指定します。定義コールで指定した定義バッファ長は、文字数より大きくする必要があります。

属性のデータ型

ub4 *

OCI_ATTR_CHARSET_FORM

モード

READ/WRITE

説明

定義ハンドルのキャラクタ・セット・フォームです。デフォルトのフォームはSQLCS_IMPLICITです。この属性を設定すると、定義ハンドルでクライアント側のデータベースまたは各国語キャラクタ・セットを使用できます。この属性は、各国語キャラクタ・セットの場合はSQLCS_NCHARに設定し、データベース・キャラクタ・セットの場合はSQLCS_IMPLICITに設定します。

属性のデータ型

ub1 *

OCI_ATTR_CHARSET_ID

モード

READ/WRITE

説明

定義ハンドルのキャラクタ・セットIDです。出力データのキャラクタ・セットがUTF-16である場合、ユーザーはキャラクタ・セットIDOTTをOCI_UTF16IDに設定する必要があります。定義値バッファはutextバッファであるとみなされ、インジケータおよび戻り値の長さセマンティクスは、キャラクタ・セマンティクス(utextの数)に変更されます。ただし、先行するOCIDefineコールでは、定義値バッファのサイズをバイト単位で指定する必要があります。

OCI_ATTR_CHARSET_IDは、OCI_ATTR_CHARSET_FORM (設定する場合)の後に設定する必要があります。OCI_ATTR_CHARSET_FORMを設定する前にOCI_ATTR_CHARSET_IDを設定すると、予想しない結果になります。

関連項目:
「OCIバインドおよび定義における文字変換」

属性のデータ型

ub2 *

OCI_ATTR_LOBPREFETCH_LENGTH

モード

READ/WRITE

説明

特定の列からフェッチするLOBのプリフェッチ長とチャンク・サイズを指定します。

属性のデータ型

boolean */boolean

OCI_ATTR_LOBPREFETCH_SIZE

モード

READ/WRITE

説明

特定の列からフェッチするLOBロケータのデフォルト・キャッシュ・バッファ・サイズを上書きします。

属性のデータ型

ub4 */ub4

OCI_ATTR_MAXCHAR_SIZE

モード

WRITE

説明

クライアント・アプリケーションが定義バッファに格納できる最大文字数を指定します。

関連項目:
「OCI_ATTR_MAXCHAR_SIZE属性の使用」

属性のデータ型

sb4 *

OCI_ATTR_PDPRC

モード

WRITE

説明

パック10進数の精度を指定します。SQLT_PDN値の場合、精度は2*(value_sz-1)に等しくしてください。SQLT_SLS値の場合、精度は(value_sz-1)に等しくしてください。

バインドまたは定義後に、この値は0 (ゼロ)に初期化されます。最初にOCI_ATTR_PDPRC属性を設定して、次にOCI_ATTR_PDSCLを設定します。これらの値のどちらかを変更する必要がある場合は、最初に再バインドまたは再定義の操作を実行して、次にこれらの属性を適切に再設定する必要があります。

属性のデータ型

ub2 *

OCI_ATTR_PDSCL

モード

WRITE

説明

パック10進値のスケールを指定します。

バインドまたは定義後に、この値は0 (ゼロ)に初期化されます。最初にOCI_ATTR_PDPRC属性を設定して、次にOCI_ATTR_PDSCLを設定します。これらの値のどちらかを変更する必要がある場合は、最初に再バインドまたは再定義の操作を実行して、次にこれらの属性を適切に再設定する必要があります。

属性のデータ型

sb2 *

記述ハンドル属性

記述ハンドルには、次の属性を使用します。

OCI_ATTR_PARAM

モード

READ

説明

記述のルートを指し示します。後続のOCIAttrGet()およびOCIParamGet()コールのために使用します。

属性のデータ型

ub4 *

OCI_ATTR_PARAM_COUNT

モード

READ

説明

記述ハンドル内のパラメータ数を戻します。記述ハンドルが選択リストの記述である場合は、選択リスト内の列数を示します。

属性のデータ型

ub4 *

パラメータ記述子属性

パラメータ記述子には、次の属性を使用します。

パラメータ記述子の属性の詳細なリストは、第6章を参照してください。

LOBロケータ属性

パラメータ記述子には、次の属性を使用します。

OCI_ATTR_LOBEMPTY

モード

WRITE

説明

内部LOBロケータをEmpty値に設定します。これによって、そのロケータはINSERT文またはUPDATE文のバインド変数として使用でき、LOBをEmpty値に初期化できます。LOBがEmpty値になると、OCILobWrite2()またはOCILobWrite() (非推奨)をコールして、データをLOBに移入できます。この属性は内部LOB (BLOB、CLOB、NCLOB)に対してのみ有効です。

アプリケーションから、次の宣言などの0 (ゼロ)の値を持つub4のアドレスを渡します。

ub4 lobEmpty = 0

その後にアドレス&lobEmptyを渡します。

属性のデータ型

ub4 *

複合オブジェクト属性

複合オブジェクトには、次の属性を使用します。

関連項目:
「複合オブジェクト検索」

複合オブジェクト検索ハンドル属性

複合オブジェクト検索ハンドルには、次の属性を使用します。

OCI_ATTR_COMPLEXOBJECT_LEVEL

モード

WRITE

説明

複合オブジェクト検索のネスト・レベルです。

属性のデータ型

ub4 *

OCI_ATTR_COMPLEXOBJECT_COLL_OUTOFLINE

モード

WRITE

説明

オブジェクト型アウト・ラインにあるコレクション属性をフェッチするかどうかを示します。

属性のデータ型

ub1 *

複合オブジェクト検索記述子の属性

複合オブジェクト検索記述子には、次の属性を使用します。

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE

モード

WRITE

説明

複合オブジェクト検索に続くREFのタイプです。

属性のデータ型

void *

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE_LEVEL

モード

WRITE

説明

後に続くOCI_ATTR_COMPLEXOBJECTCOMP_TYPE型のREFのネスト・レベルです。

属性のデータ型

ub4 *

Streamsアドバンスト・キューイング記述子の属性

Streamsアドバンスト・キューイング記述子には、次の属性を使用します。

関連項目:
『Oracle Streamsアドバンスト・キューイング・ユーザーズ・ガイドおよびリファレンス』

OCIAQEnqOptions記述子の属性

次に示す属性は、OCIAQEnqOptions記述子のプロパティです。

OCI_ATTR_MSG_DELIVERY_MODE

モード

WRITE

説明

エンキュー・コールがキュー内に永続メッセージまたはバッファ・メッセージをエンキューできるようにするには、OCIAQEnqOptions記述子のOCI_ATTR_MSG_DELIVERY_MODE属性をそれぞれOCI_MSG_PERSISTENTまたはOCI_MSG_BUFFEREDに設定します。この属性のデフォルト値はOCI_MSG_PERSISTENTです。

属性のデータ型

ub2

OCI_ATTR_RELATIVE_MSGID

モード

READ/WRITE

説明

この機能は非推奨です。今後のリリースでは削除される可能性があります。

順序逸脱操作で参照されるメッセージのメッセージ識別子を指定します。この値は、OCI_ATTR_SEQUENCE_DIVISIONでOCI_ENQ_BEFOREが指定されている場合にのみ有効です。順序逸脱が未指定の場合には、この値は無視されます。

属性のデータ型

OCIRaw *

OCI_ATTR_SEQUENCE_DEVIATION

モード

READ/WRITE

説明

この機能は新しいアプリケーションでは非推奨ですが、互換性のため保持されています。

現在エンキューされているメッセージを、キューにあるその他のメッセージより先にデキューするかどうかを指定します。

属性のデータ型

ub4

有効な値

次に示す値のみ有効です。

- OCI_ENQ_BEFORE - メッセージは、OCI_ATTR_RELATIVE_MSGIDで指定したメッセージより先にエンキューされます。

- OCI_ENQ_TOP - メッセージは、その他のあらゆるメッセージより先にエンキューされます。

OCI_ATTR_TRANSFORMATION

モード

READ/WRITE

説明

メッセージがデータベースにエンキューされる前に適用する必要がある変換の名前です。変換はDBMS_TRANSFORMを使用して作成する必要があります。

属性のデータ型

oratext *

OCI_ATTR_VISIBILITY

モード

READ/WRITE

説明

エンキュー要求のトランザクション動作を指定します。

属性のデータ型

ub4

有効な値

次に示す値のみ有効です。

- OCI_ENQ_ON_COMMIT - エンキューはカレント・トランザクションの一部です。操作は、トランザクションがコミットするときに完了します。これは、デフォルトです。

- OCI_ENQ_IMMEDIATE - エンキューはカレント・トランザクションの一部ではありません。固有のトランザクションで操作が行われます。

OCIAQDeqOptions記述子の属性

次に示す属性は、OCIAQDeqOptions記述子のプロパティです。

OCI_ATTR_CONSUMER_NAME

モード

READ/WRITE

説明

コンシューマ名です。コンシューマ名に一致するメッセージのみがアクセスされます。キューが複数のコンシューマに対して設定されていない場合、このフィールドはNULLに設定します。

属性のデータ型

oratext *

OCI_ATTR_CORRELATION

モード

READ/WRITE

説明

デキューするメッセージの相関識別子を指定します。パーセント符号(%)やアンダースコア(_)などの特殊なパターン・マッチング文字を使用できます。複数のメッセージがパターンに一致する場合、デキューの順序は確定されません。

属性のデータ型

oratext *

OCI_ATTR_DEQ_MODE

モード

READ/WRITE

説明

デキューに対応付けられたロック動作を指定します。

属性のデータ型

ub4

有効な値

次に示す値のみ有効です。

- OCI_DEQ_BROWSE - ロックを取得することなくメッセージを読み取ります。これは、SELECT文と同じです。

- OCI_DEQ_LOCKED - メッセージを読み取り、書込みロックを取得します。ロックは、トランザクションの継続時間中は有効です。これは、SELECT FOR UPDATE文と同じです。

- OCI_DEQ_REMOVE - メッセージを読み取り、それを更新または削除します。これは、デフォルトです。メッセージは、保存プロパティに基づいてキュー・テーブルに保存されます。

- OCI_DEQ_REMOVE_NODATA - メッセージの受取りを確認しますが、実際のメッセージ内容は送付しません。

OCI_ATTR_DEQ_MSGID

モード

READ/WRITE

説明

デキューするメッセージのメッセージ識別子を指定します。

属性のデータ型

OCIRaw *

OCI_ATTR_DEQCOND

モード

READ/WRITE

説明

この属性は、SQL問合せのWHERE句に類似したブール式です。このブール式には、メッセージ・プロパティの条件、ユーザー・データ・プロパティ(オブジェクト・ペイロードのみ)およびPL/SQLまたはSQL関数を含めることができます。

メッセージ・ペイロード(オブジェクト・ペイロード)のデキュー条件を指定するには、句にオブジェクト型の属性を使用します。ペイロードが格納されたキュー・テーブルの特定の列を指定するには、各属性の前に修飾子としてtab.user_dataを追加する必要があります。

属性は4000文字を超えないようにします。複数のメッセージがデキュー条件を満たす場合、デキューの順序は不確定であり、キューのソート順序は適用されません。

属性のデータ型

oratext *

例

checkerr(errhp, OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS,
(dvoid *)"tab.priority between 2 and 4" ,
strlen("tab.priority between 2 and 4"),
OCI_ATTR_DEQCOND, errhp));

OCI_ATTR_MSG_DELIVERY_MODE

モード

WRITE

説明

キューから永続メッセージ、バッファ・メッセージまたはこの両方のメッセージをデキューするためのデキュー・コールを指定するには、OCIAQDeqOptions記述子のOCI_ATTR_MSG_DELIVERY_MODE属性を、それぞれOCI_MSG_PERSISTENT、OCI_MSG_BUFFEREDまたはOCI_MSG_PERSISTENT_OR_BUFFEREDに設定します。この属性のデフォルト値はOCI_MSG_PERSISTENTです。

属性のデータ型

ub2

OCI_ATTR_NAVIGATION

モード

READ/WRITE

説明

取り出すメッセージの位置を指定します。最初に位置が判断されます。次に検索基準が適用されます。最後にメッセージが取り出されます。

属性のデータ型

ub4

有効な値

次に示す値のみ有効です。

- OCI_DEQ_FIRST_MSG - 検索基準に一致する最初の使用可能なメッセージを取り出します。これにより、位置はキューの先頭にリセットされます。

- OCI_DEQ_NEXT_MSG - 検索基準に一致する次の使用可能なメッセージを取り出します。前のメッセージがメッセージ・グループに属していた場合は、検索基準に一致し、なおかつメッセージ・グループに属する、次に使用可能なメッセージがAQにより取り出されます。これは、デフォルトです。

- OCI_DEQ_NEXT_TRANSACTION - 残りのカレント・トランザクション・グループ(ある場合)をスキップし、次のトランザクション・グループから最初のメッセージを取り出します。このオプションは、現行のキューに対してメッセージをグループ化できる場合のみ使用できます。

- OCI_DEQ_FIRST_MSG_MULTI_GROUP - OCIAQDeqArray()のコールによって位置がキューの先頭にリセットされ、選択可能でかつ検索条件に一致するメッセージが(場合により複数のトランザクション・グループから) itersに達するまでデキューされます。トランザクション・グループを識別するために、新しいメッセージ・プロパティOCI_ATTR_TRANSACTION_NOが定義されます。同じトランザクション・グループに属するメッセージはすべて、このメッセージ・プロパティに対し同一の値を持ちます。

- OCI_DEQ_NEXT_MSG_MULTI_GROUP - OCIAQDeqArray()のコールによって、選択可能でかつ検索条件に一致する次のセットのメッセージが(場合により複数のトランザクション・グループから) itersに達するまでデキューされます。トランザクション・グループを識別するために、新しいメッセージ・プロパティOCI_ATTR_TRANSACTION_NOが定義されます。同じトランザクション・グループに属するメッセージはすべて、このメッセージ・プロパティに対し同一の値を持ちます。

OCI_ATTR_TRANSFORMATION

モード

READ/WRITE

説明

メッセージのデキュー後、ただしデキューするアプリケーションにメッセージを戻す前に適用することが必要な、変換の名前です。変換はDBMS_TRANSFORMを使用して作成する必要があります。

属性のデータ型

oratext *

OCI_ATTR_VISIBILITY

モード

READ/WRITE

説明

新しいメッセージをカレント・トランザクションの一部としてデキューするかどうかを指定します。BROWSEモードを使用しているときは、この可視性(visibility)パラメータは無視されます。

属性のデータ型

ub4

有効な値

次に示す値のみ有効です。

- OCI_DEQ_ON_COMMIT - デキューはカレント・トランザクションの一部になります。これは、デフォルトです。

- OCI_DEQ_IMMEDIATE - デキューされたメッセージはカレント・トランザクションの一部にはなりません。固有のトランザクションが構成されます。

OCI_ATTR_WAIT

モード

READ/WRITE

説明

検索基準に一致するメッセージがないときの待機時間を指定します。同じグループのメッセージがデキューされている場合、このパラメータは無視されます。

属性のデータ型

ub4

有効な値

ub4値はいずれも有効ですが、さらに次のような定数が事前定義されています。

- OCI_DEQ_WAIT_FOREVER - いつまでも待機します。これは、デフォルトです。

- OCI_DEQ_NO_WAIT - 待機しません。

注意:
OCI_DEQ_NO_WAITオプションを使用してキューのポーリングを行う場合、空のキューをポーリングするとメッセージはデキューされません。OCI_ATTR_NAVIGATIONのデフォルト設定OCI_DEQ_NEXT_MSGのかわりに、OCI_DEQ_FIRST_MSGオプションを使用します。また、デキューにはOCI_ATTR_WAITの0 (ゼロ)以外の待機設定(1を推奨)も使用できます。

OCIAQMsgProperties記述子の属性

次に示す属性は、OCIAQMsgProperties記述子のプロパティです。

OCI_ATTR_ATTEMPTS

モード

READ

説明

あるメッセージに対して今までに何回デキューが試みられたかを指定します。このパラメータを、エンキュー時刻に設定することはできません。

属性のデータ型

sb4

有効な値

sb4値はいずれも有効です。

OCI_ATTR_CORRELATION

モード

READ/WRITE

説明

エンキュー時にプロデューサがメッセージに付けたIDを指定します。

属性のデータ型

oratext *

有効な値

文字列は128バイトまで有効です。

OCI_ATTR_DELAY

モード

READ/WRITE

説明

エンキューしたメッセージを遅延させる秒数を指定します。遅延はメッセージがデキュー可能になった後の秒数を示します。メッセージID (msgid)によりデキューすると、遅延指定は上書きされます。遅延を設定すると、エンキューされたメッセージはWAITING状態となり、遅延時間が終了するとともにREADY状態となります。DELAY処理にはキュー・モニターを起動させる必要があります。遅延は、メッセージをエンキューするプロデューサが設定することに注意してください。

属性のデータ型

sb4

有効な値

すべてのsb4値が有効ですが、さらに次のような定数が事前定義されています。

OCI_MSG_NO_DELAY - メッセージが即時にデキューできることを示します。
OCI_ATTR_ENQ_TIME

モード

READ

説明

メッセージがエンキューされた時間を指定します。この値はシステムにより判断されるため、ユーザーは設定できません。

属性のデータ型

OCIDate

OCI_ATTR_EXCEPTION_QUEUE

モード

READ/WRITE

説明

正常に処理できないメッセージの移動先となるキューの名前を指定します。メッセージが移動されるのは、デキューがmax_retries以内の回数で成功しなかった場合とメッセージの有効期限が切れた場合です。例外キューのメッセージはすべてEXPIRED状態です。

デフォルトは、キュー・テーブルと対応付けられた例外キューです。移動時に指定の例外キューが存在しない場合、メッセージはキュー・テーブルと対応付けられたデフォルトの例外キューに移動し、警告がアラート・ファイルにログ記録されます。デフォルトの例外キューが使用されている場合は、デキュー時にNULL値が戻されます。

この属性は有効なキュー名を参照する必要があります。

属性のデータ型

oratext *

OCI_ATTR_EXPIRATION

モード

READ/WRITE

説明

メッセージの期限切れを指定します。デキューにおいてメッセージを使用可能にする時間(秒)を決定します。このパラメータは、遅延からのオフセットです。期限切れ処理にはキュー・モニターを起動させる必要があります。

期限切れ前のメッセージはREADY状態です。期限切れ前にデキューされないメッセージは、EXPIRED状態となって例外デキューに移動します。

属性のデータ型

sb4

有効な値

すべてのsb4値が有効ですが、さらに次のような定数が事前定義されています。

OCI_MSG_NO_EXPIRATION - メッセージは期限切れになりません。
OCI_ATTR_MSG_DELIVERY_MODE

モード

READ

説明

デキュー・コールの後、OCIクライアントはOCIAQMsgProperties記述子のOCI_ATTR_MSG_DELIVERY_MODE属性を読み取り、永続メッセージまたはバッファ・メッセージがデキューされたかどうかを判断できます。属性の値は、永続メッセージの場合はOCI_MSG_PERSISTENT、バッファ・メッセージの場合はOCI_MSG_BUFFEREDです。

属性のデータ型

ub2

OCI_ATTR_MSG_STATE

モード

READ

説明

デキュー時のメッセージの状態を指定します。このパラメータを、エンキュー時刻に設定することはできません。

属性のデータ型

ub4

有効な値

次の値のみが戻されます。

- OCI_MSG_WAITING - メッセージの遅延時間がまだ経過していません。

- OCI_MSG_READY - メッセージは処理できる状態にあります。

- OCI_MSG_PROCESSED - メッセージは処理され、保存されています。

- OCI_MSG_EXPIRED - メッセージは例外キューに移動しました。

OCI_ATTR_ORIGINAL_MSGID

モード

READ/WRITE

説明

そのメッセージを生成した最後のキューのメッセージのIDです。メッセージがあるキューから別のキューに伝播される際に、この属性はメッセージの最後の伝播元であるキューのIDを識別します。メッセージが複数のキューを経由して伝播されている場合、この属性は、このメッセージを生成した最初のキューではなく最後のキューのメッセージのIDを識別します。

属性のデータ型

OCIRaw *

OCI_ATTR_PRIORITY

モード

READ/WRITE

説明

メッセージの優先度を指定します。数値が小さいほど高い優先度を示します。優先度は、負数も含めたあらゆる数値で指定できます。

デフォルト値は0 (ゼロ)です。

属性のデータ型

sb4

OCI_ATTR_RECIPIENT_LIST

モード

WRITE

説明

このパラメータは、複数のコンシューマが可能なキューに対してのみ有効です。デフォルトの受信者はキューのサブスクライバです。このパラメータはデキュー時にコンシューマに戻されません。

属性のデータ型

OCIAQAgent **

OCI_ATTR_SENDER_ID

モード

READ/WRITE

説明

メッセージの最初の送信者を識別します。

属性のデータ型

OCIAgent *

OCI_ATTR_TRANSACTION_NO

モード

READ

説明

トランザクションごとにグループ化されたキューの場合、メッセージのトランザクション・グループを識別します。この属性は、OCIAQDeqArray()コールが成功した後に移入されます。1つのグループ内のすべてのメッセージがこの属性に同一の値を持ちます。この属性は、エンキューされたメッセージのトランザクション・グループを設定するためにOCIAQEnqArray()コールによって使用することはできません。

属性のデータ型

oratext *

OCIAQAgent記述子の属性

次に示す属性は、OCIAQAgent記述子のプロパティです。

OCI_ATTR_AGENT_ADDRESS

モード

READ/WRITE

説明

プロトコル特定の受信者アドレスです。プロトコルが0 (デフォルト)の場合、アドレスのフォームは[schema.]queue[@dblink]です。

属性のデータ型

oratext *

有効な値

128バイト以下の任意の文字列を指定できます。

OCI_ATTR_AGENT_NAME

モード

READ/WRITE

説明

メッセージのプロデューサ名またはコンシューマ名です。

属性のデータ型

oratext *

有効な値

30バイト以下の任意のOracle Database識別子を指定できます。

OCI_ATTR_AGENT_PROTOCOL

モード

READ/WRITE

説明

アドレスを解釈しメッセージを伝播させるプロトコルです。デフォルト値(現在はこの値のみサポートされています)は0 (ゼロ)です。

属性のデータ型

ub1

有効な値

有効な値は0 (ゼロ)のみです。これはデフォルトでもあります。

OCIServerDNs記述子の属性

次に示す属性は、OCIServerDNs記述子のプロパティです。

OCI_ATTR_DN_COUNT

モード

READ

説明

記述子に挿入されたデータベース・サーバーの数です。

属性のデータ型

ub2

OCI_ATTR_SERVER_DN

モード

READ/WRITE

説明

読取りモードの場合、この属性は、記述子にすでに挿入されているOracle Databaseの識別名のリストを戻します。

書込みモードの場合、この属性は、Oracle Databaseの識別名を取得します。

属性のデータ型

oratext **/oratext *

サブスクリプション・ハンドル属性

サブスクリプション・ハンドルには、次の属性を使用します。

関連項目:

- 「OCIでのパブリッシュ・サブスクライブの通知」

- 「連続問合せ通知」

OCI_ATTR_SERVER_DNS

モード

READ/WRITE

説明

クライアントが登録用に使用するOracle Databaseの識別名です。

属性のデータ型

OCIServerDNs *

OCI_ATTR_SUBSCR_CALLBACK

モード

READ/WRITE

説明

サブスクリプション・コールバックです。属性OCI_ATTR_SUBSCR_RECPTPROTOがOCI_SUBSCR_PROTO_OCIに設定されているか、または値が設定されていない場合、この属性は、サブスクリプション・ハンドルが登録コールOCISubscriptionRegister()に渡される前に設定する必要があります。

属性のデータ型

ub4 (void *, OCISubscription *, void *, ub4, void *, ub4)

OCI_ATTR_SUBSCR_CQ_QOSFLAGS

モード

WRITE

説明

連続問合せ(CQ)通知に固有のQOS(サービス品質フラグ)を設定します。渡すことができる可能な値については、「連続問合せ通知のサブスクリプション・ハンドル属性」を参照してください。

属性のデータ型

ub4 *

OCI_ATTR_SUBSCR_CTX

モード

READ/WRITE

説明

システムによって呼び出された際に、クライアントからOCI_ATTR_SUBSCR_CALLBACKが示すユーザー・コールバックに渡されるコンテキストです。属性OCI_ATTR_SUBSCR_RECPTPROTOがOCI_SUBSCR_PROTO_OCIに設定されているか、または値が設定されていない場合、この属性は、サブスクリプション・ハンドルが登録コールOCI Subscription Register()に渡される前に設定する必要があります。

属性のデータ型

void *

OCI_ATTR_SUBSCR_HOSTADDR

モード

READ/WRITE

説明

OCISubscriptionRegister()を使用して通知を登録する前に、通知の送信先であるOCI通知クライアントのリスニング・エンドポイントのクライアントIP (IPv4またはIPv6書式)を指定します。IPv4アドレスをドット付き10進数書式(192.0.2.34など)で入力するか、IPv6アドレスを16進数書式(2001:0db8:0000:0000:0217:f2ff:fe4b:4cedなど)で入力します。

関連項目:
IPアドレス用のIPv6書式の詳細は、『Oracle Database Net Services管理者ガイド』を参照してください。

属性のデータ型

text *

例

/* Set notification client address*/
text ipaddr[16] = "192.0.2.34";
(void) OCIAttrSet((dvoid *) envhp, (ub4) OCI_HTYPE_ENV,
(dvoid *) ipaddr, (ub4) strlen(ipaddr),
(ub4) OCI_ATTR_SUBSCR_HOSTADDR, errhp);

OCI_ATTR_SUBSCR_IPADDR

モード

READ/WRITE

説明

通知を受信するために、OCIクライアントが通知のリスニング用に登録したクライアントのIPアドレス(IPv4またはIPv6)です。たとえば、ドット付き10進数書式(192.1.2.34など)でのIPv4アドレスや、16進数書式(2001:0db8:0000:0000:0217:f2ff:fe4b:4cedなど)でのIPv6アドレスなどです。

関連項目:
IPアドレス用のIPv6書式の詳細は、『Oracle Database Net Services管理者ガイド』を参照してください。

属性のデータ型

oratext *

OCI_ATTR_SUBSCR_NAME

モード

READ/WRITE

説明

サブスクリプション名です。すべてのサブスクリプションは、サブスクリプション名によって識別されます。サブスクリプション名は、指定された長さの一連のバイト数から構成されます。サブスクリプション名のバイト長は、この名前がNULLで終了しないことを前提として指定する必要があります。名前にマルチバイト・キャラクタが含まれる可能性があるため、この前提は重要です。

クライアントでは、OCIAttrSet()コールを使用して、OCI_HTYPE_SUBSCRのハンドル・タイプとOCI_ATTR_SUBSCR_NAMEの属性タイプを指定することによりサブスクリプション・ハンドルのサブスクリプション名属性を設定できます。

すべてのサブスクリプション・コールバックには、OCI_ATTR_SUBSCR_NAME属性およびOCI_ATTR_SUBSCR_NAMESPACE属性が設定されたサブスクリプション・ハンドルが必要です。これらの属性が設定されていない場合は、エラーが戻されます。サブスクリプション・ハンドルに設定されるサブスクリプション名は、そのネームスペースと一貫性を持たせる必要があります。

属性のデータ型

oratext *

OCI_ATTR_SUBSCR_NAMESPACE

モード

READ/WRITE

説明

サブスクリプション・ハンドルが使用されるネームスペースです。この属性の有効な値は、OCI_SUBSCR_NAMESPACE_AQ、OCI_SUBSCR_NAMESPACE_DBCHANGEおよびOCI_SUBSCR_NAMESPACE_ANONYMOUSです。

サブスクリプション・ハンドルに設定されるサブスクリプション名は、そのネームスペースと一貫性を持たせる必要があります。

属性のデータ型

ub4 *

注意:
OCI_OBJECTモードは通知のグループ化を使用する際に必須です。

OCI_ATTR_SUBSCR_NTFN_GROUPING_CLASS

モード

READ/WRITE

説明

通知グループ化クラスです。デフォルトの0(ゼロ)に設定した場合、他の通知グループ化属性はすべて0(ゼロ)である必要があります。最新のリリースで時間について実装されており、現行の唯一のグループ化基準です。OCI_SUBSCR_NTFN_GROUPING_CLASS_TIMEに設定できます。

属性のデータ型

ub1 *

OCI_ATTR_SUBSCR_NTFN_GROUPING_REPEAT_COUNT

モード

READ/WRITE

説明

グループ化を実行する回数です。通知の繰返し回数です。正の整数で指定します。グループ化通知を永続的に送信するには、OCI_NTFN_GROUPING_FOREVERに設定します。

属性のデータ型

sb4 *

OCI_ATTR_SUBSCR_NTFN_GROUPING_START_TIME

モード

READ/WRITE

説明

グループ化の開始時間です。有効なTIMESTAMP WITH TIME ZONEに設定します。デフォルトは現行のTIMESTAMP WITH TIME ZONEです。

属性のデータ型

OCIDateTime */OCIDateTime **

OCI_ATTR_SUBSCR_NTFN_GROUPING_TYPE

モード

READ/WRITE

説明

通知グループ化のフォーマットです。グループ内のすべてのイベントのサマリーまたはグループ内の最後のイベントのみのいずれかです。OCIAttrSet()を使用して、通知グループ化型OCI_SUBSCR_NTFN_TYPE_SUMMARYまたはOCI_SUBSCR_NTFN_TYPE_LASTのいずれかに設定します。デフォルトは通知のサマリーです。もう1つは最後の通知です。

属性のデータ型

ub1 *

OCI_ATTR_SUBSCR_NTFN_GROUPING_VALUE

モード

READ/WRITE

説明

グループ化クラスの値を指定します。時間については、この値は秒単位で指定したグループ化通知の期間です。つまり、この期間の後、OCI_ATTR_SUBSCR_NTFN_GROUPING_REPEAT_COUNTに到達するまでグループ化通知が定期的に送信されます。

属性のデータ型

ub4 *

OCI_ATTR_SUBSCR_PAYLOAD

モード

READ/WRITE

説明

通知とともに送信する必要があるペイロードに対応するバッファです。バッファ長も同じ属性設定コールに指定できます。サブスクリプションで転送を実行するには、この属性を設定する必要があります。現行リリースでは、タイプ化されていない(ub1 *)ペイロードのみをサポートします。

属性のデータ型

ub1 *

OCI_ATTR_SUBSCR_PORTNO

モード

READ/WRITE

説明

通知を受信するためのクライアント・ポートです。クライアントの環境ハンドルで設定されます。

属性のデータ型

ub4 *

OCI_ATTR_SUBSCR_QOSFLAGS

モード

READ/WRITE

説明

サーバーのサービス・レベル品質です。可能な設定は、次のとおりです。

- OCI_SUBSCR_QOS_RELIABLE－ 信頼性。データベースに障害が発生しても、通知は行われます。非永続キューやバッファ・メッセージに対してはサポートされません。

- OCI_SUBSCR_QOS_PURGE_ON_NTFN－ 受信後、通知を削除し、サブスクリプションも削除します。

- OCI_SUBSCR_QOS_PAYLOAD－ ペイロード通知。

属性のデータ型

ub4 *

OCI_ATTR_SUBSCR_RECPT

モード

READ/WRITE

説明

属性OCI_ATTR_SUBSCR_RECPTPROTOがOCI_SUBSCR_PROTO_MAIL、OCI_SUBSCR_PROTO_HTTPまたはOCI_SUBSCR_PROTO_SERVERに設定されているときの通知の受信者名です。

OCI_SUBSCR_PROTO_HTTPの場合は、OCI_ATTR_SUBSCR_RECPTによって、通知の送信先HTTP URL (http://www.oracle.com:80など)が示されます。データベースでHTTP URLの妥当性がチェックされることはありません。

OCI_SUBSCR_PROTO_MAILの場合は、OCI_ATTR_SUBSCR_RECPTによって、通知の送信先の電子メール・アドレス(xyz@oracle.comなど)が示されます。データベース・システムで電子メール・アドレスの妥当性がチェックされることはありません。

OCI_SUBSCR_PROTO_SERVERの場合、OCI_ATTR_SUBSCR_RECPTは、通知がある場合に呼び出されるデータベース・プロシージャ(schema.procedureなど)を示します。サブスクライバには、実行するプロシージャに対する適切な権限が必要です。

関連項目:
プロシージャ定義については、「通知プロシージャ」を参照してください。

属性のデータ型

oratext *

OCI_ATTR_SUBSCR_RECPTPRES

モード

READ/WRITE

説明

クライアントが通知を受信するための表現です。有効な値は、OCI_SUBSCR_PRES_DEFAULTおよびOCI_SUBSCR_PRES_XMLです。

設定しない場合、この属性は、OCI_SUBSCR_PRES_DEFAULTにデフォルト設定されます。

XML表示のイベント通知の場合、この属性をOCI_SUBSCR_PRES_XMLに設定します。それ以外の場合は、属性を設定しないままにするか、OCI_SUBSCR_PRES_DEFAULTに設定します。

属性のデータ型

ub4

OCI_ATTR_SUBSCR_RECPTPROTO

モード

READ/WRITE

説明

クライアントが通知を受信するためのプロトコルです。有効な値は次のとおりです。

- OCI_SUBSCR_PROTO_OCI

- OCI_SUBSCR_PROTO_MAIL

- OCI_SUBSCR_PROTO_SERVER

- OCI_SUBSCR_PROTO_HTTP

OCIクライアントでイベント通知を受信する場合は、OCI_SUBSCR_PROTO_OCIに設定します。

電子メールをイベント通知で送信する場合は、OCI_SUBSCR_PROTO_MAILに設定します。イベント通知によってPL/SQLプロシージャをデータベースで呼び出す場合は、OCI_SUBSCR_PROTO_SERVERに設定します。HTTP URLをイベント通知に送信する場合は、OCI_SUBSCR_PROTO_HTTPに設定します。

設定しない場合、この属性は、OCI_SUBSCR_PROTO_OCIにデフォルト設定されます。

OCI_SUBSCR_PROTO_OCIの場合は、サブスクリプション・ハンドルを登録コールOCISubscriptionRegister()に渡す前に、OCI_ATTR_SUBSCR_CALLBACK属性とOCI_ATTR_SUBSCR_CTX属性を設定しておく必要があります。

OCI_SUBSCR_PROTO_MAIL、OCI_SUBSCR_PROTO_SERVERおよびOCI_SUBSCR_PROTO_HTTPの場合は、サブスクリプション・ハンドルを登録コールOCISubscriptionRegister()に渡す前に、OCI_ATTR_SUBSCR_RECPT属性を設定しておく必要があります。

属性のデータ型

ub4 *

OCI_ATTR_SUBSCR_TIMEOUT

モード

READ/WRITE

説明

登録タイムアウトの時間隔(秒)です。0 (ゼロ)または未指定の場合、登録はサブスクリプションが明示的に登録解除されるまで有効です。

属性のデータ型

ub4 *

連続問合せ通知属性

次の属性は、連続問合せ通知に使用されます。

OCI_ATTR_CHNF_CHANGELAG

モード

WRITE

説明

このトランザクション数ごとに連続問合せ通知がクライアントから行われます。

属性のデータ型

ub4 *

OCI_ATTR_CHNF_OPERATIONS

モード

WRITE

説明

操作タイプに基づいて通知をフィルタするために使用します。

属性のデータ型

ub4 *

関連項目:
フラグ値の詳細は、「連続問合せ通知」を参照してください。

OCI_ATTR_CHNF_ROWIDS

モード

WRITE

説明

TRUEの場合、連続問合せ通知メッセージには、操作タイプやROWIDなどの行レベルの詳細が含まれます。デフォルトはFALSEです。

属性のデータ型

boolean *

OCI_ATTR_CHNF_TABLENAMES

モード

READ

説明

登録された表名のリストを取り出すための属性です。これらの属性は、問合せの実行後にサブスクリプション・ハンドルから使用できます。

属性のデータ型

OCIColl **

連続問合せ通知の記述子の属性

次の属性は、連続問合せ通知の記述子に使用されます。

OCI_ATTR_CHDES_DBNAME

モード

READ

説明

データベース名です。

属性のデータ型

oratext **

OCI_ATTR_CHDES_NFTYPE

モード

READ

説明

通知タイプを記述するフラグです。

属性のデータ型

ub4 *

関連項目:
フラグ値の詳細は、「連続問合せ通知」を参照してください。

OCI_ATTR_CHDES_ROW_OPFLAGS

モード

READ

説明

操作タイプ(INSERT、UPDATE、DELETEまたはOTHER)です。

属性のデータ型

ub4 *

OCI_ATTR_CHDES_ROW_ROWID

モード

READ

説明

ROWIDの文字列表現です。

属性のデータ型

oratext **

OCI_ATTR_CHDES_TABLE_CHANGES

モード

READ

説明

表の操作を記述するコレクション型です。コレクションの各要素は、OCI_ATTR_CHDES_TABLEから始まる属性を持つOCI_DTYPE_TABLE_CHDES型の表連続問合せ記述子(OCITableChangeDesc *)です。次のエントリを参照してください。

属性のデータ型

OCIColl **

OCI_ATTR_CHDES_TABLE_NAME

モード

READ

説明

スキーマおよび表名です。たとえば、HR.EMPLOYEESです。

属性のデータ型

oratext **

OCI_ATTR_CHDES_TABLE_OPFLAGS

モード

READ

説明

表の操作を記述するフラグです。

属性のデータ型

ub4 *

関連項目:
フラグ値は、「OCI_DTYPE_TABLE_CHDES」を参照してください。

OCI_ATTR_CHDES_TABLE_ROW_CHANGES

モード

READ

説明

表の行への変更を記述する埋込みコレクションです。コレクションの各要素は、OCI_ATTR_CHDES_ROW_OPFLAGSおよびOCI_ATTR_CHDES_ROW_ROWID属性を持つOCI_DTYPE_ROW_CHDES型の行連続問合せ記述子(OCIRowChangeDesc *)です。

属性のデータ型

OCIColl **

通知の記述子の属性

次に、記述子OCI_DTYPE_AQNFYの属性を示します。

OCI_ATTR_AQ_NTFN_GROUPING_COUNT

モード

READ

説明

AQネームスペース用です。グループ内の受信した通知数です。

属性のデータ型

ub4 *

OCI_ATTR_AQ_NTFN_GROUPING_ MSGID_ARRAY

モード

READ

説明

AQネームスペース用です。この場合のグループは、メッセージIDのOCIコレクションです。

属性のデータ型

OCIColl **

OCI_ATTR_CONSUMER_NAME

モード

READ

説明

通知のコンシューマ名です。

属性のデータ型

oratext *

OCI_ATTR_MSG_PROP

モード

READ

説明

メッセージ・プロパティです。

属性のデータ型

OCIAQMsgProperties **

OCI_ATTR_NFY_FLAGS

モード

READ

説明

0=通常、1=タイムアウト通知、2=グループ化通知となります。

属性のデータ型

ub4 *

OCI_ATTR_NFY_MSGID

モード

READ

説明

メッセージIDです。

属性のデータ型

OCIRaw *

OCI_ATTR_QUEUE_NAME

モード

READ

説明

通知のキュー名です。

属性のデータ型

oratext *

無効化された問合せの属性

この項では、OCI_DTYPE_CQDESの属性について説明します。詳細は、「OCI_DTYPE_CQDES」を参照してください。

OCI_ATTR_CQDES_OPERATION

モード

READ

説明

問合せ時に発生した操作です。値OCI_EVENT_QUERYCHANGE(問合せ結果セットの変更)またはOCI_EVENT_DEREG(問合せ登録解除)のいずれかを使用できます。

属性のデータ型

ub4 *

OCI_ATTR_CQDES_QUERYID

モード

READ

説明

無効化された問合せの問合せIDです。

属性のデータ型

ub8 *

OCI_ATTR_CQDES_TABLE_CHANGES

モード

READ

説明

問合せ結果セットの変更原因となった表に対するDMLまたはDDL操作を記述する、表連続問合せ記述子のコレクションです。コレクションの各要素はOCI_DTYPE_TABLE_CHDES型です。

属性のデータ型

OCIColl *

ダイレクト・パス・ロード・ハンドル属性

次の属性は、ダイレクト・パス・ロード・ハンドルに使用されます。

関連項目:
ダイレクト・パス・ロードおよびダイレクト・パス・ハンドルの割当ての詳細は、「ダイレクト・パス・ロードの概要」および「オブジェクト型のダイレクト・パス・ロード」を参照してください。

ダイレクト・パス・コンテキスト・ハンドル(OCIDirPathCtx)の属性

次の属性は、ダイレクト・パス・コンテキスト・ハンドルに使用されます。

OCI_ATTR_BUF_SIZE

モード

READ/WRITE

説明

ストリーム転送バッファのサイズを設定します。デフォルト値は64KBです。

属性のデータ型

ub4 */ub4 *

OCI_ATTR_CHARSET_ID

モード

READ/WRITE

説明

文字データのデフォルトのキャラクタ・セットIDです。このキャラクタ・セットIDは、列レベルで上書きできることに注意してください。キャラクタ・セットIDが列レベルまたは表レベルで指定されていない場合は、グローバル・サポート環境設定が使用されます。

属性のデータ型

ub2 */ub2 *

OCI_ATTR_DATEFORMAT

モード

READ/WRITE

説明

SQLT_CHRからDTYDATに変換する際の、デフォルトの日付書式文字列です。この日付書式文字列は、列レベルで上書きできることに注意してください。日付書式文字列が列レベルまたは表レベルで指定されていない場合は、グローバル・サポート環境設定が使用されます。

属性のデータ型

oratext **/oratext *

OCI_ATTR_DIRPATH_DCACHE_DISABLE

モード

READ/WRITE

説明

この属性を1に設定すると、サイズを超えた場合に日付キャッシュが使用禁止になります。デフォルト値は0 (ゼロ)です。これは、キャッシュ・オーバーフロー時にキャッシュ内の検索が続行されることを示します。

関連項目:
この属性および次の4つの属性については、「OCIのダイレクト・パス・ロードでの日付キャッシュの使用」を参照してください。

属性のデータ型

ub1 */ub1 *

OCI_ATTR_DIRPATH_DCACHE_HITS

モード

READ

説明

日付キャッシュのヒット数を問い合せます。

属性のデータ型

ub4 *

OCI_ATTR_DIRPATH_DCACHE_MISSES

モード

READ

説明

日付キャッシュに関する現在のミスの数を問い合せます。

属性のデータ型

ub4 *

OCI_ATTR_DIRPATH_DCACHE_NUM

モード

READ

説明

日付キャッシュ内の現在のエントリ数を問い合せます。

属性のデータ型

ub4 *

OCI_ATTR_DIRPATH_DCACHE_SIZE

モード

READ/WRITE

説明

表に日付キャッシュのサイズ(要素数単位)を設定します。日付キャッシュを使用禁止にするには、デフォルト値の0を設定します。

属性のデータ型

ub4 */ub4 *

OCI_ATTR_DIRPATH_INDEX_MAINT_METHOD

モード

READ/WRITE

説明

行単位で索引行の挿入を実行します。

次の値が有効です。

OCI_DIRPATH_INDEX_MAINT_SINGLE_ROW

属性のデータ型

ub1 */ub1 *

OCI_ATTR_DIRPATH_MODE

モード

READ/WRITE

説明

ダイレクト・パス・コンテキストのモードです。

- OCI_DIRPATH_LOAD - ロード操作(デフォルト)

- OCI_DIRPATH_CONVERT - 変換専用操作

属性のデータ型

ub1 */ub1 *

OCI_ATTR_DIRPATH_NO_INDEX_ERRORS

モード

READ/WRITE

説明

OCI_ATTR_DIRPATH_NO_INDEX_ERRORSが1である場合、索引はロード中のどの時点でも使用不可に設定されません。索引エラーが検出された場合、ロードは異常終了します。つまり、行はロードされず、索引はそのままとなります。デフォルトは0 (ゼロ)です。

属性のデータ型

ub1 */ub1 *

OCI_ATTR_DIRPATH_NOLOG

モード

READ/WRITE

説明

各セグメントのNOLOG属性は、イメージREDOと無効化REDOのどちらが生成されるかを次のように判断します。

- 0－ ロードされるセグメントの属性を使用します。

- 1－ ログ記録を行いません。必要に応じてDDL文を上書きします。

属性のデータ型

ub1 */ub1 *

OCI_ATTR_DIRPATH_OBJ_CONSTR

モード

READ/WRITE

説明

次のように、置換可能なオブジェクト表のオブジェクト型を示します。

OraText *obj_type; /* stores an object type name */
OCIAttrSet((void *)dpctx,
(ub4)OCI_HTYPE_DIRPATH_CTX,
(void *) obj_type,
(ub4)strlen((const char *) obj_type),
(ub4)OCI_ATTR_DIRPATH_OBJ_CONSTR, errhp);

属性のデータ型

oratext **/oratext *

OCI_ATTR_DIRPATH_PARALLEL

モード

READ/WRITE

説明

この値を1に設定すると、複数ロード・セッションで、共通のセグメントを同時にロードできます。デフォルトは0 (ゼロ)です(非パラレル)。

属性のデータ型

ub1 */ub1 *

OCI_ATTR_DIRPATH_SKIPINDEX_METHOD

モード

READ/WRITE

説明

使用できない索引の処理方法を示します。

次の値が有効です。

- OCI_DIRPATH_INDEX_MAINT_SKIP_UNUSABLE (使用できない索引をスキップする)

- OCI_DIRPATH_INDEX_MAINT_DONT_SKIP_UNUSABLE (使用できない索引をスキップしない)

- OCI_DIRPATH_INDEX_MAINT_SKIP_ALL (すべての索引メンテナンスをスキップする)

属性のデータ型

ub1 */ub1 *

OCI_ATTR_LIST_COLUMNS

モード

READ

説明

ダイレクト・パス・コンテキストに対応付けられた列リストのパラメータ記述子に、ハンドルを戻します。OCI_ATTR_NUM_COLS属性で列数を設定した後で、列リスト・パラメータ記述子を取り出すことができます。

関連項目:
「列パラメータ属性へのアクセス」

属性のデータ型

OCIParam* *

OCI_ATTR_NAME

モード

READ/WRITE

説明

ロードされる表の名前です。

属性のデータ型

oratext **/oratext *

OCI_ATTR_NUM_COLS

モード

READ/WRITE

説明

表にロードされる列の数です。

属性のデータ型

ub2 */ub2 *

OCI_ATTR_NUM_ROWS

モード

READ/WRITE

説明

読取り時: これまでにロードした行の数です。

書込み時: ダイレクト・パスおよびダイレクト・パス関数の列配列に対して割り当てられた行の数です。

属性のデータ型

ub2 */ub2 *

OCI_ATTR_SCHEMA_NAME

モード

READ/WRITE

説明

ロードされる表が存在するスキーマの名前です。指定しない場合は、デフォルトで、接続ユーザーのスキーマが使用されます。

属性のデータ型

oratext **/oratext *

OCI_ATTR_SUB_NAME

モード

READ/WRITE

説明

ロードされるパーティションまたはサブパーティションの名前です。指定しない場合は、表全体がロードされます。名前は、その表に属する有効なパーティションまたはサブパーティションの名前にする必要があります。

属性のデータ型

oratext **/oratext *

ダイレクト・パス関数のコンテキスト・ハンドル(OCIDirPathFuncCtx)属性

これらの属性の詳細な説明は、「ダイレクト・パス関数コンテキストと属性」を参照してください。

OCI_ATTR_DIRPATH_EXPR_TYPE

モード

READ/WRITE

説明

スカラー列以外の関数コンテキストのOCI_ATTR_NAMEで指定された式の型を示します。

次の値が有効です。

- OCI_DIRPATH_EXPR_OBJ_CONSTR (列オブジェクトのオブジェクト型名)

- OCI_DIRPATH_EXPR_REF_TBLNAME (参照オブジェクトの表名)

- OCI_DIRPATH_EXPR_SQL (列値を導出するためのSQL文字列)

属性のデータ型

ub1 */ub1 *

OCI_ATTR_LIST_COLUMNS

モード

READ

説明

ダイレクト・パス関数コンテキストに対応付けられた列リストのパラメータ記述子に、ハンドルを戻します。列リストのパラメータ記述子は、列数(スカラー列以外の列に対応付けられた属性または引数の数)を設定した後に、OCI_ATTR_NUM_COLS属性を使用して取り出すことができます。

関連項目:
「列パラメータ属性へのアクセス」

属性のデータ型

OCIParam* *

OCI_ATTR_NAME

モード

READ/WRITE

説明

関数コンテキストが列オブジェクトを記述している場合はオブジェクト型名、SQL文字列を記述している場合はSQL関数、REF列を記述している場合は参照表名です。

属性のデータ型

oratext **/oratext *

OCI_ATTR_NUM_COLS

モード

READ/WRITE

説明

列が列オブジェクトの場合は、ロードするオブジェクト属性の数です。列がSQL文字列またはREF列の場合は、処理する引数の数です。このパラメータは、列リストが取り出される前に設定する必要があります。

属性のデータ型

ub2 */ub2 *

OCI_ATTR_NUM_ROWS

モード

READ

説明

これまでにロードした行の数です。

属性のデータ型

ub4 *

ダイレクト・パス関数の列配列ハンドル(OCIDirPathColArray)属性

次の属性は、ダイレクト・パス関数の列配列ハンドルに使用されます。

OCI_ATTR_COL_COUNT

モード

READ

説明

最後に処理された行の最終列です。

属性のデータ型

ub2 *

OCI_ATTR_NUM_COLS

モード

READ

説明

列配列の列ディメンションです。

属性のデータ型

ub2 *

OCI_ATTR_NUM_ROWS

モード

READ

説明

列配列の行ディメンションです。

属性のデータ型

ub4 *

OCI_ATTR_ROW_COUNT

モード

READ

説明

OCIDirPathColArrayToStream()の最後のコールで正しく変換された行数です。

属性のデータ型

ub4 *

ダイレクト・パス・ストリーム・ハンドル(OCIDirPathStream)属性

次の属性は、ダイレクト・パス・ストリーム・ハンドルに使用されます。

OCI_ATTR_BUF_ADDR

モード

READ

説明

ストリーム・データの先頭のバッファ・アドレスです。

属性のデータ型

ub1 **

OCI_ATTR_BUF_SIZE

モード

READ

説明

ストリーム・データのバイト単位のサイズです。

属性のデータ型

ub4 *

OCI_ATTR_ROW_COUNT

モード

READ

説明

最後のOCIDirPathLoadStream()コールで正しくロードされた行数です。

属性のデータ型

ub4 *

OCI_ATTR_STREAM_OFFSET

モード

READ

説明

最後に処理された行の、ストリーム・バッファへのオフセットです。

属性のデータ型

ub4 *

ダイレクト・パス列パラメータ属性

アプリケーションでは、各列パラメータ記述子に対して属性を設定することにより、ロードする列、およびデータの外部書式を指定します。列パラメータ記述子は、OCIParamGet()によって、列パラメータ・リストのパラメータとして取得されます。表の列パラメータ・リストは、ダイレクト・パス・コンテキストのOCI_ATTR_LIST_COLUMNS属性から取得されます。非スカラー列の場合、列パラメータ・リストは、そのダイレクト・パス関数コンテキストのOCI_ATTR_LIST_COLUMNS属性から取得されます。

すべてのパラメータは1を基準としていることに注意してください。

列パラメータ属性へのアクセス

次のコード例は、スカラー列のダイレクト・パス列パラメータ属性の使用方法を示しています。この属性にアクセスするには、最初に、ロードする列の数を設定して、OCI_ATTR_LIST_COLUMNS属性から列パラメータ・リストを取得する必要があります。

関連項目:
リストで定義されているデータ構造は、「スカラー列に対するダイレクト・パス・ロードの例」を参照してください。

...
/* set number of columns to be loaded */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((void *)dpctx, (ub4)OCI_HTYPE_DIRPATH_CTX,
(void *)&tblp->ncol_tbl,
(ub4)0, (ub4)OCI_ATTR_NUM_COLS, ctlp->errhp_ctl));

/* get the column parameter list */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrGet((void *)dpctx, OCI_HTYPE_DIRPATH_CTX,
(void *)&ctlp->colLstDesc_ctl, (ub4 *)0,
OCI_ATTR_LIST_COLUMNS, ctlp->errhp_ctl));

これで、パラメータ属性を設定できます。

/* set the attributes of each column by getting a parameter handle on each
* column, then setting attributes on the parameter handle for the column.
* Note that positions within a column list descriptor are 1-based. */

for (i = 0, pos = 1, colp = tblp->col_tbl, fldp = tblp->fld_tbl;
i < tblp->ncol_tbl;
i++, pos++, colp++, fldp++)
{
/* get parameter handle on the column */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIParamGet((const void  *)ctlp->colLstDesc_ctl,
(ub4)OCI_DTYPE_PARAM, ctlp->errhp_ctl,
(void  **)&colDesc, pos));

colp->id_col = i;                  /* position in column array */

/* set external attributes on the column */
/* column name */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
(void  *)colp->name_col,
(ub4)strlen((const char *)colp->name_col),
(ub4)OCI_ATTR_NAME, ctlp->errhp_ctl));

/* column type */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
(void  *)&colp->exttyp_col, (ub4)0,
(ub4)OCI_ATTR_DATA_TYPE, ctlp->errhp_ctl));

/* max data size */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
(void  *)&fldp->maxlen_fld, (ub4)0,
(ub4)OCI_ATTR_DATA_SIZE, ctlp->errhp_ctl));

if (colp->datemask_col)    /* set column (input field) date mask */
{
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
(void  *)colp->datemask_col,
(ub4)strlen((const char *)colp->datemask_col),
(ub4)OCI_ATTR_DATEFORMAT, ctlp->errhp_ctl));
}
if (colp->prec_col)
{
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
(void  *)&colp->prec_col, (ub4)0,
(ub4)OCI_ATTR_PRECISION, ctlp->errhp_ctl));
}
if (colp->scale_col)
{
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
(void  *)&colp->scale_col, (ub4)0,
(ub4)OCI_ATTR_SCALE, ctlp->errhp_ctl));
}
if (colp->csid_col)
{
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
(void  *)&colp->csid_col, (ub4)0,
(ub4)OCI_ATTR_CHARSET_ID, ctlp->errhp_ctl));
}
/* free the parameter handle to the column descriptor */
OCI_CHECK((void  *)0, 0, ociret, ctlp,
OCIDescriptorFree((void  *)colDesc, OCI_DTYPE_PARAM));
}
...

OCI_ATTR_CHARSET_ID

モード

READ/WRITE

説明

キャラクタ列のキャラクタ・セットIDです。設定しない場合は、ダイレクト・パス・コンテキスト内に設定されたキャラクタ・セットIDがデフォルトとして使用されます。

属性のデータ型

ub2 */ub2 *

OCI_ATTR_DATA_SIZE

モード

READ/WRITE

説明

列の外部データのバイト単位の最大サイズです。これは、変換バッファ・サイズに影響する可能性があります。

属性のデータ型

ub4 */ub4 *

OCI_ATTR_DATA_TYPE

モード

READ/WRITE

説明

列の外部データ型を戻すか、または設定します。次のデータ型が有効です。

- SQLT_CHR

- SQLT_DATE

- SQLT_TIMESTAMP

- SQLT_TIMESTAMP_TZ

- SQLT_TIMESTAMP_LTZ

- SQLT_INTERVAL_YM

- SQLT_INTERVAL_DS

- SQLT_CLOB

- SQLT_BLOB

- SQLT_INT

- SQLT_UIN

- SQLT_FLT

- SQLT_PDN

- SQLT_BIN

- SQLT_NUM

- SQLT_NTY

- SQLT_REF

- SQLT_VST

- SQLT_VNU

属性のデータ型

ub2 */ub2 *

OCI_ATTR_DATEFORMAT

モード

READ/WRITE

説明

列の日付変換マスクです。設定しない場合、日付書式は、デフォルトでダイレクト・パス・コンテキスト内に設定された日付変換マスクになります。

属性のデータ型

oratext **/oratext *

OCI_ATTR_DIRPATH_OID

モード

READ/WRITE

説明

ロードする列は、オブジェクト表のオブジェクトID列であることを示します。

属性のデータ型

ub1 */ub1 *

OCI_ATTR_DIRPATH_SID

モード

READ/WRITE

説明

ロードする列は、ネストした表のsetid列であることを示します。

属性のデータ型

ub1 */ub1 *

OCI_ATTR_NAME

モード

READ/WRITE

説明

ロードされる列の名前を戻すか、または設定します。OCIAttrGet()をコールする前に、列名と列名の長さの両方を0に初期化します。

属性のデータ型

oratext **/oratext *

OCI_ATTR_PRECISION

モード

READ/WRITE

説明

精度を戻すか、または設定します。

属性のデータ型

明示的な記述の場合は、ub1 */ub1 *

暗黙的な記述の場合は、sb2 */sb2 *

OCI_ATTR_SCALE

モード

READ/WRITE

説明

パック10進数およびゾーン10進数の入力データ型からの変換のスケール(小数点以下の桁数)を戻すか、または設定します。

属性のデータ型

sb1 */sb1 *

プロセス・ハンドル属性

共有システムのパラメータは、OCIAttrSet()コールおよびOCIAttrGet()コールを使用して設定および読取りができます。使用するハンドル・タイプはプロセス・ハンドルOCI_HTYPE_PROCです。

関連項目:
「OCI_ATTR_SHARED_HEAPALLOC」

属性OCI_ATTR_MEMPOOL_APPNAME、OCI_ATTR_MEMPOOL_HOMENAMEおよびOCI_ATTR_MEMPOOL_INSTNAMEは、それぞれアプリケーション、ホームおよびインスタンスの名前を指定し、プロセスを正しい共有プール領域にマップするために同時に使用できます。これらの属性を指定しない場合は、内部のデフォルト値が使用されます。次に、特定の動作に対する属性の有効な設定を示します。

- インスタンス名、アプリケーション名(非修飾): この設定では、特定の名前の実行可能ファイルのみが、共通の共有サブシステムに接続できます。たとえば、「Office」という名前のOCIアプリケーションが、「Office」が存在するディレクトリに関係なく、共通の共有サブシステムに接続できます。

- インスタンス名、ホーム名: この設定では、特定のホーム・ディレクトリ内の一連の実行可能ファイルが、共有サブシステムの同じインスタンスに接続できます。たとえば、ORACLE_HOMEディレクトリに存在するすべてのOCIアプリケーションが、共通の共有サブシステムを使用できます。

- インスタンス名、ホーム名、アプリケーション名(非修飾): この設定では、特定の実行可能ファイルのみが、共有サブシステムに接続できます。たとえば、ORACLE_HOMEディレクトリ内の「Office」という名前の1つのアプリケーションが、指定の共有サブシステムに接続できます。

OCI_ATTR_MEMPOOL_APPNAME

モード

READ/WRITE

説明

実行可能ファイルのファイル名または完全修飾パス名です。

属性のデータ型

oratext *

OCI_ATTR_MEMPOOL_HOMENAME

モード

READ/WRITE

説明

共通の共有サブシステム・インスタンスを使用する実行可能ファイルが存在するディレクトリ名です。

属性のデータ型

oratext *

OCI_ATTR_MEMPOOL_INSTNAME

モード

READ/WRITE

説明

共有サブシステムのインスタンスを識別する、任意のユーザー定義名です。

属性のデータ型

oratext *

OCI_ATTR_MEMPOOL_SIZE

モード

READ/WRITE

説明

共有プールのバイト単位のサイズです。この属性は次のように設定されます。

ub4 plsz = 1000000;
OCIAttrSet((void  *)0, (ub4) OCI_HTYPE_PROC,
(void  *)&plsz, (ub4) 0, (ub4) OCI_ATTR_POOL_SIZE, 0);

属性のデータ型

ub4 *

OCI_ATTR_PROC_MODE

モード

READ

説明

現在設定されているすべてのプロセス・モードを戻します。読み取られる値には、現在設定されているすべてのOCIプロセス・モードの論理和をとった値が含まれます。特定のモードが設定されているかどうかを判断するには、そのモードで値の論理積をとります。たとえば、次のようにします。

ub4 mode;
boolean is_shared;

OCIAttrGet((void  *)0, (ub4)OCI_HTYPE_PROC,
(void  *) &mode, (ub4 *) 0,
(ub4)OCI_ATTR_PROC_MODE, 0);

is_shared = mode & OCI_SHARED;

属性のデータ型

ub4 *

イベント・ハンドル属性

OCIEventハンドルは、イベント・ペイロードの属性をカプセル化します。このハンドルは、イベント・コールバックをコールする前に暗黙的に割り当てられます。

関連項目:
「HAイベント通知」

イベント・コールバックは、次の属性とともにOCIAttrGet()を使用して、イベントの属性を取得します。

OCI_ATTR_DBDOMAIN

モード

READ

説明

この属性を使用してOCIAttrGet()をコールすると、このイベントによる影響を受けたデータベース・ドメイン名が取り出されます。これもサーバー・ハンドル属性です。

属性のデータ型

oratext **

OCI_ATTR_DBNAME

モード

READ

説明

この属性を使用してOCIAttrGet()をコールすると、このイベントによる影響を受けたデータベース名が取り出されます。これもサーバー・ハンドル属性です。

属性のデータ型

oratext **

OCI_ATTR_EVENTTYPE

モード

READ

説明

発生したイベントのイベント型OCI_EVENTTYPE_HAです。

属性のデータ型

ub4 *

OCI_ATTR_HA_SOURCE

モード

READ

説明

イベント型がOCI_EVENTTYPE_HAである場合、この属性を使用してイベントのソースを取得します。次の値が有効です。

- OCI_HA_SOURCE_DATABASE

- OCI_HA_SOURCE_NODE

- OCI_HA_SOURCE_INSTANCE

- OCI_HA_SOURCE_SERVICE

- OCI_HA_SOURCE_SERVICE_MEMBER

- OCI_HA_SOURCE_ASM_INSTANCE

- OCI_HA_SOURCE_SERVICE_PRECONNECT

属性のデータ型

ub4 *

OCI_ATTR_HA_SRVFIRST

モード

READ

説明

この属性を使用してOCIAttrGet()をコールすると、Oracle Real Application Clusters (Oracle RAC) HA DOWNイベントによる影響を受けたサーバー・ハンドルのリストから最初のサーバー・ハンドルが取り出されます。

属性のデータ型

OCIServer **

OCI_ATTR_HA_SRVNEXT

モード

READ

説明

この属性を使用してOCIAttrGet()をコールすると、Oracle RAC HA DOWNイベントによる影響を受けたサーバー・ハンドルのリストから次のサーバー・ハンドルが取り出されます。

属性のデータ型

OCIServer **

OCI_ATTR_HA_STATUS

モード

READ

説明

有効な値はOCI_HA_STATUS_DOWNです。現在、サブスクライブされているのはDOWNイベントのみです。

属性のデータ型

ub4 *

OCI_ATTR_HA_TIMESTAMP

モード

READ

説明

HAイベントが発生した時刻です。

属性のデータ型

OCIDateTime **

OCI_ATTR_HOSTNAME

モード

READ

説明

この属性を使用してOCIAttrGet()をコールすると、このイベントによる影響を受けたホストの名称が取り出されます。

属性のデータ型

oratext **

OCI_ATTR_INSTNAME

モード

READ

説明

この属性を使用してOCIAttrGet()をコールすると、このイベントによる影響を受けたインスタンスの名称が取り出されます。これもサーバー・ハンドル属性です。

属性のデータ型

oratext **

OCI_ATTR_INSTSTARTTIME

モード

READ

説明

この属性を使用してOCIAttrGet()をコールすると、このイベントによる影響を受けたインスタンスの起動時間が取り出されます。これもサーバー・ハンドル属性です。

属性のデータ型

OCIDateTime **

OCI_ATTR_SERVICENAME

モード

READ

説明

この属性を使用してOCIAttrGet()をコールすると、このイベントによる影響を受けたサービスの名称が取り出されます。名前の長さはub4 *です。これもサーバー・ハンドル属性です。

属性のデータ型

oratext **

B OCIデモ・プログラム

OCIコールの使用方法を示すコード例を提供しています。これらのプログラムはあくまでも例であり、すべてのオペレーティング・システムで実行できるとはかぎりません。

『Oracle Database Examplesインストレーション・ガイド』の説明に従って、デモ・プログラムをイインストールする必要があります。デモ・プログラムの位置、名前および可用性は、オペレーティング・システムによって異なります。LinuxまたはUNIXワークステーションでは、デモ・プログラムは$ORACLE_HOME/rdbms/demoディレクトリにインストールされています。Windowsシステムの場合は、付録Dを参照してください。

LinuxまたはUNIXプラットフォームでOCIクライアント・アプリケーションの開発に必要なOCIヘッダー・ファイルは、$ORACLE_HOME/rdbms/publicディレクトリにインストールされています。demo_rdbms.mkファイルは$ORACLE_HOME/rdbms/demoディレクトリ内にあるサンプルMakefileです。Windowsシステムでの類似ファイルは、samplesディレクトリ内のmake.batです。Makefile内に指示があります。

demo_rdbms.mkファイルを大幅に変更しないかぎり、demo_rdbms.mkファイルが$ORACLE_HOME/rdbms/publicディレクトリを含む場合に行われた変更によって影響を受けることはありません。高度にカスタマイズしたMakefileが、INCLUDEパスの$ORACLE_HOME/rdbms/publicディレクトリにあることを確認してください。

OCIアプリケーションまたは外部プロシージャを構築するための新しいmakefileを開発するには、独自のマクロをリンク行に追加して、指定したmakefileをカスタマイズします。ただし、独自のmakefileのメンテナンスを簡単にするために、指定したマクロをデモmakefile内に保持しておく必要があります。

特定のヘッダー・ファイルまたはSQLファイルがアプリケーションで必要になった場合には、デモ・プログラム・ファイルでの指定に従って、それらのファイルも用意されています。設定やプログラム実行のヒントは、デモ・プログラムの最初に記載されたコメントの情報を参照してください。

表B-1に、重要なデモ・プログラムおよびそのプログラムで示されるOCI機能を示します。拡張子.sqlが付いた関連ファイルを検索してください。

表B-1 OCIデモ・プログラム

プログラム名

示される機能

cdemo81.c

リリース8の機能を使用した基本SQL処理の使用

cdemo82.c

ユーザー定義オブジェクトの基本処理の実行

cdemocor.c

複合オブジェクト検索(COR)を使用したパフォーマンス向上

cdemodr1.c cdemodr2.c cdemodr3.c

基本データ型のLOBおよびREFで使用されるRETURNING句を伴うINSERT、UPDATEおよびDELETE文の使用

cdemodsa.c

表の情報の記述

cdemodsc.c

オブジェクト型の情報の記述

cdemofo.c

アプリケーション・フェイルオーバー・コールバックの登録および操作

cdemolb.c

LOBデータの作成と挿入およびその後のデータの読取り、書込み、コピー、追加および切捨て

cdemolb2.c

ストリーム・モードおよびコールバック関数を使用したCLOBおよびBLOB列の書込みおよび読取り

cdemolbs.c

LOBバッファリング・システムを使用したLOBの書込みおよび読取り

cdemobj.c

REFオブジェクトの確保およびナビゲーション

cdemocoll.c

ネストした表とVARRAYの挿入および選択

cdemorid.c

INSERT、UPDATE、DELETE文およびフェッチを使用した1ラウンドトリップでの複数ROWIDの取得

cdemoses.c

セッション切替えおよび移行の使用

cdemothr.c

OCIThreadパッケージの使用

cdemosyev.c

事前定義済サブスクリプションの登録およびクライアント通知用に呼び出すコールバック関数の指定(アドバンスト・キューイングの詳細は『Oracle Streamsアドバンスト・キューイング・ユーザーズ・ガイド』を参照してください)。

ociaqdemo00.c

ociaqdemo01.c

ociaqdemo02.c

ociaqarrayenq.c

ociaqarraydeq.c

Streamsアドバンスト・キューイング。100メッセージをエンキュー

メッセージをブロックしてデキュー

複数のエージェントをリスニング

10メッセージを配列してエンキュー

10メッセージを配列からデキュー

cdemodp.c、cdemodp_lip.c

ダイレクト・パス・ロード関数を使用したデータのロード

cdemdpco.c

cdemdpno.c

cdemdpin.c

cdemdpit.c

cdemdpro.c

cdemdpss.c

ダイレクト・パス・ロード関数を使用した列オブジェクトのロード

ダイレクト・パス・ロード関数を使用した、ネストされた列オブジェクトのロード

導出タイプ(継承)のロード - ダイレクト・パス

継承があるオブジェクト表のロード - ダイレクト・パス

ダイレクト・パス・ロード関数を使用した参照のロード

ダイレクト・パス・ロード関数を使用したSQL文字列のロード

cdemoucb.c、cdemoucbl.c

静的および動的ユーザー・コールバックの使用

cdemoupk.c、cdemoup1.c、cdemoup2.c

複数パッケージでの動的ユーザー・コールバックの使用

cdemodt.c

日時および時間隔の例。(PL/SQLプロシージャまたは関数でのINおよびOUTバインドのデモ)

cdemosc.c

スクロール・カーソル

cdemol2l.c

LONG API (データ・インタフェース)を使用したLOBへのアクセス

cdemoin1.c

表にある継承されたタイプを変更し、その表からレコードを表示する継承デモ

cdemoin2.c

属性の代入性を提示する継承デモ

cdemoin3.c

オブジェクト、継承されたタイプ、オブジェクト表およびサブ表を記述した継承デモ

cdemoanydata1.c

任意データ・デモ。任意データ表との間での行の挿入と選択

cdemoanydata2.c

任意データ・デモ。OCITypeBeginCreate()を使用してタイプをピース単位に作成し、作成した新しいタイプを記述

cdemoqc.c

SQLヒントを使用した問合せキャッシュ

cdemoqc2.c

SQLヒントおよび表注釈を使用した問合せキャッシュ

cdemosp.c

セッション・プーリング

cdemocp.c

接続プーリング

cdemocpproxy.c

プロキシ機能を使用した接続プーリング

cdemostc.c

文キャッシュ

cdemouni.c

OCI UTF16 APIのプログラム

nchdemo1.c

NCHARの暗黙的変換機能およびコード・ポイント機能の表示

C OCI関数のサーバー・ラウンドトリップ

この付録では、様々なOCIコール中に発生するサーバー・ラウンドトリップについて説明します。サーバー・ラウンドトリップ は、クライアントからサーバーに送信し、クライアントに戻るトリップとして定義されます。この情報は、プログラマがアプリケーションで特定の作業を実行するための最も効率的な方法を判断するのに役立ちます。

この付録では、次の項目について説明します。

- サーバー・ラウンドトリップの概要

- リレーショナル関数のラウンドトリップ

- LOB関数のラウンドトリップ

- オブジェクト関数およびキャッシュ関数のラウンドトリップ

- 記述操作のラウンドトリップ

- データ型マッピング関数および操作関数のラウンドトリップ

- 任意型関数および任意データ関数のラウンドトリップ

- その他のローカル関数

サーバー・ラウンドトリップの概要

この付録では、様々なOCIコール中に発生するサーバー・ラウンドトリップについて説明します。この情報は、アプリケーションで特定の作業を実行するための最も効率的な方法を判断するのに役立ちます。

リレーショナル関数のラウンドトリップ

各OCIリレーショナル関数に必要なサーバー・ラウンドトリップ回数のリストを表C-1に示します。

表C-1 リレーショナル操作用のサーバー・ラウンドトリップ

関数

サーバー・ラウンドトリップ回数

OCIBreak()

1

OCIDBShutdown()

1

OCIDBStartup()

1

OCIEnvCreate()

0

OCIEnvInit()

0

OCIErrorGet()

0

OCIInitialize()

0

OCILdaToSvcCtx()

0

OCILogoff()

1

OCILogon()

1

OCILogon2()

接続プールまたはセッション・プール: OCISessionGet()と同じ

通常: 2 (認証とTAF状況に基づく)

OCIPasswordChange()

1

OCIPing()

1

OCIReset()

0

OCIServerAttach()

1

OCIServerDetach()

1

OCIServerVersion()

1

OCISessionBegin()

1

OCISessionEnd()

1

OCISessionGet()

セッション・プール: 0 (ログイン数の増分)。接続プール: 1から(1+ (増分 * ログイン数))。キャッシュ・ヒットに依存: 1 (ユーザー・セッションの場合)、オプションの増分 (1次セッションの場合)。

通常: 1ログイン

OCISessionPoolCreate()

sessMin*ログイン数

OCISessionPoolDestroy()

キャッシュ内のセッション数*ログオフ数

OCISessionRelease()

セッション・プーリング: 0。明示的セッションがフラグ・セットを破棄したときは例外。

通常: 1ログイン

OCIStmtExecute()

1

OCIStmtFetch()

0または1

OCIStmtFetch2()

プリフェッチで0。それ以外は1。

OCIStmtGetPieceInfo()

1

OCIStmtPrepare()

0

OCIStmtSetPieceInfo()

0

OCISvcCtxToLda()

0

OCITerminate()

1

OCITransCommit()

1

OCITransDetach()

1

OCITransForget()

1

OCITransPrepare()

1

OCItransRollback()

1

OCITransStart()

1

OCIUserCallbackGet()

0

OCIUserCallbackRegister()

0

LOB関数のラウンドトリップ

OCILobコールで発生するサーバー・ラウンドトリップ回数のリストを表C-2に示します。

注意:
ラウンドトリップの回数を最低限に抑えるために、LOBのデータ・インタフェースを使用できます。CLOB列の文字データまたはBLOB列のRAWデータをバインドまたは定義できます。

関連項目:

- INSERT文およびUPDATE文の使用方法および使用例は、「LOBデータのバインド」を参照してください。

- SELECT文の使用方法および使用例は、「LOBデータの定義」を参照してください。

ラウンドトリップの回数が0または1のコールの場合、LOBバッファリングが有効であり、要求がクライアントで完了すれば、ラウンドトリップは発生しません。

表C-2 OCILobコール用のサーバー・ラウンドトリップ

関数

サーバー・ラウンドトリップ回数

OCILobAppend()

1

OCILobArrayRead()

1

OCILobArraywrite()

1

OCILobAssign()

0

OCILobCharSetForm()

0

OCILobCharSetId()

0

OCILobClose()

1

OCILobCopy()

1

OCILobCopy2()

1

OCILobCreateTemporary()

1

OCILobDisableBuffering()

0

OCILobEnableBuffering()

0

OCILobErase()

1

OCILobErase2()

1

OCILobFileClose()

1

OCILobFileCloseAll()

1

OCILobFileExists()

1

OCILobFileGetName()

0

OCILobFileIsOpen()

1

OCILobFileOpen()

1

OCILobFileSetName()

0

OCILobFlushBuffer()

このLOBのバッファにある変更ページごとに1

OCILobFreeTemporary()

1

OCILobGetChunkSize()

1

OCILobGetLength()

1

OCILobGetLength2()

1

OCILobGetStorageLimit()

1

OCILobIsEqual()

0

OCILobIsOpen()

1

OCILobIsTemporary()

0

OCILobLoadFromFile()

1

OCILobLoadFromFile2()

1

OCILobLocatorAssign()

ソース・ロケータまたは宛先ロケータのいずれかが一時LOBを参照している場合は1ラウンドトリップ

OCILobLocatorIsInit()

0

OCILobOpen()

1

OCILobRead()

0または1

OCILobRead2()

0または1

OCILobTrim()

1

OCILobTrim2()

1

OCILobWrite()

0または1

OCILobWrite2()

0または1

OCILobWriteAppend()

0または1

OCILobWriteAppend2()

0または1

オブジェクト関数およびキャッシュ関数のラウンドトリップ

オブジェクト関数およびキャッシュ関数に必要なサーバー・ラウンドトリップ回数のリストを表C-3に示します。これらの値では、キャッシュがウォームな状態であると想定しています。つまり、アプリケーションで必要な型記述子オブジェクトがすでにロードされているということです。

表C-3 オブジェクト関数およびキャッシュ関数用のサーバー・ラウンドトリップ

関数

サーバー・ラウンドトリップ回数

OCICacheFlush()

1

OCICacheFree()

0

OCICacheRefresh()

1

OCICacheUnmark()

0

OCICacheUnpin()

0

OCIObjectArrayPin()

1

OCIObjectCopy()

0

OCIObjectExists()

0

OCIObjectFlush()

1

OCIObjectFree()

0

OCIObjectGetInd()

0

OCIObjectGetObjectRef()

0

OCIObjectGetTypeRef()

0

OCIObjectIsDirty()

0

OCIObjectIsLocked()

0

OCIObjectLock()

1

OCIObjectMarkDelete()

0

OCIObjectMarkDeleteByRef()

0

OCIObjectMarkUpdate()

0

OCIObjectNew()

0

OCIObjectPin()

1。必要なオブジェクトがすでにキャッシュにある場合は0。

OCIObjectPinCountReset()

0

OCIObjectPinTable()

1

OCIObjectRefresh()

1

OCIObjectUnmark()

0

OCIObjectUnmarkByRef()

0

OCIObjectUnpin()

0

記述操作のラウンドトリップ

OCIDescribeAny()、OCIAttrGet()およびOCIParamGet()に必要なサーバー・ラウンドトリップ回数のリストを表C-4に示します。

表C-4 記述操作用のサーバー・ラウンドトリップ

関数

サーバー・ラウンドトリップ回数

OCIAttrGet()

型オブジェクトがオブジェクト・キャッシュにない場合は、型を記述するために2ラウンドトリップ。

各コレクション要素、各型属性、メソッドまたはメソッド引数記述子につき1ラウンドトリップ。 コレクション要素、型属性またはメソッド引数に対してOCI_ATTR_TYPE_NAMEまたはOCI_ATTR_SCHEMA_NAMEを使用している場合は、さらに1ラウンドトリップ。

最初のOCIAttrGet()コールの後で、オブジェクト・キャッシュに記述されるすべての型オブジェクトがすでにある場合は0。

OCIDescribeAny()

型記述子オブジェクトのREF取得のために1ラウンドトリップ。

OCIParamGet()

0

データ型マッピング関数および操作関数のラウンドトリップ

データ型マッピング関数および操作関数のラウンドトリップ回数のリストを表C-5に示します。表内のアスタリスクは、特定の接頭辞を持つすべての関数のサーバー・ラウンドトリップ回数が同じになることを示します。たとえば、OCINumberAdd()、OCINumberPower()およびOCINumberFromText()では、サーバー・ラウンドトリップはすべて0となります。

表C-5 データ型の操作関数用のサーバー・ラウンドトリップ

関数

サーバー・ラウンドトリップ回数

OCIColl*()

0。コレクションがキャッシュにロードされていない場合は1。

OCIDate*()

0

OCIIter*()

0。コレクションがキャッシュにロードされていない場合は1。

OCINumber*()

0

OCIRaw*()

0

OCIRef*()

0

OCIString*()

0

OCITable*()

0。ネストした表がキャッシュにロードされていない場合は1。

任意型関数および任意データ関数のラウンドトリップ

任意型関数および任意データ関数に必要なサーバー・ラウンドトリップ回数のリストを表C-6に示します。リストされていない関数は、ラウンドトリップを生成しません。

表C-6 任意型関数および任意データ関数のサーバー・ラウンドトリップ

関数

サーバー・ラウンドトリップ回数

OCIAnyDataAttrGet()

0。型情報がキャッシュにロードされていない場合は1。

OCIAnyDataAttrSet()

0。型情報がキャッシュにロードされていない場合は1。

OCIAnyDataCollGetElem()

0。型情報がキャッシュにロードされていない場合は1。

その他のローカル関数

ローカルであるため、サーバー・ラウンドトリップが不要な関数のリストを表C-7に示します。

表C-7 ローカルに処理される関数

ローカル関数名

注意

OCIAttrGet()

オブジェクト型を記述すると、このコールは、型記述子オブジェクトをフェッチするためにラウンドトリップを1回行います。

OCIAttrSet()

OCIBindArrayOfStruct()

OCIDefineArrayOfStruct()

OCIBindByName()

OCIBindByPos()

OCIBindDynamic()

OCIBindObject()

OCIDefineByPos()

OCIDefineDynamic()

OCIDefineObject()

OCIDescriptorAlloc()

OCIDescriptorFree()

OCIEnvCreate()

OCIEnvInit()

OCIErrorGet()

OCIHandleAlloc()

OCIHandleFree()

OCILdaToSvcCtx()

OCIStmtGetBindInfo()

OCIStmtPrepare()

OCIStmtRelease()

OCIStmtPrepare2()

OCISvcCtxToLda()

D OCI for Windowsスタート・ガイド

この付録では、Windows 2003、Windows 2000およびWindows XPの各オペレーティング・システムに該当するOCIの機能のみ説明します。Windows NTは、サポート対象外になりました。

この章は、次の項目で構成されています。

- OCI for Windowsパッケージの内容

- WindowsでのOracleディレクトリ構造

- Windows用サンプルOCIプログラム

- Windows用OCIアプリケーションのコンパイル

- Windows用OCIアプリケーションのリンク

- Windows用OCIアプリケーションの実行

- Oracle XAライブラリ

- Object Type Translator for Windowsの使用

OCI for Windowsパッケージの内容

Oracle Call Interface for Windowsパッケージには、次のものが含まれています。

- Oracle Call Interface(OCI)

- Required Support Files (RSF)

- Oracle Universal Installer

- OCIアプリケーションのコンパイル用ヘッダー・ファイル

- OCIアプリケーションのリンク用ライブラリ・ファイル

- OCIアプリケーションの構築方法を示すサンプル・プログラム

OCI for Windowsパッケージには、OCIプログラムをリンクするために必要な追加ライブラリが含まれています。

関連項目:
単純なOCIのインストール・オプションは、「OCI Instant Client」を参照してください。

WindowsでのOracleディレクトリ構造

OCIは、デフォルトのOracle Databaseインストールに含まれます。Oracle Databaseをインストールする場合、Oracle Universal Installerにより、ORACLE_BASE\ORACLE_HOMEディレクトリの下のoci、binおよびprecompディレクトリにOCIファイルが作成されます。これらのファイルには、OCIアプリケーションのリンクおよび実行に必要なライブラリ・ファイル、およびOracle Formsなどの他のOracle for Microsoft Windows製品へのリンクに必要なライブラリ・ファイルが含まれます。

ORACLE_BASE\ORACLE_HOMEディレクトリには、表D-1で説明している、OCIに関連のある次のディレクトリが含まれています。

表D-1 ORACLE_HOMEディレクトリと内容

ディレクトリ名

内容

\bin

実行可能ファイルおよびヘルプ・ファイル

\oci

Windows用Oracle Call Interfaceディレクトリ・ファイル

\oci\include

oci.hおよびociap.hなどのヘッダー・ファイル

\oci\samples

サンプル・プログラム

\precomp\admin\ottcfg.cfg

Object Type Translatorユーティリティおよびデフォルト構成ファイル

Windows用サンプルOCIプログラム

OCIのインストール時に、サンプル・プログラムのセットおよび対応するプロジェクト・ファイルがORACLE_BASE¥ORACLE_HOME¥oci¥samplesサブディレクトリにコピーされます。OCIのインストールの成功を確認し、OCIアプリケーションの開発手順を理解するために、これらのサンプル・プログラムをビルドし、実行することをお薦めします。

サンプルをビルドするには、コマンド・プロンプトでバッチ・ファイル(make.bat)を実行します。たとえば、cdemo1.cサンプルをビルドするには、samplesディレクトリで次のコマンドを入力します。

C:> make cdemo1

これらのサンプル・プログラムの使用後、削除しても構いません。

ociucb.cプログラムは、ociucb.batを使用してコンパイルします。このバッチ・ファイルはDLLを作成し、ORACLE_BASE¥ORACLE_HOME¥binディレクトリに格納します。ユーザー・コールバック関数をロードするには、環境レジストリ変数ORA_OCI_UCBPKGにOCIUCBを設定します。

Windows用OCIアプリケーションのコンパイル

OCIアプリケーションをコンパイルする際には、適切なOCIヘッダー・ファイルを含める必要があります。ヘッダー・ファイルは、\ORACLE_BASE\ORACLE_HOME\oci\includeディレクトリに格納されています。

Microsoft Visual C++については、「オプション」ダイアログ・ボックスのライブラリのセクションで、¥ORACLE_BASE¥ORACLE_HOME¥oci¥lib¥msvcを指定する必要があります。Borlandコンパイラについては、¥ORACLE_BASE¥ORACLE_HOME¥oci¥lib¥bcを指定します。

たとえば、Microsoft Visual C++ 8.0を使用している場合、「ツール」メニュー内にある「オプション」ダイアログの「ディレクトリ」ページで、適切なパス\oracle\db_1\oci\includeを入力する必要があります。

注意:
現行のOCIリリースでは、Microsoft Visual C++ 7.1以降のみがサポートされています。

関連項目:
アプリケーションのコンパイル方法および特別なコンパイラ・オプションに関する固有の情報は、コンパイラのドキュメントを参照してください。

Windows用OCIアプリケーションのリンク

OCIコールは、Oracleが提供するDynamic Link Libraries (DLL)で実装されます。DLLはORACLE_BASE¥ORACLE_HOME¥binディレクトリに格納されており、Required Support Files (RSF)の一部です。

Microsoft Compiler用のoci.libインポート・ライブラリのみ提供しています。BorlandコンパイラもOracleによってOCIでの使用がサポートされています。リリースごとの再リンクやコンパイルを回避するために、アプリケーションを必ずoci.libにリンクすることをお薦めします。

oci.libをMicrosoft Compilerとともに使用する場合、特別なリンク・オプションを指定する必要はありません。

oci.lib

アプリケーションをoci.libにリンクすることをお薦めします。これにより、Oracle DLLの正しいバージョンがロードされます。

LoadLibrary()使用時のクライアントDLLのロード

LoadLibrary()関数により、クライアントDLLのロードのために次のディレクトリがこの順序で検索されます。

- アプリケーションのロード元ディレクトリ、またはoci.dllが格納されているディレクトリ

- 現行ディレクトリ

- Windows

- 32ビットWindowsシステム・ディレクトリ(system32)。このディレクトリへのパスを取得するには、Windows APIのGetWindowsDirectory()関数を使用します。

- 16ビットWindowsディレクトリ(system)。このディレクトリへのパスを取得するためのWin32関数は存在しませんが、検索されます。

- PATH環境変数にリスト表示されているディレクトリ

Windows用OCIアプリケーションの実行

OCIアプリケーションを実行する際、OCIアプリケーションを実行するコンピュータ上に、対応するRequired Support Files (RSF)のセット全体がインストールされていることを確認してください。

Oracle XAライブラリ

XA Application Program Interface (API)は、通常、Oracle Databaseが次のようなトランザクション処理(TP)モニターと対話するために使用されます。

- Oracle Tuxedo

- IBM Transarc Encina

- IBM CICS

また、TPモニター文をクライアント・プログラムでも使用できます。XA APIの使用は、OCIによってサポートされています。

Oracle XAライブラリは、Oracle Database Enterprise Editionの一部として自動的にインストールされます。表D-2に、Oracleホーム・ディレクトリに作成されるコンポーネントを示します。oci.libインポート・ライブラリにはXAエクスポートが含まれています。

表D-2 Oracle XAコンポーネント

コンポーネント

位置

xa.h

ORACLE_BASE¥ORACLE_HOME¥oci¥include

Oracle XAライブラリを使用したOCIプログラムのコンパイルおよびリンク

Oracle XAライブラリを使用してOCIプログラムのコンパイルおよびリンクを行うには、次の手順を実行します。

1. Microsoft Visual C++またはBorlandコンパイラを使用してprogram.cをコンパイルします。必ずパスにORACLE_BASE¥ORACLE_HOME¥rdbms¥xaを含めてください。

2. program.objを、表D-3に示されているライブラリとリンクします。

表D-3 リンク・ライブラリ

ライブラリ

位置

oraxa11.lib

ORACLE_BASE¥ORACLE_HOME¥rdbms¥xa

oci.lib

ORACLE_BASE\ORACLE_HOME\oci\lib\msvcまたは

ORACLE_BASE¥ORACLE_HOME¥oci¥lib¥bc

3. program.exeを実行します。

XAの動的な登録の使用

データベースでは、XAの動的な登録をサポートしています。XAの動的な登録は、XA準拠TPモニターと対話するアプリケーションのパフォーマンスを改善します。TPモニターがWindows上でOracle Databaseに対しXAの動的な登録を使用するようにするには、TPモニターが稼働しているWindowsシステムに、環境変数またはレジストリ変数のいずれかを追加する必要があります。手順は、次のいずれかの項を参照してください。

- 現行セッション用の環境変数の追加

- 全セッション用のレジストリ変数の追加

現行セッション用の環境変数の追加

コマンド・プロンプトで環境変数を追加すると、現行セッションのみが影響を受けます。

環境変数の追加手順

TPモニターがインストールされているコンピュータから、コマンド・プロンプトで次のように入力します。

C:\> set ORA_XA_REG_DLL = vendor.dll

この例では、vendor.dllは、ベンダーが提供するTPモニターのDLLです。

全セッション用のレジストリ変数の追加

レジストリ変数を追加すると、Windowsシステム上の全セッションが影響を受けます。1つのTPモニターのみが稼働しているコンピュータでは、この方法が便利です。

レジストリ変数の追加手順

1. TPモニターがインストールされているコンピュータに移動します。

2. コマンド・プロンプトで次のように入力します。

C:\> regedt32

「レジストリ エディタ」ウィンドウが表示されます。

3. HKEY_LOCAL_MACHINE¥SOFTWARE¥ORACLE¥HOMEIDに移動します。

4. 「編集」メニューの「値の追加」を選択します。「値の追加」ダイアログ・ボックスが表示されます。

5. 値の名前テキスト・ボックスに「ORA_XA_REG_DLL」と入力します。

6. 「データ型」リストから「REG_EXPAND_SZ」を選択します。

7. 「OK」をクリックします。文字列エディタ・ダイアログ・ボックスが表示されます。

8. 「文字列」フィールドに「vendor.dll」と入力します。vendor.dllは、ベンダーが提供するTPモニターのDLLです。

9. 「OK」をクリックします。レジストリ・エディタによってパラメータが追加されます。

10. 「レジストリ」メニューから「終了」を選択します。
レジストリが終了します。

XAおよびTPモニターに関する情報

XAおよびTPモニターに関して、次の一般的な情報を参照してください。

- 『Distributed TP: The XA Specification』(C193)、The Open Group発行。

- 次のWebサイトを参照してください。
http://www.opengroup.org/publications/catalog/tp.htm

- ご使用のTPモニター固有のドキュメント

- Oracle XAライブラリの詳細およびXAの動的な登録の使用方法の詳細は、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』のOracle XAでのアプリケーションの開発に関する項を参照してください。

- Oracle Tuxedoの情報は、次を参照してください。

http://www.oracle.com/products/middleware/tuxedo/index.html

Object Type Translator for Windowsの使用

オブジェクトを利用するには、データベースに対してObject Type Translator (OTT)を実行して、C構造体を含むヘッダー・ファイルを生成します。たとえば、データベースにPERSON型が作成された場合、PERSONの属性に対応する要素を持つC構造体がOTTにより生成されます。さらに、C構造体のインスタンスのNULL情報を表現するNULLインジケータ構造体が作成されます。

intypeファイルは、どのオブジェクト型を変換する必要があるかをOTTに指示します。また、このファイルは生成された構造体の命名も制御します。

注意:
Oracle Database 10gリリース1より、INTYPEファイル・アシスタントは使用できません。

CASE=LOWERなど、intypeファイル内のCASE仕様は、intypeファイルのTYPEまたはTRANSLATE文によって特別にはリストされていないC識別子にのみ適用されます。intypeファイルでは、TYPE PersonおよびType PeRsOnなどのように、型名を適切な大/小文字で入力することが重要です。

Windowsでは、OTTはコマンドラインから起動できます。構成ファイルは、コマンドラインで名前を付けることもできます。Windowsの場合、構成ファイルは、ORACLE_BASE¥ORACLE_HOME¥precomp¥adminに格納されているottcfg.cfgです。

E 非推奨のOCI関数

表E-1は、Oracle 11g R2 (11.2)より前のリリースで非推奨になったOCI関数を示しています。今後のリリースでは、これらの関数は使用されなくなる可能性があります。

表E-1 非推奨のOCI関数

関数グループ

非推奨の関数

初期化

OCIEnvInit()、OCIInitialize()

文

OCIStmtFetch()

Lob

OCILobCopy()、OCILobErase()、OCILobGetLength()、OCILobLoadFromFile()、OCILobRead()、OCILobTrim()、OCILobWrite()、OCILobWriteAppend()

Streamsアドバンスト・キューイング関数

OCIAQListen()

非推奨の初期化関数

表E-2は、この項で説明している非推奨の初期化関数を示しています。

表E-2 非推奨の初期化関数

関数

用途

OCIEnvInit()

環境ハンドルを初期化します。

OCIInitialize()

OCIプロセス環境を初期化します。

OCIEnvInit()

用途

OCI環境ハンドルを割り当て、初期化します。この関数は非推奨です。

構文

sword OCIEnvInit ( OCIEnv    **envhpp,
ub4       mode,
size_t    xtramemsz,
void      **usrmempp );

パラメータ

envhpp (OUT)

環境へのハンドルのポインタです。

mode (IN)

環境モードの初期化を指定します。次のモードが有効です。

- OCI_DEFAULT

- OCI_ENV_NO_UCB

OCI_DEFAULTモードの場合、OCIライブラリでハンドルが常にmutex化されます。

OCI_ENV_NO_UCBモードは、環境の初期化時に動的コールバック・ルーチンOCIEnvCallbackのコールを抑止するために使用します。デフォルトでは、このコールは抑止されません。

関連項目:
「動的なコールバック登録」

xtramemsz (IN)

環境の継続時間中に割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

環境の継続時間中コールによってユーザー用に割り当てられた、xtramemszサイズのユーザー・メモリーのポインタを戻します。

コメント

注意:
OCIEnvCreate()は、OCIInitialize()コールおよびOCIEnvInit()コールのかわりに使用します。OCIInitialize()およびOCIEnvInit()コールは、下位互換性を保つためにサポートされています。

このコールは、OCI環境ハンドルの割当ておよび初期化を行います。初期化済のハンドルには何も行いません。OCI_ERRORまたはOCI_SUCCESS_WITH_INFOが戻った場合は、この環境ハンドルを使用してOracle固有のエラーおよび診断を取得できます。

これはローカルに処理され、サーバー・ラウンドトリップはありません。

環境ハンドルは、OCIHandleFree()を使用して解放できます。

関連項目:
xtramemszパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください。

関連関数

OCIHandleAlloc()、OCIHandleFree()、OCIEnvCreate()、OCITerminate()

OCIInitialize()

用途

OCIプロセス環境を初期化します。この関数は非推奨です。

構文

sword OCIInitialize ( ub4           mode,
const void    *ctxp,
const void    *(*malocfp)
( void  *ctxp,
size_t size ),
const void    *(*ralocfp)
( void  *ctxp,
void  *memptr,
size_t newsize ),
const void    (*mfreefp)
( void  *ctxp,
void  *memptr ));

パラメータ

mode (IN)

モードの初期化を指定します。次のモードが有効です。

- OCI_DEFAULT - デフォルト・モード。

- OCI_THREADED - スレッド環境。このモードでは、ユーザーに公開されていない内部データ構造がマルチ・スレッドによって同時にアクセスされないように保護します。

- OCI_OBJECT - オブジェクト機能を使用します。

- OCI_EVENTS - パブリッシュ/サブスクライブ通知を利用します。

ctxp (IN)

メモリー・コールバック・ルーチン用のユーザー定義コンテキストです。

malocfp (IN)

ユーザー定義のメモリー割当て関数です。modeがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。

ctxp (IN/OUT)

ユーザー定義のメモリー割当て関数のためのコンテキスト・ポインタです。

size (IN)

ユーザー定義のメモリー割当て関数によって割り当てられるメモリーのサイズです。

ralocfp (IN)

ユーザー定義のメモリー再割当て関数です。modeがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。

ctxp (IN/OUT)

ユーザー定義のメモリー再割当て関数のためのコンテキスト・ポインタです。

memptr (IN/OUT)

メモリー・ブロックのポインタです。

newsize (IN)

新しく割り当てられるメモリーのサイズです。

mfreefp (IN)

ユーザー定義のメモリー解放関数です。modeがOCI_THREADEDの場合、このメモリー解放ルーチンは、スレッド・セーフにしてください。

ctxp (IN/OUT)

ユーザー定義のメモリー解放関数のためのコンテキスト・ポインタです。

memptr (IN/OUT)

解放されるメモリーへのポインタです。

コメント

注意:
OCIEnvCreate()は、非推奨のOCIInitialize()コールのかわりに使用します。OCIInitialize()コールは、下位互換性を保つためにサポートされています。

このコールは、OCIプロセス環境を初期化します。OCIInitialize()は、他のOCIをコールする前にコールする必要があります。

この関数を使用すると、アプリケーションでコールバックを使用して固有のメモリー管理関数を定義できます。アプリケーションでこのようなメモリー管理関数(つまりメモリー割当て、メモリー再割当ておよびメモリー解放)がすでに定義されている場合は、この関数のコールバック・パラメータを使用して登録する必要があります。

これらのメモリー・コールバックはオプションです。アプリケーションで、この関数のメモリー・コールバックにNULL値を渡すと、デフォルトのプロセス・メモリー割当てメカニズムが使用されます。

関連項目:

- OCIを使用したマルチスレッド・アプリケーションのプログラミングの詳細は、「OCIマルチスレッド開発の概要」を参照してください。

- オブジェクトを使用したOCIプログラミングの詳細は、第11章を参照してください。

例

次の文は、ユーザー定義メモリー関数がない場合に、スレッド・モードおよびオブジェクト・モードでOCIInitialize()をコールする方法の例です。

OCIInitialize((ub4) OCI_THREADED | OCI_OBJECT, (void  *)0,
(void  * (*)()) 0, (void  * (*)()) 0,  (void (*)()) 0 );

関連関数

OCIHandleAlloc()、OCIHandleFree()、OCIEnvCreate()、OCITerminate()

非推奨の文関数

表E-3は、この項で説明している非推奨の文関数を示しています。

表E-3 非推奨の文関数

関数

用途

OCIStmtFetch()

問合せから行をフェッチします。

OCIStmtFetch()

用途

問合せから行をフェッチします。この関数は非推奨です。OCIStmtFetch2()を使用してください。

構文

sword OCIStmtFetch ( OCIStmt     *stmtp,
OCIError    *errhp,
ub4         nrows,
ub2         orientation,
ub4         mode );

パラメータ

stmtp (IN)

文(アプリケーション要求)ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

nrows (IN)

現行の位置からフェッチされる行数です。

orientation (IN)

リリース9.0より前で使用可能な値は、OCI_FETCH_NEXT (デフォルト値)のみです。

mode (IN)

OCI_DEFAULTを渡します。

コメント

プリフェッチされた行で間に合う場合、フェッチ・コールはローカル・コールになります。ただしこれは、アプリケーションに対して透過的に行われます。

LOB列が読み取られる場合、LOBロケータに対して実行される後続のLOB操作のために、それらのロケータがフェッチされます。LONG列の場合、プリフェッチはオフになります。

この関数は、次のエラーのいずれかが発生するとEOFのOCI_NO_DATAおよびOCI_SUCCESS_WITH_INFOを戻します。

- ORA-24344 - 正常に終了しましたが、コンパイル・エラーがあります。

- ORA-24345 - 切捨てまたはNULLフェッチ・エラーが発生しました。

- ORA-24347 - 警告: グループ関数にNULL列があります。

nrowsパラメータに0 (ゼロ)を設定してOCIStmtFetch()をコールした場合は、カーソルが取り消されます。

OCI_ATTR_ROWS_FETCHEDを使用して、最後のフェッチ・コールでユーザーのバッファに正常にフェッチされた行数を検索します。

関連関数

OCIStmtExecute()、OCIStmtFetch2()

非推奨のLOB関数

表E-4は、この項で説明している非推奨のLOB関数を示しています。

表E-4 非推奨のLOB関数

関数

用途

OCILobCopy()

LOBの一部または全部を別のLOBにコピーします。

OCILobErase()

LOBの一部を消去します。

OCILobGetLength()

LOBの長さを取得します。

OCILobLoadFromFile()

BFILEからLOBをロードします。

OCILobRead()

LOBの一部を読み取ります。

OCILobTrim()

LOBを切り捨てます。

OCILobWrite()

LOBに書き込みます。

OCILobWriteAppend()

LOBの末尾からデータを書き込みます。

OCILobCopy()

用途

LOB値の全体または一部を別のLOB値にコピーします。この関数は非推奨です。OCILobCopy2()を使用してください。

構文

sword OCILobCopy ( OCISvcCtx        *svchp,
OCIError         *errhp,
OCILobLocator    *dst_locp,
OCILobLocator    *src_locp,
ub4              amount,
ub4              dst_offset,
ub4              src_offset );

パラメータ

次を参照してください。
「OCILobCopy2()」

OCILobErase()

用途

内部LOBデータの一部を指定のオフセットの位置から消去します。この関数は非推奨です。OCILobErase2()を使用してください。

構文

sword OCILobErase ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCILobLocator   *locp,
ub4             *amount,
ub4             offset );

パラメータ

次を参照してください。
「OCILobErase2()」

OCILobGetLength()

用途

LOBの長さを取得します。この関数は非推奨です。OCILobGetLength2()を使用してください。

構文

sword OCILobGetLength ( OCISvcCtx      *svchp,
OCIError       *errhp,
OCILobLocator  *locp,
ub4            *lenp );

パラメータ

次を参照してください。
「OCILobGetLength2()」

OCILobLoadFromFile()

用途

ファイルの全体または一部を内部LOBにロードおよびコピーします。この関数は非推奨です。OCILobLoadFromFile2()を使用してください。

構文

sword OCILobLoadFromFile ( OCISvcCtx        *svchp,
OCIError         *errhp,
OCILobLocator    *dst_locp,
OCILobLocator    *src_locp,
ub4              amount,
ub4              dst_offset,
ub4              src_offset );

パラメータ

次を参照してください。
「OCILobLoadFromFile2()」

OCILobRead()

用途

LOBまたはBFILEの一部をコールの指定どおりにバッファに読み取ります。この関数は非推奨です。OCILobRead2()を使用してください。

構文

sword OCILobRead ( OCISvcCtx          *svchp,
OCIError           *errhp,
OCILobLocator      *locp,
ub4                *amtp,
ub4                offset,
void               *bufp,
ub4                bufl,
void               *ctxp,
OCICallbackLobRead (cbfp)
( void          *ctxp,
const void    *bufp,
ub4           len,
ub1           piece
)
ub2                csid,
ub1                csfrm );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

一意にLOBまたはBFILEを参照するLOBまたはBFILEロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

amtp (IN/OUT)

表E-5に示すように、amtpの値は、バイト数または文字数のいずれかで表される量です。

表E-5 OCILobRead()のamtpの文字数またはバイト数

LOBまたはBFILE

入力

固定幅のクライアント側キャラクタ・セットによる出力

可変幅のクライアント側キャラクタ・セットによる出力

BLOBおよびBFILE

バイト

バイト

バイト

CLOBおよびNCLOB

文字

文字

バイト 脚注 1

脚注 1 入力量は、サーバー側のCLOBまたはNCLOBから読み取る文字数を示します。出力量は、バッファbufpに読み取られたバイト数を示します。

次の場合、パラメータamtpは読み取られたデータの総量です。

- データがストリーム・モードで読み取られない場合(1ピースのみ読み取られ、ポーリングまたはコールバックは行われません)。

- データがコールバックによってストリーム・モードで読み取られる場合

データがポーリングを使用してストリーム・モードで読み取られる場合、パラメータamtpは読み取られた最後のピースの長さです。

読み取られる量がバッファの長さより多い場合、ストリーム・モードでのLOBの読取りは、入力オフセットからLOBの終わりまでか、指定されたバイト数の読取りまで、いずれか先に達するところまで行われます。入力時にこの値が0 (ゼロ)の場合は、入力オフセットからLOBの末尾までストリーム・モードでデータが読み取られます。

ストリーム・モード(ポーリングまたはコールバックのいずれかで実行)の場合、LOB値は入力オフセットから連続して読み取られます。

データがピース単位で読み取られる場合、amtpパラメータには常に読み取られた各ピースの長さが含まれます。

コールバック関数が定義されている場合は、パイプからbuflバイトが読み取られるたびにそのコールバック関数が呼び出されます。各ピースがbufpに書き込まれます。

コールバック関数が定義されていない場合は、OCI_NEED_DATAエラー・コードが戻ります。アプリケーションでは、OCI_NEED_DATAエラー・コードが戻らなくなるまで何度もOCILobRead()をコールし、LOBのピースを読み取る必要があります。ピースのサイズを変えながら複数の場所を読み取る場合は、コールごとにバッファ・ポインタと長さを変えることができます。

offset (IN)

入力時、これはLOB値の先頭からの絶対オフセットです。文字LOB (CLOB、NCLOB)ではLOBの先頭からの文字数であり、バイナリLOBまたはBFILEではバイト数です。先頭位置は1です。

ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。

bufp (IN/OUT)

ピースの読取り先バッファへのポインタです。buflのメモリー長が割り当てられるとみなされます。

bufl (IN)

オクテットで示したバッファの長さです。buflパラメータがバイト数で指定され、amtpパラメータが文字で指定されている場合、この値は、CLOBおよびNCLOBのamtp値(csfrm=SQLCS_NCHAR)とは異なります。

ctxp (IN)

コールバック関数用のコンテキスト・ポインタです。NULLにできます。

cbfp (IN)

各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、ピースごとにOCI_NEED_DATAが戻ります。

コールバック関数は、OCI_CONTINUEを戻して読取りを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの読取りは終了します。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。

len (IN)

bufpにおけるカレント・ピースのバイト長です。

piece (IN)

ピースは、OCI_FIRST_PIECE、OCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

csid (IN)

バッファ・データのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。サーバーとクライアントの設定が同一である場合を除き、サーバーのキャラクタ・セットとはみなされません。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - データベース・キャラクタ・セットID

- SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。csfrmが指定されていない場合は、デフォルトが使用されます。

コメント

LOBまたはBFILEの一部をコールの指定どおりにバッファに読み取ります。NULL属性のLOBまたはBFILEから読み取るとエラーになります。

注意:
LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm)を指定します。

BFILEの場合は、オペレーティング・システム・ファイルがサーバー上に存在しており、それらのファイルは、入力ロケータを使用してOCILobFileOpen()またはOCILobOpen()によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がOracle Databaseにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。

OCILobRead()に対してポーリング・モードを使用するとき、最初のコールではoffsetおよびamtpの値を指定する必要がありますが、その後のOCILobRead()のポーリング・コールではこれらの値を指定する必要はありません。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

注意:
OCILobRead()操作を終了して文ハンドルを解放するには、OCIBreak()コールを使用します。

次のルールは、CLOBおよびNCLOBのクライアント側可変幅キャラクタ・セットに適用されます。

- ポーリング・モードを使用する場合は、最初のOCILobRead()コールでamtpパラメータとoffsetパラメータのみ指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。

- コールバックを使用する場合、lenパラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenパラメータをチェックします。

次のルールは、CLOBおよびNCLOBのクライアント側の固定幅キャラクタ・セットおよびサーバー側の可変幅キャラクタ・セットに適用されます。

- CLOB値またはNCLOB値を読み取る場合は、OCILobRead()をコールするたびにamtpパラメータを参照し、バッファに格納された量を確認します。戻り値が文字数の場合(クライアント側のキャラクタ・セットが固定幅の場合)は、この値をバイトに変換して、バッファに格納された量を判断します。コールバックを使用する場合は、常にlenパラメータをチェックしてバッファに格納された量を確認します。この値は、常にバイト単位です。

UTF-16形式でデータを読み取るには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

関連項目:

- Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください。

- BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

- LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

- 付録B「OCIデモ・プログラム」

- ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

- 「OCIでのポーリング・モード操作」

関連関数

OCIErrorGet()、OCILobRead2()、OCILobWrite()、OCILobWrite2()、OCILobFileSetName()、OCILobWriteAppend()、OCILobWriteAppend2()

OCILobTrim()

用途

LOB値を短い長さに切り捨てます。この関数は非推奨です。OCILobTrim2()を使用してください。

構文

sword OCILobTrim ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCILobLocator   *locp,
ub4             newlen );

パラメータ

次を参照してください。
「OCILobTrim2()」

OCILobWrite()

用途

バッファをLOBに書き込みます。この関数は非推奨です。OCILobWrite2()を使用してください。

構文

sword OCILobWrite ( OCISvcCtx       *svchp,
OCIError        *errhp,
OCILobLocator   *locp,
ub4             *amtp,
ub4             offset,
void            *bufp,
ub4             buflen,
ub1             piece,
void            *ctxp,
OCICallbackLobWrite      (cbfp)
(
void     *ctxp,
void     *bufp,
ub4      *lenp,
ub1      *piecep
)
ub2             csid,
ub1             csfrm );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

amtp (IN/OUT)

表E-6に示すように、amtpの値は、バイト数または文字数のいずれかで表される量です。

表E-6 OCILobWrite()のamtpの文字数またはバイト数

LOBまたはBFILE

固定幅のクライアント側キャラクタ・セットによる入力

可変幅のクライアント側キャラクタ・セットによる入力

出力

BLOBおよびBFILE

バイト

バイト

バイト

CLOBおよびNCLOB

文字

バイト 脚注 1

文字

脚注 1 入力量は、ユーザーがLOBに書き込むデータのバイト数であり、bufp内のバイト数ではありません。これはbuflenで指定します。データがピース単位で書き込まれる場合、書き込むバイト量はbuflenより大きくなることがあります。出力量は、サーバー側のCLOBまたはNCLOBに書き込まれた文字数を表します。

これは、常にNULL以外のポインタにする必要があります。EOFまでの書込みを指定する場合は、変数を宣言してゼロを設定し、そのアドレスをこのパラメータに渡します。

入力時に量が指定されていて、データがピース単位で書き込まれる場合、パラメータamtpにはコール終了時(最後のピースが書き込まれた時点)に各ピースの長さの合計が格納され、書込み途中は未定義になります。ピース単位の読取りとは異なることに注意してください。指定された量がサーバーに送信されない場合は、エラーが戻されます。

amtpが0 (ゼロ)の場合は、ストリーム・モードが使用され、ユーザーがOCI_LAST_PIECEを指定するまでデータが書き込まれます。

offset (IN)

入力時、これはLOB値の先頭からの絶対オフセットです。文字LOBではLOBの先頭からの文字数であり、バイナリLOBではバイト数です。先頭位置は1です。

ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。

bufp (IN)

ピースの書込み元バッファへのポインタです。バッファ内のデータの長さは、buflenで渡された値であると想定しています。ポーリング・メソッドを使用してピース単位でデータが書き込まれている場合でも、bufpにはこのコール起動時のLOBの最初のピースを含める必要があります。コールバックを指定した場合は、bufpを使用してデータを指定しないでください。指定した場合、エラーが発生します。

buflen (IN)

バッファ内のデータの長さ(バイト数)です。buflenパラメータがバイト数で指定され、amtpパラメータが文字数で指定されている場合、この値は、CLOBおよびNCLOBのamtp値とは異なります。

注意:
このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、buflenの値を必要に応じて調整する必要があります。

piece (IN)

書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECEです。ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE、OCI_NEXT_PIECEおよびOCI_LAST_PIECEがあります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

cbfp (IN)

ピース単位書込みで各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、標準ポーリング・メソッドが使用されます。

コールバック関数は、OCI_CONTINUEを戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。コールバックは、次のパラメータを取ります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。このパラメータは、OCILobWrite()ルーチンに入力として渡されるbufpと同じです。

lenp (IN/OUT)

buffer (IN)内のデータのバイト数、およびbufp (OUT)内のカレント・ピースのバイト数です。

piecep (OUT)

ピースはOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

csid (IN)

バッファ内のデータのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - データベース・キャラクタ・セットID

- SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。

コメント

バッファを指定どおりに内部LOBに書き込みます。LOBにデータが存在する場合は、バッファに格納されたデータによって上書きされます。バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。

注意:
LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm)を指定します。

OCILobWrite()に対してポーリング・モードを使用するとき、最初のコールではoffsetおよびamtpの値を指定する必要がありますが、その後のOCILobWrite()のポーリング・コールではこれらの値を指定する必要はありません。

pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。

コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufpから書き込まれます。コールバック関数が定義されていない場合、OCILobWrite()は、OCI_NEED_DATAエラー・コードを戻します。LOBのピースの書込みを続けるには、アプリケーションでOCILobWrite()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。

pieceパラメータの値がOCI_LAST_PIECEのときは、ポーリングまたはコールバック方式が使用されているかどうかに関係なく、ピース単位書込み操作は終了します。

(どの入力方法を使用した場合も) Oracle Databaseに渡されるデータの量が、amtpパラメータに指定された量より少ない場合は、ORA-22993エラーが戻されます。

この関数は内部LOBでのみ有効です。BFILEは読取り専用のため、取り扱えません。LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

クライアント側のキャラクタ・セットが可変幅の場合、CLOBおよびNCLOBの入力量はバイト数で、出力量は文字数で表されます。入力量は、ユーザーがLOBに書き込むデータのバイト数であり、bufp内のバイト数ではありません。これはbuflenで指定します。データがピース単位で書き込まれる場合、書き込むバイト量はbuflenより大きくなることがあります。出力量は、サーバー側のCLOBまたはNCLOBに書き込まれた文字数を表します。

UTF-16形式でデータを書き込むには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:

- Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください。

- LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

- 付録B「OCIデモ・プログラム」

- ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください。

- 「OCIでのポーリング・モード操作」

関連関数

OCIErrorGet()、OCILobRead()、OCILobRead2()、OCILobAppend()、OCILobCopy()、OCILobCopy2()、OCILobWriteAppend()、OCILobWriteAppend2()、OCILobWrite2()

OCILobWriteAppend()

用途

LOBの末尾からデータの書込みを開始します。この関数は非推奨です。OCILobWriteAppend2()を使用してください。

構文

sword OCILobWriteAppend ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
void  *bufp,
ub4 buflen,
ub1 piece,
void  *ctxp,
OCICallbackLobWrite   (cbfp)
(
void     *ctxp,
void     *bufp,
ub4      *lenp,
ub1      *piecep
)
ub2 csid,
ub1 csfrm );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。

amtp (IN/OUT)

表E-7に示すように、amtpの値は、バイト数または文字数のいずれかで表される量です。

表E-7 OCILobWriteAppend()のamtpの文字数またはバイト数

LOBまたはBFILE

固定幅のクライアント側キャラクタ・セットによる入力

可変幅のクライアント側キャラクタ・セットによる入力

出力

BLOBおよびBFILE

バイト

バイト

バイト

CLOBおよびNCLOB

文字

バイト 脚注 1

文字

脚注 1 入力量は、ユーザーがLOBに書き込むデータのバイト数であり、bufp内のバイト数ではありません。これはbuflenで指定します。データがピース単位で書き込まれる場合、書き込むバイト量はbuflenより大きくなることがあります。出力量は、サーバー側のCLOBまたはNCLOBに書き込まれた文字数を表します。

入力時に量が指定されていて、データがピース単位で書き込まれる場合、パラメータamtpにはコール終了時(最後のピースが書き込まれた時点)に各ピースの長さの合計が格納され、書込み途中は未定義になります。(ピース単位の読取りとは異なることに注意してください)。指定された量がサーバーに送信されない場合は、エラーが戻されます。amtpが0 (ゼロ)の場合は、ストリーム・モードが使用され、ユーザーがOCI_LAST_PIECEを指定するまでデータが書き込まれます。

クライアント側のキャラクタ・セットが可変幅の場合、CLOBまたはNCLOBの入力量は文字ではなくバイトで表されます。

bufp(IN)

ピースの書込み元バッファへのポインタです。バッファ内のデータの長さは、buflenで渡された値であると想定しています。ピース単位でデータが書き込まれている場合でも、bufpにはこのコール起動時のLOBの最初のピースを含める必要があります。コールバックを指定した場合は、bufpを使用してデータを指定しないでください。指定した場合、エラーが発生します。

buflen (IN)

バッファ内のデータの長さ(バイト数)です。このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、buflenの値を必要に応じて調整する必要があります。

piece (IN)

書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECEです。ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE、OCI_NEXT_PIECEおよびOCI_LAST_PIECEがあります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

cbfp (IN)

ピース単位書込みで各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、標準ポーリング・メソッドが使用されます。コールバック関数は、OCI_CONTINUEを戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。コールバックは、次のパラメータを取ります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。

lenp (IN/OUT)

buffer (IN)内のデータのバイト数、およびbufp (OUT)内のカレント・ピースのバイト数です。

piecep (OUT)

ピースはOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

csid (IN)

バッファ・データのキャラクタ・セットIDです。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

- SQLCS_IMPLICIT - データベース・キャラクタ・セットID

- SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。

コメント

バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufpから書き込まれます。コールバック関数が定義されていない場合、OCILobWriteAppend()は、OCI_NEED_DATAエラー・コードを戻します。

LOBのピースの書込みを続けるには、アプリケーションでOCILobWriteAppend()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。pieceパラメータの値がOCI_LAST_PIECEのときは、ピース単位の書込みは終了します。

LOBバッファリングが有効な場合、OCILobWriteAppend()はサポートされません。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

クライアント側のキャラクタ・セットが可変幅の場合、CLOBまたはNCLOBの入力量は文字ではなくバイトで表されます。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:
「LOBの読取り/書込みパフォーマンスの向上」

関連関数

OCIErrorGet()、OCILobRead()、OCILobRead2()、OCILobAppend()、OCILobCopy()、OCILobCopy2()、OCILobWrite()、OCILobWrite2()、OCILobWriteAppend2()

非推奨のStreamsアドバンスト・キューイング関数

表E-8は、この項で説明している非推奨のStreamsアドバンスト・キューイング関数を示しています。

表E-8 非推奨のStreamsアドバンスト・キューイング関数

関数

用途

OCIAQListen()

リストのエージェントの代理として1つ以上のキューをリスニングします。

OCIAQListen()

用途

リストのエージェントのかわりに1つ以上のキューをリスニングします。この関数は非推奨です。OCIAQListen2()を使用してください。

構文

sword OCIAQListen (OCISvcCtx      *svchp,
OCIError       *errhp,
OCIAQAgent     **agent_list,
ub4            num_agents,
sb4            wait,
OCIAQAgent     **agent,
ub4            flags);

パラメータ

svchpp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

agent_list (IN)

メッセージを監視するエージェントのリストです。

num_agents (IN)

エージェント・リスト内のエージェント数です。

wait (IN)

リスニング・コールのタイムアウト時間です。

agent (OUT)

メッセージの出力先のエージェントです。OCIAgentはOCI記述子です。

flags (IN)

現行では使用されていません。OCI_DEFAULTとして渡されます。

コメント

メッセージが存在し、リスト内のエージェントに対してそのメッセージを使用する準備ができたときに戻されるブロッキング・コールです。待機時間が終了してもメッセージが検出されない場合は、エラーが戻されます。

関連関数

OCIAQEnq()、OCIAQDeq()、OCIAQListen2()、OCISvcCtxToLda()、OCISubscriptionEnable()、OCISubscriptionPost()、OCISubscriptionRegister()、OCISubscriptionUnRegister()

索引
A  B  C  D  E  F  G  H  I  K  L  M  N  O  P  Q  R  S  T  U  V  W  X

数字

64ビットの整数のサポート, 3.3.3

A

管理ハンドル, 10.2

属性, A.6

説明, 10.2

ADR, 10.5 ADRベースの場所, 10.5.1 ADR, 作成の制御, 10.5.3 ADRCIコマンドライン・ツール, 10.5.2 ADT

「オブジェクト型」を参照

アドバンスト・キューイング

エージェント記述子, 2.3.1.13

デキュー・オプション記述子, 2.3.1.13

記述子, 2.3.1.13.7

エンキュー・オプション記述子, 2.3.1.13

リスニング・オプション記述子, 2.3.1.13

メッセージ・プロパティ記述子, 2.3.1.13, 2.3.1.13

通知記述子, 2.3.1.13

利点

OCI, 1.1.1

割当て時間

例, 14.1.9.1

オブジェクト, 14.1.9

ANSI DATE記述子, 2.3.1.13 AnyData, 12.13 AnyDataSet, 12.13 AnyType, 12.13 アプリケーション・コンテキスト, 8.6 アプリケーションの初期化, 2.4.1.3 AQ

「Oracle Streamsアドバンストキューイング」を参照。

引数の属性, 6.2.11 配列

バインド, 12.14.4

定義, 12.15.3.1

DML, 最大行数, 5.1.2

スキップ・パラメータ, 5.5.1.1

構造体配列, 5.5

標識変数, 5.5.3

使用されるOCIコール, 5.5.2

スキップ・パラメータ, 5.5.1

アトミックNULL, 11.3.14 属性記述子オブジェクト, 12.12.1 属性

管理ハンドル, A.6

認証情報ハンドル, A.5.2

バインド・ハンドル, A.11

複合オブジェクト検索(COR)記述子, A.16.2

複合オブジェクト検索(COR)ハンドル, A.16.1

接続プール・ハンドル, A.7

連続問合せ通知, A.18.1

連続問合せ通知記述子, A.18.2

定義ハンドル, A.12

説明, A.12

記述ハンドル, A.13 ダイレクト・パス・ロード

列配列ハンドル, A.19.3

列パラメータ, A.19.5

コンテキスト・ハンドル, A.19.1

関数コンテキスト・ハンドル, A.19.2

ハンドル, A.19

ストリーム・ハンドル, A.19.4

環境ハンドル, A.2 エラー・ハンドル, A.3 イベント・ハンドル, A.21 LOBロケータ, A.15 通知記述子, A.18.3 OCIAQAgent記述子, A.17.4 OCIAQDeqOptions記述子, A.17.2 OCIAQEnqOptions記述子, A.17.1 OCIAQMsgProperties記述子, A.17.3 OCIServerDNs記述子, A.17.5 ハンドル, 2.3.1.12 オブジェクト, 11.3.9 パラメータ記述子, 6.2 パラメータ, 6.2 パラメータ記述子, A.14 プロセス・ハンドル, A.20 サーバー・ハンドル, A.5 サービス・コンテキスト・ハンドル, A.4 セッション・プール・ハンドル, A.8 文ハンドル, A.10 サブスクリプション・ハンドル, A.18 トランザクション・ハンドル, A.9 ユーザー・セッション・ハンドル, A.5.2 認証

識別名による, 8.4.1.3

X.509証明書による, 8.4.1.4

管理, 8.3.1

認証情報ハンドル, 2.3.1 認証関数, 16.1.10 自動診断リポジトリ(ADR), 10.5 自動ワークロード・リポジトリ(AWR), 10.4.5

B

BASICFILEパラメータ, 7.10

バッチ・エラー・モード, 4.4.2.1, 4.4.2.1

バッチ・ジョブ, 認証されたユーザー, 8.3.3

BFILE

データ型, 3.3.22.1, 3.3.22.1

最大サイズ, 7.6

BFILEデータ型ロケータ記述子, 2.3.1.13 binディレクトリ, D.2 BINARY_DOUBLEデータ型, 3.2.4 BINARY_FLOATデータ型, 3.2.4 文キャッシュでのバインドおよび定義, 9.5.4 バインド関数, 16.1.10 バインド・ハンドル

属性, A.11

説明, 2.3.1.5

バインド操作, 4.3, 5.1, 12.14

行われた関連付け, 5.1

例, 5.1.4

変数の初期化, 5.1

LOB, 5.2.1

名前付きデータ型, 12.14.1

名前付き対定位置, 5.1.1

OCI配列インタフェース, 5.1.2

OCI_DATA_AT_EXECモード, 5.2.2

PL/SQL, 5.1.3

定位置対名前付き, 5.1.1

REF CURSOR変数, 5.2.3

REF, 12.14.2

使用するステップ, 5.1.4

プレースホルダのバインド, 4.3.1 バインド

配列, 12.14.4

バッファの拡張, 5.8.3.3

複数バッファ, 5.6

OCINumber, 12.16.1

PL/SQLプレースホルダ, 2.7

要約, 5.2

BLOBデータ型, 3.3.22.2, 3.3.22.2 ブロック化モード, 2.6.9 ブランチ

連結解除, 8.2.3.5

複数の準備, 8.2.3.8

再開, 8.2.3.5

バインド時のバッファの拡張, 5.8.3.3 バッファ・メッセージ, 9.9.4 LOB操作のバッファリング, 7.7.2 OCIアプリケーションの構築, B

C

Cデータ型

OCIでの操作, 12.3

キャッシュ関数

サーバー・ラウンドトリップ, C.4

キャッシュ, クライアント結果, 10.4 コールバック

動的な登録, 9.6.1.6

LOB操作用, 7.7.4

LOBの読取り用, 7.7.4.2

LOBの書込み用, 7.7.4.3

外部プロシージャから, 9.6.2

LOBストリーム・インタフェース, 7.7.4.1

パラメータ・モード, 16.1.10

透過的アプリケーション・フェイルオーバーのための登録, 9.7.4

制限, 9.6.1.11

ユーザー定義関数, 9.6

カーソルの取消し, 17.1.1 OCIコールの取消し, 2.6.5 カートリッジ関数, 20 CASE OTTパラメータ, 15.8.2.10 変更通知記述子, 2.3.1.13 CHAR

外部データ型, 3.3.17

Unicodeのキャラクタ・セット変換, 2.8.8 キャラクタ・セット・フォーム, 5.8.1 キャラクタ・セットID, 5.8.1

Unicode, A.11, A.12

文字長セマンティクス, 5.8.3.3.1, 5.8.3.3.3, 5.8.3.4.1, 6.3 CHARZ

外部データ型, 3.3.18

checkerr()リスト化, 17.1.1 CHUNKサイズ, 7.6 クライアント結果キャッシュ, 10.4

最大サイズ, 10.4.4

CLIENTCONTEXTネームスペース, 8.6.1 CLOB

データ型, 3.3.22.3, 3.3.22.3

コード

サンプル・プログラム, B

デモ・プログラムのリスト, B

CODE OTTパラメータ, 15.8.2.4 コーディング・ガイドライン

予約語, 2.6.7

コヒーレンス

オブジェクト・キャッシュ, 14.1.1

コレクション

属性, 6.2.7

データ操作関数, 12.9.2

記述, 6.1

説明, 12.9

操作用関数, 12.9.1

マルチレベル, 12.10

スキャン関数, 12.9.3

列オブジェクト

ダイレクト・パス・ロード, 13.2.2

列

属性, 6.1.2.3, 6.2.10

コミット, 2.4.3

オブジェクト・アプリケーション, 14.1.8

グローバル・トランザクションの1フェーズ, 8.2.3.7

グローバル・トランザクションの2フェーズ, 8.2.3.7

互換性

OCIのリリース, 1.2

コンパイル

OCIアプリケーション, D.4

OCIとOracle XA, D.7.1

XAライブラリ, D.7

複合オブジェクト記述子, 2.3.1.13 複合オブジェクト検索, 11.3.10

記述子の属性, A.16.2

ハンドル, 2.3.1.7

ハンドル属性, A.16.1

実装, 11.3.10.2

ナビゲーショナル・プリフェッチ, 11.3.11

複合オブジェクト検索(COR)記述子, 2.3.1.13.6 COMPRESS, 7.10 CONFIG OTTパラメータ, 15.8.2.8 構成ファイル, D.2

位置, D.2

接続関数, 16.1.10 接続, 2.4.1.3 接続モード

非ブロック化, 2.6.9

接続プール・ハンドル

属性, A.7

説明, 2.3.1.11

初期化, 9.1.2.2

接続プーリング, 9.1, 9.4

コード例, 9.1.3

作成, 9.1.2.2

データベース常駐, 9.3

接続プールおよびTAF, 9.1.1.4 一貫性

オブジェクト・キャッシュ, 14.1.1

連続問合せ通知, 10.1

属性, A.18.1

記述子の属性, A.18.2

例, 10.1.6

コピー

オブジェクト, 11.3.15

COR

「複合オブジェクト検索」を参照

作成

オブジェクト, 11.3.15

カーソルの取消し, 17.1.1

D

データ・カートリッジ

OCI関数, 2, 20

データ定義言語

SQL文, 1.1.6.1

データ操作言語

SQL文, 1.1.6.3

データ構造, 2.3

「記述子」も参照

「ハンドル」も参照

データ型

ANSI DATE, 3.3.23.1

BFILE, 3.3.22.1

バインドと定義, 12.16

BLOB(バイナリ・ラージ・オブジェクト), 3.3.22.2

CLOB, 3.3.22.3

変換, 3.4

ダイレクト・パス・ロード, 13.1.1, A.19.5.1

外部, 3.1.1, 3.3

FILE, 3.3.22.1

ピース単位操作用, 5.10.1

内部, 3.2

内部コード, 3.2

INTERVAL DAY TO SECOND, 3.3.23.6

INTERVAL YEAR TO MONTH, 3.3.23.5

OCIでの操作, 12.3

マッピング関数および操作関数, C.6

OracleからCへのマッピング, 12.2

マッピング, Oracle方法論, 12.2.1

マッピング, OTTユーティリティ, 15.5

NCLOB, 3.3.22.4

Oracle, 3.1

TIMESTAMP, 3.3.23.2

TIMESTAMP WITH LOCAL TIME ZONE, 3.3.23.4

TIMESTAMP WITH TIME ZONE, 3.3.23.3

データベース接続

オブジェクト・アプリケーション用, 11.3.3

データベース常駐接続プーリング, 9.3 データベース型属性

型OCI_PTYPE_DATABASE, 6.2.14

データベース

属性, 6.2.14

記述, 6.1

停止, 10.2

起動, 10.2

DATE

外部データ型, 3.3.10

日付キャッシュ, 13.1.6 日付記述子, 2.3.1.13.5 DATE, ANSI

データ型, 3.3.23.1

日時

予期しない結果の回避, 3.3.23.7

日時および日付

アップグレード規則, 3.4.3

日時記述子, 2.3.1.13.5 DDL

「データ定義言語」を参照

DEDUPLICATE, 7.10 デフォルトのファイル名拡張子

OTTユーティリティ, 15.8.7

デフォルト名のマッピング

OTTユーティリティ, 15.8.7

定義

配列, 12.15.3.1

リターン・コードとエラー・コード, 2.5.1

定義関数, 16.1.10 定義ハンドル

属性, A.12

説明, 2.3.1.5

定義操作, 4.6, 5.3, 12.15

例, 5.3.1

LOB, 5.4.1

名前付きデータ型, 12.15.1

ピース単位フェッチ, 5.4.3

PL/SQL出力変数, 5.4.2

REF, 12.15.2

使用するステップ, 5.3.1

定義

複数バッファ, 5.6

OCINumber, 12.16.1

削除

位置指定, 2.6.6

デモ・ファイルの位置, 2.1 デモ・プログラム, B, D.3

リスト, B

記述

明示的, 4.5, 4.5.2

明示的および暗黙的, 6.1.2.3

暗黙的, 4.5, 4.5.1

コレクション, 6.1

データベース, 6.1

パッケージ, 6.1

スキーマ, 6.1

順序, 6.1

ストアド・ファンクション, 6.1

ストアド・プロシージャ, 6.1

シノニム, 6.1

表, 6.1

型, 6.1

ビュー, 6.1

選択リスト, 4.5

記述関数, 16.1.10 記述ハンドル

属性, A.13

説明, 2.3.1.6

記述操作

サーバー・ラウンドトリップ, C.5

ストアド・プロシージャの記述

例, 6.4.2

記述子, 2.3.1.13

アドバンスト・キューイング

エージェント, 2.3.1.13

デキュー・オプション, 2.3.1.13

エンキュー・オプション, 2.3.1.13

リスニング・オプション, 2.3.1.13

メッセージ・プロパティ, 2.3.1.13, 2.3.1.13

通知, 2.3.1.13

割当て, 2.4.1.2 ANSI DATE, 2.3.1.13 BFILEデータ型ロケータ, 2.3.1.13 変更通知, 2.3.1.13 複合オブジェクト, 2.3.1.13 複合オブジェクト検索, 2.3.1.13.6 登録要求でのデータベース・サーバーの識別名, 2.3.1.13 関数, 16.1.10 INTERVAL DAY TO SECOND, 2.3.1.13 INTERVAL YEAR TO MONTH, 2.3.1.13 LOBデータ型ロケータ, 2.3.1.13 オブジェクト, 12.12.1, 12.12.1 パラメータ, 2.3.1.13.3 読取り専用パラメータ, 2.3.1.13 結果セット, 2.3.1.13 行の変更, 2.3.1.13 ROWID, 2.3.1.13, 2.3.1.13.4 スナップショット, 2.3.1.13, 2.3.1.13.1 表の変更, 2.3.1.13 TIMESTAMP, 2.3.1.13 TIMESTAMP WITH LOCAL TIME ZONE, 2.3.1.13 TIMESTAMP WITH TIME ZONE, 2.3.1.13 ユーザー・コールバック, 2.3.1.13 ブランチの連結解除, 8.2.3.5 DIAG_ADR_ENABLED sqlnet.oraパラメータ, 10.5.3 DIAG_DDE_ENABLED sqlnet.oraパラメータ, 10.5.3 DIAG_RESTRICTED, 10.5.3 DIAG_SIGHANDLER_ENABLED, 10.5.3 ダイレクト・パス・ロード, 13.1

属性

OCI_ATTR_DIRPATH_NO_INDEX_ERRORS, 13.4.2.4

列配列ハンドル属性, A.19.3 列パラメータ属性, A.19.5 コンテキスト・ハンドル属性, A.19.1 列のデータ型, 13.1.1, A.19.5.1 ダイレクト・パス列配列ハンドル, 13.1.2.3 ダイレクト・パス・コンテキスト・ハンドル, 13.1.2.1 ダイレクト・パス関数コンテキスト, 13.1.2.2 ダイレクト・パス・ストリーム・ハンド, 13.1.2.4 例, 13.1.5 関数コンテキスト・ハンドル属性, A.19.2 関数, 13.1.3, 17.1.1 ハンドル属性, A.19 ハンドル, 2.3.1.10, 13.1.2 ピース単位, 13.3 制限, 13.1.4 日付列, 13.1.6 ストリーム・ハンドル属性, A.19.4 ディレクトリ構造, D.2 登録要求記述子でのデータベース・サーバーの識別名, 2.3.1.13 DML

「データ操作言語」を参照

DRCP (データベース常駐接続プーリング), 9.3 継続時間

例, 14.1.9.1

オブジェクト, 14.1.9

動的な登録

Oracle XAライブラリ, D.7.2

動的にリンクされたアプリケーション, 1.2.1

E

Editionベースの再定義, 8.7

Editions, 8.7

埋込みオブジェクト

フェッチ, 11.3.8

埋込みSQL, 1.1.6.6

OCIコールとの混在, 1.1.6.6

空のLOB, 挿入, 7.8.1 ENCRYPT, 7.10 拡張DML配列

機能, 4.4.2.1, 4.4.2.1

環境ハンドル

属性, A.2

説明, 2.3.1.2

エラー・チェック例, 17.1.1 エラー・コード

定義コール, 2.5.1

ナビゲーショナル関数, 18.1.7

エラー・ハンドル

属性, A.3

説明, 2.3.1.3

エラー

処理, 2.5

オブジェクト・アプリケーションでの処理, 11.3.19

ERRTYPE OTTパラメータ, 15.8.2.9 評価コンテキスト

属性, 6.2.17

評価コンテキスト属性, 6.2.17 イベント・コールバック, 9.8.4 イベント・ハンドル属性, A.21 例

デモ・プログラム, B

SQL文の実行, 4.4 実行

複数サーバーに対する, 4.2.1

モード, 4.4.2

スナップショット, 4.4.1

明示的記述, 4.5, 6.3.2 拡張子

OTTユーティリティのデフォルト・ファイル名, 15.8.7

外部データ型, 3.1.1, 3.3

CHAR, 3.3.17

CHARZ, 3.3.18

変換, 3.4

DATE, 3.3.10

FLOAT, 3.3.5

INTEGER, 3.3.4

LOB, 3.3.22

LONG, 3.3.8

LONG RAW, 3.3.13

LONG VARCHAR, 3.3.15

LONG VARRAW, 3.3.16

名前付きデータ型, 3.3.19

NUMBER, 3.3.2

RAW, 3.3.11

REF, 3.3.20

ROWID, 3.3.21

SQLT_BLOB, 3.3.22

SQLT_CLOB, 3.3.22

SQLT_NCLOB, 3.3.22

SQLT_NTY, 3.3.19

SQLT_REF, 3.3.20

STRING, 3.3.6

UNSIGNED, 3.3.14

VARCHAR, 3.3.9

VARCHAR2, 3.3.1

VARNUM, 3.3.7

VARRAW, 3.3.12

外部プロシージャ関数

リターン・コード, 20.1.2

with_context型, 20.1.3

外部プロシージャ

OCIコールバック, 9.6.2

外部で初期化されたコンテキスト, 8.5

F

フェイルオーバー

コールバックの例, 9.7.5

フェイルオーバー・コールバック, 9.7

構造およびパラメータ, 9.7.3

高速アプリケーション通知(FAN), 9.2.8 障害診断, 10.5

クライアント・ドライバ・レイヤー名の読取りまたは書込み, A.5.2

フェッチ

ピース単位, 5.10, 5.10.6

フェッチ操作, 4.7

LOBデータ, 4.7.1

プリフェッチ・カウントの設定, 4.7.2

FILE

オペレーティング・システム・ファイルとの関連付け, 7.3

データ型, 3.3.22.1

FLOAT

外部データ型, 3.3.5

フラッシュ, 14.1.6.1

オブジェクトの変更, 11.3.7

オブジェクト, 14.1.6.1

解放

オブジェクト, 11.3.15, 14.1.4.3

関数

属性, 6.2.2

G

汎用参照ドキュメント

OCIアプリケーションのコンパイルおよびリンク, D.4, D.5

デモ・プログラム, D.3

コマンドラインからのOTTの起動, D.8

XAリンク・ファイル名, D.7

グローバル・トランザクション, 8.2.3 グローバリゼーション・サポート, 2.8

OCI関数, 2

GTRID.「トランザクション識別子」を参照

H

HAイベント通知, 9.8

ハンドル属性, 2.3.1.12

ハンドル関数, 16.1.10

ハンドル・タイプ定数, 2.3.1

ハンドル, 2.3.1, 2.3.1

管理ハンドル, 10.2, 10.2, A.6

利点, 2.3.1.1

割当て, 2.3.1.1, 2.4.1.2

バインド・ハンドル, 2.3.1.5, A.11

Cデータ型, 2.3.1

親が解放される際に解放される子, 2.3.1.1

複合オブジェクト検索ハンドル, 2.3.1.7, A.16.1

接続プール・ハンドル, 2.3.1.11, 9.1.2.2, A.7

定義ハンドル, 2.3.1.5, A.12

記述ハンドル, 2.3.1.6, A.13

ダイレクト・パス・ロード, 2.3.1.10

環境ハンドル, 2.3.1.2, A.2

エラー・ハンドル, 2.3.1.3, A.3

解放, 2.3.1.1

プロセス属性, A.20

サーバー・ハンドル, 2.3.1.4, 2.3.1.4, A.5

サービス・コンテキスト・ハンドル, 2.3.1.4, A.4

文ハンドル, 2.3.1.5, A.10

サブスクリプション, 2.3.1.9, 9.10.1.1

トランザクション・ハンドル, 2.3.1.4, A.9

タイプ, 2.3.1

ユーザー・セッション・ハンドル, 2.3.1.4, 2.3.1.4, A.5.2

ヘッダー・ファイル

位置, 1.1.12, 2.1, D.2, D.4

oratypes.h, 3.6

HFILE OTTパラメータ, 15.8.2.7

I

暗黙的な記述, 4.5, 6.3.1

includeディレクトリ, D.2

標識変数, 2.6.4

構造体配列, 5.5.3

名前付きデータ型, 2.6.3, 2.6.4.3

REF用, 2.6.3, 2.6.4.3

名前付きデータ型の定義, 12.15.3

PL/SQL OUTバインド, 12.15.3

REF定義, 12.15.3

名前付きデータ型のバインド, 12.14.3

REFバインド, 12.14.3

INITFILE OTTパラメータ, 15.8.2.5 INITFUNC OTTパラメータ, 15.8.2.6 初期化

すべてのバッファ, 5.1.3

関数, 16.1.10

init.oraのセキュリティ・パラメータ, 8.8 空のLOBの挿入, 7.8.1 挿入

ピース単位, 5.10, 5.10.3

インスタント・クライアント, 1.3 Instant Client Light (English), 1.3.8 INTEGER外部データ型, 3.3.4 データ型の内部コード, 3.2 内部データ型, 3.2

変換, 3.4

INTERVAL DAY TO SECONDデータ型, 3.3.23.6 INTERVAL DAY TO SECOND記述子, 2.3.1.13 間隔記述子, 2.3.1.13.5 INTERVAL YEAR TO MONTHデータ型, 3.3.23.5 INTERVAL YEAR TO MONTH記述子, 2.3.1.13 intypeファイル

OTTユーティリティの実行時に提供, 15.4

構造, 15.8.4

INTYPEファイル・アシスタント, D.8 INTYPE OTTパラメータ, 15.8.2.2 IPアドレス

IPv4, A.18

IPv6, A.18

IPv6アドレス, 9.10.1.1, A.18, A.18

K

KEEP_DUPLICATES, 7.10

キーワード, 2.6.7

L

パブリッシュ・サブスクライブ通知のLDAP登録, 9.10.1.3

ライブラリ

oci.lib, D.5

リンク

OCIアプリケーション, D.5

OCIとOracle XA, D.7.1

XAライブラリ, D.7

リスト属性

型OCI_PTYPE_LIST, 6.2.12

リスト

属性, 6.2.12

lmsgenユーティリティ, 2.8.10 LoadLibrary, D.5.2 LOBおよびLONGのバインド属性, 5.2.1.2.1 LOBデータ型ロケータ記述子, 2.3.1.13 LOB関数, 17.1.1

サーバー・ラウンドトリップ, C.3

LOBロケータ, 2.3.1.13.2

属性, A.15

LOB

amountパラメータおよびoffsetパラメータ, 17.1.1

一時オブジェクトの属性, 7.4.2

バインド, 5.2.1

バッファリング, 7.7.2

コールバック, 7.7.4

キャラクタ・セット, 17.1.1

作成, 7.2

一時の作成, 7.8.1

定義, 5.4.1

一時の継続時間, 7.8.2

一時の例, 7.8.5

外部データ型, 3.3.22

フェイルオーバーは機能しない, 9.7.6

データのフェッチ, 4.7.1

固定幅キャラクタ・セット, 17.1.1

一時の解放, 7.8.1

4GBより大きい, 7.6

ロケータ, 2.3.1.13.2

変更, 7.2

OCI関数, 7.7

プリフェッチ, 7.9

最大サイズ, 7.6

一時, 7.8

可変幅キャラクタ・セット, 17.1.1

ロケータ, 2.3.1.13

LOBデータ型, 2.3.1.13.2

ロック, 14.1.7.2

オブジェクト, 14.1.7.2

最適モデル, 14.1.7.4

LONG

外部データ型, 3.3.8

LONG RAW

外部データ型, 3.3.13

LONG VARCHAR

外部データ型, 3.3.15

LONG VARRAW

外部データ型, 3.3.16

M

make.batファイル, D.3

Makefile, 2.1, 2.1, B

オブジェクトのマーク, 14.1.5.1

メタ属性

オブジェクト, 11.3.9

永続オブジェクト, 11.3.9.1

一時オブジェクト, 11.3.9.3

メソッド記述子オブジェクト, 12.12.1 メソッド結果

型OCI_PTYPE_TYPE_RESULT, 6.2.11

移行

7.xから8.0, 1.2.5

セッション, 8.3.1, 16.1.10

その他の関数, 17.1.1 複数サーバー

文の実行, 4.2.1

マルチスレッド開発

基本概念, 8.9

マルチスレッド, 8.9 mutex, 8.9

N

名前付きデータ型

バインド, 12.14.1

バインドと定義, 12.16

定義, 12.15.1

定義, 3.3.19

外部データ型, 3.3.19

標識変数, 2.6.4.3

標識変数, 2.6.3

名前/値ペアの属性

型OCI_PTYPE_NAME_VALUE, 6.2.20

システム固有のdouble, 3.3.24 システム固有のfloat, 3.3.24 ナビゲーション, 14.2 ナビゲーショナル関数

エラー・コード, 18.1.7

戻り値, 18.1.5

用語, 18.1.2

NCHAR

問題, 5.8

NCLOB

データ型, 3.3.22.4, 3.3.22.4

ネストした表

ダイレクト・パス・ロード, 13.2.1

要素順序, 12.9.5.1

操作用関数, 12.9.5

新規リリース, 再リンク, 1.2.1 NLS_LANG, 2.8.1 NLS_NCHAR, 2.8.1 NOCOMPRESS, 7.10 NOENCRYPT, 7.10 非ブロック化モード, 2.6.9 非遅延リンケージはサポート外, 8.8.3 NOT FINALオブジェクト表

ダイレクト・パス・ロード, 13.2.7

通知記述子属性, A.18.3 NULLインジケータ

オブジェクト属性に関する設定, 11.3.14

NULLインジケータ構造体, 11.3.14

OTTで生成された, 11.3.1

NULL

オブジェクト, 11.3.14

NULL

アトミック, 11.3.14

挿入, 2.6.4.1

データベースに挿入, 2.6.3

標識変数を使用して挿入, 2.6.3

NUMBER

外部データ型, 3.3.2

O

オブジェクト・アプリケーション

コミット, 14.1.8

データベース接続, 11.3.3

ロールバック, 14.1.8

オブジェクト・キャッシュ, 14.1

コヒーレンス, 14.1.1

一貫性, 14.1.1

初期化, 11.3.2

オブジェクトのロード, 14.1.4

メモリー・パラメータ, 14.1.2

操作, 14.1.3

オブジェクトの削除, 14.1.4

サイズの設定, 14.1.2

オブジェクト関数

サーバー・ラウンドトリップ, C.4

オブジェクト識別子, 11.3.17, 11.3.18

永続オブジェクト用, 11.2.2

オブジェクト参照, 11.3.17

「REF」を参照

オブジェクト・ランタイム環境

初期化, 11.3.2

オブジェクト表

ダイレクト・パス・ロード, 13.2.6

オブジェクト型

Cアプリケーションでの表現, 11.3.1

Object Type Translatorユーティリティ

「OTTユーティリティ」を参照

オブジェクト・ビュー, 11.3.9.1 オブジェクト

OCIでのアクセス, 15.7.1

割当て時間, 14.1.9

配列確保, 11.3.5.1

属性, 11.3.9

操作, 11.3.6

クライアント側キャッシュ, 14.1 コピー, 11.3.15 作成, 11.3.15 継続時間, 14.1.9 フラッシュ, 14.1.6.1 変更のフラッシュ, 11.3.7 解放, 11.3.15, 14.1.4.3 存続期間, 18.1.1 LOB一時オブジェクトの属性, 7.4.2 ロック, 14.1.7.2 OCIでの操作, 15.7.1 マーキング, 11.3.7, 14.1.5.1 インスタンスのメモリー・レイアウト, 14.1.10 メモリー管理, 14.1 メタ属性, 11.3.9 ナビゲーション, 14.2

単純, 14.2.1

NCHARおよびNVARCHAR2属性, 12.2 NULL値, 11.3.14 OCIオブジェクト・アプリケーション構造体, 11.2.1 永続, 11.2.2, 11.2.2.1 確保カウント, 11.3.13 確保継続時間, 14.1.9 確保, 11.3.5, 14.1.4.1 リフレッシュ, 14.1.6.2 2次メモリー, 14.1.10 用語, 11.2.2, 18.1.1 トップレベル・メモリー, 14.1.10 一時, 11.2.2, 11.2.2.2 型, 11.2.2, 18.1.1 マーク解除, 14.1.5.2 確保解除, 14.1.4.2 OCIでの使用方法, 11.1 OCI

コールの終了, 2.6.5

オブジェクトへのアクセスおよび操作, 15.7.1

利点, 1.1.1

オブジェクトのサポート, 1.1.5

Oracle XAライブラリ, D.7.1

概要, 1.1

分類, 1.1.3

サンプル・プログラム, D.3

OCIアプリケーション

コンパイル, 1.1.2, D.4

一般的構造, 2.2

初期化例, 2.4.1.3.3

リンク, 1.1.2, D.5

実行, D.6

ステップ, 2.4

構造, 2.2

オブジェクトを使用した構造体, 11.2.1

終了, 2.4.4

OTTユーティリティの使用, 15.7

オブジェクト付き

初期化, 11.3.2

OCIディレクトリ, D.2 OCI環境

オブジェクトの初期化, 11.3.2

OCI関数

コールの取消し, 2.6.5

データ・カートリッジ, 2

グローバリゼーション, 2

未サポート, 1.2.4

使用されなくなった, 1.2.3

リターン・コード, 2.5, 2.5.2

OCIハンドル・タイプ, 2.3.1 OCIナビゲーショナル関数, 14.3

フラッシュ関数, 14.3.2

マーク関数, 14.3.3

メタ属性アクセッサ関数, 14.3.4

その他の関数, 14.3.5

ネーミング計画, 14.3

確保/確保解除/解放関数, 14.3.1

OCIプロセス

オブジェクトの初期化, 11.3.2

OCIプログラム

「OCIアプリケーション」を参照

OCIリレーショナル関数

接続, 認証および初期化, 16.1.10

参照項目の概要, 20.1.1

Oracle Streamsアドバンスト・キューイングおよびパブリッシュ・サブスクライブ, 17.1.1, E

OCI_ATTR_ACCESS_BANNER, 8.8.2

サーバー・ハンドル属性, A.5

OCI_ATTR_ACTION, 8.5.2.3, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_ADMIN_PFILE

管理ハンドル属性, A.6

OCI_ATTR_AGENT_ADDRESS

OCIAQAgent記述子属性, A.17.4

OCI_ATTR_AGENT_NAME

OCIAQAgent記述子属性, A.17.4

OCI_ATTR_AGENT_PROTOCOL

OCIAQAgent記述子属性, A.17.4

OCI_ATTR_ALLOC_DURATION

環境ハンドル属性, A.2

OCI_ATTR_APPCTX_ATTR, 8.5.1.3

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_APPCTX_LIST, 8.5.1.2

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_APPCTX_NAME, 8.5.1.3

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_APPCTX_SIZE, 8.5.1.1, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_APPCTX_VALUE, 8.5.1.3

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_AQ_NTFN_GROUPING_ MSGID_ARRAY

通知記述子属性, A.18.3

OCI_ATTR_AQ_NTFN_GROUPING_COUNT, 9.10.2

通知記述子属性, A.18.3

OCI_ATTR_AQ_NTFN_GROUPING_MSGID_ARRAY, 9.10.2 OCI_ATTR_ATTEMPTS

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_AUDIT_BANNER, 8.8.2

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_AUTOCOMMIT_DDL

属性, 6.2.14

OCI_ATTR_BIND_COUNT

文ハンドル属性, A.10

OCI_ATTR_BIND_DN, 9.10.1.3

環境ハンドル属性, A.2

OCI_ATTR_BREAK_ON_NET_TIMEOUT

サーバー・ハンドル属性, A.5

OCI_ATTR_BUF_ADDR

ダイレクト・パス・ロード・ストリーム・ハンドル属性, A.19.4

OCI_ATTR_BUF_SIZE

ダイレクト・パス・ロード

コンテキスト・ハンドル属性, A.19.1

ストリーム・ハンドル属性, A.19.4

OCI_ATTR_CACHE

属性, 6.2.9

OCI_ATTR_CACHE_ARRAYFLUSH, 14.1.6.1

環境ハンドル属性, A.2

OCI_ATTR_CACHE_MAX_SIZE, 14.1.2

環境ハンドル属性, A.2

OCI_ATTR_CACHE_OPT_SIZE, 14.1.2

環境ハンドル属性, A.2

OCI_ATTR_CALL_TIME, 8.5.2.2

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_CATALOG_LOCATION

属性, 6.2.14

OCI_ATTR_CERTIFICATE, 8.4.1.4, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_CHAR_COUNT

バインド・ハンドル属性, A.11

定義ハンドル属性, A.12

OCI_ATTR_CHAR_SIZE, 6.2.10

属性, 6.3, 6.3.2

OCI_ATTR_CHAR_USED, 6.2.10

属性, 6.3, 6.3.2

OCI_ATTR_CHARSET_FORM, 5.8.1.1

属性, 6.2.5, 6.2.7, 6.2.10, 6.2.11

バインド・ハンドル属性, A.11

定義ハンドル属性, A.12

OCI_ATTR_CHARSET_ID, 5.8.1.1

属性, 6.2.5, 6.2.7, 6.2.10, 6.2.11, 6.2.14

バインド・ハンドル属性, A.11

定義ハンドル属性, A.12

ダイレクト・パス・ロード

列パラメータ属性, A.19.5.1

コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_CHDES_DBNAME, 10.1.5.1

連続問合せ通知記述子属性, A.18.2

OCI_ATTR_CHDES_NFTYPE, 10.1.5.1

連続問合せ通知記述子属性, A.18.2

OCI_ATTR_CHDES_QUERIES, 10.1.5.1 OCI_ATTR_CHDES_ROW_OPFLAGS, 10.1.5.1.2

連続問合せ通知記述子属性, A.18.2

OCI_ATTR_CHDES_ROW_ROWID, 10.1.5.1.2

連続問合せ通知記述子属性, A.18.2

OCI_ATTR_CHDES_TABLE_CHANGES, 10.1.5.1

連続問合せ通知記述子属性, A.18.2

OCI_ATTR_CHDES_TABLE_NAME, 10.1.5.1.2

連続問合せ通知記述子属性, A.18.2

OCI_ATTR_CHDES_TABLE_OPFLAGS, 10.1.5.1.2

連続問合せ通知記述子属性, A.18.2

OCI_ATTR_CHDES_TABLE_ROW_CHANGES, 10.1.5.1.2

連続問合せ通知記述子属性, A.18.2

OCI_ATTR_CHDES_XID, 10.1.5.1 OCI_ATTR_CHNF_CHANGELAG, 10.1.3

連続問合せ通知属性, A.18.1

OCI_ATTR_CHNF_OPERATIONS, 10.1.3

連続問合せ通知属性, A.18.1

OCI_ATTR_CHNF_REGHANDLE

文ハンドル属性, A.10

OCI_ATTR_CHNF_ROWIDS, 10.1.3

連続問合せ通知属性, A.18.1

OCI_ATTR_CHNF_TABLENAMES, 10.1.3

連続問合せ通知属性, A.18.1

OCI_ATTR_CLIENT_IDENTIFIER, 8.4.1.6, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_CLIENT_INFO, 8.5.2.3, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_CLUSTERED

属性, 6.2.1

OCI_ATTR_COL_COUNT

ダイレクト・パス・ロード列配列ハンドル属性, A.19.3

OCI_ATTR_COLLECT_CALL_TIME, 8.5.2.1, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_COLLECTION_ELEMENT

属性, 6.2.4

OCI_ATTR_COLLECTION_TYPECODE

属性, 6.2.4

OCI_ATTR_COMMENT

属性, 6.2.15, 6.2.16, 6.2.17

OCI_ATTR_COMPLEXOBJECT_ COLL_OUTOFLINE

CORハンドル属性, A.16.1

OCI_ATTR_COMPLEXOBJECT_LEVEL

CORハンドル属性, A.16.1

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE_LEVEL

COR記述子の属性, A.16.2

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE

COR記述子の属性, A.16.2

OCI_ATTR_CONDITION

属性, 6.2.15

OCI_ATTR_CONN_BUSY_COUNT

接続プール・ハンドル属性, A.7

OCI_ATTR_CONN_INCR

接続プール・ハンドル属性, A.7

OCI_ATTR_CONN_MAX

接続プール・ハンドル属性, A.7

OCI_ATTR_CONN_MIN

接続プール・ハンドル属性, A.7

OCI_ATTR_CONN_NOWAIT

接続プール・ハンドル属性, A.7

OCI_ATTR_CONN_OPEN_COUNT

接続プール・ハンドル属性, A.7

OCI_ATTR_CONN_TIMEOUT, 9.1.2.2

接続プール・ハンドル属性, A.7

OCI_ATTR_CONNECTION_CLASS, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_CONSUMER_NAME, 9.10.2, A.17.2

通知記述子属性, A.18.3

OCI_ATTR_CORRELATION

OCIAQDeqOptions記述子属性, A.17.2

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_CQ_QUERYID, 10.1.4

文ハンドル属性, A.10

OCI_ATTR_CQDES_OPERATION, 10.1.5.1.1

ダイレクト・パス・ロード・ハンドル属性, A.18.4

OCI_ATTR_CQDES_QUERYID, 10.1.5.1.1

ダイレクト・パス・ロード・ハンドル属性, A.18.4

OCI_ATTR_CQDES_TABLE_CHANGES, 10.1.5.1.1

ダイレクト・パス・ロード・ハンドル属性, A.18.4

OCI_ATTR_CURRENT_POSITION

属性, 4.8

文ハンドル属性, A.10

OCI_ATTR_CURRENT_SCHEMA, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_CURSOR_COMMIT_BEHAVIOR

属性, 6.2.14

OCI_ATTR_DATA_SIZE, 6.2.10, 6.3

属性, 6.2.5, 6.2.7, 6.2.10, 6.2.11, 6.3.2

ダイレクト・パス・ロード列パラメータ属性, A.19.5.1

OCI_ATTR_DATA_TYPE

属性, 6.1.2.1, 6.2.5, 6.2.7, 6.2.10, 6.2.11

ダイレクト・パス・ロード列パラメータ属性, A.19.5.1

OCI_ATTR_DATEFORMAT

ダイレクト・パス・ロード

列パラメータ属性, A.19.5.1

コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DBDOMAIN

イベント・ハンドル属性, A.21

OCI_ATTR_DBNAME

イベント・ハンドル属性, A.21

OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE, 7.9, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_DELAY

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_DEQ_MODE

OCIAQDeqOptions記述子属性, A.17.2

OCI_ATTR_DEQ_MSGID

OCIAQDeqOptions記述子属性, A.17.2

OCI_ATTR_DEQCOND

OCIAQDeqOptions記述子属性, A.17.2

OCI_ATTR_DESC_PUBLIC, 16.1.10 OCI_ATTR_DIRPATH_DCACHE_DISABLE, 13.1.6.5

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_DCACHE_HITS, 13.1.6.4

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_DCACHE_MISSES, 13.1.6.3

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_DCACHE_NUM, 13.1.6.2

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_DCACHE_SIZE, 13.1.6.1

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_EXPR_TYPE

ダイレクト・パス関数コンテキスト・ハンドル属性, A.19.2

関数コンテキスト属性, 13.4.2.3

OCI_ATTR_DIRPATH_INDEX_MAINT_METHOD

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_MODE

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_NO_INDEX_ERRORS, 13.4.2.4

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_NOLOG

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_OBJ_CONSTR, 13.4.2.1

ダイレクト・パス・コンテキスト属性, 13.4.1.1

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_OID

ダイレクト・パス・ロード列パラメータ属性, A.19.5.1

OCI_ATTR_DIRPATH_PARALLEL, 13.1

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DIRPATH_SID

列配列属性, 13.4.3.2

ダイレクト・パス・ロード列パラメータ属性, A.19.5.1

OCI_ATTR_DIRPATH_SKIPINDEX_METHOD

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_DISTINGUISHED_NAME, 8.4.1.3, 8.4.1.4, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_DML_ROW_OFFSET

エラー・ハンドル属性, A.3

OCI_ATTR_DN_COUNT

OCIServerDNs記述子の属性, A.17.5

OCI_ATTR_DRIVER_NAME, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_DURATION

属性, 6.2.1

OCI_ATTR_EDITION, 8.7, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_ENCAPSULATION

属性, 6.2.6

OCI_ATTR_ENQ_TIME

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_ENV

サーバー・ハンドル属性, A.5

サービス・コンテキスト・ハンドル属性, A.4

文ハンドル属性, A.10

OCI_ATTR_ENV_CHARSET_ID, 2.8.2

環境ハンドル属性, A.2

OCI_ATTR_ENV_NCHARSET_ID, 2.8.2

環境ハンドル属性, A.2

OCI_ATTR_ENV_UTF16

環境ハンドル属性, A.2

OCI_ATTR_EVAL_CONTEXT_NAME

属性, 6.2.15, 6.2.16

OCI_ATTR_EVAL_CONTEXT_OWNER

属性, 6.2.15, 6.2.16

OCI_ATTR_EVALUATION_FUNCTION

属性, 6.2.17

OCI_ATTR_EVENTTYPE

イベント・ハンドル属性, A.21

OCI_ATTR_EVTCBK, 9.8.4

環境ハンドル属性, A.2

OCI_ATTR_EVTCTX, 9.8.4

環境ハンドル属性, A.2

OCI_ATTR_EXCEPTION_QUEUE

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_EXPIRATION

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_EXTERNAL_NAME, 8.2.3.6

サーバー・ハンドル属性, A.5

OCI_ATTR_FETCH_ROWID, 10.3

文ハンドル属性, A.10

OCI_ATTR_FOCBK

サーバー・ハンドル属性, A.5

OCI_ATTR_FSPRECISION

属性, 6.2.5

OCI_ATTR_HA_SOURCE

イベント・ハンドル属性, A.21

OCI_ATTR_HA_SRVFIRST, 9.8.4

イベント・ハンドル属性, A.21

OCI_ATTR_HA_SRVNEXT, 9.8.4

イベント・ハンドル属性, A.21

OCI_ATTR_HA_STATUS

イベント・ハンドル属性, A.21

OCI_ATTR_HA_TIMESTAMP

イベント・ハンドル属性, A.21

OCI_ATTR_HAS_DEFAULT

属性, 6.2.11

OCI_ATTR_HAS_FILE

属性, 6.2.4

OCI_ATTR_HAS_LOB

属性, 6.2.4

OCI_ATTR_HAS_NESTED_TABLE

属性, 6.2.4

OCI_ATTR_HEAPALLOC

環境ハンドル属性, A.2

OCI_ATTR_HOSTNAME

イベント・ハンドル属性, A.21

OCI_ATTR_HW_MARK

属性, 6.2.9

OCI_ATTR_IN_V8_MODE

サーバー・ハンドル属性, A.5

サービス・コンテキスト・ハンドル属性, A.4

OCI_ATTR_INCR

属性, 6.2.9

OCI_ATTR_INDEX_ONLY

属性, 6.2.1

OCI_ATTR_INITIAL_CLIENT_ROLES, 8.4.1.5, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_INSTNAME

イベント・ハンドル属性, A.21

OCI_ATTR_INSTSTARTTIME

イベント・ハンドル属性, A.21

OCI_ATTR_INTERNAL_NAME, 8.2.3.6

サーバー・ハンドル属性, A.5

OCI_ATTR_IOMODE

属性, 6.2.11

OCI_ATTR_IS_CONSTRUCTOR

属性, 6.2.6

OCI_ATTR_IS_DESTRUCTOR

属性, 6.2.6

OCI_ATTR_IS_FINAL_METHOD

属性, 6.2.6

OCI_ATTR_IS_FINAL_TYPE

属性, 6.2.4

OCI_ATTR_IS_INCOMPLETE_TYPE

属性, 6.2.4

OCI_ATTR_IS_INSTANTIABLE_METHOD

属性, 6.2.6

OCI_ATTR_IS_INSTANTIABLE_TYPE

属性, 6.2.4

OCI_ATTR_IS_INVOKER_RIGHTS

属性, 6.2.2, 6.2.3, 6.2.4

OCI_ATTR_IS_MAP

属性, 6.2.6

OCI_ATTR_IS_NULL

属性, 6.2.10, 6.2.11

OCI_ATTR_IS_OPERATOR

属性, 6.2.6

OCI_ATTR_IS_ORDER

属性, 6.2.6

OCI_ATTR_IS_OVERRIDING_METHOD

属性, 6.2.6

OCI_ATTR_IS_PREDEFINED_TYPE

属性, 6.2.4

OCI_ATTR_IS_RNDS

属性, 6.2.6

OCI_ATTR_IS_RNPS

属性, 6.2.6

OCI_ATTR_IS_SELFISH

属性, 6.2.6

OCI_ATTR_IS_SUBTYPE

属性, 6.2.4

OCI_ATTR_IS_SYSTEM_GENERATED_TYPE

属性, 6.2.4

OCI_ATTR_IS_SYSTEM_TYPE

属性, 6.2.4

OCI_ATTR_IS_TEMPORARY

属性, 6.2.1

OCI_ATTR_IS_TRANSIENT_TYPE

属性, 6.2.4

OCI_ATTR_IS_TYPED

属性, 6.2.1

OCI_ATTR_IS_WNDS

属性, 6.2.6

OCI_ATTR_IS_WNPS

属性, 6.2.6

OCI_ATTR_LDAP_AUTH, 9.10.1.3

環境ハンドル属性, A.2

OCI_ATTR_LDAP_CRED, 9.10.1.3

環境ハンドル属性, A.2

OCI_ATTR_LDAP_CTX, 9.10.1.3

環境ハンドル属性, A.2

OCI_ATTR_LDAP_HOST, 9.10.1.3

環境ハンドル属性, A.2

OCI_ATTR_LDAP_PORT, 9.10.1.3

環境ハンドル属性, A.2

OCI_ATTR_LEVEL

属性, 6.2.11

OCI_ATTR_LFPRECISION

属性, 6.2.5

OCI_ATTR_LINK

属性, 6.2.8, 6.2.11

OCI_ATTR_LIST_ACTION_CONTEXT

属性, 6.2.15

OCI_ATTR_LIST_ARGUMENTS

属性, 6.1.2.4, 6.2.2, 6.2.6, 6.2.11

OCI_ATTR_LIST_COLUMNS

属性, 6.2.1

ダイレクト・パス・ロード

コンテキスト・ハンドル属性, A.19.1

関数コンテキスト・ハンドル属性, A.19.2

OCI_ATTR_LIST_OBJECTS

属性, 6.2.13

OCI_ATTR_LIST_RULES

属性, 6.2.16

OCI_ATTR_LIST_SCHEMAS

属性, 6.2.14

OCI_ATTR_LIST_SUBPROGRAMS

属性, 6.2.3

OCI_ATTR_LIST_TABLE_ALIASES

属性, 6.2.17

OCI_ATTR_LIST_TYPE

属性, 6.2.12

OCI_ATTR_LIST_TYPE_ATTRS

属性, 6.2.4

OCI_ATTR_LIST_TYPE_METHODS

属性, 6.2.4

OCI_ATTR_LIST_VARIABLE_TYPES

属性, 6.2.17

OCI_ATTR_LOBEMPTY

LOBロケータ属性, A.15

OCI_ATTR_LOBPREFETCH_LENGTH, 7.9

定義ハンドル属性, A.12

OCI_ATTR_LOBPREFETCH_SIZE, 7.9

定義ハンドル属性, A.12

OCI_ATTR_LOCKING_MODE

属性, 6.2.14

OCI_ATTR_MAP_METHOD

属性, 6.2.4

OCI_ATTR_MAX

属性, 6.2.9

OCI_ATTR_MAX_CATALOG_NAMELEN

属性, 6.2.14

OCI_ATTR_MAX_COLUMN_NAMELEN

属性, 6.2.14

OCI_ATTR_MAX_PROC_LEN

属性, 6.2.14

OCI_ATTR_MAXCHAR_SIZE

属性, 5.8.3, 5.8.3.2

バインド・ハンドル属性, A.11

定義ハンドル属性, A.12

OCI_ATTR_MAXDATA_SIZE

属性, 5.8.3

バインド・ハンドル属性, A.11

バインドで使用, 5.8.3.1

OCI_ATTR_MEMPOOL_APPNAME

プロセス・ハンドル属性, A.20

OCI_ATTR_MEMPOOL_HOMENAME

プロセス・ハンドル属性, A.20

OCI_ATTR_MEMPOOL_INSTNAME

プロセス・ハンドル属性, A.20

OCI_ATTR_MEMPOOL_SIZE

プロセス・ハンドル属性, A.20

OCI_ATTR_MIGSESSION

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_MIN

属性, 6.2.9

OCI_ATTR_MODULE, 8.5.2.3, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_MSG_DELIVERY_MODE, 17.1.1, 17.1.1

OCIAQDeqOptions記述子属性, A.17.2

OCIAQEnqOptions記述子属性, A.17.1

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_MSG_PROP, 9.10.2

通知記述子属性, A.18.3

OCI_ATTR_MSG_STATE

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_NAME

属性, 6.2.2, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.10, 6.2.11, 6.2.18, 6.2.19, 6.2.20

列配列属性, 13.4.3.1

ダイレクト・パス・ロード

列パラメータ属性, A.19.5.1

コンテキスト・ハンドル属性, A.19.1

関数コンテキスト属性, 13.4.2.2

関数コンテキスト・ハンドル属性, A.19.2

OCI_ATTR_NAVIGATION

OCIAQDeqOptions記述子属性, A.17.2

OCI_ATTR_NCHARSET_ID

属性, 6.2.14

OCI_ATTR_NFY_FLAGS, 9.10.2

通知記述子属性, A.18.3

OCI_ATTR_NFY_MSGID, 9.10.2

通知記述子属性, A.18.3

OCI_ATTR_NONBLOCKING_MODE

サーバー・ハンドル属性, 2.6.10, A.5

OCI_ATTR_NOWAIT_SUPPORT

属性, 6.2.14

OCI_ATTR_NUM_COLS

属性, 6.2.1

ダイレクト・パス・ロード

列配列ハンドル属性, A.19.3

関数コンテキスト属性, 13.4.2.5

関数コンテキスト・ハンドル属性, A.19.2

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1 OCI_ATTR_NUM_DML_ERRORS

文ハンドル属性, A.10

OCI_ATTR_NUM_ELEMS

属性, 6.2.7

OCI_ATTR_NUM_HANDLES属性, 6.2.12 OCI_ATTR_NUM_ROWS

属性, 13.4.4.1

ダイレクト・パス・ロード

列配列ハンドル属性, A.19.3

コンテキスト・ハンドル属性, A.19.1

関数コンテキスト・ハンドル属性, A.19.2

関数コンテキスト属性, 13.4.2.6 OCI_ATTR_NUM_TYPE_ATTRS

属性, 6.2.4

OCI_ATTR_NUM_TYPE_METHODS

属性, 6.2.4

OCI_ATTR_OBJ_ID

属性, 6.2

OCI_ATTR_OBJ_NAME

属性, 6.2

OCI_ATTR_OBJ_SCHEMA

属性, 6.2

OCI_ATTR_OBJECT

環境ハンドル属性, A.2

OCI_ATTR_OBJECT_DETECTCHANGE, 14.1.7.4

環境ハンドル属性, 14.1.7.4, A.2

OCI_ATTR_OBJECT_NEWNOTNULL, 18.1.7

環境ハンドル属性, A.2

OCI_ATTR_OBJID

属性, 6.2.1, 6.2.8, 6.2.9

OCI_ATTR_ORDER

属性, 6.2.9

OCI_ATTR_ORDER_METHOD

属性, 6.2.4

OCI_ATTR_ORIGINAL_MSGID

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_OVERLOAD_ID

属性, 6.2.2

OCI_ATTR_PARAM

記述ハンドル属性, A.13

属性自体が記述子である場合に使用, 16.1.10

OCI_ATTR_PARAM_COUNT

記述ハンドル属性, A.13

文ハンドル属性, A.10

OCI_ATTR_PARSE_ERROR_OFFSET文ハンドル属性, A.10 OCI_ATTR_PARTITIONED

属性, 6.2.1

OCI_ATTR_PASSWORD, 8.4.1.7, 8.4.1.7, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_PDPRC

バインド・ハンドル属性, A.11

定義ハンドル属性, A.12

OCI_ATTR_PDSCL

バインド・ハンドル属性, A.11

定義ハンドル属性, A.12

OCI_ATTR_PIN_DURATION

環境ハンドル属性, A.2

OCI_ATTR_PINOPTION

環境ハンドル属性, A.2

OCI_ATTR_POSITION

属性, 6.2.11

OCI_ATTR_PRECISION

属性, 6.1.2.3, 6.2.5, 6.2.7, 6.2.10, 6.2.11

ダイレクト・パス・ロード列パラメータ属性, A.19.5.1

OCI_ATTR_PREFETCH_MEMORY, 4.7.2

文ハンドル属性, A.10

OCI_ATTR_PREFETCH_ROWS, 4.7.2

文ハンドル属性, A.10

OCI_ATTR_PRIORITY

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_PROC_MODE

プロセス・ハンドル属性, A.20

OCI_ATTR_PROXY_CLIENT, 2.4.1.3.2

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_PROXY_CREDENTIALS, 8.4.1.2, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_PTYPE

属性, 6.2

可能な値, 6.2

OCI_ATTR_PURITY, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_PURITY_DEFAULT

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_PURITY_NEW, 9.3.3.1 OCI_ATTR_PURITY_SELF, 9.3.3.1 OCI_ATTR_QUEUE_NAME, 9.10.2

通知記述子属性, A.18.3

OCI_ATTR_RADIX

属性, 6.2.11

OCI_ATTR_RDBA

属性, 6.2.1

OCI_ATTR_RECIPIENT_LIST

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_REF_TDO

属性, 6.2.1, 6.2.4, 6.2.5, 6.2.7, 6.2.10, 6.2.11

OCI_ATTR_RELATIVE_MSGID

OCIAQEnqOptions記述子属性, A.17.1

OCI_ATTR_RELATIVE_MSGIDエンキュー・オプション, 9.9.3 OCI_ATTR_ROW_COUNT, 4.8, 4.8

ダイレクト・パス・ロード

列配列ハンドル属性, A.19.3

ストリーム・ハンドル属性, A.19.4

文ハンドル属性, A.10 OCI_ATTR_ROWID

文ハンドル属性, A.10

OCI_ATTR_ROWS_FETCHED, 4.8

文ハンドル属性, A.10

OCI_ATTR_ROWS_RETURNED

バインド・ハンドル属性, A.11

コールバックに使用, 5.7.5

OCI_ATTR_SAVEPOINT_SUPPORT

属性, 6.2.14

OCI_ATTR_SCALE

属性, 6.2.5, 6.2.7, 6.2.10, 6.2.11

ダイレクト・パス・ロード列パラメータ属性, A.19.5.1

OCI_ATTR_SCHEMA_NAME

属性, 6.2.4, 6.2.5, 6.2.7, 6.2.8, 6.2.10, 6.2.11

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_SENDER_ID

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_SEQ

属性, 6.2.9

OCI_ATTR_SEQUENCEエンキュー・オプション, 9.9.3 OCI_ATTR_SEQUENCE_DEVIATION

OCIAQEnqOptions記述子属性, A.17.1

OCI_ATTR_SERVER

サービス・コンテキスト・ハンドル属性, A.4

OCI_ATTR_SERVER_DN

OCIServerDNs記述子の属性, A.17.5

OCI_ATTR_SERVER_DNS

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SERVER_GROUP, 8.3.4

サーバー・ハンドル属性, A.5

OCI_ATTR_SERVER_STATUS, 2.5

サーバー・ハンドル属性, A.5

OCI_ATTR_SERVICENAME

イベント・ハンドル属性, A.21

OCI_ATTR_SESSION

サービス・コンテキスト・ハンドル属性, A.4

OCI_ATTR_SESSION_STATE, 9.3.10, 9.3.11, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_SHARED_HEAPALLOC

環境ハンドル属性, A.2

OCI_ATTR_SPOOL_AUTH

セッション・プール・ハンドル属性, A.8

OCI_ATTR_SPOOL_BUSY_COUNT

セッション・プール・ハンドル属性, A.8

OCI_ATTR_SPOOL_GETMODE

セッション・プール・ハンドル属性, A.8

OCI_ATTR_SPOOL_INCR

セッション・プール・ハンドル属性, A.8

OCI_ATTR_SPOOL_MAX

セッション・プール・ハンドル属性, A.8

OCI_ATTR_SPOOL_MIN

セッション・プール・ハンドル属性, A.8

OCI_ATTR_SPOOL_OPEN_COUNT

セッション・プール・ハンドル属性, A.8

OCI_ATTR_SPOOL_STMTCACHESIZE

セッション・プール・ハンドル属性, A.8

OCI_ATTR_SPOOL_TIMEOUT

セッション・プール・ハンドル属性, A.8

OCI_ATTR_SQLFNCODE

文ハンドル属性, A.10

OCI_ATTR_STATEMENT

文ハンドル属性, A.10

OCI_ATTR_STMT_STATE

文ハンドル属性, A.10

OCI_ATTR_STMT_TYPE

文ハンドル属性, A.10

OCI_ATTR_STMTCACHE_CBK

サービス・コンテキスト・ハンドル属性, A.4

OCI_ATTR_STMTCACHE_CBKCTX

文ハンドル属性, A.10

OCI_ATTR_STMTCACHESIZE, 9.5.3, 16.1.10, 16.1.10

サービス・コンテキスト・ハンドル属性, A.4

OCI_ATTR_STREAM_OFFSET

ダイレクト・パス・ロード・ストリーム・ハンドル属性, A.19.4

OCI_ATTR_SUB_NAME

属性, 6.2.11

ダイレクト・パス・ロード・コンテキスト・ハンドル属性, A.19.1

OCI_ATTR_SUBSCR_CALLBACK, 9.10.1.1, 9.10.1.3, 10.1.3

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_CQ_CHNF_QOSFLAGS, 10.1.3 OCI_ATTR_SUBSCR_CQ_QOSFLAGS

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_CTX, 9.10.1.1, 9.10.1.3

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_HOSTADDR, 9.10.1.1

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_IPADDR

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_NAME, 9.10.1.1, 9.10.1.3

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_NAMESPACE, 9.10.1.1, 9.10.1.3, 10.1.3

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_NTFN_GROUPING_CLASS, 9.10.1.1, A.18 OCI_ATTR_SUBSCR_NTFN_GROUPING_REPEAT_COUNT, 9.10.1.1

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_NTFN_GROUPING_START_TIME, 9.10.1.1

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_NTFN_GROUPING_TYPE, 9.10.1.1

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_NTFN_GROUPING_VALUE, 9.10.1.1

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_PAYLOAD, 9.10.1.1, 9.10.1.3

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_PORTNO

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_QOSFLAGS, 9.10.1.1, 9.10.1.3, 10.1.3

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_RECPT, 9.10.1.1, 9.10.1.3

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_RECPTPRES, 9.10.1.1

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_RECPTPROTO, 9.10.1.1, 9.10.1.3

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUBSCR_RECPTRES, 9.10.1.3 OCI_ATTR_SUBSCR_SERVER_DN

記述子ハンドル, 9.10.1.3

OCI_ATTR_SUBSCR_TIMEOUT, 9.10.1.1, 9.10.1.3, 10.1.3

サブスクリプション・ハンドル属性, A.18

OCI_ATTR_SUPERTYPE_NAME

属性, 6.2.4

OCI_ATTR_SUPERTYPE_SCHEMA_NAME

属性, 6.2.4

OCI_ATTR_TABLE_NAME

属性, 6.2.18

OCI_ATTR_TABLESPACE

属性, 6.2.1

OCI_ATTR_TAF_ENABLED, 9.8.6

サーバー・ハンドル属性, A.5

OCI_ATTR_TIMESTAMP

属性, 6.2

OCI_ATTR_TRANS

サービス・コンテキスト・ハンドル属性, A.4

OCI_ATTR_TRANS_NAME, 8.2.3.1

トランザクション・ハンドル属性, A.9

OCI_ATTR_TRANS_TIMEOUT

トランザクション・ハンドル属性, A.9

OCI_ATTR_TRANSACTION_IN_PROGRESS

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_TRANSACTION_NO

OCIAQMsgProperties記述子属性, A.17.3

OCI_ATTR_TRANSFORMATION (デキュー)

OCIAQDeqOptions記述子属性, A.17.2

OCI_ATTR_TRANSFORMATION (エンキュー)

OCIAQEnqOptions記述子属性, A.17.1

OCI_ATTR_TYPE

属性, 6.2.19

OCI_ATTR_TYPE_NAME

属性, 6.2.5, 6.2.7, 6.2.10, 6.2.11

OCI_ATTR_TYPECODE

属性, 6.1.2.1, 6.2.4, 6.2.5, 6.2.7, 6.2.11

OCI_ATTR_USER_MEMORY, 9.8.5

サーバー・ハンドル属性, A.5

OCI_ATTR_USERNAME, 2.4.1.3.2, 16.1.10

ユーザー・セッション・ハンドル属性, A.5.2

OCI_ATTR_VALUE

属性, 6.2.20

OCI_ATTR_VAR_METHOD_FUNCTION

属性, 6.2.19, 6.2.19

OCI_ATTR_VAR_VALUE_FUNCTION

属性, 6.2.19

OCI_ATTR_VERSION

属性, 6.2.14

OCI_ATTR_VISIBILITY

OCIAQDeqOptions記述子属性, A.17.2

OCIAQEnqOptions記述子属性, A.17.1

OCI_ATTR_WAIT

OCIAQDeqOptions記述子属性, A.17.2

OCI_ATTR_WALL_LOC, 9.10.1.3

環境ハンドル属性, A.2

OCI_ATTR_XID, 8.2.3.1

トランザクション・ハンドル属性, A.9

OCI_BATCH_ERRORS, 17.1.1 OCI_BIND_SOFT, 16.1.10, 16.1.10 OCI_COMMIT_ON_SUCCESS, 17.1.1 OCI_CONTINUE, 2.5 OCI_CPOOL_REINITIALIZE, 16.1.10 OCI_CRED_EXT, 16.1.10 OCI_CRED_PROXY, 8.4.1.1 OCI_CRED_RDBMS, 8.4.1.1, 16.1.10 OCI_DATA_AT_EXEC, 16.1.10, 16.1.10 OCI_DEFAULT, 8.9.3, 16.1.10, 16.1.10, 16.1.10, 17.1.1

OCISessionBegin()モード, 16.1.10

OCIDefineByPos()用のOCI_DEFAULTモード, 16.1.10 OCI_DEFINE_SOFT, 16.1.10 OCI_DESCRIBE_ONLY, 17.1.1 OCI_DIRPATH_COL_ERROR, 13.2.2.4 OCI_DIRPATH_DATASAVE_FINISH, 17.1.1 OCI_DIRPATH_DATASAVE_SAVEONLY, 17.1.1 OCI_DIRPATH_EXPR_OBJ_CONSTR, 13.4.2.2, 13.4.2.3 OCI_DIRPATH_EXPR_REF_TBLNAME, 13.2.4.1, 13.4.2.3 OCI_DIRPATH_EXPR_SQL, 13.4.2.2, 13.4.2.3 OCI_DIRPATH_OID列配列属性, 13.4.3.3 OCI_DTYPE_AQAGENT, 2.3.1.13 OCI_DTYPE_AQDEQ_OPTIONS, 2.3.1.13 OCI_DTYPE_AQENQ_OPTIONS, 2.3.1.13 OCI_DTYPE_AQLIS_MSG_PROPERTIES, 2.3.1.13 OCI_DTYPE_AQLIS_OPTIONS, 2.3.1.13 OCI_DTYPE_AQMSG_PROPERTIES, 2.3.1.13 OCI_DTYPE_AQNFY, 2.3.1.13 OCI_DTYPE_CHDES, 2.3.1.13 OCI_DTYPE_COMPLEXOBJECTCOMP, 2.3.1.13 OCI_DTYPE_CQDES, 10.1.5.1.1 OCI_DTYPE_DATE, 2.3.1.13 OCI_DTYPE_FILE, 2.3.1.13 OCI_DTYPE_INTERVAL_DS, 2.3.1.13 OCI_DTYPE_INTERVAL_YM, 2.3.1.13 OCI_DTYPE_LOB, 2.3.1.13 OCI_DTYPE_PARAM, 2.3.1.13, 16.1.10, 16.1.10

使用される場合, 16.1.10

OCI_DTYPE_ROW_CHDES, 2.3.1.13 OCI_DTYPE_ROWID, 2.3.1.13 OCI_DTYPE_RSET, 2.3.1.13 OCI_DTYPE_SNAP, 2.3.1.13 OCI_DTYPE_SRVDN, 2.3.1.13 OCI_DTYPE_TABLE_CHDES, 2.3.1.13 OCI_DTYPE_TIMESTAMP, 2.3.1.13 OCI_DTYPE_TIMESTAMP_LTZ, 2.3.1.13 OCI_DTYPE_TIMESTAMP_TZ, 2.3.1.13 OCI_DTYPE_UCB, 2.3.1.13 OCI_DURATION_DEFAULT, 18.1.7 OCI_DURATION_NULL, 6.2.1, 18.1.7

OCI_ATTR_DURATIONの可能な値, 6.2.1

OCI_DURATION_SESSION, 6.2.1, 14.1.4.1, 17.1.1, 20.1.3, 21.1.2, 21.1.2, 21.1.2, 21.1.2

OCI_ATTR_DURATIONの可能な値, 6.2.1

OCI_DURATION_STATEMENT, 17.1.1, 20.1.3, 21.1.2, 21.1.2, 21.1.2, 21.1.2 OCI_DURATION_TRANS, 6.2.1, 14.1.4.1

OCI_ATTR_DURATIONの可能な値, 6.2.1

OCI_DYNAMIC_FETCH, 16.1.10 OCI_ENABLE_NLS_VALIDATION, 16.1.10, 16.1.10 OCI_ENV_NO_MUTEX, 8.9.3, 16.1.10, 16.1.10 OCI_ERROR, 2.5, 8.2.3.7 OCI_EVENTS, 16.1.10, 16.1.10

通知受信のモード, 9.10.1.1

OCI_EXACT_FETCH, 17.1.1 OCI_EXT_CRED, 8.4.1.1 OCI_HTYPE_ADMIN, 2.3.1, 10.2 OCI_HTYPE_AUTHINFO, 2.3.1, 9.2.4.2 OCI_HTYPE_BIND, 2.3.1 OCI_HTYPE_COMPLEXOBJECT, 2.3.1 OCI_HTYPE_COR, 16.1.10 OCI_HTYPE_CPOOL, 2.3.1, 9.1.2.1 OCI_HTYPE_DEFINE, 2.3.1 OCI_HTYPE_DESCRIBE, 2.3.1 OCI_HTYPE_DIRPATH_COLUMN_ARRAY, 2.3.1 OCI_HTYPE_DIRPATH_CTX, 2.3.1 OCI_HTYPE_DIRPATH_FN_COL_ARRAY, 13.2.2.2, 13.4.2.6, 13.4.4 OCI_HTYPE_DIRPATH_FN_CTX, 2.3.1 OCI_HTYPE_DIRPATH_STREAM, 2.3.1 OCI_HTYPE_ENV, 2.3.1 OCI_HTYPE_ERROR, 2.3.1 OCI_HTYPE_PROC, 2.3.1 OCI_HTYPE_SERVER, 2.3.1 OCI_HTYPE_SESSION, 2.3.1 OCI_HTYPE_SPOOL, 2.3.1 OCI_HTYPE_STMT, 2.3.1, 16.1.10, 16.1.10 OCI_HTYPE_SUBSCRIPTION, 2.3.1 OCI_HTYPE_SVCCTX, 2.3.1 OCI_HTYPE_TRANS, 2.3.1 OCI_IND_NULL, 11.3.14, 16.1.10, 21.1.2 OCI_INVALID_HANDLE, 2.5 OCI_IOV, 5.6, 5.6, 16.1.10, 16.1.10 OCI_LOCK_NONE, 14.1.7.1 OCI_LOCK_X, 14.1.7.1 OCI_LOCK_X_NOWAIT, 14.1.7.1, 14.1.7.3

パラメータの使用方法, 14.1.7.3

OCI_LOGON2_STMTCACHE, 9.5.2 OCI_LTYPE_ARG_FUNCリスト属性, 6.2.12 OCI_LTYPE_ARG_PROCリスト属性, 6.2.12 OCI_LTYPE_COLUMNリスト属性, 6.2.12 OCI_LTYPE_DB_SCHリスト属性, 6.2.12 OCI_LTYPE_SCH_OBJリスト属性, 6.2.12 OCI_LTYPE_SUBPRGリスト属性, 6.2.12 OCI_LTYPE_TYPE_ARG_FUNCリスト属性, 6.2.12 OCI_LTYPE_TYPE_ARG_PROCリスト属性, 6.2.12 OCI_LTYPE_TYPE_ATTRリスト属性, 6.2.12 OCI_LTYPE_TYPE_METHODリスト属性, 6.2.12 OCI_MAJOR_VERSION, クライアント・ライブラリ・バージョン, 17.1.1 OCI_MIGRATE, 8.3.1

OCISessionBegin()モード, 16.1.10

OCI_MINOR_VERSION, クライアント・ライブラリ・バージョン, 17.1.1 OCI_NCHAR_LITERAL_REPLACE_OFF, 16.1.10, 16.1.10 OCI_NCHAR_LITERAL_REPLACE_ON, 16.1.10, 16.1.10 OCI_NEED_DATA, 2.5 OCI_NEW_LENGTH_SEMANTICS, 16.1.10 OCI_NLS_MAXBUFSZ, 22.1.2 OCI_NO_DATA, 2.5 OCI_NO_UCB, 16.1.10, 16.1.10, 16.1.10 OCI_NTV_SYNTAX, 17.1.1, 17.1.1 OCI_OBJECT, 2.4.1.1, 9.10.1.1, 16.1.10, 16.1.10 OCI_PARSE_ONLY, 17.1.1 OCI_PIN_ANY, 14.1.4.1 OCI_PIN_LATEST, 14.1.4.1 OCI_PIN_RECENT, 14.1.4.1 OCI_PRELIM_AUTH

OCISessionBegin()モード, 16.1.10

OCI_PTYPE_ARG

属性, 6.2.11

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_COL

属性, 6.2.10

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_COLL

属性, 6.2.7

OCI_PTYPE_DATABASE

属性, 6.2.14

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_EVALUATION CONTEXT

属性, 6.2.17

OCI_PTYPE_FUNC

属性, 6.2.2

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_LIST

属性, 6.2.12

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_NAME_VALUE

属性, 6.2.20

OCI_PTYPE_PKG

属性, 6.2.3

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_PROC

属性, 6.2.2

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_RULE_SET

属性, 6.2.16

OCI_PTYPE_RULES

属性, 6.2.15

OCI_PTYPE_SCHEMA

属性, 6.2.13

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_SEQ

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_SYN

属性, 6.2.8

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_TABLE

属性, 6.2.1

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_TABLE_ALIAS

属性, 6.2.18

OCI_PTYPE_TYPE

属性, 6.2.4

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_TYPE_ARG

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_TYPE_ATTR

属性, 6.2.5

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_TYPE_COLL

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_TYPE_FUNC

属性, 6.2.6

OCI_PTYPE_TYPE_METHOD, 6.2.6

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_TYPE_PROC

属性, 6.2.6

OCI_PTYPE_TYPE_RESULT

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_UNK

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_PTYPE_VARIABLE_TYPE

属性, 6.2.19

OCI_PTYPE_VIEW

属性, 6.2.1

OCI_ATTR_PTYPEの可能な値, 6.2

OCI_ROWCBK_DONE, 2.5 OCI_SESSGET_PURITY_NEW, 9.3.3.1 OCI_SESSGET_PURITY_SELF, 9.3.3.1 OCI_SESSGET_STMTCACHE, 9.5.2 OCI_SESSION_STATEFUL, 9.3.11 OCI_SESSION_STATELESS, 9.3.10, 9.3.11 OCI_SESSRLS_RETAG, 16.1.10, 16.1.10 OCI_SPC_NO_RLB, 9.2.8 OCI_STILL_EXECUTING, 2.5, 2.6.9 OCI_STMT_CACHE

OCISessionBegin()モード, 16.1.10

OCI_STMT_SCROLLABLE_READONLY, 17.1.1

属性, 4.8

OCI_SUBSCR_NAMESPACE_ANONYMOUS, A.18 OCI_SUBSCR_NAMESPACE_AQ,A.18 OCI_SUBSCR_NAMESPACE_DBCHANGE,A.18 OCI_SUBSCR_PROTO_HTTP,A.18 OCI_SUBSCR_PROTO_MAIL,A.18 OCI_SUBSCR_PROTO_OCI, A.18 OCI_SUBSCR_PROTO_SERVER, A.18 OCI_SUBSCR_QOS_PURGE_ON_NTFN, 9.10.1.1, 9.10.1.4, 10.1.3 OCI_SUBSCR_QOS_RELIABLE, 9.10.1.1, 9.10.1.4, 10.1.3 OCI_SUCCESS, 2.5, 8.2.3.7 OCI_SUCCESS_WITH_INFO, 2.5 OCI_SUPPRESS_NLS_VALIDATION, 16.1.10, 16.1.10 OCI_SYSDBA

OCISessionBegin()モード, 16.1.10

OCI_SYSOPER

OCISessionBegin()モード, 16.1.10

OCI_THREADED, 8.9.3, 16.1.10, 16.1.10 OCI_TRANS_LOOSE, 8.2.3.3 OCI_TRANS_NEW, 8.2.5.1 OCI_TRANS_READONLY, 8.2.2, 8.2.5.3 OCI_TRANS_READWRITE, 8.2.2 OCI_TRANS_RESUME, 8.2.5.2 OCI_TRANS_SERIALIZABLE, 8.2.2 OCI_TRANS_TIGHT, 8.2.3.3 OCI_TRANS_TWOPHASE, 8.2.5.2 OCI_TYPECODE, 6.1.2.1

値, 3.5, 3.5, 3.5.1

OCI_TYPECODE_NAMEDCOLLECTION

OCI_ATTR_TYPECODEの可能な値, 6.2.4

OCI_TYPECODE_NCHAR, 12.13.3, 12.13.3 OCI_TYPECODE_OBJECT

OCI_ATTR_TYPECODEの可能な値, 6.2.4

OCI_TYPECODE_TABLE

OCI_ATTR_COLLECTION_TYPECODEの可能な値, 6.2.4

OCI_TYPECODE_VARRAY

OCI_ATTR_COLLECTION_TYPECODEの可能な値, 6.2.4

OCI_TYPEENCAP_PRIVATE

OCI_ATTR_ENCAPSULATIONの可能な値, 6.2.6

OCI_TYPEENCAP_PUBLIC

OCI_ATTR_ENCAPSULATIONの可能な値, 6.2.6

OCI_UTF16ID, 2.8.1 OCI_V7_SYNTAX, 17.1.1, 17.1.1 OCIAnyDataAccess(), 21.1.2 OCIAnyDataAttrGet(), 21.1.2 OCIAnyDataAttrSet(), 21.1.2 OCIAnyDataBeginCreate(), 21.1.2 OCIAnyDataCollAddElem(), 21.1.2 OCIAnyDataCollGetElem(), 21.1.2 OCIAnyDataConvert(), 21.1.2 OCIAnyDataDestroy(), 21.1.2 OCIAnyDataEndCreate(), 21.1.2 OCIAnyDataGetCurrAttrNum(), 21.1.2 OCIAnyDataGetType(), 21.1.2 OCIAnyDataIsNull(), 21.1.2 OCIAnyDataSetAddInstance(), 21.1.2 OCIAnyDataSetBeginCreate(), 21.1.2 OCIAnyDataSetDestroy(), 21.1.2 OCIAnyDataSetEndCreate(), 21.1.2 OCIAnyDataSetGetCount(), 21.1.2 OCIAnyDataSetGetInstance(), 21.1.2 OCIAnyDataSetGetType(), 21.1.2 OCIAnyDataTypeCodeToSqlt(), 12.13.3, 21.1.2 OCIAppCtxClearAll(), 8.6.2, 16.1.10 OCIAppCtxSet(), 8.6.1, 16.1.10 OCIAQAgent

記述子の属性, A.17.4

OCIAQDeq(), 17.1.1 OCIAQDeqArray(), 17.1.1 OCIAQDeqOptions

記述子の属性, A.17.2

OCIAQEnq(), 17.1.1 OCIAQEnqArray(), 17.1.1 OCIAQEnqOptions

記述子の属性, A.17.1

OCIAQListen(), E OCIAQListen2(), 17.1.1 OCIAQMsgProperties

記述子の属性, A.17.3

OCIArray, 12.9

バインドと定義, 12.9, 12.16

OCIArrayの操作

コード例, 12.9.4

OCIArrayDescriptorAlloc(), 16.1.10 OCIArrayDescriptorFree(), 16.1.10 OCIAttrGet(), 16.1.10

記述用に使用, 4.5.1

OCIAttrSet(), 16.1.10 OCIAuthInfoの定義, 9.2.4.2 OCIAuthInfoハンドル属性, A.5.2 OCIBindArrayOfStruct(), 16.1.10 OCIBindByName(), 16.1.10 OCIBindByPos(), 16.1.10 OCIBindDynamic(), 16.1.10 OCIBindObject(), 16.1.10 OCIBinXmlCreateReposCtxFromConn(), 14.5.4.3, 23.1.2 OCIBinXmlCreateReposCtxFromCPool(), 14.5.4.4, 23.1.2 OCIBinXmlReposCtxリポジトリ・コンテキスト, 14.5.4.2 OCIBinXmlSetFormatPref(), 14.5.4.6, 23.1.2 OCIBinXmlSetReposCtxForConn(), 14.5.4.5, 23.1.2 OCIBreak(), 17.1.1

使用, 2.6.5, 2.6.11

OCICacheFlush(), 18.1.7 OCICacheFree(), 18.1.7 OCICacheRefresh(), 18.1.7 OCICacheUnmark(), 18.1.7 OCICacheUnpin(), 18.1.7 OCICharSetConversionIsReplacementUsed(), 22.1.2 OCICharSetToUnicode(), 22.1.2 OCIClientVersion(), 17.1.1 OCIColl, 12.9

バインドと定義, 12.9

OCICollAppend(), 19.1.6 OCICollAssign(), 19.1.6 OCICollAssignElem(), 19.1.6 OCICollGetElem(), 19.1.6 OCICollGetElemArray(), 19.1.6 OCICollIsLocator(), 19.1.6 OCICollMax(), 19.1.6 OCICollSize(), 19.1.6 OCICollTrim(), 19.1.6 OCIComplexObject

使用, 11.3.10.2

OCIComplexObjectComp

使用, 11.3.10.2

OCIConnectionPoolCreate(), 16.1.10 OCIConnectionPoolDestroy(), 16.1.10 OCIContextClearValue(), 20.1.3 OCIContextGenerateKey(), 20.1.3 OCIContextGetValue(), 20.1.3 OCIContextSetValue(), 20.1.3 OCIDate, 12.4

バインドと定義, 12.4, 12.16

操作使用例, 12.4.1

OCIDateAddDays(), 19.1.6 OCIDateAddMonths(), 19.1.6 OCIDateAssign(), 19.1.6 OCIDateCheck(), 19.1.6 OCIDateCompare(), 19.1.6 OCIDateDaysBetween(), 19.1.6 OCIDateFromText(), 19.1.6 OCIDateGetDate(), 19.1.6 OCIDateGetTime(), 19.1.6 OCIDateLastDay(), 19.1.6 OCIDateNextDay(), 19.1.6 OCIDateSetDate(), 19.1.6 OCIDateSetTime(), 19.1.6 OCIDateSysDate(), 19.1.6 OCIDateTimeAssign(), 19.1.6 OCIDateTimeCheck(), 19.1.6 OCIDateTimeCompare(), 19.1.6 OCIDateTimeConstruct(), 19.1.6 OCIDateTimeConvert(), 19.1.6 OCIDateTimeFromArray(), 19.1.6 OCIDateTimeFromText(), 19.1.6 OCIDateTimeGetDate(), 19.1.6 OCIDateTimeGetTime(), 19.1.6 OCIDateTimeGetTimeZoneName(), 19.1.6 OCIDateTimeGetTimeZoneOffset(), 19.1.6 OCIDateTimeIntervalAdd(), 19.1.6 OCIDateTimeIntervalSub(), 19.1.6 OCIDateTimeSubtract(), 19.1.6 OCIDateTimeSysTimeStamp(), 19.1.6 OCIDateTimeToArray(), 19.1.6 OCIDateTimeToText(), 19.1.6 OCIDateToText(), 19.1.6 OCIDateZoneToZone(), 19.1.6 OCIDBShutdown(), 16.1.10 OCIDBStartup(), 16.1.10 OCIDefineArrayOfStruct(), 16.1.10 OCIDefineByPos(), 16.1.10 OCIDefineDynamic(), 16.1.10 OCIDefineObject(), 16.1.10 OCIDescribeAny(), 16.1.10

制限, 6.1.1

概要, 6.1

使用例, 6.4

OCIDescriptorAlloc(), 16.1.10 OCIDescriptorFree(), 16.1.10 OCIDirPathAbort(), 17.1.1 OCIDirPathColArrayコンテキスト, 13.1.2.1 OCIDirPathColArrayEntryGet(), 17.1.1 OCIDirPathColArrayEntrySet(), 17.1.1 OCIDirPathColArrayReset(), 17.1.1 OCIDirPathColArrayRowGet(), 17.1.1 OCIDirPathColArrayToStream(), 17.1.1 OCIDirPathCtxコンテキスト, 13.1.2.1 OCIDirPathDataSave(), 17.1.1 OCIDirPathFinish(), 17.1.1 OCIDirPathFlushRow(), 17.1.1 OCIDirPathLoadStream(), 17.1.1 OCIDirPathPrepare(), 17.1.1 OCIDirPathStreamコンテキスト, 13.1.2.1 OCIDirPathStreamReset(), 17.1.1 OCIDuration

使用, 14.1.4.1, 14.1.9

OCIDurationBegin(), 17.1.1, 20.1.3 OCIDurationEnd(), 17.1.1, 20.1.3 OCIEnvCreate(), 16.1.10 OCIEnvInit(), E OCIEnvNlsCreate(), 2.8.1, 5.8.2, 16.1.10 OCIErrorGet(), 17.1.1 OCIEventハンドル, 9.8.1 OCIEventCallbackデータ型, 9.8.4 OCIExtProcAllocCallMemory(), 20.1.3 OCIExtProcGetEnv(), 20.1.3 OCIExtProcRaiseExcp(), 20.1.3 OCIExtProcRaiseExcpWithMsg(), 20.1.3 OCIExtractFromFile(), 20.1.3, 20.1.3, 20.1.3 OCIExtractFromList(), 20.1.3 OCIExtractFromStr(), 20.1.3 OCIExtractInit(), 20.1.3 OCIExtractReset(), 20.1.3 OCIExtractSetKey(), 20.1.3 OCIExtractSetNumKeys(), 20.1.3 OCIExtractTerm(), 20.1.3 OCIExtractToBool(), 20.1.3 OCIExtractToInt(), 20.1.3 OCIExtractToList(), 20.1.3 OCIExtractToOCINum(), 20.1.3 OCIExtractToStr(), 20.1.3 OCIFileClose(), 20.1.3 OCIFileExists(), 20.1.3 OCIFileFlush(), 20.1.3 OCIFileGetLength(), 20.1.3 OCIFileInit(), 20.1.3 OCIFileObjectデータ構造, 20.1.3 OCIFileOpen(), 20.1.3 OCIFileRead(), 20.1.3 OCIFileSeek(), 20.1.3 OCIFileTerm(), 20.1.3 OCIFileWrite(), 20.1.3 OCIFormatInit(), 20.1.3 OCIFormatString(), 20.1.3 OCIFormatTerm(), 20.1.3 OCIHandleAlloc(), 16.1.10 OCIHandleFree(), 16.1.10 OCIInd

使用, 11.3.14

OCIInitialize(), E OCIIntervalAdd(), 19.1.6 OCIIntervalAssign(), 19.1.6 OCIIntervalCheck(), 19.1.6 OCIIntervalCompare(), 19.1.6 OCIIntervalDivide(), 19.1.6 OCIIntervalFromNumber(), 19.1.6 OCIIntervalFromText(), 19.1.6 OCIIntervalFromTZ(), 19.1.6 OCIIntervalGetDaySecond(), 19.1.6 OCIIntervalGetYearMonth(), 19.1.6 OCIIntervalMultiply(), 19.1.6 OCIIntervalSetDaySecond(), 19.1.6 OCIIntervalSetYearMonth(), 19.1.6 OCIIntervalSubtract(), 19.1.6 OCIIntervalToNumber(), 19.1.6 OCIIntervalToText(), 19.1.6 OCIIOV構造体, 5.6 OCIIter, 12.9

バインドと定義, 12.9

使用例, 12.9.4

OCIIterCreate(), 19.1.6 OCIIterDelete(), 19.1.6 OCIIterGetCurrent(), 19.1.6 OCIIterInit(), 19.1.6 OCIIterNext(), 19.1.6 OCIIterPrev(), 19.1.6 OCILdaToSvcCtx(), 17.1.1 oci.lib, D.5 OCILobAppend(), 17.1.1 OCILobArrayRead(), 7.9, 17.1.1 OCILobArrayWrite(), 17.1.1 OCILobAssign(), 17.1.1 OCILobCharSetForm(), 17.1.1 OCILobCharSetId(), 17.1.1 OCILobClose(), 17.1.1 OCILobCopy(), E OCILobCopy2(), 17.1.1 OCILobCreateTemporary(), 17.1.1 OCILobDisableBuffering(), 17.1.1 OCILobEnableBuffering(), 17.1.1 OCILobErase(), E OCILobErase2(), 17.1.1 OCILobFileClose(), 17.1.1 OCILobFileCloseAll(), 17.1.1 OCILobFileExists(), 17.1.1 OCILobFileGetName(), 17.1.1 OCILobFileIsOpen(), 17.1.1 OCILobFileOpen(), 17.1.1 OCILobFileSetName(), 17.1.1 OCILobFlushBuffer(), 17.1.1 OCILobFreeTemporary(), 17.1.1 OCILobGetChunkSize(), 7.6, 17.1.1 OCILobGetContentType(), 17.1.1 OCILobGetLength(), E OCILobGetLength2(), 17.1.1 OCILobGetOptions(), 17.1.1 OCILobGetStorageLimit(), 17.1.1 OCILobIsEqual(), 17.1.1 OCILobIsOpen(), 17.1.1 OCILobIsTemporary(), 17.1.1 OCILobLoadFromFile(), E OCILobLoadFromFile2(), 17.1.1 OCILobLocatorAssign(), 17.1.1 OCILobLocatorIsInit(), 17.1.1 OCILobOpen(), 17.1.1 OCILobRead(), E OCILobRead2(), 17.1.1 OCILobSetContentType(), 17.1.1 OCILobSetOptions(), 17.1.1 OCILobTrim(), E OCILobTrim2(), 17.1.1 OCILobWrite(), E OCILobWrite2(), 17.1.1 OCILobWriteAppend(), E OCILobWriteAppend2(), 17.1.1 OCILockOpt

可能な値, 18.1.7, 18.1.7

OCILogoff(), 16.1.10 OCILogon(), 16.1.10

使用方法, 2.4.1.3.1

OCILogon2(), 16.1.10 OCIMemoryAlloc(), 20.1.3 OCIMemoryFree(), 20.1.3 OCIMemoryResize(), 20.1.3 OCIMessageClose(), 22.1.2 OCIMessageGet(), 22.1.2 OCIMessageOpen(), 22.1.2 OCIMultiByteInSizeToWideChar(), 22.1.2 OCIMultiByteStrCaseConversion(), 22.1.2 OCIMultiByteStrcat(), 22.1.2 OCIMultiByteStrcmp(), 22.1.2 OCIMultiByteStrcpy(), 22.1.2 OCIMultiByteStrlen(), 22.1.2 OCIMultiByteStrncat(), 22.1.2 OCIMultiByteStrncmp(), 22.1.2 OCIMultiByteStrncpy(), 22.1.2 OCIMultiByteStrnDisplayLength(), 22.1.2 OCIMultiByteToWideChar(), 22.1.2 OCINlsCharSetConvert(), 22.1.2 OCINlsCharSetIdToName(), 22.1.2, 22.1.2, 22.1.2, 22.1.2, 22.1.2 OCINlsCharSetNameTold(), 22.1.2 OCINlsEnvironmentVariableGet(), 5.8.2, 22.1.2 OCINlsGetInfo(), 2.8.2, 22.1.2 OCINlsNameMap(), 22.1.2 OCINlsNumericInfoGet(), 22.1.2 OCINumber, 12.6

バインドの例, 12.16.1

バインドと定義, 12.6, 12.16

定義の例, 12.16.1

使用例, 12.6.1

OCINumberAbs(), 19.1.6 OCINumberAdd(), 19.1.6 OCINumberArcCos(), 19.1.6 OCINumberArcSin(), 19.1.6 OCINumberArcTan(), 19.1.6 OCINumberArcTan2(), 19.1.6 OCINumberAssign(), 19.1.6 OCINumberCeil(), 19.1.6 OCINumberCmp(), 19.1.6 OCINumberCos(), 19.1.6 OCINumberDec(), 19.1.6 OCINumberDiv(), 19.1.6 OCINumberExp(), 19.1.6 OCINumberFloor(), 19.1.6 OCINumberFromInt(), 19.1.6 OCINumberFromReal(), 19.1.6 OCINumberFromText(), 19.1.6 OCINumberHypCos(), 19.1.6 OCINumberHypSin(), 19.1.6 OCINumberHypTan(), 19.1.6 OCINumberInc(), 19.1.6 OCINumberIntPower(), 19.1.6 OCINumberIsInt(), 19.1.6 OCINumberIsZero(), 19.1.6 OCINumberLn(), 19.1.6 OCINumberLog(), 19.1.6 OCINumberMod(), 19.1.6 OCINumberMul(), 19.1.6 OCINumberNeg(), 19.1.6 OCINumberPower(), 19.1.6 OCINumberPrec(), 19.1.6 OCINumberRound(), 19.1.6 OCINumberSetPi(), 19.1.6 OCINumberSetZero(), 19.1.6 OCINumberShift(), 19.1.6 OCINumberSign(), 19.1.6 OCINumberSin(), 19.1.6 OCINumberSqrt(), 19.1.6 OCINumberSub(), 19.1.6 OCINumberTan(), 19.1.6 OCINumberToInt(), 19.1.6 OCINumberToReal(), 19.1.6 OCINumberToRealArray(), 19.1.6 OCINumberToText(), 19.1.6 OCINumberTrunc(), 19.1.6 OCIObjectArrayPin(), 18.1.7 OCIObjectCopy(), 18.1.7 OCIObjectExists(), 18.1.7 OCIObjectFlush(), 18.1.7 OCIObjectFree(), 18.1.7 OCIObjectGetAttr(), 18.1.7 OCIObjectGetInd(), 18.1.7

使用例, 11.3.14

OCIObjectGetObjectRef(), 18.1.7 OCIObjectGetProperty(), 18.1.7 OCIObjectGetTypeRef(), 18.1.7 OCIObjectIsDirty(), 18.1.7 OCIObjectIsLocked(), 18.1.7 OCIObjectLifetime

可能な値, 18.1.7

OCIObjectLock(), 18.1.7 OCIObjectLockNoWait(), 18.1.7 OCIObjectMarkDelete(), 18.1.7 OCIObjectMarkDeleteByRef(), 18.1.7 OCIObjectMarkStatus

可能な値, 18.1.7

OCIObjectMarkUpdate(), 18.1.7 OCIObjectNew(), 18.1.7 OCIObjectPin(), 18.1.7 OCIObjectPinCountReset(), 18.1.7 OCIObjectPinTable(), 18.1.7 OCIObjectRefresh(), 18.1.7 OCIObjectSetAttr(), 18.1.7 OCIObjectUnmark(), 18.1.7 OCIObjectUnmarkByRef(), 18.1.7 OCIObjectUnpin(), 18.1.7 OCIParamGet(), 16.1.10

記述用に使用, 4.5.1

OCIParamSet(), 16.1.10 OCIPasswordChange(), 17.1.1 OCIPing(), 17.1.1 OCIPinOpt

使用, 14.1.4.1

OCIRaw, 12.8

バインドと定義, 12.8, 12.16

操作使用例, 12.8.2

OCIRawAllocSize(), 19.1.6 OCIRawAssignBytes(), 19.1.6 OCIRawAssignRaw(), 19.1.6 OCIRawPtr(), 19.1.6 OCIRawResize(), 19.1.6 OCIRawSize(), 19.1.6 OCIRef, 12.11

バインドと定義, 12.11

使用例, 12.11.2

OCIRefAssign(), 19.1.6 OCIRefClear(), 19.1.6 OCIRefFromHex(), 19.1.6 OCIRefHexSize(), 19.1.6 OCIRefIsEqual(), 19.1.6 OCIRefIsNull(), 19.1.6 OCIRefToHex(), 19.1.6 OCIReset(), 17.1.1

使用, 2.6.11

OCIRowid ROWID記述子, 2.3.1.13.4 OCIRowidToChar(), 17.1.1 OCIServerAttach(), 16.1.10

shadow processes, 16.1.10

OCIServerDetach(), 16.1.10 OCIServerDNs記述子の属性, A.17.5 OCIServerRelease(), 17.1.1 OCIServerVersion(), 17.1.1 OCISessionBegin(), 2.4.1.3.3, 2.8.5, 8.3.1, 16.1.10 OCISessionEnd(), 16.1.10 OCISessionGet(), 16.1.10 OCISessionPoolCreate(), 16.1.10 OCISessionPoolDestroy(), 16.1.10 OCISessionRelease(), 16.1.10 OCIStmtExecute(), 17.1.1

プリフェッチ, 4.4

itersパラメータの使用, 4.4

OCIStmtFetch(), E OCIStmtFetch2(), 4.8, 17.1.1 OCIStmtGetBindInfo(), 16.1.10 OCIStmtGetPieceInfo(), 17.1.1 OCIStmtPrepare(), 17.1.1 OCIStmtPrepare2(), 17.1.1

SQL文の準備, 4.2

OCIStmtRelease(), 17.1.1 OCIStmtSetPieceInfo(), 17.1.1 OCIString, 12.7

バインドと定義, 12.7, 12.16

操作使用例, 12.7.2

OCIStringAllocSize(), 19.1.6 OCIStringAssign(), 19.1.6 OCIStringAssignText(), 19.1.6 OCIStringPtr(), 19.1.6 OCIStringResize(), 19.1.6 OCIStringSize(), 19.1.6 OCISubscriptionDisable(), 17.1.1 OCISubscriptionEnable(), 17.1.1 OCISubscriptionPost(), 17.1.1 OCISubscriptionRegister(), 17.1.1 OCISubscriptionUnRegister(), 17.1.1 OCISvcCtxToLda(), 17.1.1 OCITable, 12.9

バインドと定義, 12.9, 12.16

OCITableDelete(), 19.1.6 OCITableExists(), 19.1.6 OCITableFirst(), 19.1.6 OCITableLast(), 19.1.6 OCITableNext(), 19.1.6 OCITablePrev(), 19.1.6 OCITableSize(), 19.1.6 OCITerminate(), 16.1.10 OCIThreadパッケージ, 8.10 OCIThreadClose(), 17.1.1 OCIThreadCreate(), 17.1.1 OCIThreadHandleGet(), 17.1.1 OCIThreadHndDestroy(), 17.1.1 OCIThreadHndInit(), 17.1.1 OCIThreadIdDestroy(), 17.1.1 OCIThreadIdGet(), 17.1.1 OCIThreadIdInit(), 17.1.1 OCIThreadIdNull(), 17.1.1 OCIThreadIdSame(), 17.1.1 OCIThreadIdSet(), 17.1.1 OCIThreadIdSetNull(), 17.1.1 OCIThreadInit(), 17.1.1 OCIThreadIsMulti(), 17.1.1 OCIThreadJoin(), 17.1.1 OCIThreadKeyDestroy(), 17.1.1 OCIThreadKeyGet(), 17.1.1 OCIThreadKeyInit(), 17.1.1 OCIThreadKeySet(), 17.1.1 OCIThreadMutexAcquire(), 17.1.1 OCIThreadMutexDestroy(), 17.1.1 OCIThreadMutexInit(), 17.1.1 OCIThreadMutexRelease(), 17.1.1 OCIThreadProcessInit(), 17.1.1 OCIThreadTerm(), 17.1.1 OCITransCommit(), 17.1.1 OCITransDetach(), 17.1.1 OCITransForget(), 17.1.1 OCITransMultiPrepare(), 8.2.3.8, 17.1.1 OCITransPrepare(), 17.1.1 OCITransRollback(), 17.1.1 OCITransStart(), 17.1.1 OCIType

説明, 12.12.1

OCITypeAddAttr(), 21.1.2 OCITypeArrayByName(), 18.1.7 OCITypeArrayByRef(), 18.1.7 OCITypeBeginCreate(), 21.1.2 OCITypeByName(), 18.1.7 OCITypeByRef(), 18.1.7 OCITypeCode, 3.5 OCITypeElem

説明, 12.12.1

OCITypeEndCreate(), 21.1.2 OCITypeMethod

説明, 12.12.1

OCITypeSetBuiltin(), 21.1.2 OCITypeSetCollection(), 21.1.2 OCIUnicodeToCharSet(), 22.1.2 OCIUserCallbackGet(), 17.1.1 OCIUserCallbackRegister(), 17.1.1 OCIWcharデータ型, 2.8.7 OCIWideCharInSizeToMultiByte(), 22.1.2 OCIWideCharIsAlnum(), 22.1.2 OCIWideCharIsAlpha(), 22.1.2 OCIWideCharIsCntrl(), 22.1.2 OCIWideCharIsDigit(), 22.1.2 OCIWideCharIsGraph(), 22.1.2 OCIWideCharIsLower(), 22.1.2 OCIWideCharIsPrint(), 22.1.2 OCIWideCharIsPunct(), 22.1.2 OCIWideCharIsSingleByte(), 22.1.2 OCIWideCharIsSpace(), 22.1.2 OCIWideCharIsUpper(), 22.1.2 OCIWideCharIsXdigit(), 22.1.2 OCIWideCharMultiByteLength(), 22.1.2 OCIWideCharStrCaseConversion(), 22.1.2 OCIWideCharStrcat(), 22.1.2 OCIWideCharStrchr(), 22.1.2 OCIWideCharStrcmp(), 22.1.2 OCIWideCharStrcpy(), 22.1.2 OCIWideCharStrlen(), 22.1.2 OCIWideCharStrncat(), 22.1.2 OCIWideCharStrncmp(), 22.1.2 OCIWideCharStrncpy(), 22.1.2 OCIWideCharStrrchr(), 22.1.2 OCIWideCharToLower(), 22.1.2 OCIWideCharToMultiByte(), 22.1.2 OCIWideCharToUpper(), 22.1.2 OCIXmlDbFreeXmlCtx(), 14.5.3, 23.1.2 ocixmldb.hヘッダー・ファイル, 14.5.3 OCIXmlDbInitXmlCtx(), 14.5.3, 23.1.2 OID

「オブジェクト識別子」を参照

不透明, 定義, 1.1 コミット時ロック

実装, 14.1.7.4

ORA_EDITION環境変数, 8.7 ORA_NCHAR_LITERAL_REPLACE, 16.1.10 エンキュー中のORA-25219エラー, 9.9.3 Oracle Call Interface

「OCI」を参照

Oracleデータ型, 3.1

Cへのマッピング, 12.2

Oracle Database

トランザクション処理モニター, D.7

Oracle RAC, 9.2.8 Oracle Real Application Clusters, 9.2.8 Oracle Streamsアドバンスト・キューイング

デキュー関数, 17.1.1

説明, 9.9

記述子の属性, A.17

エンキュー関数, 17.1.1

関数, 17.1.1, E

OCIおよび, 9.9

OCI記述子, 9.9.2

OCI関数, 9.9.1

OCIとPL/SQL, 9.9.3

OCIでのパブリッシュ・サブスクライブの通知, 9.10

Oracle XAライブラリ

追加ドキュメント, D.7.3

OCIプログラムのコンパイルおよびリンク, D.7.1

動的な登録, D.7.2

Oracle XML DB OCI関数, 14.5, 23.1.2 orasb8データ型, 7.6 oratypes.h

OCIでのパラメータ・ソース, 3.6

内容, 3.6

定義, 3.6

oraub8データ型, 7.6 ORE

「オブジェクト・ランタイム環境」を参照

OTT

「OTTユーティリティ」を参照

OTTパラメータ, 15.8.1, 15.8.2

CASE, 15.8.2.10

CODE, 15.8.2.4

CONFIG, 15.8.2.8

ERRTYPE, 15.8.2.9

HFILE, 15.8.2.7

INITFILE, 15.8.2.5

INITFUNC, 15.8.2.6

INTYPE, 15.8.2.2

OUTTYPE, 15.8.2.3

SCHEMA_NAMES, 15.8.2.11

TRANSITIVE, 15.8.2.12

URL, 15.8.2.13

USERID, 15.8.2.1

表示される場所, 15.8.3

OTTユーティリティ

コマンドライン, 15.3, D.8

コマンドライン構文, 15.8.1

データベースでの型の作成, 15.2.1

データ型マッピング, 15.5

初期化関数

コール, 15.7.2

作業, 15.7.3

intypeファイル, 15.8.4 outtypeファイル, 15.6 概要, 15.1 パラメータ, 15.8.2

「OTTパラメータ」を参照

intypeファイルの提供, 15.4 リファレンス, 15.8 制限事項, 15.8.8 サンプル出力, 11.3.1 OCIでの使用方法, 11.3.1 使用方法, 15, 15.2 ottcfg.cfg, D.2 outtypeファイル, 15.8.4

OTTユーティリティの実行時, 15.6

OUTTYPE OTTパラメータ, 15.8.2.3

P

パッケージ

属性, 6.2.3

記述, 6.1

パラメータ記述子, 2.3.1.13.3

属性, 6.2, A.14

オブジェクト, 12.12.1

パラメータ

属性, 6.2

バッファ長, 16.1.9

モード, 16.1.4

文字列を渡す, 2.6.2.3

文字列長, 16.1.9

パスワード管理, 8.3, 8.3.2 永続オブジェクト, 11.2.2.1

メタ属性, 11.3.9.1

ピース単位

LOBのバインドおよび定義, 5.10.7

フェッチ, 5.10.6

ピース単位操作, 5.10.3

フェッチ, 5.10, 5.10.6.1

PL/SQL, 5.10.4

挿入, 5.10

更新, 5.10

有効なデータ型, 5.10.1

確保カウント, 11.3.13 確保継続時間

例, 14.1.9.1

オブジェクト, 14.1.9

オブジェクトの確保, 14.1.4.1 プレースホルダ

ルール, 4.3.1

PL/SQL,1.1.6.5

NESTED TABLEのバインドおよび定義, 5.9

REF CURSORのバインドおよび定義, 5.9

プレースホルダのバインド, 2.7

出力変数の定義, 5.4.2

ピース単位操作, 5.10.4

OCIアプリケーションでの使用, 2.7

OCIアプリケーションでの使用, 2.7

OCIプログラムでの使用, 5.1.5

ポーリング・モード, 2.6.8 位置指定の削除, 2.6.6 位置指定の更新, 2.6.6 プリフェッチ

OCIStmtExecute()中, 4.4

LOB, 7.9

プリフェッチ・メモリー・サイズの設定, 4.7.2

行カウントの設定, 4.7.2

単一のメッセージで複数のブランチを準備, 8.2.3.8 プロシージャ

属性, 6.2.2

プロセス

ハンドル属性, A.20

プロキシ・アクセス, 2.4.1.3.2 プロキシ認証, 2.4.1.3.2, 8.4.1.7, 8.4.1.7 パブリッシュ・サブスクライブ

_SYSTEM_TRIG_ENABLEDパラメータ, 9.10.4

COMPATIBLEパラメータ, 9.10.1.1

例, 9.10.4

関数, 9.10.1, 17.1.1, E

ハンドル属性, 9.10.1.1, A.18

LDAP登録, 9.10.1.3

通知コールバック, 9.10.2

OCIでの通知, 9.10

サブスクリプション・ハンドル, 9.10.1.1

Q

問合せ

明示的記述, 4.5.2

「SQL問合せ」を参照

R

RAW

外部データ型, 3.3.11

読取り専用パラメータ記述子, 2.3.1.13 REF

外部データ型, 3.3.20

REF列

ダイレクト・パス・ロード, 13.2.4

REF CURSOR変数

バインドと定義, 5.9

オブジェクトへの参照

「REF」を参照

リフレッシュ, 14.1.6.2

オブジェクト, 14.1.6.2

REF

バインド, 12.14.2

CURSOR変数, バインド, 5.2.3

定義, 12.15.2

外部データ型, 3.3.20

標識変数, 2.6.3, 2.6.4.3

サーバーからの取出し, 11.3.4

登録

ユーザー・コールバック, 9.6.1

レジストリ

REGEDT32, D.7.2.3

リレーショナル関数, C.8

サーバー・ラウンドトリップ, C.2

再リンク, 必要, 1.2.1 Required Support Files, D.1 予約済ネームスペース, 2.6.7.1 予約語, 2.6.7 結果キャッシュ, 10.4 結果セット, 4.8 結果セット記述子, 2.3.1.13 ブランチの再開, 8.2.3.5 オブジェクト型の属性の取出し

例, 6.4.3

表用の列データ型の取出し

例, 6.4.1

名前付きコレクション型のコレクション要素のデータ型の取出し

例, 6.4.4

戻り値

ナビゲーショナル関数, 18.1.5

RETURNING句

バインド, 5.7.2

エラー処理, 5.7.3

変数の初期化, 5.7.2

OCIでの使用, 5.7

REFで, 5.7.4

ロールバック, 2.4.3

オブジェクト・アプリケーション, 14.1.8

行の変更記述子, 2.3.1.13 ROWID

外部データ型, 3.3.21

暗黙的なフェッチ, 10.3

論理, 3.2.3

OCIRowid記述子, 2.3.1.13.4

ユニバーサルROWID, 3.2.3

位置指定の更新および削除に使用, 2.6.6

ROWID記述子, 2.3.1.13 RSF, D.1 ルール・セット

属性, 6.2.16

型OCI_PTYPE_RULE_SET, 6.2.16

ルール

属性, 6.2.15

型OCI_PTYPE_RULE, 6.2.15

OCIアプリケーションの実行, D.6

S

サンプル・プログラム, B, D.3

samplesディレクトリ, D.2

sb1

定義, 3.6

sb2

定義, 3.6

sb4

定義, 3.6

バインド/定義用の散布/収集, 5.6 スキーマ型属性

型OCI_PTYPE_SCHEMA, 6.2.13

SCHEMA_NAMES OTTパラメータ, 15.8.2.11

使用方法, 15.8.6

SCHEMA.QUEUE, 17.1.1 SCHEMA.QUEUE:CONSUMER_NAME, 17.1.1 スキーマ

属性, 6.2.13, 6.2.15, 6.2.16, 6.2.17, 6.2.18, 6.2.19, 6.2.20

記述, 6.1

スクリプト

ユーザーの認証, 8.3.3

スクロール・カーソル

例, 4.8.2

OCI, 4.8

パフォーマンスの向上, 4.8.1

Instant Client Light用SDK, 1.3.9 2次メモリー

オブジェクト, 14.1.10

SECUREFILEパラメータ, 7.10 SecureFile, 7.10

OCILobGetContentType(), 17.1.1

OCILobSetContentType(), 17.1.1

SecureFiles LOB, 7.10 セキュリティ

init.oraパラメータ, 8.8

OCI拡張機能, 8.8

選択リスト

記述, 4.5

順序

属性, 6.2.9

記述, 6.1

サーバー・ハンドル

属性, A.5

説明, 2.3.1.4

サービス・コンテキストでの設定, 2.3.1.4

サーバー・ラウンドトリップ

キャッシュ関数, C.4

データ型マッピング関数および操作関数, C.6

定義, C

記述操作, C.5

LOB関数, C.3

オブジェクト関数, C.4

リレーショナル関数, C.8

サービス・コンテキスト・ハンドル

属性, A.4

説明, 2.3.1.4

要素, 2.3.1.4

セッション作成, 2.4.1.3 セッション管理, 8.3, 8.3.4 セッションの移行, 8.3.1, 16.1.10 セッション・プール・ハンドル

属性, A.8

セッション・プーリング, 9.2, 9.4

例, 9.2.7

機能, 9.2.1

実行時接続ロード・バランシング, 9.2.8

タグ付け, 9.2

データベースの停止, 10.2 シグナル・ハンドラ, 8.9 スキップ・パラメータ

構造体配列, 5.5.1

標準配列, 5.5.1.1

スナップショット記述子, 2.3.1.13, 2.3.1.13.1 スナップショット

実行, 4.4.1

SQL問合せ

プレースホルダのバインド

「バインド操作」を参照

出力変数の定義, 4.6, 5.3, 12.15

「定義操作」を参照

結果のフェッチ, 4.7 文の種類, 1.1.6.4 SQL文, 1.1.6

プレースホルダのバインド, 4.3, 5.1, 12.14

準備するタイプの決定, 4.2

実行, 4.4

実行の準備, 4.2

処理, 4.1

型

制御文, 1.1.6.2

データ定義言語, 1.1.6.1

データ操作言語, 1.1.6.3

埋込みSQL, 1.1.6.6

PL/SQL, 1.1.6.5

問合せ, 1.1.6.4

SQLCS_IMPLICIT, 5.8.1.1, 17.1.1, 17.1.1, 17.1.1, 17.1.1, 17.1.1, 17.1.1, 17.1.1, E, E, E SQLCS_NCHAR, 5.8.1.1, 17.1.1, 17.1.1, 17.1.1, 17.1.1, 17.1.1, 17.1.1, 17.1.1, E, E, E sqlnet.ora, 8.8 sqlnet.ora, ADRの制御, 10.5.3 SQLT型コード, 3.5.1 SQLT_BDOUBLE, 3.3.24 SQLT_BFLOAT, 3.3.24 SQLT_CHR, A.19.1 SQLT_IBDOUBLE, 3.2.4, 6.2.10 SQLT_IBFLOAT, 3.2.4, 6.2.10 SQLT_NTY

バインドの例, 12.17.1

定義の例, 12.17.2

説明, 3.3.19

オブジェクト・メモリーの事前割当て, 12.15.3

SQLT_REF

定義, 3.3.20

説明, 3.3.20

データベースの起動, 10.2 STATEFUL, 9.3.11 ステートフル・セッション, 9.1.1.2 STATELESS, 9.3.11 ステートレス・セッション, 9.1.1.2 文キャッシュ, 9.5

コード例, 9.5.5

文ハンドル

属性, A.10

説明, 2.3.1.5

静的にリンクされたアプリケーション, 1.2.1 ストアド・ファンクション

記述, 6.1

ストアド・プロシージャ

記述, 6.1

STRING

外部データ型, 3.3.6

文字列

パラメータとして渡す, 2.6.2.3

構造体

配列, 5.5

サブプログラム属性, 6.2.2 サブスクリプション・ハンドル, 2.3.1.9

属性, A.18

OCIでのUTF-16 Unicodeサポート, 2.8.1, 2.8.1, 2.8.5, 2.8.5, 2.8.7, 2.8.8 sword

oratypes.hファイルの定義, 3.6

シノニム

属性, 6.2.8

記述, 6.1

T

表別名

属性

型OCI_PTYPE_TABLE_ALIAS, 6.2.18

表の変更記述子, 2.3.1.13 表

属性, 6.2.1

記述, 6.1

OCIDescribeAny()およびOCIStmtExecute()に関する制限, 6.1.1

TAF(透過的アプリケーション・フェイルオーバー)

コールバックの登録, 9.7.4

コールバック, 9.7

対応接続, 9.8.6

接続プール, 9.1.1.4

OCIコールバック, 9.7

タグ付け

カスタム・プーリング, 9.8.5

セッション・プーリング, 9.2, 16.1.10, 16.1.10

TDO

定義, 12.14.1

説明, 12.12.1

オブジェクト・キャッシュ内, 14.4

取得, 12.12.1

用語

ナビゲーショナル関数, 18.1.2

このマニュアルで使用される, 1.1.6.7

スレッド・ハンドルの説明, 2.3.1.8, 8.10.3.1 スレッド管理関数, 17.1.1 スレッド・セーフティ, 8.9

利点, 8.9.1

基本概念, 8.9

OCIでの実装, 8.9.3

7.xと8.0コールの混在, 8.9.3.2

必要なOCIコール, 8.9.3

3層アーキテクチャ, 8.9.2

スレッド・パッケージ, 8.10 3層アーキテクチャ

スレッド・セーフティ, 8.9.2

クライアントおよびサーバーで異なるタイム・ゾーン・ファイル, 10.6 TIMESTAMPデータ型, 3.3.23.2 TIMESTAMP記述子, 2.3.1.13 TIMESTAMP WITH LOCAL TIME ZONEデータ型, 3.3.23.4 TIMESTAMP WITH LOCAL TIME ZONE記述子, 2.3.1.13 TIMESTAMP WITH TIME ZONEデータ型, 3.3.23.3 TIMESTAMP WITH TIME ZONE記述子, 2.3.1.13 OCIからのTimesTen In-Memory Databaseアクセス, はじめに, 1.1, 10 TNS_ADMIN, 1.3.6 tnsnames.oraファイル, 1.3.2 トップレベル・メモリー

オブジェクト, 14.1.10

トランザクション・ハンドル

属性, A.9

説明, 2.3.1.4

トランザクション識別子, 8.2.3.1 トランザクション処理モニター

追加ドキュメント, D.7.3

Oracle Databaseとの対話, D.7

型, D.7

トランザクションの複雑度

OCIでのレベル, 8.2

トランザクション

コミット, 2.4.3

関数, 17.1.1

グローバル, 8.2.3

ブランチの状態, 8.2.3.4

ブランチ, 8.2.3.3

1フェーズ・コミット, 8.2.3.7

トランザクション識別子, 8.2.3.1

2フェーズ・コミット, 8.2.3.7

グローバルな例, 8.2.4 初期化パラメータ, 8.2.5 ローカル, 8.2.1 OCI関数

トランザクション, 8.1

読取り専用, 8.2.2 ロールバック, 2.4.3 シリアライズ可能, 8.2.2 一時オブジェクト, 11.2.2.2

LOB

属性, 7.4.2

メタ属性, 11.3.9.3 TRANSITIVE OTTパラメータ, 15.4, 15.5.2, 15.8.2.12 透過的アプリケーション・フェイルオーバー

「TAF」を参照

型属性

属性, 6.2.5

型記述子オブジェクト, 11.3.1, 12.12.1 型の変更, 11.5

オブジェクト・キャッシュ, 14.4

型関数

属性, 6.2.6

型の継承

OTTユーティリティ・サポート, 15.5.4

型メソッド属性, 6.2.6 型プロシージャ

属性, 6.2.6

型参照, 11.3.17 型コード, 3.5 型

属性, 6.2.4

記述, 6.1

U

ub1

定義, 3.6

ub2

定義, 3.6

ub4

定義, 3.6

Unicode

キャラクタ・セットID, A.11, A.11, A.12

データ・バッファ位置合せ, 2.8.8

OCILobRead(), E

OCILobWrite(), 17.1.1, 17.1.1, E

ユニバーサルROWID, 3.2.3 オブジェクトのマーク解除, 14.1.5.2 オブジェクトの確保解除, 11.3.13, 14.1.4.2 UNSIGNED

外部データ型, 3.3.14

更新

ピース単位, 5.10, 5.10.3

位置指定, 2.6.6

アップグレード

7.xから8.0, 1.2.5

7.xから8.0 OCI, 1.2.6

OCIのアップグレード, 1.2 URL OTTパラメータ, 15.8.2.13 UROWID

ユニバーサルROWID, 3.2.3

ユーザー・コールバック記述子, 2.3.1.13 ユーザー・メモリー

割当て, 2.3.1.13.8

ユーザー・セッション・ハンドル

属性, A.5.2

説明, 2.3.1.4

サービス・コンテキストでの設定, 2.3.1.4

ユーザー定義コールバック関数, 9.6

登録, 9.6.1

USERID OTTパラメータ, 15.8.2.1 名前付きコレクション型についての明示的な記述の使用

例, 6.4.4

名前付きオブジェクト型についての明示的な記述の使用方法

例, 6.4.3

表の列データ型を取り出す明示的な記述の使用方法

例, 6.4.1

utext

Unicodeデータ型, 5.8.2, 5.8.3.5.2

UTF-16データ, コード例, 5.8.3.5.2

V

値, 11.2.2

オブジェクト・アプリケーション, 11.2.2.3

VARCHAR

外部データ型, 3.3.9

VARCHAR2

外部データ型, 3.3.1

変数型の属性

型OCI_PTYPE_VARIABLE_TYPE, 6.2.19

VARNUM

外部データ型, 3.3.7

VARRAW

外部データ型, 3.3.12

VARRAY, 3.3.19, 12.9

オブジェクトとして, 11.1

Cマッピング, 15.5.1

定義コール, 12.15.1

サポートされていないダイレクト・パス・ロード, 13.1.4

イテレータ, 19.1.6

NULL, 11.3.14

またはコレクション・イテレータの例, 12.9.4

スキャン, 19.1.6

バージョンの互換性, 1.2.1 ビュー

属性, 6.2.1

記述, 6.1

W

wchar_tデータ型, 2.8.7, 5.8.3.5.2, 22.1.2

with_context

外部プロシージャ関数に対する引数, 20.1.3

X

XAライブラリ

OCIプログラムのコンパイルおよびリンク, D.7.1

関数, D.7

OCIサポート, 1.1.12

概要, D.7

XA仕様, 8.2.3.1 xa.hヘッダー, 1.1.12 XID

「トランザクション識別子」を参照

XML DB関数, 14.5.3, 23.1.2 OCIでのXMLのサポート, 14.5, 23.1 xtramem_szパラメータ

使用方法, 2.3.1.13.8

Oracleの法律上の注意点

コピーライト

Copyright © 1994-2017, 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 Corporationおよびその関連会社は一切の責任を負いかねます。

商標と登録商標について

OracleおよびJavaはオラクルおよびその関連会社の登録商標です。その他の社名、商品名等は各社の商標または登録商標である場合があります。

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

第三者のコンテンツ、製品、サービスに対する免責事項

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

Pre-General Availability (一般提供前)版のドキュメントについて

このドキュメントがPre-General Availability (一般提供前)版の場合:

このドキュメントはPre-General Availability (一般提供前)版であり、デモおよび暫定使用のみを目的としたものです。このソフトウェアを使用するハードウェアに限定するものではありません。Oracle Corporationおよびその関連会社は、このドキュメントに関して一切の責任を負わず、いかなる保証もいたしません。また、このドキュメントを使用したことによって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。

非公開のPre-General Availability (一般提供前)版のドキュメントについて

このドキュメントが非公開のPre-General Availability (一般提供前)版の場合:

このドキュメントに含まれる情報は、情報の共有のみを目的としたものであって、顧客諮問委員会(Customer Advisory Board)のメンバーとしてのお客様の立場でのみ、またはお客様のPre-General Availability Trial Agreement (Pre-GAトライアル契約)のみに従って検討されるべきものとします。マテリアル、コード、または機能の提供をお約束するものではなく、購入決定を行う際の判断材料とすべきではありません。このドキュメントに記載されている特徴または機能の開発、リリースおよび時期については、オラクルの裁量により決定されます。

このドキュメントには、ソフトウェアまたは印刷物などの形式を問わず、オラクルが独占的な権利を有する財産的情報が含まれています。この機密資料へのアクセスと使用は、お客様とオラクルとの間で締結され、お客様が遵守に同意した、Oracle Master Agreement、Oracle License and Oracle Services Agreement (オラクル・ライセンスおよびサービスに関する契約書)、Oracle Partner Network Agreement、Oracle Distribution Agreementまたはその他のライセンス契約の条件に従うものとします。このドキュメントとその内容の開示、コピー、複製および配布には、オラクルによる事前の承諾を必要とします。このドキュメントはライセンス契約の一部となるものではなく、オラクルおよびその子会社や関連会社との契約を構成するものではありません。

ドキュメントのアクセシビリティ

オラクルのアクセシビリティについての詳細情報は、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)を参照してください。