OCIのオブジェクト・ステータス取得関数

この項では、OCIのオブジェクト・ステータス取得関数について説明します。

表18-8 オブジェクト・ステータス取得関数

関数	用途
OCIObjectExists()	インスタンスの存在ステータスを取得します。
OCIObjectGetProperty()	特定のオブジェクト・プロパティのステータスを取得します。
OCIObjectIsDirty()	インスタンスの使用済ステータスを取得します。
OCIObjectIsLocked()	インスタンスのロック状態を取得します。

OCIObjectExists()

用途

スタンドアロン・インスタンスの存在メタ属性を戻します。

構文

sword OCIObjectExists ( OCIEnv         *env,
                        OCIError       *err,
                        void           *ins,
                        boolean        *exist );

パラメータ

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

この関数は、インスタンスの存在を戻します。インスタンスが値の場合、この関数は常にTRUEを戻します。インスタンスは、スタンドアロン型の永続または一時オブジェクトにしてください。

関連関数

OCIObjectPin()

OCIObjectGetProperty()

用途

オブジェクトの指定されたプロパティを取り出します。

構文

sword OCIObjectGetProperty ( OCIEnv              *envh,
                             OCIError            *errh,
                             const void          *obj,
                             OCIObjectPropId     propertyId,
                             void                *property,
                             ub4                 *size );

パラメータ

env (IN/OUT)

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

err (IN/OUT)

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

obj (IN)

そのプロパティが戻されるオブジェクトです。

propertyId (IN)

目的のプロパティを識別する識別子です。

property (OUT)

目的のプロパティがコピーされるバッファです。

size (IN/OUT)

入力の際は、コール元から渡されるプロパティ・バッファのサイズがこのパラメータによって指定されます。

出力の際は、戻されるプロパティのサイズがバイト単位でここに格納されます。このパラメータは、OCI_OBJECTPROP_SCHEMA、OCI_OBJECTPROP_TABLEなどの文字列型のプロパティのみに必要です。非文字列型のプロパティの場合は、サイズが固定しているため、このパラメータは無視されます。

この関数によりオブジェクトの指定されたプロパティが戻されます。目的のプロパティはpropertyIdで識別されます。プロパティの値はpropertyにコピーされ、文字列型プロパティの場合は、文字列のサイズがsizeによって戻されます。

オブジェクトは、その存続期間と参照可能性に基づいて永続、一時および値に分類されます。プロパティのいくつかは永続オブジェクトのみに適用され、また他のプロパティは永続オブジェクトと一時オブジェクト（の両方）に適用されます。指定したオブジェクトに適用されないプロパティを取得しようとすると、エラーが戻されます。このようなエラーを回避するには、最初にそのオブジェクト（のOCI_OBJECTPROP_LIFETIMEプロパティ）が永続、一時、値のどれであるかをチェックしてから、他のプロパティを適切に問い合せるようにします。

様々なプロパティIDとそれに対応するproperty引数の型を次に示します。

OCI_OBJECTPROP_LIFETIME: このプロパティによって、指定されたオブジェクトが永続オブジェクト、一時オブジェクト、または値のインスタンスかのいずれであるかが識別されます。property引数はOCIObjectLifetime型の変数へのポインタにしてください。可能な値は、次のとおりです。

OCI_OBJECT_PERSISTENT
OCI_OBJECT_TRANSIENT
OCI_OBJECT_VALUE

OCI_OBJECTPROP_SCHEMA: このプロパティによって、オブジェクトが存在する表のスキーマ名が戻されます。指定されたオブジェクトが一時インスタンスまたは値を指し示している場合は、エラーが戻されます。スキーマ名の保持に入力バッファのサイズが足りない場合は、エラーが戻され、エラー・メッセージで必要なサイズが表示されます。成功した場合は、sizeによって、戻されたスキーマ名のサイズがバイト単位で戻されます。property引数は、text型の配列にしてください。コール元は、sizeをバイト単位で配列のサイズに設定する必要があります。
OCI_OBJECTPROP_TABLE: このプロパティによってそのオブジェクトが存在する表名が戻されます。指定されたオブジェクトが一時インスタンスまたは値を指し示している場合は、エラーが戻されます。表名の保持に入力バッファが足りない場合は、エラーが戻され、エラー・メッセージで必要なサイズが表示されます。成功した場合は、sizeによって、戻された表名のサイズがバイト単位で戻されます。property引数は、text型の配列にしてください。コール元では、sizeを配列のサイズにバイト単位で設定する必要があります。
OCI_OBJECTPROP_PIN_DURATION: このプロパティによってオブジェクトの確保継続時間が戻されます。指定されたオブジェクトが値のインスタンスを指し示している場合は、エラーが戻されます。property引数はOCIDuration型の変数へのポインタにしてください。有効な値は、次のとおりです。

