OCIフラッシュまたはリフレッシュ関数

表18-4は、この項で説明しているOCIフラッシュまたはリフレッシュ関数を示しています。

表18-4 フラッシュまたはリフレッシュ関数

関数	用途
「OCICacheFlush()」	キャッシュ内の変更済永続オブジェクトをサーバーにフラッシュします。
「OCICacheRefresh()」	確保されている永続オブジェクトをリフレッシュします。
「OCIObjectFlush()」	単一の変更済永続オブジェクトをサーバーにフラッシュします。
「OCIObjectRefresh()」	永続オブジェクトをリフレッシュします。

OCICacheFlush()

用途

この関数は、変更済永続オブジェクトをサーバーにフラッシュします。

構文

sword OCICacheFlush ( OCIEnv              *env, 
                      OCIError            *err, 
                      const OCISvcCtx     *svc, 
                      void                *context,
                      OCIRef              *(*get)
                                          ( void    *context,
                                            ub1     *last ), 
                      OCIRef              **ref );

パラメータ

env (IN/OUT)

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

err (IN/OUT)

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

svc (IN)

OCIサービス・コンテキストです。

context (IN) [オプション]

クライアント・コールバック関数getへの引数であるユーザー・コンテキストを指定します。ユーザー・コンテキストがない場合、このパラメータはNULLに設定します。

get (IN) [オプション]

フラッシュを必要とする使用済オブジェクトのバッチを取り出すイテレータとして機能するクライアント定義関数です。関数がNULLでない場合は、使用済オブジェクトの参照を取得するために、この関数がコールされます。これは、クライアント関数によってNULL参照が戻されるか、lastパラメータがTRUEに設定されるまで繰り返されます。クライアント関数がコールされるたびにget()にcontextパラメータが渡されます。ユーザー・コールバックを指定しない場合、このパラメータはNULLにする必要があります。クライアント関数によって戻されたオブジェクトが使用済永続オブジェクトでない場合、そのオブジェクトは無視されます。

クライアント関数から戻されたすべてのオブジェクトは、同じサービス・コンテキストを使用して更新するか、または確保する必要があります。そうしない場合、エラーが発生します。キャッシュは、戻されたオブジェクトを使用済とマークを付けられた順序でフラッシュします。

このパラメータにNULLを渡すと(たとえば、クライアント定義関数が指定されていない場合)、指定されたサービス・コンテキストのすべての使用済永続オブジェクトが、使用済とマークされた順序でフラッシュされます。

ref (OUT) [オプション]

オブジェクトのフラッシュでエラーが発生すると、(*ref)はエラーの原因となったオブジェクトを指し示します。refがNULLの場合、オブジェクトは戻りません。*refがNULLの場合は、参照が割り当てられ、そのオブジェクトを指し示すように設定されます。*refがNULLでない場合は、オブジェクトの参照が指定の領域にコピーされます。エラーの原因が使用済オブジェクトでない場合は、指定のREFがNULL参照になるように初期化されます(OCIRefIsNull(*ref)がTRUEになります)。

REFはセッション継続時間(OCI_DURATION_SESSION)に対して割り当てられます。アプリケーションはOCIObjectFree()関数を使用して、割り当てられたREFを解放できます。

この関数は、オブジェクト・キャッシュの変更済永続オブジェクトをサーバーにフラッシュします。オブジェクトは、新たに作成された順序、または更新済や削除済のマークが設定された順序でフラッシュされます。

関連関数

OCIObjectFlush()

OCICacheRefresh()

用途

キャッシュ内のすべての確保済永続オブジェクトをリフレッシュします。

構文

sword OCICacheRefresh ( OCIEnv            *env, 
                       OCIError           *err, 
                       const OCISvcCtx    *svc,
                       OCIRefreshOpt      option, 
                       void               *context,
                       OCIRef             *(*get)(void  *context), 
                       OCIRef             **ref );

パラメータ

