OCIコレクションおよびイテレータ関数

この項では、コレクションおよびイテレータ関数について説明します。

表19-3 コレクションおよびイテレータ関数

関数	用途
OCICollAppend()	コレクションに要素を追加します。
OCICollAssign()	コレクションを割り当てます。
OCICollAssignElem()	コレクションに要素を割り当てます。
OCICollGetElem()	要素へのポインタを取得します。
OCICollGetElemArray()	コレクションから要素の配列を取得します。
OCICollIsLocator()	コレクションがロケータベースであるかどうかを示します。
OCICollMax()	コレクションの最大要素数を戻します。
OCICollSize()	コレクションのカレント・サイズ（要素数単位）を取得します。
OCICollTrim()	コレクションから要素を切り捨てます。
OCIIterCreate()	VARRAY要素をスキャンするためのイテレータを作成します。
OCIIterDelete()	イテレータを削除します。
OCIIterGetCurrent()	カレント・コレクション要素を取得します。
OCIIterInit()	イテレータを初期化して指定のコレクションをスキャンします。
OCIIterNext()	次のコレクション要素を取得します。
OCIIterPrev()	前のコレクション要素を取得します。

OCICollAppend()

用途

コレクションの最後に要素を追加します。

構文

sword OCICollAppend ( OCIEnv              *env,
                      OCIError            *err,
                      const void          *elem,
                      const void          *elemind,
                      OCIColl             *coll );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

elem (IN)

与えられたコレクションの最後に追加される要素へのポインタです。

elemind (IN) [オプション]

要素のNULLインジケータ情報へのポインタです。elemind == NULLの場合、追加された要素のNULLインジケータ情報は、NULL以外に設定されます。

coll (IN/OUT)

更新されたコレクションです。

要素の追加は、コレクションのサイズを1要素分増やし、最終要素のデータを指定の要素のデータで更新（ディープ・コピー）することと等価です。指定の要素elemへのポインタはこの関数によって保存されないことに注意してください。つまり、elemは厳密に入力パラメータです。

この関数は、コレクションのカレント・サイズが、要素を追加する前のコレクションの最大サイズ（上限）と等しい場合、エラーを戻します。また、この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()

OCICollAssign()

用途

あるコレクションを別のコレクションに割り当てます（ディープ・コピーします）。

構文

sword OCICollAssign ( OCIEnv              *env,
                      OCIError            *err,
                      const OCIColl       *rhs,
                      OCIColl             *lhs );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

rhs (IN)

割当て元となる右側（ソース）コレクションです。

lhs (OUT)

割当て先となる左側（ターゲット）コレクションです。

rhs（ソース）をlhs（ターゲット）に割り当てます。lhsコレクションは、rhsのサイズに応じて変更されます。lhsに要素が格納されている場合は、割当てに先立ってその要素が削除されます。この関数はディープ・コピーを実行します。要素用のメモリーはオブジェクト・キャッシュから取られます。

lhsコレクションとrhsコレクションの要素の型が一致しない場合はエラーが戻ります。lhsの上限がrhsコレクション内の現行の要素数より小さい場合もエラーが戻ります。次の場合にもエラーが戻されます。

入力パラメータがNULLである場合
lhsコレクションとrhsコレクションの型が一致しない場合
lhsコレクションの上限がrhsコレクション内の現行の要素数より小さい場合

関連関数

OCIErrorGet()、OCICollAssignElem()

OCICollAssignElem()

用途

指定の要素値elemをcoll[index]の要素に割り当てます。

構文

sword OCICollAssignElem ( OCIEnv           *env,
                          OCIError         *err,
                          sb4              index,
                          const void       *elem,
                          const void       *elemind,
                          OCIColl          *coll );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

index (IN)

割当て先となる要素の索引です。

elem (IN)

割当て元となる要素（ソース要素）です。

elemind (IN) [オプション]

要素のNULLインジケータ情報へのポインタです。elemind == NULLの場合、割り当てられた要素のNULLインジケータ情報は、NULL以外に設定されます。

coll (IN/OUT)

更新されるコレクションです。

コレクションの型がNESTED TABLEである場合は、要素が削除されているときと同様に、指定の索引位置に要素が存在しない場合があります。このような場合は、indexの位置に指定の要素が挿入されます。それ以外の場合は、indexの位置にある要素がelemの値で更新されます。

指定の要素はディープ・コピーされること、およびelemは厳密に入力パラメータであることに注意してください。

