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

表18-8は、この項で説明しているその他のオブジェクト関数を示しています。

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

関数	用途
「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環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()および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()、OCIEnvNlsCreate()および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()、OCIEnvNlsCreate()および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()、OCIEnvNlsCreate()および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()、OCIEnvNlsCreate()および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()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。

err (IN/OUT)

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

object (IN)

ロックされている永続オブジェクトへのポインタです。事前に確保されることが必要です。

コメント

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

関連項目: 「更新するためのオブジェクトのロック」

関連関数

OCIObjectPin()、OCIObjectIsLocked()、OCIObjectGetProperty()、OCIObjectLockNoWait()

OCIObjectLockNoWait()

用途

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

構文

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

パラメータ

env (IN/OUT)

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

err (IN/OUT)

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

object (IN)

ロックされている永続オブジェクトへのポインタです。事前に確保されることが必要です。

コメント

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

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

関連項目: 「更新するためのオブジェクトのロック」

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

• OCI_INVALID_HANDLE (環境ハンドルまたはエラー・ハンドルがNULLである場合)

• OCI_SUCCESS (操作が成功した場合)

• OCI_ERROR (操作が失敗した場合)

関連関数

OCIObjectPin()、OCIObjectIsLocked()、OCIObjectGetProperty()、OCIObjectLock()

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)

これはオーバーロードされたパラメータです。このパラメータの使用方法は、作成されるインスタンスの種類によって決まります。詳細は、表18-9を参照してください。

• インスタンスの永続オブジェクト型の場合、このパラメータは確保継続時間を指定します。

• インスタンスの一時オブジェクト型の場合、このパラメータは割当て時間および確保継続時間を指定します。

• インスタンスの値型の場合、このパラメータは割当て時間を指定します。

value (IN)

作成されたオブジェクトが値かどうかを指定します。TRUEの場合は、値が作成されます。それ以外の場合は、参照可能オブジェクトが作成されます。インスタンスがオブジェクトではない場合、このパラメータは無視されます。

instance (OUT)

新規に作成されたインスタンスのアドレスです。環境ハンドルが適切に設定され、オブジェクトがOCIStringの場合、インスタンスはUTF-16 (Unicode)の文字列であることが可能です。

コメント

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

関連項目: 「型コード」

表18-9は、パラメータtypecode (またはtdo)、valueおよびtableに基づいて、異なる種類のインスタンスが作成されることを示しています。

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

インスタンスの型	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から読取りを開始できるようになります。

注意: Oracle Databaseでは、バイナリ・ファイル(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        *attr_null_status, 
                         const void          *attr_null_struct,
                         const void          *attr_value );

パラメータ

env (IN/OUT)

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