OCI_DURATION_SESSION
OCI_DURATION_TRANS

関連項目:

継続時間については、「オブジェクト継続時間」を参照してください。

OCI_OBJECTPROP_ALLOC_DURATION: このプロパティによって、オブジェクトの割当て時間が戻されます。property引数はOCIDuration型の変数へのポインタにしてください。次の値が有効です。

OCI_DURATION_SESSION
OCI_DURATION_TRANS

継続時間については、「オブジェクト継続時間」を参照してください。

OCI_OBJECTPROP_LOCK: このプロパティによってオブジェクトのロック状況が戻されます。可能なロック状況はOCILockOptによって列挙されます。指定されたオブジェクトが一時インスタンスまたは値インスタンスを指し示している場合は、エラーが戻されます。property引数はOCILockOpt型の変数へのポインタにしてください。オブジェクトのロック状況は、OCIObjectIsLocked()関数をコールしても取り出せます。次の値が有効です。

OCI_LOCK_NONE－ロックなし
OCI_LOCK_X－排他ロック
OCI_LOCK_X_NOWAIT－ NOWAITオプションを使用した排他ロック

関連項目:

「NOWAITオプションを使用したロック」

OCI_OBJECTPROP_MARKSTATUS: このプロパティによって使用済ステータスが戻され、オブジェクトが新規のオブジェクトであるか、更新されたオブジェクトであるか、削除されたオブジェクトであるかが示されます。指定されたオブジェクトが一時インスタンスまたは値インスタンスを指し示している場合は、エラーが戻されます。property引数はOCIObjectMarkStatus型にしてください。次の値が有効です。

OCI_OBJECT_NEW
OCI_OBJECT_DELETED
OCI_OBJECT_UPDATED

次のマクロを使用してマーク状態をテストすることが可能です。

OCI_OBJECT_IS_UPDATED (flag)
OCI_OBJECT_IS_DELETED (flag)
OCI_OBJECT_IS_NEW (flag)
OCI_OBJECT_IS_DIRTY (flag)

OCI_OBJECTPROP_VIEW: このプロパティによって指定されたオブジェクトがビュー・オブジェクトであるかどうかが識別されます。戻されたプロパティ値がTRUEの場合、そのオブジェクトはビューであり、そうでない場合はビューではありません。指定されたオブジェクトが一時インスタンスまたは値インスタンスを指し示している場合は、エラーが戻されます。このproperty引数はブール型にする必要があります。

OCIObjectIsDirty()

用途

オブジェクトに使用済マークが設定されているかどうかをチェックします。

構文

sword OCIObjectIsDirty ( OCIEnv       *env,
                         OCIError     *err,
                         void         *ins,
                         boolean      *dirty );

パラメータ

env (IN/OUT): オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。
ins (IN): インスタンスへのポインタです。
dirty (OUT): 使用済ステータスに対する値を戻します。

この関数に渡すインスタンスはスタンドアロンにしてください。インスタンスがオブジェクトの場合、そのインスタンスは確保されることが必要です。

この関数は、インスタンスの使用済ステータスを戻します。インスタンスが値の場合、この関数は使用済ステータスに対して常にFALSEを戻します。

OCIObjectIsLocked()

用途

オブジェクトのロック状況を取得します。

構文

sword OCIObjectIsLocked ( OCIEnv       *env,
                          OCIError     *err,
                          void         *ins,
                          boolean      *lock );

パラメータ

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

この関数は、インスタンスのロック状況を戻します。インスタンスが値の場合、この関数は常にFALSEを戻します。

関連関数

OCIObjectLock()、OCIObjectGetProperty()