この関数は、入力パラメータがNULLであるか、または指定の索引が指定のコレクションの上限を超えている場合にエラーを戻します。

関連関数

OCIErrorGet()、OCICollAssign()

OCICollGetElem()

用途

指定の索引位置にある要素へのポインタを取得します。

構文

sword OCICollGetElem ( OCIEnv           *env,
                       OCIError         *err,
                       const OCIColl    *coll,
                       sb4              index,
                       boolean          *exists,
                       void             **elem,
                       void             **elemind );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

このコレクション内の要素へのポインタが戻されます。

index (IN)

ポインタが戻される要素の索引です。

exists (OUT)

指定した索引の要素が存在しない場合はFALSEに設定されます。それ以外の場合はTRUEに設定されます。

elem (OUT)

要求する要素のアドレスが戻されます。

elemind (OUT) [オプション]

NULLインジケータ情報のアドレスが戻されます。elemind == NULLの場合、NULLインジケータ情報は戻されません。

指定の位置にある要素のアドレスを取得します。また、この関数は、オプションで要素のNULLインジケータ情報のアドレスを戻します。

コレクションの各要素型と対応する要素ポインタの型を次の表に示します。要素ポインタはOCICollGetElem()のelemパラメータによって戻されます。

表19-4 要素ポインタ

要素型	*elemの設定
Oracle `NUMBER`（`OCINumber`）	`OCINumber*`
日付（`OCIDate`）	`OCIDate*`
日時（`OCIDateTime`）	`OCIDateTime *`
時間隔（`OCIInterval`）	`OCIInterval *`
可変長文字列（`OCIString*`）	`OCIString **`
可変長RAW（`OCIRaw*`）	`OCIRaw**`
オブジェクト参照（`OCIRef*`）	`OCIRef**`
LOBロケータ（`OCILobLocator*`）	`OCILobLocator**`
オブジェクト型（personなど）	`person*`

OCICollGetElem()で戻される要素ポインタは、要素データにアクセスするために使用できる書式のみでなく、代入文のターゲットとして使用できる書式の場合もあります。

たとえば、要素型がオブジェクト参照（OCIRef*）であるコレクションの要素を反復するとします。OCICollGetElem()のコールにより、参照ハンドル（OCIRef**）へのポインタが戻ります。コレクション要素へのポインタを取得した後、新しい参照を割り当てることでそれを修正できます。

この修正は、次のようなREF割当て関数によって実行できます。

sword OCIRefAssign( OCIEnv       *env,
                    OCIError     *err,
                    const OCIRef *source,
                    OCIRef       **target );

OCIRefAssign()のtargetパラメータの型はOCIRef**であることに注意してください。したがってOCICollGetElem()は、OCIRef**を戻します。*targetがNULLの場合は、OCIRefAssign()によって新しいREFが割り当てられ、targetパラメータに戻されます。

同様に、コレクション要素がタイプ文字列（OCIString*）のものである場合、OCICollGetElem()は文字列ハンドル（つまり、OCIString**）へのポインタを戻します。OCIStringAssign()またはOCIStringAssignText()を介して新しい文字列を割り当てる場合、ターゲットの型はOCIString **にしてください。

コレクションの要素型がOracle NUMBERの場合、OCICollGetElem()はOCINumber*を戻します。OCINumberAssign()のプロトタイプを次に示します。

sword OCINumberAssign(OCIError        *err,
                      const OCINumber *from,
                      OCINumber       *to);

この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCICollAssignElem()

OCICollGetElemArray()

用途

開始索引を指定されたコレクションから要素の配列を取得します。

構文

sword OCICollGetElemArray ( OCIEnv              *env,
                            OCIError            *err,
                            const OCIColl       *coll,
                            sb4                 index,
                            boolean             *exists,
                            void                **elem,
                            void                **elemind,
                            uword               *nelems );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

このコレクション内の要素へのポインタが戻されます。

index (IN)

この要素の開始索引です。

exists (OUT)

指定した索引の要素が存在しない場合はFALSEに設定されます。それ以外の場合はTRUEに設定されます。

elem (OUT)

要求する要素のアドレスが戻されます。

elemind (OUT)

[オプション]NULLインジケータ情報のアドレスが戻されます。elemind == NULLの場合、NULLインジケータ情報は戻されません。

nelems (IN)

elemおよびelemind両方に対するポインタの最大数です。

指定の位置から要素のアドレスを取得します。また、この関数は、オプションで要素のNULLインジケータ情報のアドレスを戻します。

