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

バインド関数、定義関数および記述関数をリストし、説明します。

表25-4は、この項で説明しているバインド関数、定義関数および記述関数を示しています。

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

関数	用途
OCIBindArrayOfStruct()	静的配列バインド用のスキップ・パラメータを設定します。
OCIBindByName()	名前によりバインドします
OCIBindByName2()	名前によりバインドします。クライアント上で、戻される長さがUB2MAXVALを超える場合に使用します。
OCIBindByPos()	位置によりバインドします
OCIBindByPos2()	位置によりバインドします。クライアント上で、戻される長さがUB2MAXVALを超える場合に使用します。
OCIBindDynamic()	OCI_DATA_AT_EXECモードでバインドした後、追加属性を設定します。
OCIBindObject()	名前付きデータ型のバインド用の追加属性を設定します。
OCIDefineArrayOfStruct()	静的配列定義用の追加属性を設定します。
OCIDefineByPos()	出力変数の関連性を定義します。
OCIDefineByPos2()	出力変数の関連性を定義します。クライアント上で、戻される長さがUB2MAXVALを超える場合に使用します。
OCIDefineDynamic()	OCI_DYNAMIC_FETCHモードでの定義用の追加属性を設定します。
OCIDefineObject()	名前付きデータ型の定義用の追加属性を設定します。
OCIDescribeAny()	既存のスキーマ・オブジェクトを記述します。
OCIStmtGetBindInfo()	バインドおよびインジケータ変数名とハンドルを取得します。

25.4.1 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での構造体配列のバインドと定義について」を参照してください

25.4.2 OCIBindByName()

プログラム変数とSQL文またはPL/SQLブロック内のプレースホルダを関連付けます。

用途

プログラム変数と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に代わる新しい指定です。

さらに、OCIStmtPrepare2()で説明したように、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の場合は、バインド・ハンドルで追加コールを行い、データ型固有の属性を設定する必要があります。レコード、コレクションおよびブールの詳細は「コメント」を参照してください。名前付きデータ型SQLT_CHRでは、実際の長さが0の場合、後続の空白はOCIBindByName()によって切り捨てられます。後続の空白が切り捨てられることを避けるには、実際の長さを指定します。

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)

コーディングの一貫性を確保するために、理論的にはこのパラメータはOCIStmtPrepare2()で使用される可能性のある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 *型である必要があります。このモードは、分散または集約のバインドに使用されることが目的であり、複数のバッファを1つの位置にバインドまたは定義できます。たとえば、列Aの最初の10行を1つのバッファに、次の5行を1つのバッファに、そして残りの25行を別のバッファにバインドまたは定義できます。これにより、配列の実行操作を行う場合に、それらのすべてを1つの大きなバッファに割り当ててコピーする必要がなくなります。

  関連項目:

  複数バッファのバインドと定義について

割り当てたバッファは、不要になった際にクライアント側で解放する必要があります。

コメント

このコールは、基本バインド操作を実行するときに使用します。バインドは、プログラム変数のアドレスとSQL文またはPL/SQLブロック内のプレースホルダの関連付けを作成します。このバインド・コールは、バインドされるデータの型も指定し、実行時にデータを提供するメソッドも指示できます。

エンコーディングの決定は、文ハンドルの設定をデフォルトとして使用してバインド・ハンドルで行うか、modeパラメータを明示的に指定してその設定を上書きして行うことができます。

OCIBindByName()およびOCIBimdByName2()は、bindppパラメータによって指示されたバインド・ハンドルの暗黙的な割当ても行います。**bindppに非NULLポインタが渡されると、このポインタはOCIHandleAlloc()またはOCIBindByName()のコールで以前に割り当てられた有効なハンドルを指し示していると、OCIでは想定されます。

OCIアプリケーション内のデータは、プレースホルダに静的または動的にバインドできます。操作の実行の直前にすべてのINバインド・データとOUTバインド・バッファが正しく定義された場合、バインドは静的になります。アプリケーションの要求によって、INバインド・データとOUTバインド・バッファが実行時にクライアント・ライブラリに提供された場合、バインドは動的になります。動的バインドを指定するには、このコールのmodeパラメータをOCI_DATA_AT_EXECに設定します。

関連項目:

動的バインドの詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください

