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ビット符号付き整数 | 3 | signed char | SQLT_INT |
| 16ビット符号付き整数 | 3 | signed short, signed int | SQLT_INT |
| 32ビット符号付き整数 | 3 | signed int, signed long | SQLT_INT |
| FLOAT | 4 | float, double | SQLT_FLT |
| LONG | 8 | char[n] | SQLT_LNG |
| NULL終了文字列 | 5 | char[n+1] | SQLT_STR |
| LONG | 8 | char[n] | SQLT_LNG |
| VARCHAR | 9 | char[n+sizeof(short integer)] | 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 (注記2参照) | SQLT_CLOB |
| Binary LOB descriptor | 113 | OCILobLocator (注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によって生成された結果セットから行セットを取得します。クエリを実行した後、この関数を複数回呼び出すことで、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 Language Call Interface』を参照してください。