使用上の注意

この項には次のトピックが含まれます:

コンテキストの初期化および永続性

CLSCRS APIを使用する場合、最初にclscrsコンテキストを初期化する必要があります。このコンテキストを作成および終了するためのコールは次のとおりです。

clscrs_init_crs: clscrsコンテキストを初期化します。
clscrs_term_crs: clscrsコンテキストを終了します。

コンテキストが不要になると、コール元によってそのコンテキストは終了されます。

スレッドのサポート

CLSCRS_FLAG_USETHREADSフラグを指定して初期化した場合、CLSCRS APIによってスレッドが内部的に生成される場合があります。APIの各関数は、コール元のスレッドのコンテキストで実行されます。APIコンテキスト・オブジェクトは、複数のスレッドによって同時に使用できない場合があります。ただし、クライアント側でのスレッド・アフィニティは必要ありません。一度に対応できるのはコンテキストごとに1つのスレッドであるというルールに従って、プロセスは複数のAPIコンテキストを作成し、様々なスレッドで使用する場合があります。

CLSCRS APIデータ構造

次のエンティティはAPIコールに渡され、APIコールからの戻り値が含まれます。

clscrs_sp: 文字列ペア(sp)には、名前および値の文字列が含まれます。値はNULLの場合もあります。作成されたり破棄されること、およびその内容を調べることで値を置換することが可能です。文字列ペアは、1つの文字列ペア・リスト(splist)のみのメンバーの場合もあります。
clscrs_splist: 文字列ペア・リスト(splist)は、様々なコンテキストで使用される0(ゼロ)個以上の文字列ペアのリストです。APIで文字列ペアを文字列ペア・リストに追加したり、リストから削除することまたはAPIで文字列ペアを繰り返し適用することができます。

clscrs_entity_type: Oracle Clusterwareエンティティのタイプの識別に使用できる列挙タイプ。

列挙タイプは次のように定義します。

/* enum to specify the entity type */ 
typedef enum
{ 
   clscrs_entity_res              = 1, /* resource */ 
   clscrs_entity_restype          = 2, /* resource type */ 
   clscrs_entity_serverpool       = 3, /* server pool */ 
   clscrs_entity_server           = 4, /* server */ 
   clscrs_entity_resinst          = 5, /* resource instances */ 
   clscrs_entity_config_policy    = 6, /* configuration policy */ 
   clscrs_entity_config_policyset = 7, /* configuration policy 
set */ 
   clscrs_entity_server_category  = 8  /* server category */ 
} clscrs_entity_type;

clscrs_crsentity: このデータ構造(crsentity)はOracle Clusterwareエンティティを示し、これには、名前、およびOracle Clusterwareエンティティが使用されるコンテキストに適した追加データが含まれます。APIには、Oracle Clusterwareエンティティの属性データが含まれる場合もあれば、操作に関するステータスおよび戻りメッセージが示される場合もあります。シングル・エンティティは、1つのclscrs_crsentitylistのみのメンバーの場合もあります。
clscrs_crsentitylist: エンティティ・リスト(crsentitylist)は、clscrs_crsentityの0個以上のインスタンスが含まれるデータ構造です。APIによって、エンティティ・リストでエンティティを追加したり削除すること、またはエンティティを繰り返し適用することができます。

メモリー管理

CLSCRS APIは、要素およびリストに対して機能します。要素はリストに追加されます。要素およびリストの両方に対するメモリーの割当ておよび解放は、明示的なAPIコールを介して行われます。割り当てられたメモリーの解放は、コール元によって行われます。ただし、要素がリストに追加されている場合は、そのリストのみを破棄する必要があり、リストを破棄することで、その要素も暗黙的に破棄されます。要素がリストに追加されていない場合は、要素を破棄する必要があります。再帰的リストの場合、親リストを破棄すると、それに含まれるリストもすべて破棄されます。clscrs_spおよびclscrs_crsentity要素は、コール元によって破棄される必要があります。これらがclscrs_splistまたはclscrs_crsentitylistに属する場合は、リストを破棄すると、clscrs_spおよびclscrs_crsentityのエンティティがそれぞれ破棄されます。

たとえば、リソースが作成されてリソース・リストに追加された場合は、そのリソース・リストのみが破棄され、個々のリソースは破棄されません。また、リソース・リストを破棄すると、個々のリソースのメモリーが解放されます。

メモリーは、APIによって、次のコールを介して割り当てられます。

clscrs_sp_create()
clscrs_crsentity_create()
clscrs_serverpool_create()
clscrs_type_create()
clscrs_splist_create()
clscrs_crsentitylist_create()
clscrs_entity_id_create()

前述のリストの各コールには、対応するclscrs_*_destroy()コールがあります。

エラーの処理およびトレース

対話形式および非対話形式のCLSCRS APIは、それぞれ異なるエラー処理メカニズムを使用します。

非対話形式CLSCRS APIでは、エラー・コードは関数コールの戻り値として戻されます。次に例を示します。

clscrsret clscrs_sp_get_value(clscrs_sp *sp, oratext **value);

エラー・コードは、clscrsret値として戻されます。

対話形式CLSCRS APIでは、出力結果は次のように表示されます。

