プライマリ・コンテンツに移動
Pro*C/C++プログラマーズ・ガイド
12c リリース1(12.1)
B71397-03
目次へ移動
目次 		索引へ移動
索引
前
前 		次
次

COLLECTION文

この項では、COLLECTION文について説明します。

COLLECTION GET

用途

COLLECTION GET文は、OBJECT GET文に似ていますが、コレクションを対象としています。コレクション要素の取得、現行のスライスの設定、要素のC言語のデータ型への変換(必要な場合)を行います。

構文

EXEC SQL [AT [:]database] [FOR :num]
   COLLECTION GET :collect [[INDICATOR] :collect_ind]
      INTO :hv [[INDICATOR] :hv_ind] ;

変数

num (IN)

要求する要素の数。この句を省略すると、コレクションから取得する要素の数は、ホスト変数の配列サイズ(スカラーは1)により決定されます。

collect (IN)

ホスト変数Cコレクション記述子。

collect_ind (IN)

コレクションのNULL状態を戻すオプションの標識変数。

hv (OUT)

コレクション要素値を受け取るホスト変数。

hv_ind (OUT)

スカラーまたは配列にスライスの各要素の状態が格納されている場合、hvのNULL状態を戻すオプションの標識変数。

使用上の注意

最後のCOLLECTION GETから実際に戻される要素の数は、sqlca.sqlerrd[2]に設定されます(すべてのGET累計ではありません)。sqlerrdも参照してください。

スライスのエンドポイントのいずれかまたは両方がコレクションの境界を超過したときは、戻される要素数が要求した数よりも少ないことがあります。これは次の場合に発生します。

  • コレクション記述子が、正しい構文のALLOCATE文で初期化されなかった場合、NULLの場合、その他の理由で無効な場合。

  • コレクションがNULLの場合。対応付けられるインジケータは-1になります。

  • コレクションが空(要素がない)の場合。

  • コレクションに残っている要素数を超える要素が要求された場合。

  • COLLECTION TRIM文が実行された結果、現行のスライスで終了インデックスが開始インデックスよりも前になっている場合。

Cコレクション記述子が適切に初期化されなかった場合は、エラーになります。前述のリスト以外の場合は、ORA-01403: no data foundというエラーが発生します。この場合、エラー発生前に正常に取得できた要素の合計数は、sqlca.sqlerrd[2]に格納されたままです。

最初のGETまたはRESET後の最初のGETにより、スライスは次のようになります。

  • スライスの終了インデックスは、検出された最後の要素のインデックスになります。これは、要求する要素数によって変わります。コレクションに要求を満たせるだけの要素が残っていない場合、最後のインデックスはコレクションの最後のインデックスになります。

引き続きGETを実行すると、スライスのインデックスは次のようになります。

  • 直前のスライスのエンドポイントの後に最初に検出された要素のインデックスが、開始インデックスになります。直前のスライスのエンドポイントの後に要素が残っていない場合、開始インデックスはコレクションの最後の要素のインデックスになります。

  • 次のスライスの終了インデックスは、検出された最後の要素のインデックスになります。これは、要求する要素数によって変わります。直前のスライスで指定された位置で、要求を満たせるだけの要素がコレクションに残っていない場合、終了インデックスはコレクションの最後のインデックスになります。

COLLECTION SET

用途

COLLECTION SET文は、OBJECT SET文に似ていますが、コレクションの要素値の更新に使用します。現行のスライスの要素は、C固有型からOracleデータ型に変換されます。

構文

EXEC SQL [AT [:]database] [FOR :num]
   COLLECTION SET :collect [[INDICATOR] :collect_ind]
      TO :hv [[INDICATOR] :hv_ind] ;

変数

num (IN)

このオプションのスカラー値は、スライス内で更新される要素の最大数です。この句を省略すると、コレクションから更新される要素数は、ホスト変数の配列サイズ(スカラーは1)により決定されます。

collect (OUT)

ホスト変数Cコレクション記述子。

collect_ind (OUT)

コレクションのNULL状態を決定するオプションの標識変数。

hv (IN)

コレクション内で更新される値を含むホスト変数。

hv_ind (IN)

ホスト変数のNULL状態を表す、対応付けられた標識変数。

使用上の注意

