25.4 バインド関数、定義関数および記述関数
バインド関数、定義関数および記述関数をリストし、説明します。
表25-4は、この項で説明しているバインド関数、定義関数および記述関数を示しています。
表25-4 バインド関数、定義関数および記述関数
関数 | 用途 |
---|---|
静的配列バインド用のスキップ・パラメータを設定します。 |
|
名前によりバインドします |
|
名前によりバインドします。クライアント上で、戻される長さが |
|
位置によりバインドします |
|
位置によりバインドします。クライアント上で、戻される長さが |
|
|
|
名前付きデータ型のバインド用の追加属性を設定します。 |
|
静的配列定義用の追加属性を設定します。 |
|
出力変数の関連性を定義します。 |
|
出力変数の関連性を定義します。クライアント上で、戻される長さが |
|
|
|
名前付きデータ型の定義用の追加属性を設定します。 |
|
既存のスキーマ・オブジェクトを記述します。 |
|
バインドおよびインジケータ変数名とハンドルを取得します。 |
25.4.1 OCIBindArrayOfStruct()
静的配列バインド用のスキップ・パラメータを設定します。
用途
静的配列バインド用のスキップ・パラメータを設定します。
構文
sword OCIBindArrayOfStruct ( OCIBind *bindp, OCIError *errhp, ub4 pvskip, ub4 indskip, ub4 alskip, ub4 rcskip );
パラメータ
コメント
このコールは、静的配列バインドに必要なスキップ・パラメータを設定します。これは、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 );
パラメータ
コメント
このコールは、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
パラメータによって定義されます。クライアント・ライブラリで、フェッチ済データを戻すためのバッファが必要な場合は、このコールバックが呼び出され、ピースまたはすべてのデータを戻すための実行時バッファが提供されます。関連項目:
-
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での定義の概要」を参照してください
-
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
パラメータによって定義されます。クライアント・ライブラリで、フェッチ済データを戻すためのバッファが必要な場合は、このコールバックが呼び出され、ピースまたはすべてのデータを戻すための実行時バッファが提供されます。関連項目:
-
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での定義の概要」を参照してください
-
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)
-
このパラメータは次のいずれかです。
-
記述されるオブジェクト名を含む文字列。
OCIEnvNlsCreate()
の直前のコールのcharset
パラメータで指定されたエンコーディングであることが必要です。 -
TDOに対する
REF
のポインタ(型用)。 -
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のポインタの場合
-
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
(不明なスキーマ・オブジェクト用)
コメント
このコールは、表、ビュー、シノニム、プロシージャ、ファンクション、パッケージ、順序、型、スキーマおよびデータベースなどの既存のスキーマ・オブジェクトを記述する汎用的な記述コールです。さらに、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文字列が取り出されるかどうかが決定されます。
このコールは、ローカルで処理されます。