その他のOCIオブジェクト関数

この項では、その他のオブジェクト関数について説明します。

表18-9 その他のオブジェクト関数

関数	用途
OCIObjectCopy()	1つのインスタンスを別のインスタンスにコピーします。
OCIObjectGetAttr()	オブジェクト属性を取得します。
OCIObjectGetInd()	インスタンスの`NULL`インジケータ構造体を取得します。
OCIObjectGetObjectRef()	指定のオブジェクトへの参照を戻します。
OCIObjectGetTypeRef()	インスタンスのTDOへの参照を取得します。
OCIObjectLock()	永続オブジェクトをロックします。
OCIObjectLockNoWait()	永続オブジェクトをロックしますが、ロック待機は行いません。
OCIObjectNew()	新規インスタンスを作成します。
OCIObjectSetAttr()	オブジェクト属性を設定します。

OCIObjectCopy()

用途

ソース・インスタンスを宛先インスタンスにコピーします。

構文

sword OCIObjectCopy ( OCIEnv              *env,
                      OCIError            *err,
                      const OCISvcCtx     *svc,
                      void                *source,
                      void                *null_source,
                      void                *target,
                      void                *null_target,
                      OCIType             *tdo,
                      OCIDuration         duration,
                      ub1                 option );

パラメータ

env (IN/OUT)

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

err (IN/OUT)

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

svc (IN)

OCIサービス・コンテキスト・ハンドルで、コピー処理が発生するサービス・コンテキストを指定します。

source (IN)

ソース・インスタンスへのポインタです。ポインタがオブジェクトの場合は、確保する必要があります。

関連項目:

「OCIObjectPin()」

null_source (IN): ソース・オブジェクトのNULLインジケータ構造体へのポインタです。
target (IN): ターゲット・インスタンスへのポインタです。ポインタがオブジェクトの場合は、確保する必要があります。
null_target (IN): ターゲット・オブジェクトのNULLインジケータ構造体へのポインタです。
tdo (IN): ソースとターゲットの両方に対するTDOです。OCIDescribeAny()で取り出せます。
duration (IN): ターゲット・メモリーの割当て時間です。
option (IN): このパラメータは使用されていません。0（ゼロ）またはOCI_DEFAULTを渡します。

この関数は、sourceインスタンスの内容をtargetインスタンスにコピーします。この関数は、次のすべてがコピーされるディープ・コピーを実行します。

すべての最上位属性（後述の例外参照）
最上位属性から到達可能な（ソースの）すべての2次メモリー
インスタンスのNULLインジケータ構造体

メモリーは、durationパラメータに指定された継続時間の間、割り当てられます。

次のデータ項目はコピーされません。

optionパラメータにオプションOCI_OBJECTCOPY_NOREFが指定されている場合、ソース内のすべての参照はコピーされません。ターゲット内の参照はNULLに設定されます。
属性が内部LOBの場合は、ソース・オブジェクトのLOBロケータのみがコピーされます。LOBデータのコピーはOCIObjectFlush()がコールされるまで作成されません。ターゲット・オブジェクトがフラッシュされるまで、ソースとターゲットのロケータはともに同じLOB値を参照します。

ターゲットまたはターゲットの格納インスタンスは、事前に作成されることが必要です。これは、ターゲット・オブジェクトの存在の有無に応じて、OCIObjectNew()またはOCIObjectPin()を使用して実行できます。

sourceインスタンスとtargetインスタンスは、同じ型にしてください。ソースとターゲットが別々のデータベースに置かれている場合は、両方のデータベースに同じ型が存在することが必要です。

関連関数

OCIObjectPin()

OCIObjectGetAttr()

用途

オブジェクト属性を取り出します。

構文

sword OCIObjectGetAttr ( OCIEnv             *env,
                         OCIError           *err,
                         void               *instance,
                         void               *null_struct,
                         struct OCIType     *tdo,
                         const OraText      **names,
                         const ub4          *lengths,
                         const ub4          name_count,
                         const ub4          *indexes,
                         const ub4          index_count,
                         OCIInd             *attr_null_status,
                         void               **attr_null_struct,
                         void               **attr_value,
                         struct OCIType     **attr_tdo );

パラメータ

