Oracle Database Access C API

26 Oracle Database Access C API

この章では、最初にOracle Database Access C API、特にC対応のOCIリレーショナル関数について説明します。

各関数コールの詳細を説明するとともに、使用しているアプリケーションでOCI関数をコールする方法についても説明します。

26.1 OCIパイプライン関数

OCIパイプライン関数をリストし、説明します。

表26-1 OCIパイプライン関数

関数	用途
`OCIPipelineBegin()`	操作のパイプライン・ブロックの開始を指定します。
`OCIPipelineProcess()`	操作を処理します。
`OCIPipelineEnd()`	操作のパイプライン・ブロックの終了を指定します。

26.1.1 OCIPipelineBegin()

この関数は、操作のOCIパイプライン・ブロックの開始を示します。

用途

OCIPipelineBegin()関数は、OCIパイプライン操作の開始を示します。サービス・コンテキストをパイプライン・モードに設定するすべてのプロローグ・アクティビティ。

構文

sword OCIPipelineBegin(OCISvcCtx  *svchp,
                        ub4                  errSetID,
                        boolean              errSetMode,
                        OCIPipelineOpCbk     pipeOpCbk,
                        void                *pipeOpCbkCtx,
                        OCIError            *errhp,
                        ub4                  mode);

パラメータ

svchp (IN): OCIサービス・コンテキストです。
cbk (IN): 各OCIパイプライン操作に対して実行されるコール。
cbkCtx (IN): コールバックのコンテキスト。
errhp (IN/OUT): エラー・ハンドル

mode (IN)

サポートされるモード:

OCI_PIPELINE_CONT_ON_ERROR
OCI_PIPELINE_ABORT_ON_ERROR

戻り値

OCI_SUCCESS: 関数が成功した場合。
OCI_ERROR: 関数が失敗すると、実際のエラーをerrhpから取得できます。

26.1.1.1 コールバックとコンテキスト

この項では、OCIパイプライン操作で使用されるコールバック・コンテキストおよびコールバック・コンテキストについて説明します。

コールバックおよびコンテキストは、アプリケーションが操作の結果を処理できるようにするためにOCIPipelineBegin()関数に提供されます。このコールバックは、サーバーで実行され、レスポンスとともに返されるすべての操作に対して実行されます。これは、パイプライン・ブロック内のすべての操作に対して1つの標準コールバックです。

構文

typedef sword (*OCIPipelineOperationCallback) (
OCISvcCtxt       	*svchp, 
ub4                      operationIndex, 
OCIPipelineOperation    *hndlp, 
ub4                      operationStatus, 
void                    *callbackCtx, 
OCIError                *errhp);

パラメータ

svchp: 操作が実行されているサービス・コンテキスト。
operationIndex: サービス・コンテキストの操作キュー内の操作の索引。
hndlp: 操作ハンドル・ポインタ。
operationStatus: 操作のステータス(OCI_ERROR/OCI_SUCCESS)には、OCI関数の有効な戻り値のいずれかを指定できます。
callbackCtx: コールバック・コンテキストはアプリケーション提供のコンテキストです。
errhp: エラー・ハンドル・ポインタ。

ノート:
アプリケーションは、コールバック内の別のOCI操作をパイプライン化できません。非簡易再帰が作成されます。

26.1.2 OCIPipelineProcess()

OCIoperationIDで指定されたパイプライン操作を処理します。

用途

OCIPipelineProcess()は、前の操作から取得された保留中の操作を処理します。アプリケーションがパイプライン操作ハンドルでOCIPipelineProcess()関数を使用すると、この操作ハンドルが処理されるまで、パイプラインの下半分のすべての操作がキューに入れられます。それぞれのコールバックも処理されます。指定された操作に先行するすべての操作が完了してから戻ります。

操作の実行は、次のセマンティクスに従って行われます。

アプリケーションが最初の操作を処理する場合、最初の操作のみが処理されます。
アプリケーションがK番目の操作を処理する場合、K番目の操作より前のすべての操作が処理されます。
アプリケーションが最後の操作を処理する場合、最後の操作より前のすべての操作が処理されます。