関連関数

OCIErrorGet()、OCICollGetElem()

OCICollIsLocator()

用途

コレクションがロケータベースであるかどうかを示します。

構文

sword OCICollIsLocator ( OCIEnv *env,
                         OCIError *err,
                         const OCIColl *coll,
                         boolean *result );

パラメータ

env (IN)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

コレクション項目です。

result (OUT)

コレクション項目がロケータベースである場合はTRUEを戻します。それ以外の場合はFALSEを戻します。

この関数は、コレクションがロケータベースであるかどうかを確認するためのテストを行います。コレクション項目がロケータベースである場合はresultパラメータにTRUEを戻します。それ以外の場合はFALSEを戻します。

関連関数

OCIErrorGet()

OCICollMax()

用途

指定のコレクションの最大サイズを要素数単位で取得します。

構文

sb4 OCICollMax ( OCIEnv           *env,
                 const OCIColl    *coll );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

coll (IN)

要素数が戻されるコレクションです。collは有効なコレクション記述子を指し示している必要があります。

指定されたコレクションが保持できる要素の最大数を戻します。値0（ゼロ）は、そのコレクションには上限がないことを示します。

戻り値

指定のコレクションの上限。

関連関数

OCIErrorGet()、OCICollSize()

OCICollSize()

用途

指定のコレクションのカレント・サイズを要素数単位で取得します。

構文

sword OCICollSize ( OCIEnv           *env,
                    OCIError         *err,
                    const OCIColl    *coll
                    sb4              *size );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

要素の数が戻されるコレクションです。有効なコレクション識別子を指し示している必要があります。

size (OUT)

コレクション内の現行の要素数です。

指定されたコレクションの現行の要素数を戻します。ネストした表の場合、要素を削除してもこのカウントは減分されません。したがって、このカウントには要素の削除によって発生した空きが含まれています。切捨て操作（OCICollTrim()）では、切り捨てられた要素の数のみが、このカウントから減分されます。削除済の要素を差し引いたカウントを取得するには、OCITableSize()を使用します。

次の疑似コードで例をいくつか示します。

OCICollSize(...);
// assume 'size' returned is equal to 5
OCITableDelete(...); // delete one element
OCICollSize(...);
// 'size' returned is still 5

削除済の要素を差し引いたカウントを取得するには、OCITableSize()を使用します。前述の例を続けます。

OCITableSize(...)
// 'size' returned is equal to 4

切捨て操作（OCICollTrim()）は、切り捨てられた要素の数のみこのカウントを減分します。前述の例を続けます。

OCICollTrim(..,1..); // trim one element
OCICollSize(...);
// 'size' returned is equal to 4

この関数は、コレクションのオブジェクト・キャッシュへのロード中にエラーが発生した場合、または入力パラメータがNULLである場合にエラーを戻します。

関連関数

OCIErrorGet()、OCICollMax()

OCICollTrim()

用途

指定数の要素をコレクションの最後から切り捨てます。

構文

sword OCICollTrim ( OCIEnv         *env,
                    OCIError       *err,
                    sb4            trim_num,
                    OCIColl        *coll );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

trim_num (IN)

切り捨てる要素数です。

coll (IN/OUT)

この関数は、trim_num要素をcollの最後から削除（解放）します。

要素は、コレクションの末尾から削除されます。trim_numがコレクションのカレント・サイズよりも大きい場合はエラーを戻します。

関連関数

OCIErrorGet()、OCICollSize()

OCIIterCreate()

用途

要素またはコレクションをスキャンするためのイテレータを作成します。

構文

sword OCIIterCreate ( OCIEnv               *env,
                      OCIError             *err,
                      const OCIColl        *coll,
                      OCIIter              **itr );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

スキャンするコレクションです。このリリースでは、有効なコレクション型としてVARRAYとNESTED TABLEが含まれています。

itr (OUT)

割り当てられたコレクション・イテレータのアドレスは、この関数で戻されます。

イテレータは、オブジェクト・キャッシュの中に作成されます。イテレータは、コレクションの先頭を指し示すように初期化されます。

イテレータの作成直後にOCIIterNext()をコールした場合は、コレクションの最初の要素が戻ります。イテレータの作成直後にOCIIterPrev()をコールした場合は、「コレクションの先頭にいる」ことを示すエラーが戻ります。

この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIIterDelete()

OCIIterDelete()

用途

コレクション・イテレータを削除します。

構文