env (IN/OUT): オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize() (非推奨)の説明を参照してください。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。
svc (IN): OCIサービス・コンテキストです。
option (IN) [オプション]: OCI_REFRESH_LOADEDが指定されると、そのトランザクションの間にロードされたすべてのオブジェクトをリフレッシュします。オプションがOCI_REFRESH_LOADEDで、getパラメータがNULLでない場合、このパラメータは無視されます。
context (IN) [オプション]: クライアント・コールバック関数getへの引数であるユーザー・コンテキストを指定します。ユーザー・コンテキストがない場合、このパラメータはNULLに設定します。
get (IN) [オプション]: リフレッシュされる必要があるオブジェクトのバッチを取り出すイテレータとして機能するクライアント定義関数です。関数がNULLでない場合は、オブジェクトの参照を取得するために、この関数がコールされます。参照がNULLでない場合、オブジェクトはリフレッシュされます。このステップは、この関数からNULL参照が戻されるまで繰り返されます。クライアント関数がコールされるたびにget()にcontextパラメータが渡されます。ユーザー・コールバックを指定しない場合、このパラメータはNULLにする必要があります。
ref (OUT) [オプション]: オブジェクトのリフレッシュでエラーが発生すると、(*ref)はエラーの原因となったオブジェクトを指し示します。refがNULLの場合、オブジェクトは戻りません。*refがNULLの場合は、参照が割り当てられ、そのオブジェクトを指し示すように設定されます。*refがNULLでない場合は、オブジェクトの参照が指定の領域にコピーされます。エラーの原因がオブジェクトでない場合は、指定のrefがNULL参照になるように初期化されます(OCIRefIsNull(*ref)がTRUEになります)。

この関数は、すべての確保済永続オブジェクトをリフレッシュします。確保解除されたすべての永続オブジェクトは、オブジェクト・キャッシュから解放されます。

関連関数

OCIObjectRefresh()

OCIObjectFlush()

用途

変更済永続オブジェクトをサーバーにフラッシュします。

構文

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

パラメータ

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

この関数は、変更済永続オブジェクトをサーバーにフラッシュします。フラッシュ時には、オブジェクトの排他ロックが暗黙的に取得されます。この関数によってオブジェクトがサーバーに書き込まれるときに、トリガーを起動できます。この関数は、一時オブジェクトと値、および未修正の永続オブジェクトに対して、エラーを戻します。

オブジェクトは、サーバーでトリガーによって変更できます。キャッシュにあるオブジェクトとデータベースとの間の整合性を保つために、アプリケーションではキャッシュにあるオブジェクトの解放やリフレッシュを行うことができます。

フラッシュするオブジェクトに内部LOB属性があり、そのLOB属性がOCIObjectCopy()、OCILobAssign()またはOCILobLocatorAssign()操作によって変更されたり、別のLOBロケータの割当てによって変更された場合は、フラッシュによって、割当て時にソースLOB内に存在していたLOB値のコピーか、内部LOBのロケータまたはオブジェクトのコピーが生成されます。

関連関数

OCIObjectPin()、OCICacheFlush()

OCIObjectRefresh()

用途

カレント・データベースの最新のスナップショットから永続オブジェクトをリフレッシュします。

構文

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

パラメータ

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

この関数は、サーバー内の最新のスナップショットから取り出されたデータを使用して、オブジェクトをリフレッシュします。オブジェクトは、オブジェクト・キャッシュ内のオブジェクトとサーバー内のオブジェクトとの間に整合性がなくなったときにリフレッシュされる必要があります。

注意:

オブジェクトをサーバーにフラッシュすると、トリガーを起動してサーバー内のさらに多くのオブジェクトを変更できます。その場合、オブジェクト・キャッシュ内にある(トリガーによって変更したオブジェクトと)同一のオブジェクトは最新の状態ではなくなり、リフレッシュしないとロックまたはフラッシュできません。

これは、ユーザーがSQL文またはPL/SQLプロシージャを発行してサーバー内のオブジェクトを変更したときに発生します。

注意:

最後のフラッシュ以降にオブジェクト(使用済オブジェクト)に対して行われた変更は、マークされていないオブジェクトがこの関数でリフレッシュされると失われます。

表18-5は、リフレッシュの後、オブジェクトの様々なメタ属性フラグと継続時間がどのように変更されるかを示しています。

表18-5 リフレッシュ後のオブジェクトの状態

オブジェクト属性	リフレッシュ後の状態
既存	適切な値に設定
確保済	変更なし
割当て時間	変更なし
確保継続時間	変更なし

リフレッシュされたオブジェクトは、その場で置き換えられます。オブジェクトがその場で置き換えられると、オブジェクトのトップレベル・メモリーが再利用されるため、新しいデータが同じメモリー・アドレスにロードされるようになります。NULLインジケータ構造体のトップレベル・メモリーも再利用されます。トップレベル・メモリー・チャンクとは異なり、2次メモリー・チャンクは解放され、再割当てが行われます。

ポインタはオブジェクトのリフレッシュ後に無効になる場合があるため、2次メモリー・チャンクのアドレスをローカル変数に割り当てるときなど、2次メモリー・チャンクへのポインタを保持する機能の記述時には注意が必要です。

この関数は、一時オブジェクトまたは値に対して何も影響を与えません。

関連関数

OCICacheRefresh()