構文

sword OCIPipelineProcess (OCISvcCtx     *svchp,
                          OCIPipelineOperationID  opID,
	                   ub4              	timeout,
                          OCIError               *errhp,
                          ub4            	  mode);

パラメータ

svchp (IN): OCIサービス・コンテキストです。

hndl (IN/OUT): 操作ハンドル。

timeout (IN): この関数の完了または操作の終了のタイムアウト(ミリ秒)。値が0に設定されている場合は、永続的に、または操作が完了するまで待機します。

errhp (OUT): エラー・ハンドル。

mode (IN)

次のモードがサポートされています。

OCI_DEFAULT

この関数で指定されたタイムアウトは、このコールで実行される操作のセットに対するものです。指定された操作の前に操作がある場合、この操作の前にすべての操作が読み取られます。

次のコード・スニペットは、パイプライン・モードで3つの文を実行し、3つの文すべての下半分を順番に処理するアプリケーションを示しています。

OCIPipelineBegin(svchp …);
OCIStmtExecute(stmthp1, ….,  OCI_DEFAULT) – Send
OCIStmtExecute(stmthp2, … ,OCI_DEFAULT) - Send
OCIStmtExecute(stmthp3, …, OCI_DEFAULT) – Send
			
OCIPipelineOperations *oparr = NULL;
ub4 arrlen = 0;
status = OCIAttrGet(svchp, OCI_HTYPE_SVC, &oparr, &arrlen, OCI_ATTR_PIPELINE_OPERATIONS, errhp, OCI_DEFAULT);
for(int i =0; i < arrlen, i< arrlen)
{  
rc = OCIPipelineProcess(svchp, oparr[i], 1000, errhp, 
                        OCI_DEFAULT); // recv (ith statement)
     if(!rc)
       break;
}
 OCIPipelineEnd(svchp, timeout …);

26.1.3 OCIPipelineEnd()

この関数は、操作のパイプライン・ブロックの終了を示します。

用途

この関数は、操作のパイプライン・ブロックの終了を示します。デフォルトでは、この関数はブロックされています。つまり、この関数OCIPipelineEnd()は、パイプライン内の他の操作とともにキューに入れられます。このモードでは、キューに入れられた操作は処理されません。同期ポイントの導入はアプリケーションの責任です。デフォルトでは、この関数はブロックされています。すべての操作を読み取り、「Pipeline End」のRPCを送受信します。ブロック・モードでは、このサービス・コンテキストに関連付けられているすべてのOCIパイプライン操作を処理し、OCIPipelineBegin()によって作成されたパイプライン・ブロックを終了するために使用されます。コールバックは、サーバーで正常に実行されたすべての操作に対してコールされます。

構文


sword OCIPipelineEnd (OCISvcCtx *svchp,
      	              ub4        timeout,
                      OCIError  *errhp,
        	      ub4        mode);

パラメータ

svchp (IN): OCIサービス・コンテキストです。

timeout (IN): この関数の完了または終了のタイムアウト(ミリ秒)。

errhp (OUT): エラー・ハンドル。

mode (IN)

次のモードがサポートされています。

OCI_DEFAULT

戻り値:

OCI_SUCCESS: 関数が成功した場合。
OCI_ERROR: これが失敗した場合は、errhpを使用して実際のエラーを取得できます。

次のコード・スニペットは、サービス・コンテキストでのOCIPipelineEnd関数の使用方法を示しています。

OCIPipelineBegin(svchp … OCI_DEFAULT);
OCIStmtExecute(stmthp1, .. , OCI_DEFAULT) – Send
OCIStmtExecute(stmthp2, .. , OCI_DEFAULT) - Send
OCIStmtExecute(stmthp3, .. , OCI_DEFAULT) – Send

OCIPipelineEnd(svchp, timeout, errhp, OCI_DEFAULT);  
/*All 3 stmts are complete here */