env (IN/OUT): オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。
instance (IN): オブジェクトへのポインタです。
null_struct (IN): オブジェクトまたは配列のNULLインジケータ構造体です。
tdo (IN): TDO（記述子オブジェクト型）へのポインタです。
names (IN): 属性名の配列です。パス式に属性名を指定します。
lengths (IN): 属性名長（バイト単位）の配列です。
name_count (IN): 配列namesの要素数です。
indexes (IN) [オプション]: 現行ではサポートされていません。(ub4 *)0で渡します。
index_count (IN) [オプション]: 現行ではサポートされていません。(ub4)0で渡します。
attr_null_status (OUT): 属性タイプが基本形の場合、属性はNULLステータスです。
attr_null_struct (OUT): このパラメータはオブジェクトおよび不透明属性に対してのみ指定します。コレクションに対しては指定しません。コレクション（パスOCICollGetElem）の場合、attr_null_structはNULLです。コレクションについては、コレクション全体がNULLであるかどうかを示します。
attr_value (OUT): 属性値へのポインタです。
attr_tdo (OUT): 属性のTDOへのポインタです。

この関数は、オブジェクトまたは配列から値を取得します。パラメータinstanceがオブジェクトを指し示している場合は、パス式によってそのオブジェクトの属性の位置が指定されます。オブジェクトが確保され、戻された値はオブジェクトの確保が解除されるまで有効であるとみなされます。

attr_null_statusとattr_null_structの両方がともにNULLである場合、NULL情報は戻されません。

関連関数

OCIObjectSetAttr()

OCIObjectGetInd()

用途

スタンドアロン・インスタンスのNULLインジケータ構造体を取得します。

構文

sword OCIObjectGetInd ( OCIEnv        *env,
                        OCIError      *err,
                        void          *instance,
                        void          **null_struct );

パラメータ

env (IN/OUT): オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。
instance (IN): NULLインジケータ構造体が取り出されるインスタンスへのポインタです。インスタンスは、スタンドアロン型にしてください。instanceがオブジェクトの場合は、事前に確保されることが必要です。
null_struct (OUT): インスタンスのNULLインジケータ構造体です。

関連項目:

NULLインジケータ構造体とその使用例は、「NULLインジケータ構造体」を参照してください。

なし

関連関数

OCIObjectPin()

OCIObjectGetObjectRef()

用途

指定された永続オブジェクトへの参照を戻します。

構文

sword OCIObjectGetObjectRef ( OCIEnv        *env,
                              OCIError      *err,
                              void          *object,
                              OCIRef        *object_ref );

パラメータ

env (IN/OUT): オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。
object (IN): 永続オブジェクトへのポインタです。事前に確保されることが必要です。
object_ref (OUT): objectに指定されているオブジェクトへの参照です。参照は、事前に割り当てられることが必要です。これは、OCIObjectNew()によって実行できます。

この関数は、オブジェクトへのポインタによって指定された特定の永続オブジェクトへの参照を戻します。（オブジェクトではなく）値をこの関数に渡すと、エラーになります。

関連項目:

オブジェクトのメタ属性の詳細は、「オブジェクトのメタ属性」を参照してください。

関連関数

OCIObjectPin()

OCIObjectGetTypeRef()

用途

スタンドアロン・インスタンスの型記述子オブジェクト（TDO）への参照を戻します。

構文

sword OCIObjectGetTypeRef ( OCIEnv        *env,
                            OCIError      *err,
                            void          *instance,
                            OCIRef        *type_ref );

パラメータ

env (IN/OUT): オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。
instance (IN): スタンドアロン・インスタンスへのポインタです。これはスタンドアロン型であることが必要で、インスタンスがオブジェクトの場合は、事前に確保されていることも必要です。
type_ref (OUT): オブジェクトの型に対する参照です。参照は事前に割り当てられることが必要です。これは、OCIObjectNew()によって実行できます。

なし

関連関数

OCIObjectPin()

OCIObjectLock()

用途

永続オブジェクトをサーバー側でロックします。

構文

sword OCIObjectLock ( OCIEnv        *env,
                      OCIError      *err,
                      void          *object );

パラメータ

env (IN/OUT): オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。
object (IN): ロックされている永続オブジェクトへのポインタです。事前に確保されることが必要です。

この関数は、一時オブジェクトと値ではエラーを戻します。また、オブジェクトが存在しない場合にもエラーを戻します。

関連項目:

オブジェクトのロックの詳細は、「更新するためのオブジェクトのロック」を参照してください。

OCIObjectLockNoWait()

用途