次の制限があります。

  • COLLECTION GETは、COLLECTION SETの前に実行する必要があります。

  • スライスの開始インデックスおよび終了インデックスは、常に変わりません。コレクションに格納されている要素数が、現行のスライスに格納できる要素数より少ない場合も変わりません。SET文では、スライスのエンドポイントは変更されません。現行のスライスの要素のみが変更されます。

  • COLLECTION SETでは、現行のスライスの要素のみが更新されます。COLLECTION SET文を使用して、新しい要素をコレクションに追加することはできません。

  • 現行のスライスに含まれる要素の数を超える要素をSET文で更新すると、既存のスライスに格納されている要素のみが更新されます。スライスのエンドポイント外の残りの要素は更新されず、ホスト変数で指定されたその他の値は使用されません。

オプションのFOR句で指定したホスト変数または値numの次元により、コレクションで更新を要求できる要素の最大数が決まります。

変数sqlca.sqlerrd[2]により、直前のSET文で正常に更新された要素の数が戻されます(累計ではありません)。次のような場合は、GET文と同様に、設定要求数よりも少ないことがあります。

  • Cコレクション記述子が、構文の正しいALLOCATE文で正常に初期化されなかった場合、NULLの場合、またはその他の理由で無効の場合。

  • コレクションが空の場合。

  • コレクションの現行のスライスの位置で、コレクションの残りの部分の要素数が、設定要求数よりも少なかった場合。

  • 現行のスライスのエンドポイントを超えた場合。既存のスライスの要素数以上の要素を設定すると、この状態になります。

  • コレクションに対してTRIMが実行され、コレクションの終了インデックスの最大値が現行のスライスの開始インデックスを下回った場合。

COLLECTION GETまたはSETの直後にCOLLECTION SETを実行した場合は、既存のスライスの要素の値のみが更新されます。COLLECTION SETの直後にCOLLECTION GETを実行すると、すでに説明したように次のスライスに移ります。

COLLECTION RESET

用途

コレクション・スライスのエンドポイントをコレクションの最初にリセットします。

構文

EXEC SQL [AT [:]database]
   COLLECTION RESET :collect 
      [ [INDICATOR] :collect_ind] ;

変数

collect (IN/OUT)

エンドポイントをリセットするコレクション。

collect_ind

コレクションのNULL状態を決定するオプションの標識変数。

使用上の注意

指定したコレクションがNULLまたは無効の場合は、エラーが発生します。

COLLETION RESETはコレクションのサイズまたは内容には影響しません。

COLLECTION APPEND

用途

コレクションの最後に要素のセット(1つ以上)を追加します。コレクションのサイズが増加します。

構文

EXEC SQL [AT [:]database] [FOR :num]
   COLLECTION APPEND :src [[INDICATOR] :src_ind]
      TO :collect [[INDICATOR] :collect_ind] ;

変数

num (IN)

追加する要素数が格納されたスカラー。指定しない場合は、配列サイズsrcが追加する要素数になります。

src (IN)

コレクションに追加する要素のスカラーまたは配列。

src_ind (IN)

追加する要素のNULL状態を決定するオプションの標識変数(スカラーまたは配列)。

collect (IN OUT)

要素を追加するコレクション。

collect_ind (IN)

コレクションのNULL状態を決定するオプションの標識変数。

使用上の注意

要素は一度に1つずつ追加されます(コレクションのサイズは1ずつ増加し、データがその要素にコピーされます)。

変数sqlca.sqlerrd[2]により、最後のAPPENDで正常に追加された要素数が戻されます(累計ではありません)。コレクションの上限を超えて要素を追加したり、NULLコレクションを追加したりすると、エラーが発生します。上限以内の要素のみが追加されます。

COLLECTION TRIM

用途

コレクションの最後から要素を削除します。

構文

EXEC SQL [AT [:]database]
   COLLECTION TRIM :num
      FROM :collect [[INDICATOR] :collect_ind] ;

変数

num (IN)

削除する要素数を示すホスト・スカラー変数。最大許容値は2GBです。

collect (IN OUT)

切り捨てるコレクション。

collect_ind (IN)

コレクションのNULL状態を決定するオプションの標識変数。

使用上の注意

次の制限が適用されます。

  • FOR句は使用できません。

  • numの最大値は2GBです(4バイト符号付きバイナリ変数の最大数)。

  • numにインジケータを使用することはできません。

numがコレクションのサイズよりも大きい場合、エラーが戻されます。TRIM文で現行のスライスから要素を削除すると、警告が戻されます。

COLLECTION DESCRIBE

用途

コレクションについての情報が戻されます。

構文

EXEC SQL [AT [:]database] 
   COLLECTION DESCRIBE :collect [[INDICATOR] :collect_ind]
      GET attribute1 [{, attributeN}]
         INTO :hv1 [[INDICATOR] :hv_ind1] [{, hvN [[INDICATOR] :hv_indN]}] ;

