I Oracle Clusterware C Application Program Interface
この付録では、Oracle Clusterware C Application Program Interface(API)について説明します。この付録の内容は次のとおりです。
関連項目:
Oracle Clusterwareを使用したアプリケーションの高可用性の実現の詳細は、「Oracle Clusterwareを使用したアプリケーションの高可用性の実現」を参照してください。
I.1 Oracle Clusterwareのプログラミング・インタフェース(C API)について
I.1.1 概要
CLSCRSは、Oracle ClusterwareのCベースAPIのセットです。CLSCRS APIを使用すると、Oracle Clusterwareによって管理されるエンティティの操作を管理できます。これらのエンティティには、リソース、リソース・タイプおよびサーバー・プールが含まれます。APIを使用してOracle Clusterwareにユーザー・アプリケーションを登録することができるため、クラスタウェアでユーザー・アプリケーションを管理して高可用性を維持できます。アプリケーションが登録されると、そのアプリケーションを管理してステータスを問い合せることができます。アプリケーションが不要になった場合には、そのアプリケーションを停止して、Oracle Clusterwareから登録解除することができます。
Oracle Clusterwareサービスは、Oracle Clusterwareの一部として実行されるクラスタ・レディ・サービスによって提供されます。CLSCRS APIでは、すべての関数コールで明示的に名前が指定されているコンテキストが使用されます。APIでは、処理レベルまたはスレッド・レベルでの格納は行われません。診断ロギングのコールバックを使用できます。
注意:
Oracle Clusterwareの高可用性APIは、Oracle Databaseクライアント・インストール・メディアからインストールできます。
I.1.2 使用上の注意
この項には次のトピックが含まれます:
コンテキストの初期化および永続性
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
: メッセージのタイプ(エラー、警告または進捗)
例I-1に、コールバック・メカニズムの例を示します。
例I-1 コールバック・メカニズム
void myCallback(void *arg, const oratext *pId, const oratext *pMsg,
clscrs_msgtype msgType)
{
if (pMsg != NULL)
{
cout << pMsg << endl;
}
}
例I-2に、対話形式APIでコールバック・メカニズムを使用する方法を示します。
例I-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コールの前述のコンパレータおよび演算子に対する正しいタイプを取得するには、clscrsx.h
ファイル(Oracle Clusterware Webページhttp://www.oracle.com/goto/clusterware
からダウンロード可能)にある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の使用方法の詳細は、clscrsx.h
ファイル(Oracle Clusterware Webページhttp://www.oracle.com/goto/clusterware
からダウンロード可能)を参照してください。
注意:
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
例I-3に、対話形式CLSCRS APIでのフィルタの使用を示します。
例I-3 対話形式CLSCRS APIのフィルタ
clscrs_start_resource2(myCompFilter, NULL, env, msgf2, NULL, 0, pOpStatus);
スクリプト・エージェントの使用方法
スクリプト・エージェントのエントリ・ポイントでCLSCRS APIを使用する場合は、次の点を考慮してください。
-
start、stop、cleanなどの一部のアクションは、リソース・インスタンスでロックされた状態で実行されます。そのため、リソースに対する操作が直接行われるリクエストや、関係性が拡張されることで行われるリクエストをサーバーに発行すると、デッドロックの原因になります。
-
通常、読取り専用の発行(
clscrs_stat2
)は初回のチェックでないかぎり安全で、この場合、デッドロックの原因にもなるため、スクリプト・エージェントではサーバー上でのコールバックは実行しないでください。clsagfw
APIを使用して、チェック・エントリ・ポイントを問い合せます。
関連項目:
スクリプト・エージェントの例は、「Oracle Clusterwareのリソース・リファレンス」を参照してください。
ヘルプ・インタフェース
clscrsx.h
ファイル(Oracle Clusterware Webページhttp://www.oracle.com/goto/clusterware
からダウンロード可能)に、CLSCRS APIの完全なリスト(それぞれの使用方法を含む)、およびcrsapp.c
という名前のデモがあります。
I.1.3 非推奨のCLSCRS API
表I-1に非推奨のCLSCRS APIおよびそれに対応するOracle Clusterwareの代替APIを示します。
表I-1 非推奨のCLSCRS API
非推奨のAPI | 代替 |
---|---|
clscrs_check_resource |
clscrs_check_resource2 |
clscrs_entity |
clscrs_entity_type |
clscrs_fail_resource |
代替なし |
clscrs_msgf |
clscrs_msgf2 |
clscrs_register_resource |
clscrs_register_resource2 |
clscrs_relocate_resource |
clscrs_relocate_resource2 |
clscrs_res_attr_count |
clscrs_crsentity_attr_count |
clscrs_res_create |
clscrs_crsentity_create |
clscrs_res_create |
clscrs_crsentitylist_create |
clscrs_res_destroy |
clscrs_crsentity_destroy |
clscrs_res_get_attr |
clscrs_crsentity_get_attr |
clscrs_res_get_attr_list |
clscrs_crsentity_get_attr_list |
clscrs_res_get_name |
clscrs_crsentity_get_name |
clscrs_res_get_node_list |
clscrs_crsentity_get_node_list |
clscrs_res_get_op_status |
clscrs_crsentity_get_op_status |
clscrs_res_get_reslist |
clscrs_crsentity_get_crsentitylist |
clscrs_res_set_attr |
clscrs_crsentity_set_attr |
clscrs_res_set_attr_list |
clscrs_crsentity_set_attr_list |
clscrs_res_set_reslist |
clscrs_crsentity_set_crsentitylist |
clscrs_reslist_append |
clscrs_crsentitylist_append |
clscrs_reslist_count |
clscrs_crsentitylist_count |
clscrs_reslist_delete_res |
clscrs_crsentitylist_delete_crsentity |
clscrs_reslist_destroy |
clscrs_crsentitylist_destroy |
clscrs_reslist_find |
clscrs_crsentitylist_find |
clscrs_reslist_first |
clscrs_crsentitylist_first |
clscrs_reslist_next |
clscrs_crsentitylist_next |
clscrs_start_resource |
clscrs_start_resource2 |
clscrs_stat |
clscrs_stat2 |
clscrs_stop_resource |
clscrs_stop_resource2 |
clscrs_unregister_resource |
clscrs_unregister_resource2 |
I.1.4 既存のCLSCRS APIの変更点
Oracleによって、clscrs_stat2
APIに次のフラグが追加されています。
-
CLSCRS_STATFLAG_SERVERBYCATEGORY
: 特定のサーバー・カテゴリに一致するサーバーを問い合せるには、このフラグを使用します。 -
CLSCRS_STATFLAG_CATEGORYBYSERVER
: 特定のサーバーに一致するサーバー・カテゴリを問い合せるには、このフラグを使用します。
Oracleによって、clscrs_start_resource2
およびclscrs_stop_resource2
APIに次のフラグが追加されています。
-
CLSCRS_FLAG_T_HA_PREPARE
: リソースを処理する外部管理インタフェースを準備するようにOracle Clusterwareデーモン(CRSD)に指定するには、透過的HA (start2
/stop2
API)でこのフラグを使用します。コールが戻ってきた際、成功の場合は、インタフェースはリソースを起動または停止し、他方のフラグ(CLSCRS_FLAG_T_HA_FINISH
)を使用してコールバックすると想定されます。 -
CLSCRS_FLAG_T_HA_FINISH
: このフラグは、透過的HAでCLSCRS_FLAG_T_HA_PREPARE
とともに使用します。起動または停止アクション終了時のCRSD (start2/stop2 API)への2つ目のコールで、このフラグを使用する必要があります。CRSDはAPIの起動が適用されるインスタンスを認識する必要があるため、クライアントはこのフラグで、リソースではなくリソースのインスタンスを指定する必要があることに注意してください。 -
CLSCRS_NO_STATE_RESTORATION
: このフラグは、リソースAPIを起動および停止するため、および状態が影響を受けたリソースのリソース状態の復元をスキップするようにCRSDに指定するために使用できます。このフラグを使用しない場合、通常はこの手順が試行されます。
I.2 対話形式CLSCRS API
これらのAPIは、コマンドを実行するために、クラスタ・レディ・サービス・デーモン(CRSD)をコールします。
これらのAPIが機能するには、CRSDが起動され、実行されている必要があります。
表I-2 Oracle Clusterwareの対話形式CLSCRS APIのサマリー
C API | 説明 |
---|---|
clscrs_check_resource2 |
指定されたリソースのチェック・エントリ・ポイントを実行するようにOracle Clusterwareに通知します。 |
clscrs_get_server_by_category |
特定のサーバー・カテゴリに一致するサーバーのリストを取得します。 |
clscrs_is_crs_admin |
ユーザーがOracle Clusterware管理者かどうかをチェックします。 |
clscrs_register_resource2 |
入力リソース・リストにリソースを登録します。 |
clscrs_register_servercategory |
入力サーバー・カテゴリ・リストにサーバー・カテゴリを登録します。 |
clscrs_register_serverpool |
サーバーの入力リストに使用するサーバー・プールを登録します。 |
clscrs_register_type |
入力リソース・リストにリソース・タイプを登録します。 |
clscrs_relocate_resource2 |
リソース識別子のリストを再配置します。 |
clscrs_relocate_server |
サーバーのリストを再配置します。 |
clscrs_request_action |
特定のアクション・セットを実行するようにOracle Clusterwareに通知します。 |
clscrs_restart_resource |
名前が指定されたリソース・セットを再起動するようにOracle Clusterwareに指定します。 |
clscrs_start_resource2 |
名前が指定されたリソース・セットを起動するようにOracle Clusterwareに通知します。 |
clscrs_stat2 |
特定のリソースに関する情報を取得します。 |
clscrs_stat3 |
特定のエンティティに関する情報を取得します。 |
clscrs_stop_resource2 |
名前が指定されたリソース・セットを停止するようにOracle Clusterwareに通知します。 |
clscrs_stop_resource_in_pools |
サーバー・プールの特定のリソースを停止するようにOracle Clusterwareに指定します。 |
clscrs_start_resource_in_pools |
サーバー・プールの特定のリソースを起動するようにOracle Clusterwareに指定します。 |
clscrs_unregister_resource2 |
リソース名の入力リストのリソースを登録解除します。 |
clscrs_unregister_servercategory |
入力サーバー・カテゴリ・リストでサーバー・カテゴリを登録解除します。 |
clscrs_unregister_serverpool |
指定されたサーバー・プールを登録解除します。 |
clscrs_unregister_type |
入力リストのリソース・タイプを登録解除します。 |
clscrs_whatif_add_server |
サーバーを追加した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_delete_server |
サーバーを削除した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_fail_resource |
リソースの障害が発生した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_register_resource |
リソースを登録した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_register_serverpool |
サーバー・プールを登録した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_relocate_resource |
リソースを再配置した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_relocate_server |
サーバーを再配置した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_set_activepolicy |
ポリシーをアクティブ化した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_start_resource |
リソースを起動した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_stop_resource |
リソースを停止した場合に発生する事象をシミュレーションします。 |
clscrs_whatif_unregister_serverpool |
サーバー・プールを登録解除した場合に発生する事象をシミュレーションします。 |
I.3 非対話形式CLSCRS API
コンテキストの初期化、対話形式APIのリクエスト・ペイロードの準備、対話形式APIの処理後の出力などの機能には、非対話形式CLSCRS APIを使用できます。非対話形式CLSCRS APIはCRSDをコールしません。
コールバック・エラーのレポート・メカニズムは、非対話形式CLSCRS APIでは使用できません。clscrs_stat2
、clscrs_stat3
、およびすべてのclscrs_whatif_*
APIを除くすべての対話形式CLSCRS APIでは、このコールバック・メカニズムが使用されます。これらのAPIのクライアントは、コールバック・メカニズムを使用して、エラー、警告および進捗メッセージをCRSDから受信します。
フィルタを使用して、Oracle Clusterwareエンティティのリストを減らすこともできます。また、対話形式APIのフィルタを使用して、Oracle Clusterwareエンティティのリストを減らすこともできます。
スレッド・セーフティ
APIデータ構造の管理のために提供されるルーチンは、複数のスレッドの同じAPIコンテキストで同時に使用できませんが、クライアント側でのスレッド・アフィニティは必要ありません。各インスタンスで個別のAPIが使用されている場合は、このプロセスにより、複数のスレッドでこれらのルーチンが起動する可能性があります。
次の表に、非対話形式CLSCRS APIを示します。
表I-3 非対話形式CLSCRS API
C API | 説明 |
---|---|
clscrs_action_getentity |
アクションのエンティティを戻します。 |
clscrs_action_getparams |
アクションのパラメータのリストを戻します。 |
clscrs_action_gettype |
アクションのタイプを戻します。 |
clscrs_actionlist_count |
アクション・リスト内のアクションの数を計算します。 |
clscrs_actionlist_create |
アクション・リストを作成します。 |
clscrs_actionlist_destroy |
アクション・リストを破棄します。 |
clscrs_actionlist_first |
アクション・リスト内の最初のアクションを戻します。 |
clscrs_actionlist_next |
アクション・リスト内の次のアクションを戻します。 |
clscrs_actionlist_print |
アクション・リストを出力します。 |
clscrs_actionlist_seqid |
アクション・リストの順序IDを戻します。 |
clscrs_compfilter_create |
2つの値を比較する簡易フィルタを構成します。 |
clscrs_crsentity_attr_count |
エンティティの属性の数をカウントします。 |
clscrs_crsentity_create |
新しいエンティティを作成します(メモリーを割り当てます)。 |
clscrs_crsentity_destroy |
エンティティを破棄してメモリーを解放します。 |
clscrs_crsentity_get_attr |
エンティティ、サーバー・プール、またはサーバー属性の値を取得します。 |
clscrs_crsentity_get_attr_list |
エンティティ、リソース・タイプ、サーバー・プール、またはサーバーの属性リストを取得します。 |
clscrs_crsentity_get_crsentitylist |
エンティティのエンティティ・リストを取得します。 |
clscrs_crsentity_get_name |
エンティティの名前を取得します。 |
clscrs_crsentity_get_node_list |
現在エンティティをホスティングしているノードのリストを取得します。 |
clscrs_crsentity_get_op_status |
エンティティの操作のステータスを取得します。 |
clscrs_crsentity_get_registered |
エンティティの登録ステータスを取得します。 |
clscrs_crsentity_set_attr |
エンティティおよびサーバー・プールの属性を設定します。 |
clscrs_crsentity_set_attr_list |
エンティティ、リソース・タイプ、サーバー・プール、またはサーバーの属性リストを設定します。 |
clscrs_crsentity_set_crsentitylist |
エンティティのリソース・リストを設定します。 |
clscrs_crsentitylist_append |
エンティティ・リストにエンティティを追加します。 |
clscrs_crsentitylist_count |
エンティティ・リストのエンティティの数をカウントします。 |
clscrs_crsentitylist_create |
エンティティのリストを作成します。 |
clscrs_crsentitylist_delete_crsentity |
特定の名前に一致するエンティティをエンティティ・リストから削除します。 |
clscrs_crsentitylist_destroy |
エンティティ・リストを破棄してメモリーを解放します。 |
clscrs_crsentitylist_find |
特定の名前に一致するエンティティ・リストのエンティティを検索します。 |
clscrs_crsentitylist_first |
エンティティ・リストの最初のエンティティを取得します。 |
clscrs_crslist_next |
エンティティ・リストから現行の次のエンティティを取得します。 |
clscrs_entity_id_create |
リソース、リソース・タイプ、サーバー・グループなどのOracle Clusterwareエンティティを識別するエンティティ識別子を作成します。 |
clscrs_entity_id_destroy |
|
clscrs_exprfilter_create |
比較フィルタまたは式フィルタ(あるいはその両方)で式フィルタを構成します。 |
clscrs_filter_destroy |
フィルタのメモリーを解放します。 |
clscrs_get_entity_type |
指定されたエンティティ識別子に対応するエンティティ・タイプを取得します。 |
clscrs_get_fixed_attrlist |
属性グループ識別子に対応する属性のリストを取得します。 |
clscrs_get_resource_instance_details |
使用されているリソース・インスタンス識別子から、リソース名、カーディナリティ、程度などのリソース・インスタンスの詳細を取得します。 |
clscrs_getnodename |
ノード名を取得します。 |
clscrs_init_crs |
Oracle Clusterwareと通信するためにコンテキストを初期化します。 |
clscrs_sp_get |
文字列ペアの名前要素および値要素を取得します。 |
clscrs_sp_get_value |
文字列ペアの値要素を取得します。 |
clscrs_sp_set |
文字列ペアの値の部分を変更します。 |
clscrs_splist_append |
文字列ペア・リスト( |
clscrs_splist_count |
文字列ペア・リスト( |
clscrs_splist_create |
新しい文字列ペア・リストを作成します。 |
clscrs_splist_create_and_set |
新しい文字列ペア・リスト( |
clscrs_splist_delete_sp |
文字列ペア・リスト( |
clscrs_splist_destroy |
文字列ペア・リスト( |
clscrs_splist_find |
文字列ペア・リスト( |
clscrs_splist_first |
文字列ペア・リスト( |
clscrs_splist_next |
文字列ペア・リスト( |
clscrs_splist_replace |
文字列ペア・リスト( |
clscrs_term_crs |
Oracle Clusterwareと通信するためにコンテキストを解放します。 |
clscrs_type_create |
新しいリソース・タイプを作成します。 |
clscrs_type_get_attr |
リソース・タイプの属性の値またはプロパティを取得します。 |
clscrs_type_set_attr |
リソース・タイプに属性を追加します。 |
関連トピック
I.4 コマンド評価API
コマンド評価APIを使用して、計画済または計画外の仮定上のイベントに対するOracle Clusterwareの反応を予測できます。
Oracle Clusterwareでは、システムでのイベントに応じて、対応アクション計画を生成できます。このアクション計画は、一連のリソース状態の移行またはサーバー・プールの再構成(あるいはその両方)で構成されます。コマンド評価APIは、このアクション計画を外部に公開し、イベントの結果を実際の発生前にクライアントが予測できるようにするメカニズムを備えています。
また、以降の各項に示すAPIにフラグを指定することにより、Oracle Clusterwareがイベントに対するレスポンス・アクション計画を作成するために行った決定の理由を説明する、妥当なコマンド評価情報を取得できます。
コマンド評価レスポンス計画は、次のイベント・カテゴリで使用可能です。
-
リソース: 起動、停止、再配置、追加および変更
-
サーバー・プール: 追加、削除および変更
-
サーバー: 追加、削除および再配置
-
ポリシー: アクティブ・ポリシーの変更
-
サーバー・カテゴリ: 変更
-
サーバー・プール: 追加、削除および変更
-
サーバー: 追加および削除
-
ポリシー: アクティブ・ポリシーの変更
Oracle Clusterwareではコマンド評価の出力がアクションのリストとして提供され、各アクションがOracle Clusterwareによって実行される特定の手順を示します。各アクションはclscrs_action
構造によってカプセル化され、clscrs_actionlist
構造がアクションの順序全体を表します。また、Oracle Clusterwareでは、それらの構造を作成、調査、反復、および破棄するための関数セット(アクション構造用のclscrs_action_*
とアクション・リスト用のclscrs_actionlist_*
)が用意されています。使用方法は、対応するエンティティ・リストおよびエンティティの関数と同じです。
また、コマンド評価APIでは、予想されるシステム状態を問い合せる機能もクライアントに提供されています。clscrs_querylist
構造でstat3
書式を使用して問合せを指定し、clscrs_crsentitylist
構造によって結果が提供されます。使用方法の詳細は、stat3
の項を参照してください。
Oracle Clusterwareによって提供される各コマンド評価レスポンスには、Oracle Clusterwareの現在の状態を示す順序IDが含まれます。順序IDは、Oracle Clusterwareによって管理される新しいイベントごとに増分されます。Oracle Clusterwareでは、順序IDが変更されないかぎり、提供されたアクション計画が対象イベントに対してそのまま実行されることが保証されます。たとえば、whatif start resource FOO
リクエストに対してOracle Clusterwareから提供されるアクション計画は、順序IDが変更されていないかぎり、実際のstart resource FOO
リクエストが送信されたときにOracle Clusterwareによって実行されるアクションと同じです。
例I-4に、コマンド評価APIの使用方法を示します。
例I-4 コマンド評価APIの使用例
boolean tracectx = TRUE;
oratext *resid;
clscrs_ctx *ctx;
clscrs_env env;
clscrs_splist *resid_list;
clscrs_action *cur_actn;
clscrs_actionlist *alist;
clscrs_splist *params;
// Init crs
clscrs_init_crs(&ctx, (clscrs_msgf)clsuslztrace, &tracectx, (ub4)0);
// Init parameters to the call
clscrs_entity_id_create(ctx, "MYRES", clscrs_entity_res, &resid);
clscrs_splist_create(ctx, &resid_list);
clscrs_splist_append(resid_list, resid, NULL);
clscrs_actionlist_create(ctx, &alist);
// Make call into the what-if API
clscrs_whatif_start_resource(resid_list, nodename, flags, NULL, NULL, alist);
// Process the resulting list of actions
for(clscrs_actionlist_first(alist,&cur_actn);cur_actn;clscrs_actionlist_next(alist,&cur_actn))
{
params = clscrs_action_getparams(cur_actn);
switch(clscrs_action_gettype(cur_actn))
{
case clscrs_actiontype_resstate:
// Read params and do something
break;
case clscrs_actiontype_srvmove:
// Read params and do something
break;
case clscrs_actiontype_newgroup:
// Read params and do something
break;
case clscrs_actiontype_errorcase:
// Read params and do something
break;
}
}
clscrs_actionlist_destroy(alist);
clscrs_splist_destroy(resid_list);
clscrs_term_crs(&ctx);
この項では、APIのパラメータを、入力を指定するものと、関数が正常に完了した際に情報を表示するものとに分けて説明します。
I.4.1 clscrs_whatif_set_activepolicy
特定のポリシーをアクティブ化した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_set_activepolicy(const oratext *name, uword flags,
clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: ポリシーの名前。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
CLSCRS_FLAG_WHYIF
: 妥当なコマンド評価情報を表示します。-
CLSCRS_FLAG_FORCE
qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.2 clscrs_whatif_fail_resource
特定のリソースで障害が発生した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_fail_resource(clscrs_splist *name, const oratext *server,
uword flags, clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: リソースID、インスタンスIDまたはフィルタ。server
: リソースの障害が発生するサーバーの名前。NULLが許可されます。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.3 clscrs_whatif_register_resource
特定のリソースを追加または変更した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_register_resource(const oratext *name, clscrs_splist *attrs,
uword flags, clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: リソースの名前。attrs
: 指定されたリソースの属性。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
-
CLSCRS_FLAG_FORCE
-
CLSCRS_FLAG_REG_UPDATE
(リソースを変更する場合) qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.4 clscrs_whatif_relocate_resource
特定のリソースを再配置した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_relocate_resource(clscrs_splist *name, const oratext *destnode,
uword flags, clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: リソースID、インスタンスIDまたはフィルタ。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
-
CLSCRS_FLAG_FORCE
qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.5 clscrs_whatif_start_resource
特定のリソースを起動した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_start_resource(clscrs_splist *name, const oratext *node,
uword flags, clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: リソースID、インスタンスIDまたはフィルタ。node
: リソースを起動するノードの名前。NULLが許可されます。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
-
CLSCRS_FLAG_FORCE
qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.6 clscrs_whatif_stop_resource
特定のリソースを停止した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_stop_resource(clscrs_splist *name, uword flags,
clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: リソースID、インスタンスIDまたはフィルタ。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
-
CLSCRS_FLAG_FORCE
qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.7 clscrs_whatif_register_serverpool
特定のサーバー・プールを登録した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_register_serverpool(const oratext *pname, clscrs_splist *attrs,
uword flags, clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: サーバー・プールの名前。attrs
: 指定されたサーバー・プールの属性。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
CLSCRS_FLAG_WHYIF
: 妥当なコマンド評価情報を表示します。-
CLSCRS_FLAG_FORCE
-
CLSCRS_FLAG_REG_UPDATE
(サーバー・プールを変更する場合) qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.8 clscrs_whatif_unregister_serverpool
特定のサーバー・プールを登録解除した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_unregister_serverpool(const oratext *poolname, uword flags,
clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: サーバー・プールの名前。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
CLSCRS_FLAG_WHYIF
: 妥当なコマンド評価情報を表示します。-
CLSCRS_FLAG_FORCE
qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.9 clscrs_whatif_add_server
サーバーを追加した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_add_server(const oratext *name, clscrs_splist *attrs, uword flags,
clscrs_querylist *qlist, clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: サーバーの名前。attrs
: 指定されたサーバーの属性。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
CLSCRS_FLAG_WHYIF
: 妥当なコマンド評価情報を表示します。-
CLSCRS_FLAG_FORCE
qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.10 clscrs_whatif_delete_server
サーバーを削除した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_delete_server(const oratext *name, uword flags,
clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: サーバーの名前。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
CLSCRS_FLAG_WHYIF
: 妥当なコマンド評価情報を表示します。-
CLSCRS_FLAG_FORCE
qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.4.11 clscrs_whatif_relocate_server
サーバーを異なるサーバー・プールに再配置した場合にOracle Clusterwareが実行するアクションを決定します。
構文
clscrs_whatif_relocate_server(const oratext *name, const oratext *topool,
uword flags, clscrs_querylist *qlist,
clscrs_crsentitylist *status,
clscrs_actionlist *alist);
入力
name
: サーバーの名前。topool
: サーバーの再配置先のサーバー・プールの名前。flags
:CLSCRS_FLAG_NONE
-
CLSCRS_FLAG_WHATIF_VERBOSE
-
CLSCRS_FLAG_FORCE
qlist
: Oracle Clusterwareエンティティ・ステータスのクライアント問合せを指定します。NULLは、問合せを指定しないことを示します。
出力
status
: 戻されるエンティティ情報が含まれるリスト。alist
: Oracle Clusterwareによって実行されるアクションが含まれるアクション・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: Oracle Clusterwareによってリクエストが正常に完了されたこと、またはエンティティがフィルタに一致しなかったことを示します。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INTERNAL_ERROR
: 予期しない非ユーザー・エラーが発生した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 正しくない引数が指定された場合に表示されます。
I.5 サーバーのカテゴリ化API
Oracle Clusterwareは、clsrcs_entity_server_category
というエンティティを備えています。
この項では、APIのパラメータを、入力を指定するものと、関数が正常に完了した際に情報を表示するものとに分けて説明します。
I.5.1 clscrs_servercategory_create
サーバー・カテゴリを作成します。
構文
clscrs_servercategory_create(clscrs_ctx *ctx, const oratext *sc_name,
clscrs_crsentity **sc);
入力
ctx
: CLSCRSコンテキスト。sc_name
: サーバー・カテゴリの名前。
出力
sc
: 新しく作成したサーバー・カテゴリ。
戻り値
clscrsretSUCC
: Oracle Clusterwareがリクエストを正常に完了したことを示します。clscrsretNOMEM
: メモリーを割り当てることができない場合に表示されます。clscrsretBADCTX
: コンテキストがNULLの場合に表示されます。clscrsretBADARG
: サーバー名がNULLの場合に表示されます。
I.5.2 clscrs_servercategory_destroy
サーバー・カテゴリのメモリを解放します。
構文
clscrs_servercategory_destroy(clscrs_crsentity **sc);
入力
sc_name
: メモリーを解放するために破棄するサーバー・カテゴリの名前。
戻り値
clscrsretSUCC
: Oracle Clusterwareがリクエストを正常に完了したことを示します。
I.5.3 clscrs_register_servercategory
指定したサーバー・カテゴリを入力サーバー・カテゴリ・リストに登録します。
構文
clscrs_register_servercategory(clscrs_crsentitylist *in_entitylist, uword flags,
clscrs_msgf2 msgf, void *msgarg,
clscrs_crsentitylist *op_status);
入力
in_entitylist
: 登録するサーバー・カテゴリのリスト。flags
:CLSCRS_FLAG_REG_UPDATE
-
CLSCRS_FLAG_QUEUE
-
CLSCRS_FLAG_FORCE
-
CLSCRS_FLAG_NONE
msgf
: ユーザー・メッセージ・コールバック(NULLにできます)。msgarg
: ユーザー・コールバック引数(NULLにできます)。
出力
op_status
: 各サーバー・カテゴリの登録操作のステータスを保持するエンティティ・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: すべての入力サーバー・カテゴリが正常に登録されていることを示します。CLSCRS_STAT_FAILURE
: 1つ以上のサーバー・カテゴリを登録できない場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 入力エンティティ・リストのいずれかのサーバー・カテゴリに属性がない場合に表示されます。
使用上の注意
-
サーバー・カテゴリの属性は、入力サーバー・カテゴリ・リストに含まれます。
-
op_status
リストには、各サーバー・カテゴリの登録操作の結果が含まれ、有効な属性は含まれません。 -
コール元は、
in_entitylist
を作成して移入する必要があり、op_status
リストを作成する必要があります。これらのリストは両方とも、コール元によって破棄される必要があります。 -
op_status
リストは別のAPIコールで再利用できません。これは、APIコールごとに作成して破棄する必要があります。 -
CLSCRS_FLAG_REG_UPDATE
フラグを渡すことで、すでに登録済のサーバー・カテゴリの1つ以上の属性を変更できます。 -
フラグは、入力エンティティ・リストのすべてのサーバー・カテゴリに適用されます。
I.5.4 clscrs_unregister_servercategory
指定したサーバー・カテゴリを入力リストから登録解除します。
構文
clscrs_unregister_servercategory(clscrs_splist *sclist, uword flags,
clscrs_msgf2 msgf, void *msgarg,
clscrs_crsentitylist *op_status);
入力
sclist
: 登録を解除するサーバー・カテゴリのリスト。flags
: オプション・フラグを指定します。msgf
: ユーザー・メッセージ・コールバック(NULLにできます)。msgarg
: ユーザー・コールバック引数(NULLにできます)。
出力
op_status
: 各サーバー・カテゴリの登録解除操作のステータスを保持するエンティティ・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: すべての入力サーバー・カテゴリが正常に登録されていることを示します。CLSCRS_STAT_FAILURE
: 1つ以上のサーバー・カテゴリを登録解除できない場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。
使用上の注意
-
op_status
リストには、各サーバー・カテゴリの登録解除操作の結果が含まれます。 -
コール元は、
sclist
を作成して移入する必要があり、op_status
リストを作成する必要があります。これらのリストは両方とも、コール元によって破棄される必要があります。 -
op_status
リストは別のAPIコールで再利用できず、APIコールごとに作成して破棄する必要があります。
I.5.5 clscrs_get_server_by_category
特定のサーバー・カテゴリに一致するサーバーのリストを取得します。
構文
clscrs_get_server_by_category(clscrs_splist *in_list,
clscrs_crsentitylist *out_entitylist);
入力
in_list
: サーバー・カテゴリのリストまたはフィルタ。
出力
out_entitylist
: サーバー・カテゴリに一致しているサーバーをリストします。
戻り値
CLSCRS_STAT_SUCCESS
: すべての入力サーバー・カテゴリが正常に登録されていることを示します。CLSCRS_STAT_FAILURE
: 1つ以上のサーバー・カテゴリを登録解除できない場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。
I.5.6 clscrs_register_server
サーバー属性を変更します。
構文
clscrs_register_server(clscrs_crsentitylist *in_entitylist, uword flags,
clscrs_msgf2 msgf, void *msgarg,
clscrs_crsentitylist *op_status);
入力
in_entitylist
: 登録するサーバー・カテゴリのリスト。flags
:CLSCRS_FLAG_QUEUE
-
CLSCRS_FLAG_FORCE
-
CLSCRS_FLAG_REG_UPDATE
-
CLSCRS_FLAG_NONE
msgf
: ユーザー・メッセージ・コールバック(NULLにできます)。msgarg
: ユーザー・コールバック引数(NULLにできます)。
出力
op_status
: 各サーバーの登録操作のステータスを保持するエンティティ・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: すべての入力サーバー・カテゴリが正常に登録されていることを示します。CLSCRS_STAT_FAILURE
: 1つ以上のサーバー・カテゴリを登録できない場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。CLSCRS_STAT_INVALID_ARGS
: 入力エンティティ・リストのいずれかのサーバー・カテゴリに属性がない場合に表示されます。
使用上の注意
-
サーバーの属性は、入力サーバー・リストに含まれます。
-
op_status
リストには、各サーバーの変更操作の結果が含まれますが、有効な属性は含まれません。 -
コール元は、
in_entitylist
を作成して移入する必要があり、op_status
リストを作成する必要があります。これらのリストは両方とも、コール元によって破棄される必要があります。 -
op_status
リストは別のAPIコールで再利用できず、APIコールごとに作成して破棄する必要があります。
注意:
現在、Oracleではサポートされているのみであるため、CLSCRS_FLAG_REG_UPDATE
フラグは常に渡される必要があります。フラグは、入力エンティティ・リストのすべてのサーバーに適用されます。
(オプション)ここで、APIまたはサブプログラムの使用に関する詳細情報を提供します。
I.6 STAT3 API
Oracle Clusterware 11gリリース2 (11.2)では、リソースやサーバー・プールなどのいくつかのエンティティが管理されます。ただし、このリリースのインタフェースでは、タイプによるエンティティの取得(読取り)のみが許可されており、1回の取得で1つのタイプのエンティティ以外を戻すことができませんでした。そのため、異なるタイプのエンティティを取得する必要があったり、さらに決定を下すためにデータ構造の一貫したビューが必要なクライアントは、特殊なイベント順序IDを使用した回避策に頼ることになり、必要に応じて問合せリクエストを複数回にわたって再発行する必要がありました(理論上、状態/構成が変化し続けるシステムでは、このような解決策には無限に時間がかかります)。
Oracle Clusterware 12cは、複数の種類のエンティティの一貫した読取りを実行するメカニズムを備えています。このメカニズムはエンティティに対して透過的に機能するため、新しい管理対象エンティティを追加してもメカニズムを変更する必要はありません。
このために使用されるのが、clscrs_stat3
APIです。
I.6.1 clscrs_stat3
qlist
で特定されたOracle Clusterwareエンティティに関する情報を取得します。
構文
clscrs_stat3(clscrs_querylist *qlist,
uword flags,
clscrs_crsentitylist *out_entitylist);
入力
qlist
: 問合せるOracle Clusterwareエンティティのリスト。
出力
out_entitylist
: 戻されたエンティティ情報を保持するエンティティ・リスト。
戻り値
CLSCRS_STAT_SUCCESS
: APIがOracle Clusterwareに正常に問合せを実行したことを示します。CLSCRS_STAT_FAILURE
: Oracle Clusterwareへの問合せでエラーが発生した場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。
使用上の注意
-
情報は
out_entitylist
に戻されます。問合せは、その後の出力セットが一貫性を持つように実行されます。 -
clscrs_query
オブジェクトを作成し、それらをclscrs_querylist
オブジェクトに追加してから、そのオブジェクトをこの関数に渡します。各エンティティ・タイプに必要な属性は、clscrs_query
オブジェクトに含まれている必要があります。属性リストが空の場合、Oracle Clusterwareによってすべての属性が戻されます。 -
out_entitylist
は空のリストとして作成して渡す必要があります。エンティティのエラーはout_entitylist
に戻されます。 -
出力はネストされたエンティティ・リストとして戻されます。個々の問合せの結果は、
out_entitylist
の各エンティティとして戻されます。個々の問合せの出力は、その特定のエンティティのエンティティ・リストとして戻されます。out_entitylist
に含まれるエンティティのOracle Clusterwareエンティティ・タイプを取得するためにclscrs_crsentity_get_type
をコールすることで、エンティティの結果のタイプを確認できます。たとえば、一方はリソース、もう一方はリソース・タイプに対する2つの問合せがある場合、
out_entitylist
には前述のOracle Clusterwareエンティティ・タイプそれぞれに対して1つずつ、2つのエンティティ・オブジェクトが含まれます。それらの各エンティティ・オブジェクトのエンティティ・リストには、問合せの結果が含まれます。特定のオブジェクトがどのようなタイプのエンティティ・オブジェクトかを判断するには、そのエンティティ・オブジェクトに対してclscrs_crsentity_get_type
関数をコールする必要があります。問合せで0個の一致が戻された場合、そのエンティティ・オブジェクトのエンティティ・リストのサイズはゼロになります。
注意:
Oracleでは、エンティティ・タイプごとに1つのclscrs_query
オブジェクトのみがサポートされています。同じエンティティ・タイプに対して複数のclscrs_query
オブジェクトが作成された場合、Oracleではstat3
APIの動作は保証されません。
I.7 その他のAPI
この項では、APIのパラメータを、入力を指定するものと、関数が正常に完了した際に情報を表示するものとに分けて説明します。
I.7.1 clscrs_get_error_details
他のCLSCRS APIの起動中に何らかの障害が発生した場合に、clsk
例外スタックを戻します。
構文
clscrs_get_error_details(oratext* error_buf, size_t* buf_size);
入力
error_buf
: エラー・スタックが移入されるバッファ。buf_size
:error_buf
のバッファのサイズ。特定のバッファのサイズが必要なものよりも小さい場合、APIによって必要なバッファ・サイズの値が戻されます。
戻り値
clscrsretSUCC
: エラー・スタックが正常に出力されたことを示します。clscrsretEMPTY
: エラー・スタックが空の場合に表示されます。clscrsretBADARG
:error_buf
かbuf_size
のいずれかがNULLの場合に表示されます。clscrsretBUFFSMALL
: 指定したバッファ・サイズが必要なサイズよりも小さい場合に表示されます。
使用上の注意
コール元がerror_buf
のメモリーを割り当てます。
I.7.2 clscrs_request_action
名前が指定されたリソース・セットに対してアクションを実行するようにOracle Clusterwareに指定します。
構文
clscrs_request_action(oratext *action_name, clscrs_splist *ridlist,
clscrs_env env, clscrs_msgf2 msgf,
void *msgarg, uword flag, clscrs_reslist *op_status);
入力
action_name
: 実行されるアクションの名前。ridlist
: 停止するリソースまたはリソース・インスタンスのIDのリスト、あるいはフィルタ。env
: 停止操作に環境引数を指定します。msgf
: ユーザー・メッセージ・コールバック(NULLにできます)。msgarg
: ユーザー・コールバック引数(NULLにできます)。flag
:async
またはqueue
オプションのいずれか。
出力
op_status
: 各リソースのアクション操作のステータスを保持するリソース・リスト。
戻り値
CLSCRS_STAT_INVALID_RESNAME
:ridlist
が空の場合に表示されます。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_SUCCESS
: リクエストしたすべてのエンティティに対してリクエストが正常に完了した場合またはフィルタに一致するエンティティがない場合に表示されます。CLSCRS_STAT_FAILURE
: 1つ以上のリソースまたはリソースIDが正常に停止しない場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。
使用上の注意
-
1つ目の引数には、リソースIDのリストまたはフィルタのいずれかを指定できます。
-
フィルタを指定すると、1回のコールで問合せとアクションを実行できます。フィルタによってすべての登録済リソースが検索されます。
I.7.3 clscrs_restart_resource
名前が指定されたリソース・セットを再起動するようにOracle Clusterwareに指定します。
構文
clscrs_restart_resource(clscrs_splist *ridlist,
clscrs_env env, clscrs_msgf2 msgf, void *msgarg,
uword flag, clscrs_reslist *op_status);
入力
ridlist
: 再起動するリソースまたはリソース・インスタンスのIDのリスト、あるいはフィルタ。env
: 再起動操作に環境引数を指定します。msgf
: ユーザー・メッセージ・コールバック(NULLにできます)。msgarg
: ユーザー・コールバック引数(NULLにできます)。flag
:async
、force
またはevent
オプションのいずれか。
出力
op_status
: 各リソースの再起動操作のステータスを保持するリソース・リスト。
戻り値
CLSCRS_STAT_INVALID_RESNAME
:ridlist
が空の場合に表示されます。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_SUCCESS
: リクエストしたすべてのエンティティに対してリクエストが正常に完了した場合またはフィルタに一致するエンティティがない場合に表示されます。CLSCRS_STAT_FAILURE
: 1つ以上のリソースまたはリソースIDが正常に起動しない場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。CLSCRS_STAT_WRONG_ACTIVE_VERSION
: クラスタをOracle Clusterware 12cにアップグレードする前にAPIを使用した場合に表示されます。
使用上の注意
-
フラグが
async
の場合、指定したmsgf
コールバック関数はコールされません。このAPIでは、Oracle Clusterwareへのコール開始後にOK
ステータスが戻され、非同期に再起動が実行されます。 -
フラグが
async
以外で、msgf
がNULL以外の場合、APIでは再起動プログラムから収集された出力によってmsgf
が一度に1行ずつ処理されます。オプションのevent
フラグを渡すことで、これがアクションを実行するリクエストではなく、アクションがすでに開始されていることを通知するものであると示すことができます。このフラグは、共通管理対象リソースの限定的なセットのみに対して使用することをお薦めします。 -
1つ目の引数には、リソースIDのリストまたはフィルタのいずれかを指定できます。フィルタを指定すると、1回のコールで問合せとアクションを実行できます。フィルタによってすべての登録済リソースが検索されます。
I.7.4 clscrs_start_resource_in_pools
サーバー・プール内の名前が指定されたリソース・セットを起動するようにOracle Clusterwareに指定します。
構文
clscrs_start_resource_in_pools(clscrs_splist *ridlist,clscrs_splist *spoollist,
clscrs_env env,clscrs_msgf2 msgf2, void *msgarg,
uword flags, clscrs_reslist *op_status);
入力
ridlist
: 起動するリソースまたはリソース・インスタンスのIDのリスト、あるいはフィルタ。spoollist
: 起動するリソースが実行されているサーバー・プール名のリスト、またはフィルタ。env
: 起動操作に環境引数を指定します。msgf
: ユーザー・メッセージ・コールバック(NULLにできます)。msgarg
: ユーザー・コールバック引数(NULLにできます)。flag
:async
、force
またはevent
オプションのいずれか。
出力
op_status
: 各リソースの起動操作のステータスを保持するリソース・リスト。
戻り値
CLSCRS_STAT_INVALID_RESNAME
:ridlist
が空の場合に表示されます。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_SUCCESS
: リクエストしたすべてのエンティティに対してリクエストが正常に完了した場合またはフィルタに一致するエンティティがない場合に表示されます。CLSCRS_STAT_FAILURE
: 1つ以上のリソースまたはリソースIDが正常に起動しない場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。
使用上の注意
-
clscrs_start_resource2
と似た機能ですが、この関数は追加の引数spoollist
(サーバー・プールのリストが生成される基になるサーバー・プール名のリストまたはフィルタ)を取る点が異なります。 -
この関数は、引数として
node
を取りません。
I.7.5 clscrs_stop_resource_in_pools
サーバー・プール内の名前が指定されたリソース・セットを停止するようにOracle Clusterwareに指定します。
構文
clscrs_stop_resource_in_pools(clscrs_splist *ridlist,clscrs_splist *spoollist,
clscrs_env env,clscrs_msgf2 msgf2, void *msgarg,
uword flags, clscrs_reslist *op_status);
入力
ridlist
: 停止するリソースまたはリソース・インスタンスのIDのリスト、あるいはフィルタ。spoollist
: 停止するリソースが実行されているサーバー・プール名のリスト、またはフィルタ。env
: 停止操作に環境引数を指定します。msgf
: ユーザー・メッセージ・コールバック(NULLにできます)。msgarg
: ユーザー・コールバック引数(NULLにできます)。flag
:async
、force
またはevent
オプションのいずれか。
出力
op_status
: 各リソースの停止操作のステータスを保持するリソース・リスト。
戻り値
CLSCRS_STAT_INVALID_RESNAME
:ridlist
が空の場合に表示されます。CLSCRS_STAT_AUTHORIZATION_FAILURE
: 認可が失敗した場合に表示されます。CLSCRS_STAT_SUCCESS
: リクエストしたすべてのエンティティに対してリクエストが正常に完了した場合またはフィルタに一致するエンティティがない場合に表示されます。CLSCRS_STAT_FAILURE
: 1つ以上のリソースまたはリソースIDが正常に停止しない場合に表示されます。CLSCRS_STAT_CONNECTION
: 通信エラーが発生した場合に表示されます。
使用上の注意
-
clscrs_stop_resource2
と似た機能ですが、この関数は追加の引数spoollist
(サーバー・プールのリストが生成される基になるサーバー・プール名のリストまたはフィルタ)を取る点が異なります。 -
この関数は、引数として
node
を取りません。