表18-8は、この項で説明しているその他のオブジェクト関数を示しています。
表18-8 その他のオブジェクト関数
関数 | 用途 |
---|---|
|
1つのインスタンスを別のインスタンスにコピーします。 |
|
オブジェクト属性を取得します。 |
|
インスタンスの |
|
指定のオブジェクトへの参照を戻します。 |
|
インスタンスのTDOへの参照を取得します。 |
|
永続オブジェクトをロックします。 |
|
永続オブジェクトをロックしますが、ロック待機は行いません。 |
|
新規インスタンスを作成します。 |
|
オブジェクト属性を設定します。 |
構文
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 );
パラメータ
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()をコールして診断情報を取得します。
OCIサービス・コンテキスト・ハンドルで、コピー処理が発生するサービス・コンテキストを指定します。
ソース・インスタンスへのポインタです。ポインタがオブジェクトの場合は、確保する必要があります。
ソース・オブジェクトのNULL
インジケータ構造体へのポインタです。
ターゲット・インスタンスへのポインタです。ポインタがオブジェクトの場合は、確保する必要があります。
ターゲット・オブジェクトのNULL
インジケータ構造体へのポインタです。
ソースとターゲットの両方に対するTDOです。OCIDescribeAny()
で取り出せます。
ターゲット・メモリーの割当て時間です。
このパラメータは使用されていません。0 (ゼロ)またはOCI_DEFAULT
を渡します。
コメント
この関数は、source
インスタンスの内容をtarget
インスタンスにコピーします。この関数は、次の情報すべてがコピーされるディープ・コピーを実行します。
すべての最上位属性(後述の例外参照)
最上位属性から到達可能な(ソースの)すべての2次メモリー
インスタンスのNULL
構造体
メモリーは、duration
パラメータに指定された継続時間の間、割り当てられます。
次のデータ項目はコピーされません。
option
パラメータにオプションOCI_OBJECTCOPY_NOREF
が指定されている場合、ソース内のすべての参照はコピーされません。ターゲット内の参照はNULL
に設定されます。
属性が内部LOBの場合は、ソース・オブジェクトのLOBロケータのみがコピーされます。LOBデータのコピーはOCIObjectFlush()がコールされるまで作成されません。ターゲット・オブジェクトがフラッシュされるまで、ソースとターゲットのロケータはともに同じLOB値を参照します。
ターゲットまたはターゲットの格納インスタンスは、作成されている必要があります。これは、ターゲット・オブジェクトの存在の有無に応じて、OCIObjectNew()またはOCIObjectPin()を使用して実行できます。
source
インスタンスとtarget
インスタンスは、同じ型にしてください。ソースとターゲットが別々のデータベースに置かれている場合は、両方のデータベースに同じ型が存在することが必要です。
構文
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 );
パラメータ
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()をコールして診断情報を取得します。
オブジェクトへのポインタです。
オブジェクトまたは配列のNULL
インジケータ構造体です。
型記述子オブジェクト(TDO)へのポインタです。
属性名の配列です。パス式に属性名を指定します。
属性名長(バイト単位)の配列です。
配列names
の要素数です。
現行ではサポートされていません。(ub4 *)0
で渡します。
現行ではサポートされていません。(ub4)0
で渡します。
属性タイプが基本形の場合、属性はNULL
ステータスです。
このパラメータは、オブジェクト属性および不透明な属性に対してのみ指定され、コレクションに対しては指定されません。コレクションの場合(OCICollGetElem
を渡します)、attr_null_struct
はNULL
です。また、コレクションの場合、このパラメータは全コレクションがNULL
であるかどうかを示します。
属性値へのポインタです。
属性のTDOへのポインタです。
パラメータ
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()をコールして診断情報を取得します。
NULL
インジケータ構造体が取り出されるインスタンスへのポインタです。インスタンスは、スタンドアロン型にしてください。instance
がオブジェクトの場合は、事前に確保されることが必要です。
インスタンスのNULL
インジケータ構造体です。
パラメータ
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()をコールして診断情報を取得します。
永続オブジェクトへのポインタです。事前に確保されることが必要です。
object
に指定されているオブジェクトへの参照です。参照は、事前に割り当てられることが必要です。これは、OCIObjectNew()
によって実行できます。
パラメータ
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()をコールして診断情報を取得します。
スタンドアロン・インスタンスへのポインタです。これはスタンドアロン型であることが必要で、インスタンスがオブジェクトの場合は、事前に確保されていることも必要です。
オブジェクトの型に対する参照です。参照は、事前に割り当てられることが必要です。これは、OCIObjectNew()によって実行できます。
パラメータ
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()をコールして診断情報を取得します。
ロックされている永続オブジェクトへのポインタです。事前に確保されることが必要です。
パラメータ
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()をコールして診断情報を取得します。
ロックされている永続オブジェクトへのポインタです。事前に確保されることが必要です。
コメント
この関数は、永続オブジェクトをサーバーでロックします。ただし、OCIObjectLock()とは異なり、この関数は別のユーザーがオブジェクトでロックを保持している場合でも待機せず、オブジェクトが現在別のユーザーによってロックされている場合はエラーが戻されます。この関数は、一時オブジェクトと値、または存在しない永続オブジェクトに対して、エラーを戻します。
オブジェクトのロックは、トランザクションの終了時に解除されます。
OCIObjectLockNoWait()
は、次の値を戻します。
OCI_INVALID_HANDLE
(環境ハンドルまたはエラー・ハンドルがNULL
である場合)
OCI_SUCCESS
(操作が成功した場合)
OCI_ERROR
(操作が失敗した場合)
構文
sword OCIObjectNew ( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, OCITypeCode typecode, OCIType *tdo, void *table, OCIDuration duration, boolean value, void **instance );
パラメータ
オブジェクト・モードで初期化されたOCI環境ハンドルです。ハンドルはUTF-16 (Unicode)モードで初期化することができます。OCIEnvNlsCreate()
の説明を参照してください。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()をコールして診断情報を取得します。
OCIサービス・ハンドルです。
インスタンスの型のコードです。
記述子オブジェクト型へのポインタです。TDOは、作成されるインスタンスの型を記述します。TDOの取得の詳細は、「OCITypeByName()
」を参照してください。TDOは、オブジェクトやコレクションなどの名前付き型の作成に必要です。
表をサーバーに指定している表オブジェクトへのポインタです。表が指定されていない場合、この
パラメータはNULL
に設定されます。作成するインスタンスの種類(永続、一時、値)を判断するための表オブジェクトとTDOの使用方法は、次の説明を参照してください。表オブジェクトの取出しについては、「OCIObjectPinTable()
」も参照してください。
これはオーバーロードされたパラメータです。このパラメータの使用方法は、作成されるインスタンスの種類によって決まります。詳細は、表18-9を参照してください。
インスタンスの永続オブジェクト型の場合、このパラメータは確保継続時間を指定します。
インスタンスの一時オブジェクト型の場合、このパラメータは割当て時間および確保継続時間を指定します。
インスタンスの値型の場合、このパラメータは割当て時間を指定します。
作成されたオブジェクトが値かどうかを指定します。TRUE
の場合は、値が作成されます。それ以外の場合は、参照可能オブジェクトが作成されます。インスタンスがオブジェクトではない場合、このパラメータは無視されます。
新規に作成されたインスタンスのアドレスです。環境ハンドルが適切に設定され、オブジェクトがOCIString
の場合、インスタンスはUTF-16 (Unicode)の文字列であることが可能です。
コメント
この関数は、型コードまたはTDOによって指定された型のインスタンスを新たに作成します。型コードによって、作成するオブジェクトがOCIString
であることが示されている場合は、Unicodeバッファを使用してOCIStringオブジェクトを作成できます。
表18-9は、パラメータtypecode
(またはtdo
)、value
およびtable
に基づいて、異なる種類のインスタンスが作成されることを示しています。
表18-9 作成されるインスタンス
インスタンスの型 | Table != NULL | Table == NULL |
---|---|---|
オブジェクト型(value= |
値 |
値 |
オブジェクト型(value= |
永続オブジェクト |
一時オブジェクト |
組込み型 |
値 |
値 |
コレクション型 |
値 |
値 |
この関数は、インスタンスのトップレベルのメモリー・チャンクを割り当てます。トップレベルのメモリー内の属性は初期化されます。つまり、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 )のみをサポートしています。 |
構文
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 );
パラメータ
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()をコールして診断情報を取得します。
オブジェクト・インスタンスへのポインタです。
オブジェクト・インスタンスまたは配列のNULL
インジケータ構造体です。
TDOへのポインタです。
属性名の配列です。パス式に属性名を指定します。
属性名長(バイト単位)の配列です。
配列names
の要素数です。
現行ではサポートされていません。(ub4 *)0
で渡します。
現行ではサポートされていません。(ub4)0
で渡します。
属性タイプが基本形の場合、属性はNULL
ステータスです。
オブジェクトまたはコレクション属性のNULL
インジケータ構造体です。
属性値へのポインタです。