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

表18-7は、この項で説明しているOCIのオブジェクト・ステータス取得関数を示しています。

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

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

OCIObjectExists()

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

用途

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

構文

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

パラメータ

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

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

OCIObjectGetProperty()

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

用途

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

構文

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

パラメータ

envh (IN/OUT)

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

errh (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引数はboolean型にしてください。

OCIObjectIsDirty()

用途

オブジェクトに使用済とマークが付けられているかどうかを確認します。

構文

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

パラメータ

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

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