OCIBindByName()とOCIBindByName2()、およびOCIBindByPos()とOCIBindByPos2()はどちらもパラメータとしてバインド・ハンドルを取りますが、これはバインド・コールによって暗黙的に割り当てられます。アプリケーションでバインドしているすべてのプレースホルダに別個のバインド・ハンドルが割り当てられます。

特定のデータ型をバインドする際または入力データを特定の方法で処理する際に必要となる特定の属性を指定する場合は、次の追加バインド・コールが必要です。

• 構造体配列が使用されている場合、OCIBindArrayOfStruct()をコールして必要なスキップ・パラメータを設定してください。

• 実行時にデータが動的に提供されている場合、アプリケーションでユーザー定義のコールバック関数を使用するときにはOCIBindDynamic()をコールしてコールバックを登録します。

• alenpに64キロバイト(KB)を超える長さが必要な場合は、OCIBindDynamic()を使用します。

• 名前付きデータ型がバインドされている場合、OCIBindObject()をコールしてその他の必要情報を指定する必要があります。

• RETURNING句を含む文を使用する場合は、このコールの後にOCIBindDynamic()をコールする必要があります。

INバインドの場合、OCIStmtExecute()のコールの前に、配列の各要素、各要素の実際の長さ、および実際の配列長の値を設定する必要があります。

OUTバインドの場合、OCIStmtExecute()のコールの後で、配列の各要素、各要素の実際の長さ、および実際の配列長の値がサーバーから戻されます。

レコードの場合

クライアント側で、SQLT_NTYをバインドのDTYとして使用してパッケージのレコード型がバインドされるようにする必要があります。OCIクライアントでは、オブジェクトおよびレコードは名前付き型(NTY)として示されるため、同じSQLTコードを使用する必要があります。

コレクションの場合

クライアント側で、SQLT_NTYを使用してすべてのパッケージのコレクション型がバインドされるようにする必要があります。これは、すべてのスキーマ・レベルのコレクション型をバインドするのに使用されるDTYです。

ブールの場合

クライアント側で、SQLT_BOLを使用してブール型(OCI_TYPECODE_BOOLEAN)がバインドされるようにする必要があります。

25.4.3 OCIBindByName2()

プログラム変数とSQL文またはPL/SQLブロック内のプレースホルダを関連付けます。この関数は、クライアント上で実際の長さがUB2MAXVALを超える場合、データ型を操作する際に使用します。

用途

プログラム変数とSQL文またはPL/SQLブロック内のプレースホルダを関連付けます。クライアント上で実際の長さがUB2MAXVALを超える場合、データ型を操作する際にOCIBindByName()のかわりにこのコールを使用します。

構文

sword OCIBindByName2 ( OCIStmt         *stmtp, 
                       OCIBind        **bindpp,
                       OCIError        *errhp,
                       const OraText   *placeholder,
                       sb4              placeh_len,
                       void            *valuep,
                       sb8              value_sz,
                       ub2              dty,
                       void            *indp,
                       ub4             *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に代わる新しい指定です。

さらに、OCIStmtPrepare2()で説明したように、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パラメータで指定される実際のサイズで可能な要素の最大サイズです。

value_sz > SB4MAXVALの値の場合、> SB4MAXVALの値はリリース12.1以上ではサポートされていないことを意味するORA-24452エラーが発行されます。

クライアント・アプリケーションではサイズが不明な記述子、ロケータまたはREFの場合は、特定の型へのポインタのサイズ、たとえばsizeof (OCILobLocator *)などが使用されます。

モードがOCI_IOVの場合でも同様です。

dty (IN)

バインドされる値のデータ型です。名前付きデータ型(SQLT_NTY)とREF (SQLT_REF)は、アプリケーションがオブジェクト・モードで初期化されている場合のみ有効です。名前付きデータ型またはREFの場合は、バインド・ハンドルで追加コールを行い、データ型固有の属性を設定する必要があります。レコード、コレクションおよびブールの詳細は「コメント」を参照してください。名前付きデータ型SQLT_CHRでは、実際の長さが0の場合、後続の空白はOCIBindByName2()によって切り捨てられます。後続の空白が切り捨てられることを避けるには、実際の長さを指定します。

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)