永続オブジェクトをサーバー側でロックしますが、ロック待機は行いません。ロックが使用不可能である場合は、エラーを戻します。

構文

sword OCIObjectLockNoWait ( OCIEnv        *env,
                            OCIError      *err,
                            void          *object );

パラメータ

env (IN/OUT): オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。
object (IN): ロックされている永続オブジェクトへのポインタです。事前に確保されることが必要です。

この関数は、永続オブジェクトをサーバー側でロックします。ただし、OCIObjectLock()とは異なり、この関数では、目的のオブジェクトに対するロックを別のユーザーが保持している場合に待機が行われません。オブジェクトが現在別のユーザーによってロックされている場合は、エラーが戻されます。また、この関数は、一時オブジェクトおよび値、または存在していないオブジェクトに対してエラーを戻します。

オブジェクトのロックは、トランザクションの終了時に解除されます。

関連項目:

オブジェクトのロックの詳細は、「更新するためのオブジェクトのロック」を参照してください。

OCIObjectLockNoWait()は、次の値を戻します。

OCI_INVALID_HANDLE（環境ハンドルまたはエラー・ハンドルがNULLである場合）
OCI_SUCCESS（操作が成功した場合）
OCI_ERROR（操作が失敗した場合）

OCIObjectNew()

用途

スタンドアロン・インスタンスを作成します。

構文

sword OCIObjectNew ( OCIEnv            *env,
                     OCIError          *err,
                     const OCISvcCtx   *svc,
                     OCITypeCode       typecode,
                     OCIType           *tdo,
                     void              *table,
                     OCIDuration       duration,
                     boolean           value,
                     void              **instance );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。ハンドルはUTF-16（Unicode）モードで初期化されることもあります。 OCIEnvNlsCreate()の説明を参照してください。

err (IN/OUT)

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

svc (IN)

OCIサービス・ハンドルです。

typecode (IN)

インスタンスの型のコードです。

関連項目:

「型コード」

tdo (IN) [オプション]: 記述子オブジェクト型へのポインタです。TDOは、作成されるインスタンスの型を記述します。TDOの取得の詳細は、「OCITypeByName()」を参照してください。TDOは、オブジェクトやコレクションなどの名前付き型の作成に必要です。
table (IN) [オプション]: 表をサーバーに指定している表オブジェクトへのポインタです。表が指定されていない場合、このパラメータはNULLに設定できます。作成するインスタンスの種類（永続、一時、値）を判断するための表オブジェクトとTDOの使用方法は、次の説明を参照してください。表オブジェクトの取出しについては、「OCIObjectPinTable()」も参照してください。
duration (IN): これはオーバーロードされたパラメータです。このパラメータの使用方法は、作成されるインスタンスの種類によって決まります。

永続オブジェクト。このパラメータは、確保継続時間を指定します。
一時オブジェクト。このパラメータは、割当て時間および確保継続時間を指定します。
値。このパラメータは、割当て時間を指定します。

value (IN): 作成されたオブジェクトが値かどうかを指定します。TRUEの場合は、値が作成されます。それ以外の場合は、参照可能オブジェクトが作成されます。インスタンスがオブジェクトではない場合、このパラメータは無視されます。
instance (OUT): 新規に作成されたインスタンスのアドレスです。環境ハンドルが適切に設定され、オブジェクトがOCIStringの場合、インスタンスはUTF-16（Unicode）の文字列であることが可能です。

この関数は、型コードまたはTDOによって指定された型のインスタンスを新たに作成します。型コードによって、作成するオブジェクトがOCIStringであることが示されている場合は、Unicodeバッファを使用してOCIStringオブジェクトを作成できます。

関連項目:

「型コード」

パラメータtypecode（またはtdo）、valueおよびtableに基づいて、次のような異なる種類のインスタンスが作成されます。

表18-10 作成されるインスタンス

インスタンスの型	Table != NULL	Table == NULL
オブジェクト型（value＝`TRUE`）	値	値
オブジェクト型（value＝`FALSE`）	永続オブジェクト	一時オブジェクト
組込み型	値	値
コレクション型	値	値

この関数は、インスタンスのトップレベル・メモリー・チャンクを割り当てます。トップレベル・メモリー内の属性が初期化されます。つまり、VARCHAR2の属性が長さ0（ゼロ）のOCIStringに初期化されます。インスタンスがオブジェクトの場合、そのオブジェクトに存在マークが設定されますがオブジェクトはアトミックNULLになります。

