この項には次のトピックが含まれます:
コンテキストの初期化および永続性
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
関連項目:
APIコールの前述のコンパレータおよび演算子は、$ORA_CRS_HOME/crs/demo/clscrsx.h
ファイルにあるclscrs_comparator enum
およびclscrs_operator enum
を使用して、正しいタイプを取得してください。
フィルタは2種類あり、CLSCRSにはこれらのフィルタを作成するAPIのセットがあります。
比較フィルタ: 2つの値を比較する簡易フィルタ。次に例を示します。
TYPE = ora.db.type
比較フィルタを作成するには、clscrs_compfilter_create
APIを使用します。たとえば、(TYPE = ora.db.type)
比較フィルタは次のように作成します。
clscrs_compfilter_create(ctx, clscrs_TYPE, clscrs_comparator_eq, (const oratext *)"ora.db.type", &myCompFilter);
式フィルタ: 比較フィルタまたは式フィルタ、あるいはその両方の組合せで作成されるフィルタ。次に例を示します。
((TYPE = ora.db.type) AND (CHECK_INTERVAL > 50))
比較フィルタを作成するには、clscrs_expfilter_create
APIを使用します。たとえば、式フィルタは次のように作成します。
clscrs_exprfilter_create(myCompFilter1, clscrs_operator_or, myCompFilter2, &myExprFilter);
関連項目:
clscrs_compfilter_create
およびclscrs_expfilter_create
APIの使用方法については、$ORA_CRS_HOME/crs/demo/clscrsx.h
ファイルを参照してください。
注意:
clscrs_compfilter_create
およびclscrs_expfilter_create
APIによって割り当てられるメモリーは、どちらもclscrs_filter_destroy()
がコールされると解放されます。
エンティティ・リストのかわりに、次の対話形式CLSCRS APIでフィルタを使用できます。
clscrs_start_resource2
clscrs_stat2
clscrs_stop_resource2
clscrs_check_resource2
clscrs_relocate_resource2
例H-3に、対話形式CLSCRS APIでのフィルタの使用を示します。
例H-3 対話形式CLSCRS APIのフィルタ
clscrs_start_resource2(myCompFilter, NULL, env, msgf2, NULL, 0, pOpStatus);
スクリプト・エージェントの使用方法
スクリプト・エージェントのエントリ・ポイントでCLSCRS APIを使用する場合は、次の点を考慮してください。
start、stop、cleanなどの一部のアクションは、リソース・インスタンスでロックされた状態で実行されます。そのため、リソースに対する操作が直接行われるリクエストや、関係性が拡張されることで行われるリクエストをサーバーに発行すると、デッドロックの原因になります。
通常、読取り専用の発行(clscrs_stat2
)は初回のチェックでないかぎり安全で、この場合、デッドロックの原因にもなるため、スクリプト・エージェントではサーバー上でのコールバックは実行しないでください。clsagfw
APIを使用して、チェック・エントリ・ポイントを問い合せます。
関連項目:
スクリプト・エージェントの例は、「Oracle Clusterwareのリソース・リファレンス」を参照してください。
ヘルプ・インタフェース
crsapp.c
と呼ばれるデモと併用することで、$ORA_CRS_HOME/crs/demo/clscrsx.h
ファイルで、それぞれの使用方法を含め、CLSCRS APIのリスト全体を検索できます。