コーディングの一貫性を確保するために、理論的にはこのパラメータはOCIStmtPrepare2()で使用される可能性のある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 *型である必要があります。このモードは、分散または集約のバインドに使用されることが目的であり、複数のバッファを1つの位置にバインドまたは定義できます。たとえば、列Aの最初の10行を1つのバッファに、次の5行を1つのバッファに、そして残りの25行を別のバッファにバインドまたは定義できます。これにより、配列の実行操作を行う場合に、それらのすべてを1つの大きなバッファに割り当ててコピーする必要がなくなります。

  関連項目:

  複数バッファのバインドと定義について

割り当てたバッファは、不要になった際にクライアント側で解放する必要があります。

コメント

このコールは、基本バインド操作を実行するときに使用します。バインドは、プログラム変数のアドレスとSQL文またはPL/SQLブロック内のプレースホルダの関連付けを作成します。このバインド・コールは、バインドされるデータの型も指定し、実行時にデータを提供するメソッドも指示できます。

エンコーディングの決定は、文ハンドルの設定をデフォルトとして使用してバインド・ハンドルで行うか、modeパラメータを明示的に指定してその設定を上書きして行うことができます。

OCIBindByName2()は、bindppパラメータによって指示されたバインド・ハンドルの暗黙的な割当ても行います。**bindppに非NULLポインタが渡されると、このポインタはOCIHandleAlloc()またはOCIBindByName2()のコールで以前に割り当てられた有効なハンドルを指し示していると、OCIでは想定されます。

OCIアプリケーション内のデータは、プレースホルダに静的または動的にバインドできます。操作の実行の直前にすべてのINバインド・データとOUTバインド・バッファが正しく定義された場合、バインドは静的になります。アプリケーションの要求によって、INバインド・データとOUTバインド・バッファが実行時にクライアント・ライブラリに提供された場合、バインドは動的になります。動的バインドを指定するには、このコールのmodeパラメータをOCI_DATA_AT_EXECに設定します。

関連項目:

動的バインドの詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください

OCIBindByName2()とOCIBindByPos2()は、パラメータとしてバインド・ハンドルを取りますが、これはバインド・コールによって暗黙的に割り当てられます。アプリケーションでバインドしているすべてのプレースホルダに別個のバインド・ハンドルが割り当てられます。

特定のデータ型をバインドする際または入力データを特定の方法で処理する際に必要となる特定の属性を指定する場合は、次の追加バインド・コールが必要です。

• 構造体配列が使用されている場合、OCIBindArrayOfStruct()をコールして必要なスキップ・パラメータを設定してください。

• 実行時にデータが動的に提供されている場合、アプリケーションでユーザー定義のコールバック関数を使用するときにはOCIBindDynamic()をコールしてコールバックを登録します。

• alenpに64キロバイト(KB)を超える長さが必要な場合は、OCIBindDynamic()を使用します。

• 名前付きデータ型がバインドされている場合、OCIBindObject()をコールしてその他の必要情報を指定する必要があります。

• RETURNING句を含む文を使用する場合は、このコールの後にOCIBindDynamic()をコールする必要があります。

INバインドの場合、OCIStmtExecute()のコールの前に、配列の各要素、各要素の実際の長さ、および実際の配列長の値を設定する必要があります。

OUTバインドの場合、OCIStmtExecute()のコールの後で、配列の各要素、各要素の実際の長さ、および実際の配列長の値がサーバーから戻されます。

レコードの場合

クライアント側で、SQLT_NTYをバインドのDTYとして使用してパッケージのレコード型がバインドされるようにする必要があります。OCIクライアントでは、オブジェクトおよびレコードは名前付き型(NTY)として示されるため、同じSQLTコードを使用する必要があります。

コレクションの場合

クライアント側で、SQLT_NTYを使用してすべてのパッケージのコレクション型がバインドされるようにする必要があります。これは、すべてのスキーマ・レベルのコレクション型をバインドするのに使用されるDTYです。

ブールの場合

クライアント側で、SQLT_BOLを使用してブール型(OCI_TYPECODE_BOOLEAN)がバインドされるようにする必要があります。

25.4.4 OCIBindByPos()

プログラム変数とSQL文またはPL/SQLブロック内のプレースホルダを関連付けます。

用途

