27.2 OCIフラッシュまたはリフレッシュ関数
OCIフラッシュまたはリフレッシュ関数をリストし、説明します。
表27-4は、この項で説明しているOCIフラッシュまたはリフレッシュ関数を示しています。
表27-4 フラッシュまたはリフレッシュ関数
関数 | 用途 |
---|---|
キャッシュ内の変更済永続オブジェクトをサーバーにフラッシュします。 |
|
確保されている永続オブジェクトをリフレッシュします。 |
|
単一の変更済永続オブジェクトをサーバーにフラッシュします。 |
|
永続オブジェクトをリフレッシュします。 |
27.2.1 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()
この関数によるネットワーク・ラウンドトリップは大抵1回です。
27.2.2 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
になります)。
コメント
この関数は、すべての確保済永続オブジェクトをリフレッシュします。確保解除されたすべての永続オブジェクトは、オブジェクト・キャッシュから解放されます。
ノート:
オブジェクトがリフレッシュされると、それらのオブジェクトの2次メモリーがメモリー内の別の場所に移動することがあります。このため、このコール前に保存された属性へのポインタが無効になる可能性があります。2次メモリーを使用する属性には、OCIString *
、OCIColl *
、OCIRaw *
などがあります。
27.2.3 OCIObjectFlush()
変更済永続オブジェクトをサーバーにフラッシュします。
用途
変更済永続オブジェクトをサーバーにフラッシュします。
構文
sword OCIObjectFlush ( OCIEnv *env, OCIError *err, void *object );
パラメータ
コメント
この関数は、変更済永続オブジェクトをサーバーにフラッシュします。フラッシュ時には、オブジェクトの排他ロックが暗黙的に取得されます。この関数によってオブジェクトがサーバーに書き込まれるときに、トリガーを起動できます。この関数は、一時オブジェクトと値、および未修正の永続オブジェクトに対して、エラーを戻します。
オブジェクトは、サーバーでトリガーによって変更できます。キャッシュにあるオブジェクトとデータベースとの間の整合性を保つために、アプリケーションではキャッシュにあるオブジェクトの解放やリフレッシュを行うことができます。
フラッシュするオブジェクトに内部LOB属性があり、そのLOB属性がOCIObjectCopy()
、OCILobAssign()
またはOCILobLocatorAssign()
操作によって変更されたり、別のLOBロケータの割当てによって変更された場合は、フラッシュによって、割当て時にソースLOB内に存在していたLOB値のコピーか、内部LOBのロケータまたはオブジェクトのコピーが生成されます。
27.2.4 OCIObjectRefresh()
カレント・データベースの最新のスナップショットから永続オブジェクトをリフレッシュします。
用途
カレント・データベースの最新のスナップショットから永続オブジェクトをリフレッシュします。
構文
sword OCIObjectRefresh ( OCIEnv *env, OCIError *err, void *object );
パラメータ
コメント
この関数は、サーバー内の最新のスナップショットから取り出されたデータを使用して、オブジェクトをリフレッシュします。オブジェクトは、オブジェクト・キャッシュ内のオブジェクトとサーバー内のオブジェクトとの間に整合性がなくなったときにリフレッシュされる必要があります。
ノート:
オブジェクトをサーバーにフラッシュすると、トリガーを起動してサーバー内のさらに多くのオブジェクトを変更できます。その場合、オブジェクト・キャッシュ内にある(トリガーによって変更したオブジェクトと)同一のオブジェクトは最新の状態ではなくなり、リフレッシュしないとロックまたはフラッシュできません。
これは、ユーザーがSQL文またはPL/SQLプロシージャを発行してサーバー内のオブジェクトを変更したときに発生します。
ノート:
最後のフラッシュ以降にオブジェクト(使用済オブジェクト)に対して行われた変更は、マークされていないオブジェクトがこの関数でリフレッシュされると失われます。
表27-5は、リフレッシュの後、オブジェクトの様々なメタ属性フラグと継続時間がどのように変更されるかを示しています。
表27-5 リフレッシュ後のオブジェクトの状態
オブジェクト属性 | リフレッシュ後の状態 |
---|---|
既存 |
適切な値に設定 |
確保済 |
変更なし |
割当て時間 |
変更なし |
確保継続時間 |
変更なし |
リフレッシュされたオブジェクトは、その場で置き換えられます。オブジェクトがその場で置き換えられると、オブジェクトのトップレベル・メモリーが再利用されるため、新しいデータが同じメモリー・アドレスにロードされるようになります。NULL
インジケータ構造体のトップレベル・メモリーも再利用されます。トップレベル・メモリー・チャンクとは異なり、2次メモリー・チャンクは解放され、再割当てが行われます。
ポインタはオブジェクトのリフレッシュ後に無効になる場合があるため、2次メモリー・チャンクのアドレスをローカル変数に割り当てるときなど、2次メモリー・チャンクへのポインタを保持する機能の記述時には注意が必要です。
この関数は、一時オブジェクトまたは値に対して何も影響を与えません。