attributeNは次のとおりです。

DATA_SIZE | TYPECODE | DATA_TYPE | NUM_ELEMENTS
   | PRECISION | SCALE | TYPE_NAME | TYPE_SCHEMA | SIZE | TABLE_SIZE

変数

collect (IN)

ホスト変数Cコレクション記述子。

collect_ind (IN)

コレクションのNULL状態を含むオプションの標識変数。

hv1 .. hvN (OUT)

情報が格納される出力ホスト変数。

hv_ind1 .. hv_indN (OUT)

出力ホスト変数の標識変数。

使用上の注意

次の制限が適用されます。

  • コレクションをNULLにはできません。

  • ホスト変数型は、戻される属性の型と互換性を持つ必要があります。

  • 属性の標識変数は、テキストの切捨てが行われるTYPE_NAMEおよびTYPE_SCHEMA属性値でのみ必要です。

  • FOR句は使用できません。

  • 変数sqlca.sqlerrd[2]には、エラーなしで正常に取り出された属性の数が戻されます。DESCRIBE文でエラーが発生した場合、sqlca.sqlqerrd[2]には、エラー発生前に戻された属性の数が格納されます。エラー発生時の属性数より1つ少なくなっています。

次の表は、属性、説明、および取り出される属性のC言語のデータ型を示しています。

表18-3 COLLECTION DESCRIBEの属性

属性 説明 C言語のデータ型 注意

DATA_SIZE

型属性の最大サイズ。戻される長さは、文字列のバイト長です。NUMBERの場合は22です。

unsigned short

オブジェクトまたはオブジェクトREF要素では無効です。

TYPECODE

OCI型コード。

OCITypeCode

-

DATA_TYPE

コレクション項目の内部数値型コード。

unsigned short

-

NUM_ELEMENTS

VARRAYの最大要素数。

unsigned int

VARRAY型にのみ有効です。

PRECISION

数値型属性の精度。戻される値が0の場合、記述される項目は初期化されず、データ・ディクショナリはNULLになります。

unsigned char

NUMBER型の要素にのみ有効です。

SCALE

数値型属性のスケール。戻される値が-127の場合、記述される項目は初期化されず、データ・ディクショナリはNULLになります。

signed char

NUMBER型の要素にのみ有効です。

TYPE_NAME

型の名前を含む文字列。オブジェクト型の場合、その名前が戻されます。REFの場合、REFによって参照されるデータ型の名前が戻されます。使用できる外部データ型はCHARZ、STRINGおよびVARCHARです。

char *

オブジェクトおよびオブジェクトREF要素にのみ有効です。

TYPE_SCHEMA

型を作成するスキーマ名。使用できる外部データ型はCHARZ、STRINGおよびVARCHARです。

char *

オブジェクトおよびオブジェクトREF要素にのみ有効です。

SIZE

コレクションに実際に格納されている要素数。NESTED TABLEの場合、SIZEにより空の要素が格納されます。TRIM文を実行すると、切り捨てられた要素数のみコレクションのSIZEが減少します。

signed int

-

TABLE_SIZE

NESTED TABLEの要素の数。間隔は含みません。

signed int

NESTED TABLEにのみ有効です。

表について

Pro*C/C++の外部データ型では、属性TYPE_NAMEおよびTYPE_SCHEMAのCHARZ、STRINGおよびVARCHARのみがサポートされます。

SIZEおよびTABLE_SIZEを除き、DESCRIBE属性は、すべてコレクションの要素型に依存し、コレクションの特定のインスタンスには依存しません。一方、SIZEおよびTABLE_SIZE属性は、値がコレクションの特定のインスタンスに完全に依存しています。割り当てられたコレクション記述子が再利用され、同じコレクションの異なるインスタンスが参照される場合、SIZEまたはTABLE_SIZEの値はコレクションのインスタンスごとに変わります。NUM_ELEMENTSはコレクション型(この例ではVARRAY)の属性で、コレクション要素型ではありません。また、コレクションの特定のインスタンスには依存しません。

コレクションを使用する場合の規則

  • ホスト変数コレクション記述子は、常に明示的に割り当てる必要があります。

  • メタデータ(コレクションおよびその要素型についての、データベースの内部Oracleデータ)は、ALLOCATEの実行中に収集されます。ALLOCATEが実行された接続がクローズしているとき、またはALLOCATEの実行後に型が変更されたときは、メタデータは無効になります。

  • 各Cコレクション記述子の使用を開始または終了するには、ALLOCATEまたはFREE文を使用します。

前
前 		次
次
目次へ移動
目次 		索引へ移動
索引