プログラム変数と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()がコールされている場合、プレースホルダの属性が位置別に指定されます。位置は1ベースです。

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の場合は、バインド・ハンドルで追加コールを行い、データ型固有の属性を設定する必要があります。レコード、コレクションおよびブールの詳細は「コメント」を参照してください。名前付きデータ型SQLT_CHRでは、実際の長さが0の場合、後続の空白はOCIBindByPos()によって切り捨てられます。後続の空白が切り捨てられることを避けるには、実際の長さを指定します。

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 *型である必要があります。このモードは、分散または集約のバインドに使用されることが目的であり、複数のバッファを1つの位置にバインドまたは定義できます。たとえば、列Aの最初の10行を1つのバッファに、次の5行を1つのバッファに、そして残りの25行を別のバッファにバインドまたは定義できます。これにより、配列の実行操作を行う場合に、それらのすべてを1つの大きなバッファに割り当ててコピーする必要がなくなります。

  関連項目:

  複数バッファのバインドと定義について

割り当てたバッファは、不要になった際にクライアント側で解放する必要があります。

コメント

このコールは、基本バインド操作を実行するときに使用します。バインドは、プログラム変数のアドレスと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()のコールの後で、配列の各要素、各要素の実際の長さ、および実際の配列長の値がサーバーから戻されます。

レコードの場合

クライアント側で、SQLT_NTYをバインドのDTYとして使用してパッケージのレコード型がバインドされるようにする必要があります。OCIクライアントでは、オブジェクトおよびレコードは名前付き型(NTY)として示されるため、同じSQLTコードを使用する必要があります。

コレクションの場合

クライアント側で、SQLT_NTYを使用してすべてのパッケージのコレクション型がバインドされるようにする必要があります。これは、すべてのスキーマ・レベルのコレクション型をバインドするのに使用されるDTYです。

ブールの場合

クライアント側で、SQLT_BOLを使用してブール型(OCI_TYPECODE_BOOLEAN)がバインドされるようにする必要があります。

25.4.5 OCIBindByPos2()

プログラム変数とSQL文またはPL/SQLブロック内のプレースホルダを関連付けます。このコールは、クライアント上で実際の長さがUB2MAXVALを超える場合、データ型を操作する際に使用します。

用途

プログラム変数とSQL文またはPL/SQLブロック内のプレースホルダを関連付けます。クライアント上で実際の長さがUB2MAXVALを超える場合、データ型を操作する際にOCIBindByPos()のかわりにこのコールを使用します。

構文