関数コールの戻り値によって、リクエストの概要が出力されます。サーバーでリクエストが受信されたかどうかが示されます。また、正常に完了したか、完全に失敗したか、または一部で失敗したかどうかも示されます。戻り値が正常であるということは、リクエストの受信および処理が行われ、リクエストされたすべてのエンティティに対する結果が正常であったことを示します。
リクエストが行われたエンティティごとに、op_statusリストにプログラムの完了コードが格納されます。値がsuccessではない場合は、特定のオブジェクトに対するリクエストの処理で高度な問題が発生したことを示します。
必要に応じて、APIでは、コールバック・メカニズムを使用して、ローカライズされた判読可能なエラー、警告、ステータス・メッセージを受信するように示される場合があります。コールバックが起動されるたびに、コールバックの起動に関するメッセージ、メッセージ・タイプ(重大度)およびオブジェクトIDが表示されます。

次に例を示します。

CLSCRS_STAT clscrs_register_resource2(clscrs_crsentitylist *in_crsentitylist, uword flags,
                                       clscrs_msgf2 msgf, void *msgarg,
                                       clscrs_crsentitylist *op_status);

関数によって、CLSCRS_STATという値のエラー・コードが戻されます。
CRSDによって、clscrs_msgf2コールバックを介して、エラー・メッセージ、警告メッセージ、進捗メッセージがクライアントに戻されます。クライアントには、CRSDによって戻されるこれらのメッセージを処理するコールバックが実装されている必要があります。
以前のOracle Clusterwareリリースでは、APIに、op_statusリストの一部としてOracle Clusterwareエンティティの各操作の結果も含まれていました。次のAPIを使用してその情報にアクセスできます。
```
clscrsret clscrs_entity_get_op_status(clscrs_entity *res, CLSCRS_STAT *status,
                                    oratext **msg);
```
status引数には、Oracle ClusterwareエンティティのCRSD操作に関するステータス・コードが含まれます。また、msg引数には、操作の結果に関するCRSDからのメッセージが含まれます。msg引数の各Oracle Clusterwareエンティティに対するCRSD操作の結果は引き続きop_statusリストに含まれますが、msg引数の使用によるエラー・コードおよびメッセージの取得は非推奨となり、新しいエンティティのAPIではサポートされていません。既存の使用(特にリソースでの処理)でのみサポートされます。CRSDによって戻されるメッセージを処理する場合は、コールバック関数を使用してください。

コールバック・メカニズム

対話形式CLSCRS APIでは、クライアントがCRSDによって送信されたエラー・メッセージ、警告メッセージおよび進捗メッセージを処理するために使用するコールバック・メカニズムが提供されます。

コールバック・メカニズムのシグネチャは次のとおりです。

typedef  void (*clscrs_msgf2)(void *usrp, const oratext *id, const oratext *msg,
                clscrs_msgtype msgtype);

前の構文では:

usrp: コールのコンテキストが含まれるユーザー指定のポインタ
id: メッセージに対応するエンティティの識別子
msg: 出力テキスト
msgtype: メッセージのタイプ(エラー、警告または進捗)

例H-1に、コールバック・メカニズムの例を示します。

例H-1 コールバック・メカニズム

void myCallback(void *arg, const oratext *pId, const oratext *pMsg,
                clscrs_msgtype msgType)
{
    if (pMsg != NULL)
   {
       cout << pMsg << endl;
    }
}

例H-2に、対話形式APIでコールバック・メカニズムを使用する方法を示します。

例H-2 対話形式APIでのコールバック・メカニズムの使用

clscrs_start_resource2(pResIdList, NULL,
                       env, myCallback, NULL,
                       0, pOpStatus);

コンテキストの作成時にCLSCRS_FLAG_TRACEフラグを渡すことによって、APIのデバッグ・トレース・メッセージを出力することもできます。コンテキスト作成のシグネチャは次のとおりです。

CLSCRS_STAT clscrs_init_crs(clscrs_ctx **ctx, clscrs_msgf2 errf, void *errCtx,
                             ub4 flags);

トレース・メッセージを機能させるには、clscrs_init_crs APIで、CLSCRS_FLAG_TRACEフラグおよびclscrs_msgf2コールバック・メカニズムの両方を指定する必要があります。

clscrs_msgf2コールバック・メカニズムのシグネチャは次のとおりです。

typedef  void (*clscrs_msgf)(void *usrp, const oratext *msg, sword msglen);

フィルタ

フィルタを使用して、CLSCRS APIが動作するOracle Clusterwareエンティティを絞り込むことができます。簡易フィルタは、演算子を使用した属性/値ペアです。演算子は、例に示すように空白で囲む必要があります。簡易フィルタは、Boolean演算子を使用した式フィルタと呼ばれる式に組み込むことができます。

サポートされるフィルタの演算子は次のとおりです。

=
>
<
!=
co: 次を含む
st: 次で始まる
en: 次で終わる

サポートされるブール演算子はANDおよびORです。

次にフィルタの例を示します。

TYPE = type1
((TYPE = type1) AND (CHECK_INTERVAL > 50))
(TYPE = type1) AND ((CHECK_INTERVAL > 30) OR (AUTO_START co never))
NAME en network.res
TYPE st ora.db