OCI REF関数

表19-15は、この項で説明しているOCI参照(REF)関数を示しています。

表19-15 REF関数

関数	用途
「OCIRefAssign()」	1つの`REF`を別のREFに代入します。
「OCIRefClear()」	`REF`を消去またはNULL化します。
「OCIRefFromHex()」	16進文字列を`REF`に変換します。
「OCIRefHexSize()」	`REF`の16進表現のサイズを戻します。
「OCIRefIsEqual()」	2つの`REF`が等しいかどうかを比較します。
「OCIRefIsNull()」	`REF`が`NULL`かどうかをテストします。
「OCIRefToHex()」	`REF`を16進文字列に変換します。

OCIRefAssign()

用途

あるREFを別のREFに割り当て、両方が同じオブジェクトを参照するようにします。

構文

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

パラメータ

env (IN/OUT)

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

err (IN/OUT)

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

source (IN)

コピー元のREFです。

target (IN/OUT)

コピー先のREFです。

source REFをtarget REFにコピーし、両方が同じオブジェクトを参照するようにします。target REFポインタがNULL (*target == NULL)の場合、OCIRefAssign()は、コピー操作を実行する前にOCIオブジェクト・キャッシュ内にtarget REF用のメモリーを割り当てます。

関連関数

OCIErrorGet()、OCIRefIsEqual()

OCIRefClear()

用途

指定のREFを消去またはNULLにします。

構文

void OCIRefClear ( OCIEnv        *env,
                   OCIRef        *ref );

パラメータ

env (IN/OUT)

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

ref (IN/OUT)

消去するREFです。

オブジェクトを指し示さないREFは、NULLのREFとみなされます。論理的には、NULLのREFは参照先がないREFになります。

NULLのREFは依然として有効なSQL値であり、SQLのNULLではないことに注意してください。これは、表内のNOT NULL列または行属性用の有効な非NULL定数REF値として使用できます。

REFとしてNULLポインタ値が渡されると、この関数による操作は実行されません。

関連関数

OCIErrorGet()、OCIRefIsNull()

OCIRefFromHex()

用途

指定の16進文字列をREFに変換します。

構文

sword OCIRefFromHex ( OCIEnv              *env, 
                      OCIError            *err, 
                      const OCISvcCtx     *svc, 
                      const OraText       *hex, 
                      ub4                 length, 
                      OCIRef              **ref );

パラメータ

env (IN/OUT)

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

err (IN/OUT)

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

svc (IN)

OCIサービス・コンテキスト・ハンドルです(結果のREFがこのサービス・コンテキストで初期化される場合)。

hex (IN)

REFに変換する16進テキスト文字列で、以前にOCIRefToHex()によって出力されたものです。

length (IN)

16進文字列の長さです。

ref (IN/OUT)

16進文字列が変換先となるREFです。入力時に*refがNULLの場合は、そのREF用の領域がオブジェクト・キャッシュ内に割り当てられます。それ以外の場合は、指定のREFによって占有されているメモリーが再利用されます。

この関数は、変換後のREFの書式が正しいことを保証します。生成されたREFで指し示されるオブジェクトが存在することは保証されません。

関連関数

OCIErrorGet()、OCIRefToHex()

OCIRefHexSize()

用途

REFの16進表現のサイズを戻します。

構文

ub4 OCIRefHexSize ( OCIEnv            *env,
                    const OCIRef      *ref );

パラメータ

env (IN/OUT)

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

ref (IN)

16進表現のサイズがバイト単位で戻されるREFです。

REFの16進表現のために必要なバッファ・サイズをバイト単位で戻します。最低このサイズのバッファを、REFから16進への変換関数(OCIRefToHex())に渡す必要があります。

戻り値

REFの16進表現のサイズです。

関連関数

OCIErrorGet()、OCIRefFromHex()

OCIRefIsEqual()

用途

2つのREFを比較してそれらが同等であるかどうかを判断します。

構文

boolean OCIRefIsEqual ( OCIEnv              *env,
                        const OCIRef        *x,
                        const OCIRef        *y );

パラメータ

env (IN/OUT)

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

x (IN)

比較するREFです。

y (IN)

比較するREFです。

2つのREFは、オブジェクトの種類(永続または一時)に関係なく同じオブジェクトを参照している場合のみ同等になります。

注意:

この関数では、2つのNULLのREFは等価とみなされません。

戻り値

2つのREFが同等な場合はTRUEです。

2つのREFが等しくない場合、xがNULLの場合、またはyがNULLの場合はFALSEです。

関連関数

OCIErrorGet()、OCIRefAssign()

OCIRefIsNull()

用途

REFがNULLかどうかをテストします。

構文

boolean OCIRefIsNull ( OCIEnv           *env,
                       const OCIRef     *ref );

パラメータ

env (IN/OUT)

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

ref (IN)

NULLであるかどうかをテストするREFです。

REFは、次に該当する場合のみNULLになります。

永続オブジェクトを参照するが、オブジェクトの識別子がNULLである場合
一時オブジェクトを参照するが、現時点ではオブジェクトを指し示していない場合

注意:
指し示しているオブジェクトが存在しない場合、このREFは不確定なREFです。

戻り値

指定されたREFがNULLの場合はTRUEを戻します。それ以外の場合はFALSEを戻します。

関連関数

OCIErrorGet()、OCIRefClear()

OCIRefToHex()

用途

REFを16進文字列に変換します。

構文

sword OCIRefToHex ( OCIEnv            *env,
                    OCIError          *err, 
                    const OCIRef      *ref, 
                    OraText           *hex, 
                    ub4               *hex_length );

パラメータ

env (IN/OUT)

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

err (IN/OUT)

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

ref (IN)

16進文字列に変換するREFです。refがNULLのREF (つまり、OCIRefIsNull(ref) == TRUE)の場合は、0(ゼロ)のhex_length値が戻されます。

hex (OUT)

結果の16進文字列を格納するのに十分なバッファです。文字列の内容は、コール元にとっては不透明になります。

hex_length (IN/OUT)

入力ではhexバッファのサイズを指定し、出力ではhexで戻される16進文字列の実際のサイズを指定します。

指定されたREFを16進文字列に変換し、その文字列の長さを戻します。変換された文字列は、コール元にとっては不透明になります。

戻り値

この関数は、指定されたバッファが変換後の文字列を保持できるだけの大きさがない場合はエラーを戻します。