sword OCIBindByPos2 ( OCIStmt      *stmtp, 
                      OCIBind     **bindpp,
                      OCIError     *errhp,
                      ub4           position,
                      void         *valuep,
                      sb8           value_sz,
                      ub2           dty,
                      void         *indp,
                      ub4          *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()がコールされている場合、プレースホルダの属性が位置別に指定されます。位置は1ベースです。

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パラメータで指定される実際のサイズで可能な要素の最大サイズです。

value_sz > SB4MAXVALの値の場合、> SB4MAXVALの値はリリース12.1以上ではサポートされていないことを意味するORA-24452エラーが発行されます。

クライアント・アプリケーションではサイズが不明な記述子、ロケータまたはREFの場合は、特定の型へのポインタのサイズ、たとえばsizeof (OCILobLocator *)などが使用されます。

モードがOCI_IOVの場合でも同様です。

dty (IN)

バインドされる値のデータ型です。名前付きデータ型(SQLT_NTY)とREF (SQLT_REF)は、アプリケーションがオブジェクト・モードで初期化されている場合のみ有効です。名前付きデータ型またはREFの場合は、バインド・ハンドルで追加コールを行い、データ型固有の属性を設定する必要があります。レコード、コレクションおよびブールの詳細は「コメント」を参照してください。名前付きデータ型SQLT_CHRでは、実際の長さが0の場合、後続の空白はOCIBindByPos2()によって切り捨てられます。後続の空白が切り捨てられることを避けるには、実際の長さを指定します。

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 *型である必要があります。このモードは、分散または集約のバインドに使用されることが目的であり、複数のバッファを1つの位置にバインドまたは定義できます。たとえば、列Aの最初の10行を1つのバッファに、次の5行を1つのバッファに、そして残りの25行を別のバッファにバインドまたは定義できます。これにより、配列の実行操作を行う場合に、それらのすべてを1つの大きなバッファに割り当ててコピーする必要がなくなります。

  関連項目:

  複数バッファのバインドと定義について

割り当てたバッファは、不要になった際にクライアント側で解放する必要があります。

コメント

このコールは、基本バインド操作を実行するときに使用します。バインドは、プログラム変数のアドレスとSQL文またはPL/SQLブロック内のプレースホルダの関連付けを作成します。このバインド・コールは、バインドされるデータの型も指定し、実行時にデータを提供するメソッドも指示できます。

この関数は、bindppパラメータによって指示されたバインド・ハンドルの暗黙的な割当ても行います。**bindppに非NULLポインタが渡されると、このポインタはOCIHandleAlloc()またはOCIBindByPos2()のコールで以前に割り当てられた有効なハンドルを指し示していると、OCIでは想定されます。

OCIアプリケーション内のデータは、プレースホルダに静的または動的にバインドできます。操作の実行の直前にすべてのINバインド・データとOUTバインド・バッファが正しく定義された場合、バインドは静的になります。アプリケーションの要求によって、INバインド・データとOUTバインド・バッファが実行時にクライアント・ライブラリに提供された場合、バインドは動的になります。動的バインドを指定するには、このコールのmodeパラメータをOCI_DATA_AT_EXECに設定します。

関連項目:

動的バインドの詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください

OCIBindByName2()とOCIBindByPos2()は、パラメータとしてバインド・ハンドルを取りますが、これはバインド・コールによって暗黙的に割り当てられます。アプリケーションでバインドしているすべてのプレースホルダに別個のバインド・ハンドルが割り当てられます。

特定のデータ型をバインドする際または入力データを特定の方法で処理する際に必要となる特定の属性を指定する場合は、次の追加バインド・コールが必要です。

• 構造体配列が使用されている場合、OCIBindArrayOfStruct()をコールして必要なスキップ・パラメータを設定してください。

• 実行時にデータが動的に提供されている場合、アプリケーションでユーザー定義のコールバック関数を使用するときにはOCIBindDynamic()をコールしてコールバックを登録します。

• alenpに64KBを超える長さが必要な場合は、OCIBindDynamic()を使用します。

• 名前付きデータ型がバインドされている場合、OCIBindObject()をコールしてその他の必要情報を指定する必要があります。

• RETURNING句を含む文を使用する場合は、このコールの後にOCIBindDynamic()をコールする必要があります。

INバインドの場合、OCIStmtExecute() のコールの前に、配列の各要素、各要素の実際の長さ、および実際の配列長の値を設定する必要があります。

OUTバインドの場合、OCIStmtExecute()のコールの後で、配列の各要素、各要素の実際の長さ、および実際の配列長の値がサーバーから戻されます。

レコードの場合

クライアント側で、SQLT_NTYをバインドのDTYとして使用してパッケージのレコード型がバインドされるようにする必要があります。OCIクライアントでは、オブジェクトおよびレコードは名前付き型(NTY)として示されるため、同じSQLTコードを使用する必要があります。

コレクションの場合

クライアント側で、SQLT_NTYを使用してすべてのパッケージのコレクション型がバインドされるようにする必要があります。これは、すべてのスキーマ・レベルのコレクション型をバインドするのに使用されるDTYです。

ブールの場合

クライアント側で、SQLT_BOLを使用してブール型(OCI_TYPECODE_BOOLEAN)がバインドされるようにする必要があります。

25.4.6 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()を使用して環境ハンドルを作成すると、バインド・ハンドルおよび定義ハンドルの実際の長さと戻される長さは、常にバイト単位になります。

25.4.7 OCIBindObject()

名前付きデータ型(オブジェクト)のバインドに必要な追加属性を設定します。

用途

名前付きデータ型(オブジェクト)のバインドに必要な追加属性を設定します。

構文

sword OCIBindObject ( OCIBind          *bindp,
                      OCIError         *errhp, 
                      const OCIType    *type,
                      void            **pgvpp, 
                      ub4              *pvszsp, 
                      void            **indpp, 
                      ub4              *indszp, );

パラメータ

bindp (IN/OUT)

OCIBindByName()またはOCIBindByName2()、あるいはOCIBindByPos()またはOCIBindByPos2()のコールにより戻されるバインド・ハンドルです。

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()またはOCIBindByName2()、あるいはOCIBindByPos()またはOCIBindByPos2()にOCI_DATA_AT_EXECモードが指定された場合、INバッファのポインタは、OCIBindDynamic()コールに登録されたコールバックicbfpを使用するか、OCIStmtSetPieceInfo()コールによって取得されます。

バッファはOUTデータに対して動的に割り当てられます。これらのバッファへのポインタは、次のいずれかの方法で戻されます。

• OCIBindDynamic()によって登録されたocbfp()をコールします。

• OCIStmtExecute()がOCI_NEED_DATAを戻したときにコールされたOCIStmtSetPieceInfo()によって渡されたバッファ内のバッファに対するポインタを設定します。

クライアント・ライブラリが割り当てたバッファのメモリーは、不要になったときにOCIObjectFree()コールを使用して解放する必要があります。

25.4.8 OCIDefineArrayOfStruct()

構造体配列(複数行、複数列)のフェッチで使用される静的配列定義に必要な追加属性を指定します。

用途

構造体配列(複数行、複数列)のフェッチで使用される静的配列定義に必要な追加属性を指定します。

構文

sword OCIDefineArrayOfStruct ( OCIDefine   *defnp,
                               OCIError    *errhp,
                               ub4          pvskip, 
                               ub4          indskip, 
                               ub4          rlskip,
                               ub4          rcskip );

パラメータ

defnp (IN/OUT)

OCIDefineByPos()またはOCIDefineByPos2()のコールにより戻された定義構造体のハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

pvskip (IN)

次のデータ値用のスキップ・パラメータです。

indskip (IN)

次のインジケータ位置のためのスキップ・パラメータです。

rlskip (IN)

次の戻り長さ値のためのスキップ・パラメータです。

rcskip (IN)

次のリターン・コードのためのスキップ・パラメータです。

コメント

このコールは、OCIDefineByPos()またはOCIDefineByPos2()の後続コールです。アプリケーションでオブジェクトを含む構造体配列をバインドしている場合、最初にOCIDefineObject()をコールして、次にOCIDefineArrayOfStruct()をコールする必要があります。

関連項目:

スキップ・パラメータ

25.4.9 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列に指定できます。

関連項目:

データ型コードおよび値のリストについては、「データ型」を参照してください

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 *型である必要があります。このモードは、分散または集約のバインドに使用されることが目的であり、複数のバッファを1つの位置にバインドまたは定義できます。たとえば、列Aの最初の10行を1つのバッファに、次の5行を1つのバッファに、そして残りの25行を別のバッファにバインドまたは定義できます。これにより、配列の実行操作を行う場合に、それらのすべてを1つの大きなバッファに割り当ててコピーする必要がなくなります。

  関連項目:

  複数バッファのバインドと定義について

コメント

このコールは、Oracle Databaseから取り出されたデータを受け取る出力バッファを定義します。この定義は、SELECT文がOCIアプリケーションにデータを戻すときに必要なローカル・ステップです。

このコールは、選択リスト項目用の定義ハンドルの暗黙的な割当ても行います。*defnppに非NULLポインタが渡されると、このポインタはOCIHandleAlloc()、あるいはOCIDefineByPos()またはOCIDefineByPos2()のコールで以前に割り当てられた有効なハンドルを指し示していると、OCIでは想定されます。別のアドレスに対してハンドルを再定義しているアプリケーションの場合はこれがあてはまるため、複数のフェッチに同じ定義ハンドルを再利用できます。

列をフェッチするための属性の定義は、1つ以上のコールで実行されます。最初のコールは、フェッチを指定するために必要な最小限の属性を定義するOCIDefineByPos()またはOCIDefineByPos2()です。

ある種のデータ型またはフェッチ・モードでは、OCIDefineByPos()またはOCIDefineByPos2()のコールの後に、次の追加定義コールが必要です。

• 複数列を配列フェッチするためのスキップ・パラメータを設定するには、OCIDefineArrayOfStruct()のコールが必要です。

• 名前付きデータ型(つまり、オブジェクトやコレクション)またはREFのフェッチに適切な属性を設定するには、OCIDefineObject()のコールが必要です。この場合、OCIDefineByPos()またはOCIDefineByPos2()内のデータ・バッファ・ポインタは無視されます。

• 名前付きデータ型の列を持つ複数行をフェッチするには、OCIDefineByPos()またはOCIDefineByPos2()の後に、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の暗黙的フェッチ

25.4.10 OCIDefineByPos2()

選択リスト内の項目を型と出力データ・バッファに関連付けます。このコールは、クライアント上で実際の長さがUB2MAXVALを超える場合、データ型を操作する際に使用します。

用途

選択リスト内の項目を型と出力データ・バッファに関連付けます。クライアント上で実際の長さがUB2MAXVALを超える場合、データ型を操作する際にOCIDefineByPos()のかわりにこのコールを使用します。

構文

sword OCIDefineByPos2 ( OCIStmt     *stmtp, 
                        OCIDefine  **defnpp,
                        OCIError    *errhp,
                        ub4          position,
                        void        *valuep,
                        sb8          value_sz,
                        ub2          dty,
                        void        *indp,
                        ub4         *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()を使用して追加バイトとして指定できます。

value_sz > SB4MAXVALの値の場合、> SB4MAXVALの値はリリース12.1以上ではサポートされていないことを意味するORA-24452エラーが発行されます。

マルチバイト変換環境では、指定したバイト数が、処理する文字数に対して不十分な場合、切捨てエラーが発生します。

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列に指定できます。

関連項目:

データ型コードおよび値のリストについては、「データ型」を参照してください

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 *型である必要があります。このモードは、分散または集約のバインドに使用されることが目的であり、複数のバッファを1つの位置にバインドまたは定義できます。たとえば、列Aの最初の10行を1つのバッファに、次の5行を1つのバッファに、そして残りの25行を別のバッファにバインドまたは定義できます。これにより、配列の実行操作を行う場合に、それらのすべてを1つの大きなバッファに割り当ててコピーする必要がなくなります。

  関連項目:

  複数バッファのバインドと定義について

コメント

このコールは、Oracle Databaseから取り出されたデータを受け取る出力バッファを定義します。この定義は、SELECT文がOCIアプリケーションにデータを戻すときに必要なローカル・ステップです。

このコールは、選択リスト項目用の定義ハンドルの暗黙的な割当ても行います。*defnppに非NULLポインタが渡されると、このポインタはOCIHandleAlloc()またはOCIDefineByPos2()のコールで以前に割り当てられた有効なハンドルを指し示していると、OCIでは想定されます。別のアドレスに対してハンドルを再定義しているアプリケーションの場合はこれがあてはまるため、複数のフェッチに同じ定義ハンドルを再利用できます。

列をフェッチするための属性の定義は、1つ以上のコールで実行されます。最初のコールは、フェッチを指定するために必要な最小限の属性を定義するOCIDefineByPos2()です。

ある種のデータ型またはフェッチ・モードでは、OCIDefineByPos2()のコールの後に、次の追加定義コールが必要です。

• 複数列を配列フェッチするためのスキップ・パラメータを設定するには、OCIDefineArrayOfStruct()のコールが必要です。

• 名前付きデータ型(つまり、オブジェクトやコレクション)またはREFのフェッチに適切な属性を設定するには、OCIDefineObject()のコールが必要です。この場合、OCIDefineByPos2()内のデータ・バッファ・ポインタは無視されます。

• 名前付きデータ型の列を持つ複数行をフェッチするには、OCIDefineByPos2()の後に、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の暗黙的フェッチ

25.4.11 OCIDefineDynamic()

OCIDefineByPos()またはOCIDefineByPos2()でOCI_DYNAMIC_FETCHモードが選択されたときに必要な追加属性を設定します。

用途

OCIDefineByPos()またはOCIDefineByPos2()で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()またはOCIDefineByPos2()のコールでOCI_DYNAMIC_FETCHモードが選択されている場合、必要な追加属性を設定するために使用されます。OCI_DYNAMIC_FETCHモードが選択されているときにOCIDefineDynamic()のコールがスキップされた場合、アプリケーションでは、OCIコール(OCIStmtGetPieceInfo()およびOCIStmtSetPieceInfo())を使用してデータ・ピース単位がフェッチされます。

ノート:

OCIEnvNlsCreate()を使用して環境ハンドルを作成すると、バインド・ハンドルおよび定義ハンドルの実際の長さと戻される長さは、常にバイト単位になります。

関連項目:

OCI_DYNAMIC_FETCHモードの詳細は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください

25.4.12 OCIDefineObject()

名前付きデータ型またはREFの定義のために必要な追加属性を設定します。

用途

名前付きデータ型またはREFの定義のために必要な追加属性を設定します。

構文

sword OCIDefineObject ( OCIDefine       *defnp,
                        OCIError        *errhp,
                        const OCIType   *type,
                        void           **pgvpp, 
                        ub4             *pvszsp, 
                        void           **indpp, 
                        ub4             *indszp );

パラメータ

defnp (IN/OUT)

以前OCIDefineByPos()またはOCIDefineByPos2()のコールで割り当てられた定義ハンドルです。

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()またはOCIDefineByPos2()の後続コールです。このコールは、名前付きデータ型定義のために必要な追加属性を設定します。OCI環境が非オブジェクト・モードで初期化されているときにこの関数をコールした場合は、エラーが戻ります。

このコールは、定義される名前付きデータ型用にデータ型OCITypeの型記述子オブジェクト(TDO)をパラメータとして取ります。TDOは、OCIDescribeAny()をコールして取り出すことができます。

関連項目:

• OCIプロセス環境の初期化の詳細は、「OCIEnvCreate()」および「OCIEnvNlsCreate()」を参照してください

• 複数バッファの使用例は、「複数バッファのバインドと定義について」を参照してください

25.4.13 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以外にしてください。

コメント

このコールは、表、ビュー、シノニム、プロシージャ、ファンクション、パッケージ、順序、型、スキーマおよびデータベースなどの既存のスキーマ・オブジェクトを記述する汎用的な記述コールです。さらに、OCIDescribeAny()コールでは、パッケージ内に含まれているすべてのパッケージ型およびパッケージ型の属性を記述します。このコールでは、表内の列などのサブスキーマ・オブジェクトも記述できます。このコールは、 OCIAttrGet()コールを使用して取得できるオブジェクト固有の属性を記述ハンドルに移入します。

記述ハンドルに対するOCIParamGet()は、指定位置のパラメータ記述子を戻します。パラメータ位置は1から開始します。パラメータ記述子に対してOCIAttrGet()をコールすると、ストアド・プロシージャまたはファンクション・パラメータの特定の属性、あるいは表の列記述子が戻されます。OCIDescribeAny()によってスキーマ・オブジェクト記述全体がクライアント側にキャッシュされているため、これらの後続コールは、サーバーへのラウンドトリップを別に行う必要がありません。記述ハンドルに対するOCIAttrGet()は、位置の総数も戻します。

記述ハンドルに対してOCI_ATTR_DESC_PUBLIC属性が設定されている場合、カレント・スキーマに名前付きオブジェクトが存在せずname1のみが指定されているときは、このオブジェクトはパブリック・シノニムとして参照されます。

デフォルトでは、明示的な記述(OCIDescribeAny())では非表示列は示されません。ユーザー定義の非表示列のメタデータを取得するには、OCIDescribeAny()をコールする前に記述ハンドル属性OCI_ATTR_SHOW_INVISIBLE_COLUMNSを設定する必要があります。列が非表示型かどうかを判別するには、OCIAttrGet()を使用して列属性OCI_ATTR_INVISIBLE_COLを取得します。

列が表示型かどうかを指定するプロパティは、ユーザーが制御できます。非表示列は、SELECTリストで明示的に指定されないかぎり表示されません。SELECT * FROM table-name文またはDESCRIBE文などの表の汎用アクセスでは、非表示列は表示されません。

関連項目:

記述操作の詳細は、「スキーマ・メタデータの記述」を参照してください

25.4.14 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)

OCIStmtPrepare2()によって準備される文ハンドルです。

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リスト変数はバインドとはみなされていないため、この関数には含まれません。

このコールの前に、OCIStmtPrepare2()のコールを使用して文を準備する必要があります。文ハンドルのエンコーディング設定によって、Unicode文字列が取り出されるかどうかが決定されます。

このコールは、ローカルで処理されます。