27.5 その他のOCIオブジェクト関数
その他のオブジェクト関数をリストし、説明します。
表27-8は、この項で説明しているその他のオブジェクト関数を示しています。
表27-8 その他のオブジェクト関数
| 関数 | 用途 |
|---|---|
|
1つのインスタンスを別のインスタンスにコピーします。 |
|
|
オブジェクト属性を取得します。 |
|
|
インスタンスの |
|
|
指定のオブジェクトへの参照を戻します。 |
|
|
インスタンスのTDOへの参照を取得します。 |
|
|
永続オブジェクトをロックします。 |
|
|
永続オブジェクトをロックしますが、ロック待機は行いません。 |
|
|
新規インスタンスを作成します。 |
|
|
オブジェクト属性を設定します。 |
27.5.1 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パラメータに指定された継続時間の間、割り当てられます。
属性が内部LOBである場合などには、特定のデータ項目がコピーされず、ソース・オブジェクトのLOBロケータのみがコピーされます。LOBデータのコピーはOCIObjectFlush()がコールされるまで作成されません。ターゲット・オブジェクトがフラッシュされるまで、ソースとターゲットのロケータはともに同じLOB値を参照します。
ターゲットまたはターゲットの格納インスタンスは、作成されている必要があります。これは、ターゲット・オブジェクトの存在の有無に応じて、OCIObjectNew()またはOCIObjectPin()を使用して実行できます。
sourceインスタンスとtargetインスタンスは、同じ型にしてください。ソースとターゲットが別々のデータベースに置かれている場合は、両方のデータベースに同じ型が存在することが必要です。
27.5.2 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_valueで検出されるCデータ型をリストした表24-1。 - attr_tdo (OUT)
-
属性のTDOへのポインタです。
コメント
この関数は、オブジェクトから値を取得します。戻される属性の位置は名前配列および索引配列であるパス式で指定されます。パラメータinstanceがオブジェクトを指し示している場合は、パス式によってそのオブジェクトの属性の位置が指定されます。オブジェクトが確保され、戻された値はオブジェクトの確保が解除されるまで有効であるとみなされます。戻された値は、読取り専用とみなされ、変更できません。
attr_null_statusとattr_null_structの両方がともにNULLである場合、NULL情報は戻されません。
例
パス式stanford.cs.stu[5].addrの場合、配列は次のようになります。
names = {"stanford", "cs", "stu", "addr"}
lengths = {8, 2, 3, 4}
indexes = {5}
27.5.3 OCIObjectGetInd()
スタンドアロン・インスタンスのNULLインジケータ構造体を取得します。
用途
スタンドアロン・インスタンスの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インジケータ構造体」を参照してください
コメント
なし。
27.5.4 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()によって実行できます。
コメント
この関数は、オブジェクトへのポインタの指定時に、特定の永続オブジェクトへの参照を戻します。(オブジェクトではなく)値をこの関数に渡すと、エラーになります。
27.5.5 OCIObjectGetTypeRef()
スタンドアロン・インスタンスの型記述子オブジェクト(TDO)への参照を戻します。
用途
スタンドアロン・インスタンスの型記述子オブジェクト(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()によって実行できます。
コメント
なし。
27.5.6 OCIObjectLock()
永続オブジェクトをサーバー側でロックします。
用途
永続オブジェクトをサーバー側でロックします。
構文
sword OCIObjectLock ( OCIEnv *env,
OCIError *err,
void *object );パラメータ
コメント
この関数は、一時オブジェクトと値ではエラーを戻します。また、オブジェクトが存在しない場合にもエラーを戻します。
27.5.7 OCIObjectLockNoWait()
永続オブジェクトをサーバー側でロックしますが、ロック待機は行いません。
用途
永続オブジェクトをサーバー側でロックしますが、ロック待機は行いません。ロックが使用不可能である場合は、エラーを戻します。
構文
sword OCIObjectLockNoWait ( OCIEnv *env,
OCIError *err,
void *object );パラメータ
コメント
この関数は、永続オブジェクトをサーバーでロックします。ただし、OCIObjectLock()とは異なり、この関数は別のユーザーがオブジェクトでロックを保持している場合でも待機せず、オブジェクトが現在別のユーザーによってロックされている場合はエラーが戻されます。この関数は、一時オブジェクトと値、または存在しない永続オブジェクトに対して、エラーを戻します。
オブジェクトのロックは、トランザクションの終了時に解除されます。
OCIObjectLockNoWait()は、次の値を戻します。
-
OCI_INVALID_HANDLE(環境ハンドルまたはエラー・ハンドルがNULLである場合) -
OCI_SUCCESS(操作が成功した場合) -
OCI_ERROR(操作が失敗した場合)
27.5.8 OCIObjectNew()
スタンドアロン・インスタンスを作成します。
用途
スタンドアロン・インスタンスを作成します。
構文
sword OCIObjectNew ( OCIEnv *env,
OCIError *err,
const OCISvcCtx *svc,
OCITypeCode typecode,
OCIType *tdo,
void *table,
OCIDuration duration,
boolean value,
void **instance ); パラメータ
- tdo (IN) [オプション]
-
記述子オブジェクト型へのポインタです。TDOは、作成されるインスタンスの型を記述します。TDOの取得の詳細は、「
OCITypeByName()」を参照してください。TDOは、オブジェクトやコレクションなどの名前付き型の作成に必要です。 - table (IN) [オプション]
-
表をサーバーに指定している表オブジェクトへのポインタです。表が指定されていない場合、
このパラメータはNULLに設定されます。作成するインスタンスの種類(永続、一時、値)を判断するための表オブジェクトとTDOの使用方法は、次の説明を参照してください。表オブジェクトの取出しについては、「OCIObjectPinTable()」も参照してください。 - duration (IN)
-
これはオーバーロードされたパラメータです。このパラメータの使用方法は、作成されるインスタンスの種類によって決まります。詳細は、表27-9を参照してください。
-
インスタンスの永続オブジェクト型の場合、このパラメータは確保継続時間を指定します。
-
インスタンスの一時オブジェクト型の場合、このパラメータは割当て時間および確保継続時間を指定します。
-
インスタンスの値型の場合、このパラメータは割当て時間を指定します。
コメント
この関数は、型コードまたはTDOによって指定された型のインスタンスを新たに作成します。型には複合形または基本形を指定できます。
- レコードの場合
-
OCIObjectNew()を使用してパッケージ・レコード型を作成する場合、レコード型をインスタンス化する際にクライアント側で型コードOCI_TYPECODE_RECORDが使用されるようにする必要があります。レコードは
OCIObjectNew()で指定された割当て時間で割り当てられます。これらは後でその期間の最後に解放されます。レコード・フィールド・イニシャライザは、クライアント上でインスタンス化されたレコードにはサポートされていません。たとえば、次のmypackパッケージ定義では、
OCITypeByFullName()を使用して解決すると次のエラーが戻されます:OCI-22352: Type is unsupported or contains an unsupported attribute or element.(したがって、OCIObjectNew()をコールするには至りません)。create or replace package mypack is type r is record (rec_field number := 10); end;
すべてのレコードでNULLが有効になるため、インスタンス化されたレコードのすべてのフィールドが
NULLに設定されます。PL/SQLのNULLセマンティックとの整合性を保つために、すべてのインスタンス化されたレコードはアトミック非NULLにもなります。 - コレクションの場合
-
パッケージのコレクション型の新しいインスタンスを作成する際、
valueパラメータをTRUEに設定する必要があります。これは、パッケージのコレクション型を永続または参照可能にすることはできず、常に値としてインスタンス化する必要があるためです。FALSE値パラメータでパッケージのコレクション型にOCIObjectNew()をコールするとエラーになります。パッケージのコレクションは
OCIObjectNew()で指定された割当て時間で割り当てられます。これらは後でその期間の最後に解放されます。パッケージを作成する際、クライアントで型コードを次のように使用できます。
-
OCI_TYPECODE_NAMEDCOLLECTION- スキーマ・レベルのコレクションおよびパッケージのコレクション型の場合 -
OCI_TYPECODE_ITABLE- 索引表の場合 -
OCI_TYPECODE_TABLE- ネストした表の場合 -
OCI_TYPECODE_VARRAY- VARRAYの場合
-
- ブールの場合
-
新しいブールを作成する際、クライアントで
OCI_TYPECODE_BOOLEANを使用する必要があります。 - OCI文字列オブジェクト
-
型コードによって、作成するオブジェクトが
OCIStringであることが示されている場合は、Unicodeバッファを使用してOCIStringオブジェクトを作成できます。関連項目:
表27-9は、パラメータ
typecode(またはtdo)、valueおよびtableに基づいて、異なる種類のインスタンスが作成されることを示しています。表27-9 作成されるインスタンス
インスタンスの型 Table != NULL Table == NULL オブジェクト型(value＝
TRUE)値
値
オブジェクト型(value＝
FALSE)永続オブジェクト
一時オブジェクト
組込み型
値
値
コレクション型
値
値
この関数は、インスタンスのトップレベルのメモリー・チャンクを割り当てます。トップレベルのメモリー内の属性は初期化されます。つまり、
VARCHAR2の属性は、長さが0 (ゼロ)のOCIStringに初期化されます。インスタンスがオブジェクトである場合、オブジェクトは存在するとマークが付けられますが、アトミックにはNULLです。関連項目:
オブジェクト・ビューまたはユーザー作成OIDに基づいた新規オブジェクト作成の詳細は、「オブジェクト・ビューおよび主キー・ベースのOIDを備えたオブジェクト表に基づくオブジェクトの作成」を参照してください
新規オブジェクトの属性値
デフォルトでは、新規作成されたオブジェクトのすべての属性に 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)のみをサポートしています。
27.5.9 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)
-
属性値へのポインタです。データの型と、このコールが正常に完了した後にパラメータ
attr_valueで検出されるCデータ型をリストした表24-1を参照してください。指定の要素はディープ・コピーされること、およびattr_valueは厳密に入力パラメータであることに注意してください。
コメント
この関数は、所定のオブジェクトの属性に所定の値を設定します。属性の位置は名前配列および索引配列であるパス式で指定されます。
例
パス式stanford.cs.stu[5].addrの場合、配列は次のようになります。
names = {"stanford", "cs", "stu", "addr"}
lengths = {8, 2, 3, 4}
indexes = {5}