OCI REF関数

この項では、OCI REF関数について説明します。

表19-16 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環境ハンドルです。

関連項目:

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

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環境ハンドルです。

関連項目:

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

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環境ハンドルです。

関連項目:

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

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環境ハンドルです。

関連項目:

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

ref (IN)

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

戻り値

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

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

関連関数

OCIErrorGet()、OCIRefFromHex()

OCIRefIsEqual()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

関連項目:

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

x (IN)

比較するREFです。

y (IN)

比較するREFです。

戻り値

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

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

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

注意:

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

関連関数

OCIErrorGet()、OCIRefAssign()

OCIRefIsNull()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

関連項目:

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

ref (IN)

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

戻り値

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

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

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

注意:

指し示すオブジェクトが存在しない場合、REFは参照先がないREFです。

関連関数

OCIErrorGet()、OCIRefClear()

OCIRefToHex()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

関連項目:

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

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進文字列に変換し、その文字列の長さを戻します。変換された文字列は、コール元にとっては不透明になります。

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