1. プログラマーズ・ガイド
  2. OCIのデータ型マッピング関数および操作関数
  3. OCI REF関数

28.6 OCI REF関数

OCI参照(REF)関数をリストし、説明します。

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

表28-15 REF関数

関数 用途

OCIRefAssign()

1つのREFを別のREFに代入します。

OCIRefClear()

REFをクリアまたはNULL化します。

OCIRefFromHex()

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

OCIRefHexSize()

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

OCIRefIsEqual()

2つのREFが等しいかどうかを比較します。

OCIRefIsNull()

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

OCIRefToHex()

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

28.6.1 OCIRefAssign()

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

用途

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

構文

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

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()および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用のメモリーを割り当てます。

関連トピック

28.6.2 OCIRefClear()

指定のREFをクリアまたはNULLにします。

用途

指定のREFをクリアまたはNULLにします。

構文

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

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

ref (IN/OUT)

クリアするREFです。

コメント

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

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

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

関連トピック

28.6.3 OCIRefFromHex()

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

用途

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

構文

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

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()および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で指し示されるオブジェクトが存在することは保証されません。

関連トピック

28.6.4 OCIRefHexSize()

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

用途

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

構文

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

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

ref (IN)

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

コメント

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

戻り値

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

関連トピック

28.6.5 OCIRefIsEqual()

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

用途

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

構文

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

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

x (IN)

比較するREFです。

y (IN)

比較するREFです。

コメント

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

ノート:

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

戻り値

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

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

関連トピック

28.6.6 OCIRefIsNull()

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

用途

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

構文

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

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

ref (IN)

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

コメント

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

  • 永続オブジェクトを参照するが、オブジェクトの識別子がNULLである場合

  • 一時オブジェクトを参照するが、現時点ではオブジェクトを指し示していない場合

    ノート:

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

戻り値

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

関連トピック

28.6.7 OCIRefToHex()

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

用途

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

構文

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

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()および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進文字列に変換し、その文字列の長さを戻します。変換された文字列は、コール元にとっては不透明になります。

戻り値

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

関連トピック