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

表19-2は、この項で説明しているコレクションおよびイテレータ関数を示しています。

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

関数	用途
「OCICollAppend()」	コレクションの最後に要素を追加します。
「OCICollAssign()」	あるコレクションを別のコレクションに割り当てます(ディープ・コピーします)。
「OCICollAssignElem()」	指定の要素値elemをcoll[index]の要素に割り当てます。
「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()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

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

elem (IN)

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

elemind (IN) [オプション]

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

coll (IN/OUT)

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

コメント

要素を追加することは、要素ごとにコレクションのサイズを増加させて、最後の要素のデータを指定した要素のデータで更新(ディープ・コピー)することと同等です。この関数では、指定した要素elemへのポインタは保存されません。つまり、elemは厳密に入力パラメータになります。

戻り値

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

関連関数

OCIErrorGet()

OCICollAssign()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

関連項目: 「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「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()」、「OCIEnvNlsCreate()」および「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()」、「OCIEnvNlsCreate()」および「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インジケータ情報のアドレスを戻します。

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

表19-3 要素ポインタ

要素型	*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**)へのポインタが戻ります。コレクション要素へのポインタを取得した後、新しい参照を割り当てることでそれを修正できます。

例19-1に、OCIRefAssign()関数を使用してこれを実行する方法を示します。

例19-1 コレクション要素へのポインタへの新しい参照の割当て

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*を戻します。例19-2に、OCINumberAssign()コールのプロトタイプを示します。

例19-2 OCINumberAssign()コールのプロトタイプ

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

戻り値

OCICollGetElem()関数は、入力パラメータが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()」、「OCIEnvNlsCreate()」および「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()」、「OCIEnvNlsCreate()」および「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()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

coll (IN)

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

コメント

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

戻り値

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

関連関数

OCIErrorGet()、OCICollSize()

OCICollSize()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

関連項目: 「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「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

戻り値

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

関連関数

OCIErrorGet()、OCICollMax()

OCICollTrim()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

関連項目: 「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「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()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

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

coll (IN)

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

itr (OUT)

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

コメント

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

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

戻り値

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

関連関数

OCIErrorGet()、OCIIterDelete()

OCIIterDelete()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

関連項目: 「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「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()」、「OCIEnvNlsCreate()」および「OCIInitialize()」(非推奨)

err (IN/OUT)

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

itr (IN)

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

elem (OUT)

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

elemind (OUT) [オプション]

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

コメント

カレント・イテレータ・コレクション要素へのポインタとそれに対応するNULL情報を戻します。

戻り値

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

関連関数

OCIErrorGet()、OCIIterNext()、OCIIterPrev()

OCIIterInit()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

関連項目: 「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「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()」、「OCIEnvNlsCreate()」および「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である場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIIterGetCurrent()、OCIIterPrev()

OCIIterPrev()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

関連項目: 「OCIEnvCreate()」、「OCIEnvNlsCreate()」および「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である場合はエラーを戻します。

関連関数

OCIErrorGet()、OCIIterGetCurrent()、OCIIterNext()