OBCI（OceanBase Call Interface）は、OceanBaseアーキテクチャ環境において、Oracle OCIと互換性のあるC言語インターフェース呼び出しツールであり、Oracle OCIと完全に互換性のある機能を提供します。
OBCIの紹介
OCI（Oracle Call Interface）は、Oracle社が開発したC言語向けアプリケーション開発ツールキットであり、Oracleデータベースサーバーにアクセスし、さまざまなSQL文の実行を制御することで、データベースのすべての操作を制御するためのアプリケーションプログラミングインターフェース（API）です。SQLのすべてのデータ定義、データ操作、クエリ、トランザクション管理などの操作をサポートし、CおよびC++のデータ型、呼び出し、構文、意味をサポートしています。Oracleデータベースへのアクセスを提供する一連のインターフェースサブルーチン（関数）を提供します。OBCIは、OCIのインターフェース標準を参考にしつつ、独自の特徴を組み合わせ、開発者にOracle互換機能を提供するインターフェース製品です。インターフェースの能力とユーザー動作はOracle OCIと一致しており、C言語側（OTL、Tuxdo、ECOBなど）からOceanBaseのOracleモードクラスタに迅速にアクセスする開発ユーザーのニーズを満たします。
関連する概念は以下のとおりです：
OBCI：C言語側からOceanBaseデータベースにアクセスするためのアプリケーションプログラミングインターフェースです。
OCI：C言語側からOracleデータベースにアクセスするためのアプリケーションプログラミングインターフェースです。
LibOBClient/libobclnt：OBCIが依存するC言語側のデータベース操作アクセスインターフェースです。
OceanBase Oracleモード：OceanBaseデータベースがOracle構文に互換する処理モードです。
OBCIの主な機能
OBCIを使用すると、C言語でOceanBaseデータベース（Oracleモード）のデータにアクセスし、操作できます。動的リンクライブラリ（OCIライブラリ）として標準的なデータベースアクセスおよびインデックス機能を提供しており、アプリケーションは実行時にこのライブラリをリンクすることでこれらの機能を利用できます。
OBCIが提供する主な機能は以下のとおりです：
OBCIは、データの定義、データ管理、クエリ処理、トランザクション制御などを含む、標準的なOceanBase Oracleデータベースアクセス・処理インターフェースを提供します。
OBCIのAPIインターフェースは、拡張性とマルチスレッドをサポートするアプリケーションに利用できます。
SQLアクセス関数をサポートします。データベースアクセスの管理、SQL文の処理、およびOceanBaseデータベースサーバーから取得したオブジェクトの操作に使用できます。
データ型マッピングと操作関数をサポートします。OceanBaseのデータ型属性を操作するために使用できます。
データロード関数をサポートします。SQL文を使用せずに直接データをデータベースにロードできます。
外部プロシージャ関数をサポートします。PL/SQL本体内でC言語のコールバック関数を指定できます。
OBCIの利点
OBCIは、データベースプロトコルを直接使用するか、Cインターフェースに直接アクセスしてOceanBaseデータベースなどを操作する方法と比較して、以下の利点があります：
データベースアクセス操作を高度にカプセル化し、業務実装ロジックを簡略化します。
サードパーティフレームワークの機能（Tuxdo、OTLなど）をサポートできます。
コネクションプールやステートメントキャッシュを使用でき、プログラムの拡張性を向上させます。
パラメータの動的バインディングや結果コールバック関数処理をサポートし、プログラムがパラメータや結果データを動的に処理しやすくします。
Meta情報を公開するインターフェースを提供します。
DML（INSERT、UPDATE、DELETE）において、配列などの複雑な型のデータに対する操作アクセスをサポートします。
Prefetch機能をサポートし、バックエンドとのやり取りを削減できます。
スレッドセーフを保証し、業務でのミューテックス使用を削減します。
サポートされているSQL
データ定義言語 (DDL)
制御文：
トランザクション制御
セッション制御
システム制御
データ操作言語 (DML)
クエリ
PL SQL/ノンブロッキング
データ型
OBCIは、OceanBaseデータベースのOracleモードで使用可能な内部データ型と、C言語の<oci.h>で定義された外部データ型（Oracle OCI互換）をサポートしています。
内部データ型
内部データ型とは、OceanBaseデータベースのOracleモードで使用できるデータ型を指します。
OBCIがサポートする一般的な内部データ型は以下の表のとおりです：
名前 |
説明 |
制限 |
|---|---|---|
| char | 固定長文字列 | 最大長 2000 |
| varchar2 | 可変長文字列 | 最大長 32767 |
| number | 数値型 | 精度の範囲 1 ～ 38 桁数の範囲 -84 ～ 127 |
| int | 整数型 | 最大値 38 桁 |
| binary_float | 32ビット浮動小数点数 | 最小値：1.17549E-38F 最大値：3.40282E+38F |
| binary_double | 64ビット浮動小数点数 | 最小値：2.22507485850720E-308 最大値：1.79769313486231E+308 |
| date | 日付型 | YYYY-MM-DD HH:MI:SS |
| timestamp | 時刻型 | YYYY-MM-DD HH:MI:SS [.FFFFFFFFF] |
外部データ型
外部データ型は、ホスト変数が格納するデータの型を指定するために使用されます。データベースにデータを入力する際、OBCIは入力されたホスト変数の外部データ型と内部データ型を変換します。外部プログラムにデータを出力する際、OBCIはデータベース内のテーブルの内部データ型と出力先のホスト外部データ型を変換します。
OBCIがサポートする一般的な外部データ型とその対応関係は次の表のとおりです：
外部データ型 |
エンコード |
ホスト変数のデータ型 |
OBCI型 |
|---|---|---|---|
| VARCHAR2 | 1 | char[n] | SQLT_CHR |
| NUMBER | 2 | unsigned char[21] | SQLT_NUM |
| 8-bit signed INTEGER | 3 | signed char | SQLT_INT |
| 16-bit signed INTEGER | 3 | signed short, signed int | SQLT_INT |
| 32-bit signed INTEGER | 3 | signed int, signed long | SQLT_INT |
| FLOAT | 4 | float, double | SQLT_FLT |
| LONG | 8 | char[n] | SQLT_LNG |
| NULL-terminated STRING | 5 | char[n+1] | SQLT_STR |
| LONG | 8 | char[n] | SQLT_LNG |
| VARCHAR | 9 | char[n+sizeof(short integer)] SQLT_VCS | VARCHAR |
| DATE | 12 | unsigned char[n] | SQLT_BIN |
| RAW | 23 | char[7] | SQLT_DAT |
| CHAR | 96 | char[n] | SQLT_AFC |
| REF | 110 | OCIRef | SQLT_REF |
| Character LOB descriptor | 112 | OCILobLocator (see note 2) | SQLT_CLOB |
| Binary LOB descriptor | 113 | OCILobLocator (see note 2) | SQLT_BLOB |
| ANSI DATE descriptor | 184 | OCIDateTime * | SQLT_DATE |
| TIMESTAMP descriptor | 187 | OCIDateTime * | SQLT_TIMESTAMP |
| TIMESTAMP WITH TIME ZONEdescriptor | 188 | OCIDateTime * | SQLT_TIMESTAMP_TZ |
| TIMESTAMP WITH LOCAL TIME ZONEdescriptor | 232 | OCIDateTime * | SQLT_TIMESTAMP_LTZ |
データ型の変換
OBCIプログラムでは、ホスト変数（Host Variables）に外部データ型が使用されています。データベースから外部変数にデータを読み取る場合、または外部データをデータベースに格納する場合、データ型の変換が発生します。
現在サポートされているデータ型の変換は、次の表のとおりです：
VARCHAR2/CHAR |
INT |
NUMBER |
FLOAT |
BINARY_FLOAT |
BINARY_DOUBLE |
DATE |
TIMESTAMP |
|
|---|---|---|---|---|---|---|---|---|
| CHAR/UNSIGNED CHAR | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| INT/UNSIGNED INT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| LONG/UNSIGNED LONG | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| LONG LONG/UNSIGNED LONG LONG | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| FLOAT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| DOUBLE | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | ||
| CHAR[n]/VARCHAR[n]/CHAR* | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN/OUT | IN |
説明
表に記載されていないエラーもあります。例えば、
VARCHAR2をC言語のCHARに変換する際に、オーバーフローや無効な数字などのエラーが発生する可能性があります。IN はC言語からデータベース型への変換、つまりデータベースへの書き込みをサポートしていることを示します。OUT はデータベース型からC言語への変換、つまりデータの読み取りをサポートしていることを示します。
オブジェクトと関数インターフェース
OBCIオブジェクトインターフェース
OBCIがサポートするOCI内部の一般的なオブジェクトインターフェースは、次のテーブルのとおりです。
オブジェクト |
オブジェクトの説明 |
|---|---|
| OCIEnv | OCI環境ハンドル |
| OCIError | OCIエラー処理ハンドル、処理中のエラー情報を取得するオブジェクト |
| OCISvcCtx | OCIサービスコンテキストオブジェクト（メモリ、接続など） |
| OCIStmt | OCIステートメント処理オブジェクト |
| OCIBind | OCIパラメータ変数情報 |
| OCIDefine | OCI結果変数情報 |
| OCIDescribe | OCI定義型情報 |
| OCIServer | OCIバックエンドOBServerノードオブジェクト |
| OCISession | OCI接続Session情報 |
| OCITrans | OCIトランザクションオブジェクト |
| OCICPool | OCI CPool接続プールオブジェクト |
| OCIAuthInfo | OCI接続認証情報 |
| OCILobLocator | OCI Lobオブジェクト、Lob関数処理 |
| OCIParam | OCIパラメータオブジェクト、オブジェクトのMeta情報を取得可能 |
| OCIRowid | OCI OB Rowidオブジェクト |
| OCIDate | OCI日付オブジェクト |
| OCIDateTime | OCIタイムスタンプオブジェクト |
| OCIInterval | OCI時間間隔オブジェクト |
| OCINumber | OCI高精度データオブジェクト |
| OCIString | OCI文字列オブジェクト |
OBCI関数インターフェース
初期化関連
初期化や接続認証などに関する関数は以下の表のとおりです。
関数 |
関数の説明 |
|---|---|
| OCIEnvCreate | 環境ハンドルを作成し、初期化します。 |
| OCIEnvNlsCreate | OCI関数で使用できるように、環境ハンドルを作成して初期化します。OCIEnvCreate()関数の拡張バージョンです。 |
| OCIEnvInit | 環境ハンドルを割り当て、初期化します。 |
| OCIInitialize | OCIアプリケーション環境を初期化します。OCIはこの関数で内部のグローバル変数を初期化し、一部の設定情報を読み込みます。 |
| OCILogoff | OCILogon/OCILogonを介してサーバーと確立した接続を切断します。 |
| OCILogon | ユーザー名とパスワードに基づいて、指定されたデータベースサービスにログインし、関連するコンテキストハンドルを初期化します。 |
| OCILogon2 | ユーザー名とパスワードに基づいて、指定されたデータベースサービスにログインし、関連するコンテキストハンドルを初期化します。CPOOL接続を使用して処理できます。 |
| OCIServerAttach | 指定された接続ハンドルにデータベースサービスを追加します。 |
| OCIServerDetach | 接続ハンドルとデータベースサービス名との関連を解除します。 |
| OCISessionBegin | ログイン情報を使用して、指定されたコンテキストハンドル上でデータベースサービスへの接続を開きます。 |
| OCISessionEnd | OCISessionBegin関数で開始されたコンテキストハンドルとデータベースサービス間の接続を終了します。 |
| OCIPing | 接続とサービスがアクティブ状態にあるかどうかを確認します。サービスが実行中で接続が存在する場合にのみ成功します。 |
| OCITerminal | スレッド内の処理を終了します |
オブジェクト初期化関連
HandleとDescriptorに関する関数は以下の表のとおりです。
関数 |
関数の説明 |
|---|---|
| OCIAttrGet | ハンドル上の属性値を取得します。 |
| OCIAttrSet | ハンドルの属性を設定します。 |
| OCIDescriptorAlloc | フィールドディスクリプタハンドルを格納するための領域を割り当てます。 |
| OCIDescriptorFree | OCIDescriptorAlloc で生成されたディスクリプタを解放します。 |
| OCIHandleAlloc | 各種ハンドルを割り当て、初期化します。 |
| OCIHandleFree | OCIHandleAlloc で割り当てられたハンドルを解放します。 |
| OCIParamGet | ディスクリプタハンドル上の指定された位置にあるデータを取得します。 |
パラメータバインディング結果処理関連
Bind、Define、Describeなど、パラメータや結果セットスペースに関する関数は以下の表のとおりです。
関数 |
関数の説明 |
|---|---|
| OCIBindArrayOfStruct | パラメータを配列形式でバインドします。 |
| OCIBindByName | SQLステートメント内のパラメータをパラメータ名でバインドします（同名の場合は1回のみバインド）。 |
| OCIBindByPos | SQLステートメント内でのパラメータの出現位置に基づいてバインドします。 |
| OCIDefineArrayOfStruct | 結果列を配列形式でバインドします。 |
| OCIDefineByPos | 位置に基づいて、クエリが返す結果セットの各列の値の範囲をバインドします。 |
リクエスト文処理関連
文処理に関する関数は以下の表のとおりです。
関数 |
関数の説明 |
|---|---|
| OCIStmtPrepare | SQLステートメントを準備し、Stmtpオブジェクトを初期化します。その後、OCIStmtExecuteを呼び出して実行します。 |
| OCIStmtExecute | 準備済みのステートメントを実行します。 |
| OCIStmtFetch | SQLで生成された結果セットの行セットを取得します。1つのクエリを実行した後、この関数を複数回呼び出して結果セット内のすべての行を返すことができます。OCI_NO_DATAが返されるまで繰り返します。 |
| OCIStmtRelease | OCIStmtPrepare2()を呼び出して取得したステートメントハンドルを解放します。 |
トランザクション処理関連
トランザクション処理に関する関数は以下の表のとおりです。
関数 |
関数の説明 |
|---|---|
| OCITransStart | トランザクションを開始します。 |
| OCITransCommit | SQLの実行アクションをコミットします。 |
| OCITransRollback | SQLの実行アクションをロールバックします。 |
データ型関連
各種データ型に関する関数は以下の表のとおりです。
データオブジェクト |
関数 |
関数の説明 |
|---|---|---|
| OCIString | OCIStringAllocSize | コードポイント（Unicode）またはバイト単位での文字列メモリの割り当てサイズを取得します。 |
| OCIString | OCIStringAssign | ある文字列を別の文字列に代入します。 |
| OCIString | OCIStringAssignText | ある文字列を別の文字列に代入します。 |
| OCIString | OCIStringPtr | 指定された文字列テキストへのポインタを取得します。 |
| OCIString | OCIStringSize | 指定された文字列テキストのサイズを取得します。 |
| OCIString | OCIStringResize | 指定された文字列テキストのサイズを取得します。 |
| OCILoblocator | OCILobGetLength | バイト単位での大フィールドの長さを返します。 |
| OCILoblocator | OCILobRead | 大フィールド内の指定された長さの内容を読み取ります。 |
| OCILoblocator | OCILobWrite | 内容を大フィールドストレージディスクリプタに連続して書き込みます。 |
| OCILoblocator | OCILobLocatorIsInit | 指定されたLOB/BFILEハンドルが初期化されているかどうかを判断します。 |
| OCILoblocator | OCILobOpen | LOB/BFILEオブジェクトを開きます |
| OCILoblocator | OCILobClose | LOB/BFILEオブジェクトを閉じます |
| OCILoblocator | OCILobIsOpen | LOB/FILEオブジェクトが開いているかどうかをテストします。 |
| OCILoblocator | OCILobTrim | LOB値をより短い長さに切り詰めます。 |
| OCILoblocator | OCILobTrim2 | LOB値をより短い長さに切り捨てます。OceanBaseは現在、最大48MBのLOBのみをサポートしています。 |
| OCIDate | OCIDateSysDate | クライアントの現在のシステム日付と時刻を取得します。 |
| OCIDate | OCIDateToText | 日付型を指定された形式の文字列に変換します。 |
| OCIDate | OCIDateFromText | 指定された形式に基づいて、文字列を日付型に変換します。 |
| OCIDateTime | OCIDateTimeToText | 指定された形式に従って、指定された日付を文字列に変換します。 |
| OCIDateTime | OCIDateTimeFromText | 指定された形式に従って、指定された日付を文字列に変換します。 |
| OCIDateTime | OCIDateTimeConstruct | 日時を構築します。 |
| OCIDateTime | OCIDateTimeGetTime | 日時値から時間（時、分、秒、小数秒）を取得します。 |
| OCIDateTime | OCIDateTimeGetDate | 日時値の日付（年、月、日）部分を取得します。 |
| OCIDateTime | OCIDateTimeGetTimeZoneOffset | 日時値のタイムゾーン（時、分）部分を取得します。 |
| OCINumber | OCINumberToInt | Oracle NUMBER 型を整数に変換します。 |
| OCINumber | OCINumberToReal | Oracle NUMBER 型を実数に変換します。 |
| OCINumber | OCINumberToText | 指定された形式に従って、Oracle NUMBER を文字列に変換します。 |
| OCINumber | OCINumberIsInt | OCINumberが整数かどうかをテストします。 |
| OCINumber | OCINumberFromText | 文字列をOracle NUMBERに変換します。 |
その他の関数
よく使われるその他の関数は以下の表のとおりです。
関数 |
関数の説明 |
|---|---|
| OCIBreak | この呼び出しは、サーバーに関連付けられたOBCI機能の現在の（非同期）実行を即座に終了します。 |
| OCIClientVersion | 実行時クライアントライブラリのバージョン番号を返します。 |
| OCIServerVersion | 実行時サーバーライブラリのバージョン番号を返します。 |
| OCIErrorGet | 指定されたバッファにエラーメッセージとOceanBaseエラーコードを返します。 |
| OCIPasswordChange | アカウントのパスワードを変更します。 |
| OCIPing | サーバーと往復通信を行い、接続とサーバーがアクティブ状態であることを確認します。 |
詳細を見る
OBCIの詳細および使用方法については、『OceanBase C言語呼び出しインターフェース』を参照してください。