sword OCIIterDelete ( OCIEnv           *env,
                      OCIError         *err,
                      OCIIter          **itr );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

itr (IN/OUT)

割り当てられたコレクション・イテレータです。これは戻す前に破棄されNULLに設定されます。

OCIIterCreate()のコールによって以前に作成されたイテレータを削除します。

この関数は、入力パラメータがNULLである場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIIterCreate()

OCIIterGetCurrent()

用途

カレント・イテレータ・コレクション要素へのポインタを取得します。

構文

sword OCIIterGetCurrent ( OCIEnv            *env,
                          OCIError          *err,
                          const OCIIter     *itr,
                          void              **elem,
                          void              **elemind );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

itr (IN)

現在の要素を指し示すイテレータです。

elem (OUT)

イテレータが参照した要素のアドレスが戻されます。

elemind (OUT) [オプション]

要素のNULLインジケータ情報のアドレスが戻されます。elem_ind == NULLの場合、NULLインジケータ情報は戻されません。

カレント・イテレータ・コレクション要素へのポインタとそれに対応するNULL情報を戻します。この関数は、入力パラメータがNULLである場合はエラーを戻します。

OCIIterInit()

用途

コレクションをスキャンするためのイテレータを初期化します。

構文

sword OCIIterInit ( OCIEnv              *env,
                    OCIError            *err,
                    const OCIColl       *coll,
                    OCIIter             *itr );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

coll (IN)

スキャンするコレクションです。Oracle8i以上では、有効なコレクション型としてVARRAYとNESTED TABLEが含まれています。

itr (IN/OUT)

割り当てられたコレクション・イテレータへのポインタです。

イテレータが、指定したコレクションの先頭を指し示すように初期化します。入力パラメータがNULLである場合はエラーを戻します。この関数を使用すると次のことができます。

コレクションの先頭を指し示すようにイテレータをリセットします。
割当て済のイテレータを再利用して別のコレクションをスキャンします。

関連関数

OCIErrorGet()

OCIIterNext()

用途

次のイテレータ・コレクション要素へのポインタを取得します。

構文

sword OCIIterNext ( OCIEnv            *env,
                    OCIError          *err,
                    OCIIter           *itr,
                    void              **elem,
                    void              **elemind,
                    boolean           *eoc);

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

itr (IN/OUT)

次の要素を指し示すようにイテレータを更新します。

elem (OUT)

イテレータが次要素を指し示すように更新された後、要素のアドレスを戻します。

elemind (OUT) [オプション]

要素のNULLインジケータ情報のアドレスが戻されます。elem_ind == NULLの場合、NULLインジケータ情報は戻されません。

eoc (OUT)

イテレータがコレクションの末尾にある（つまり、次の要素が存在しない）場合はTRUE、それ以外の場合はFALSEとなります。

この関数は、次のイテレータ・コレクション要素へのポインタおよびそれに対応するNULL情報を戻します。また、次の要素を指し示すようにイテレータを更新します。

この関数の実行前にイテレータがコレクションの最後の要素を指し示している場合は、この関数をコールするとeocフラグにTRUEが設定されます。この場合、イテレータは更新されません。

この関数は、入力パラメータがNULLである場合はエラーを戻します。

OCIIterPrev()

用途

直前のイテレータ・コレクション要素へのポインタを取得します。

構文

sword OCIIterPrev ( OCIEnv            *env,
                    OCIError          *err,
                    OCIIter           *itr,
                    void              **elem,
                    void              **elemind,
                    boolean           *boc );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。

関連項目:

「OCIEnvCreate()」および「OCIInitialize()」

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

itr (IN/OUT)

前の要素を指し示すように更新されるイテレータです。

elem (OUT)

イテレータが前の要素を指し示すように更新された後に戻される、前の要素のアドレスです。

elemind (OUT) [オプション]

要素のNULLインジケータのアドレスです。elemind == NULLの場合、NULLインジケータは戻されません。

boc (OUT)

イテレータがコレクションの先頭にある（つまり、前の要素が存在しない）場合はTRUE、それ以外の場合はFALSEとなります。

この関数は、前のイテレータ・コレクション要素へのポインタおよびそれに対応するNULL情報を戻します。イテレータは、前の要素を指し示すように更新されます。

この関数の実行前にイテレータがコレクションの最初の要素を指し示している場合は、この関数をコールするとbocフラグにTRUEが設定されます。この場合、イテレータは更新されません。

この関数は、入力パラメータがNULLである場合はエラーを戻します。