関連項目:

オブジェクト・ビューまたはユーザー作成OIDに基づいた新規オブジェクト作成の詳細は、「オブジェクト・ビューおよび主キー・ベースのOIDを備えたオブジェクト表に基づくオブジェクトの作成」を参照してください。

永続オブジェクト: オブジェクトに使用済および存在マークが設定されます。オブジェクトの割当て時間はセッションです。オブジェクトは、durationパラメータに指定された確保継続時間の間、確保されます。永続オブジェクトが作成されても、そのオブジェクトがサーバーにフラッシュされるまで、データベース表へのエントリは行われません。
一時オブジェクト: オブジェクトが確保されます。割当て時間および確保継続時間は、durationパラメータによって指定されます。
値: 割当て時間は、durationパラメータによって指定されます。

新規オブジェクトの属性値

デフォルトでは、新規作成されたオブジェクトのすべての属性に NULL値があります。属性データを初期化した後で、対応する各属性のNULLステータスをNULL以外に変更する必要があります。

オブジェクトの作成時に、属性をNULL以外の値に設定できます。これは、OCIAttrSet()を使用して環境ハンドルのOCI_ATTR_OBJECT_NEWNOTNULL属性をTRUEに設定することによって実行できます。その後、この属性をFALSEに設定すると、このモードを無効にできます。OCI_ATTR_OBJECT_NEWNOTNULLがTRUEに設定されている場合は、OCIObjectNew()によってNULL以外のオブジェクトが作成されます。

関連項目:

「新規オブジェクトの属性値」

LOB属性を持つオブジェクト

オブジェクトに内部LOB属性がある場合、LOBはEmpty値に設定されます。LOBへのデータ書込みを開始する前には、そのオブジェクトに使用済マークを設定して（オブジェクトを表に挿入するために）フラッシュし、再確保する必要があります。作成後にオブジェクトを確保するときは、新しく更新されたLOBロケータをサーバーから取り出すために、OCI_PIN_LATEST PINオプションを使用する必要があります。

オブジェクトに外部LOB属性（FILE）がある場合は、FILEロケータが割り当てられますが、初期化はされません。オブジェクトをデータベースにフラッシュする前に、OCILobFileSetName()をコールしてFILE属性を初期化する必要があります。最初にディレクトリ・オブジェクトおよびファイル名を指定せずにFILEのINSERTまたはUPDATEを実行すると、エラーが発生します。ファイル名を設定すると、FILEの読取りを開始できます。

注意:

現在、バイナリ・ファイル（BFILE）のみをサポートしています。

関連関数

OCIObjectPinTable()、OCIObjectFree()

OCIObjectSetAttr()

用途

オブジェクト属性を設定します。

構文

sword OCIObjectSetAttr ( OCIEnv              *env,
                         OCIError            *err,
                         void                *instance,
                         void                *null_struct,
                         struct OCIType      *tdo,
                         const OraText       **names,
                         const ub4           *lengths,
                         const ub4           name_count,
                         const ub4           *indexes,
                         const ub4           index_count,
                         const OCIInd        null_status,
                         const void          *attr_null_struct,
                         const void          *attr_value );

パラメータ

env (IN/OUT): オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。
instance (IN): オブジェクト・インスタンスへのポインタです。
null_struct (IN): オブジェクト・インスタンスまたは配列のNULLインジケータ構造体です。
tdo (IN): TDOへのポインタです。
names (IN): 属性名の配列です。パス式に属性名を指定します。
lengths (IN): 属性名長（バイト単位）の配列です。
name_count (IN): 配列namesの要素数です。
indexes (IN) [オプション]: 現行ではサポートされていません。(ub4 *)0で渡します。
index_count (IN) [オプション]: 現行ではサポートされていません。(ub4)0で渡します。
attr_null_status (IN): 属性タイプが基本形の場合、属性はNULLステータスです。
attr_null_struct (IN): オブジェクトまたはコレクション属性のNULLインジケータ構造体です。
attr_value (IN): 属性値へのポインタです。

この関数は、所定のオブジェクトの属性に所定の値を設定します。属性の位置は名前配列および索引配列であるパス式で指定されます。

例

パス式stanford.cs.stu[5].addrの場合、配列は次のようになります。

names = {"stanford", "cs", "stu", "addr"}

lengths = {8, 2, 3, 4}

indexes = {5}

関連関数

OCIObjectGetAttr()