日本語PDF
  1. Clusterware管理およびデプロイメント・ガイド
  2. Oracle Clusterware C Application Program Interface

H Oracle Clusterware C Application Program Interface

この付録では、Oracle Clusterware C Application Program Interface(API)について説明します。この付録の内容は次のとおりです。

関連項目:

Oracle Clusterwareを使用したアプリケーションの高可用性の実現の詳細は、「Oracle Clusterwareを使用したアプリケーションの高可用性の実現」を参照してください。

Oracle Clusterwareのプログラミング・インタフェース(C API)について

この章では、Oracle Clusterware (CLSCRS)のプログラミング・インタフェース(C API)の使用について説明します。

概要

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クライアント・インストール・メディアからインストールできます。

操作上のノート

Oracle Clusterwareの構成および操作要件に対するプログラミング・インタフェース(C API)について説明します。

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

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

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では、出力結果は次のように表示されます。

  1. 関数コールの戻り値によって、リクエストの概要が出力されます。サーバーでリクエストが受信されたかどうかが示されます。また、正常に完了したか、完全に失敗したか、または一部で失敗したかどうかも示されます。戻り値が正常であるということは、リクエストの受信および処理が行われ、リクエストされたすべてのエンティティに対する結果が正常であったことを示します。

  2. リクエストが行われたエンティティごとに、op_statusリストにプログラムの完了コードが格納されます。値がsuccessではない場合は、特定のオブジェクトに対するリクエストの処理で高度な問題が発生したことを示します。

  3. 必要に応じて、APIでは、コールバック・メカニズムを使用して、ローカライズされた判読可能なエラー、警告、ステータス・メッセージを受信するように示される場合があります。コールバックが起動されるたびに、コールバックの起動に関するメッセージ、メッセージ・タイプ(重大度)およびオブジェクトIDが表示されます。

たとえば:

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

  1. 関数によって、CLSCRS_STATという値のエラー・コードが戻されます。

  2. CRSDによって、clscrs_msgf2コールバックを介して、エラー・メッセージ、警告メッセージ、進捗メッセージがクライアントに戻されます。クライアントには、CRSDによって戻されるこれらのメッセージを処理するコールバックが実装されている必要があります。

  3. 以前の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

関連項目:

clscrsx.hファイル(Oracle ClusterwareのOracle Clusterware Webページからダウンロード可能)にあるclscrs_comparator enumおよびclscrs_operator enumを使用して、前述のコンパレータおよび演算子に対する正しいタイプをAPIコールでそれぞれ取得します。

フィルタは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のOracle Clusterware Webページからダウンロード可能)を参照してください。

ノート:

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を使用する場合は、次の点を考慮してください。

  1. start、stop、cleanなどの一部のアクションは、リソース・インスタンスでロックされた状態で実行されます。そのため、リソースに対する操作が直接行われるリクエストや、関係性が拡張されることで行われるリクエストをサーバーに発行すると、デッドロックの原因になります。

  2. 通常、読取り専用の発行(clscrs_stat2)は初回のチェックでないかぎり安全で、この場合、デッドロックの原因にもなるため、スクリプト・エージェントではサーバー上でのコールバックは実行しないでください。clsagfwAPIを使用して、チェック・エントリ・ポイントを問い合せます。

関連項目:

スクリプト・エージェントの例は、「Oracle Clusterwareのリソース・リファレンス」を参照してください。

ヘルプ・インタフェース

clscrsx.hファイル(Oracle ClusterwareのOracle Clusterware Webページからダウンロード可能)に、CLSCRS APIの完全なリスト(それぞれの使用方法を含む)、およびcrsapp.cという名前のデモがあります。

非推奨のCLSCRS API

表H-1に非推奨のCLSCRS APIおよびそれに対応するOracle Clusterwareの代替APIを示します。

表H-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

既存の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に指定するために使用できます。このフラグを使用しない場合、通常はこの手順が試行されます。

対話形式CLSCRS API

これらのAPIは、コマンドを実行するために、クラスタ・レディ・サービス・デーモン(CRSD)をコールします。

これらのAPIが機能するには、CRSDが起動され、実行されている必要があります。

表H-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

サーバー・プールを登録解除した場合に発生する事象をシミュレーションします。

非対話形式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を示します。

表H-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_entity_id_create()で作成されたエンティティ識別子に関連付けられたメモリーを解放します。

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

文字列ペア・リスト(splist)に新しい文字列ペア(sp)を追加します。

clscrs_splist_count

文字列ペア・リスト(splist)の文字列ペア(sp)の数をカウントします。

clscrs_splist_create

新しい文字列ペア・リストを作成します。
clscrs_splist_create_and_set

新しい文字列ペア・リスト(splist)を作成し、リストの最初の文字列ペアの名前および値を設定します。

clscrs_splist_delete_sp

文字列ペア・リスト(splist)から文字列ペア(sp)を削除します。

clscrs_splist_destroy

文字列ペア・リスト(splist)のメモリーを解放します。

clscrs_splist_find

文字列ペア・リスト(splist)の文字列ペア(sp)の値を検索します。

clscrs_splist_first

文字列ペア・リスト(splist)の最初の文字列ペア(sp)を取得します。

clscrs_splist_next

文字列ペア・リスト(splist)の現行の次の文字列ペア(sp)を取得します。現行の次の文字列ペアは、実質的に文字列ペア・リストの次の文字列ペアです。リスト・イテレータはAPI内に格納され、公開されません。

clscrs_splist_replace

文字列ペア・リスト(splist)の文字列ペア(sp)の値を置換します。

clscrs_term_crs

Oracle Clusterwareと通信するためにコンテキストを解放します。
clscrs_type_create

新しいリソース・タイプを作成します。
clscrs_type_get_attr

リソース・タイプの属性の値またはプロパティを取得します。
clscrs_type_set_attr

リソース・タイプに属性を追加します。

関連トピック

コマンド評価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によって実行されるアクションと同じです。

例H-4に、コマンド評価APIの使用方法を示します。

例H-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のパラメータを、入力を指定するものと、関数が正常に完了した際に情報を表示するものとに分けて説明します。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INTERNAL_ERROR: 予期しない非ユーザー・エラーが発生した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 正しくない引数が指定された場合に表示されます。

サーバーのカテゴリ化API

Oracle Clusterwareは、clsrcs_entity_server_categoryというエンティティを備えています。

この項では、APIのパラメータを、入力を指定するものと、関数が正常に完了した際に情報を表示するものとに分けて説明します。

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の場合に表示されます。

clscrs_servercategory_destroy

サーバー・カテゴリのメモリを解放します。

構文

clscrs_servercategory_destroy(clscrs_crsentity **sc);

入力

sc_name: メモリーを解放するために破棄するサーバー・カテゴリの名前。

戻り値

clscrsretSUCC: Oracle Clusterwareがリクエストを正常に完了したことを示します。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 入力エンティティ・リストのいずれかのサーバー・カテゴリに属性がない場合に表示されます。

使用上のノート

  • サーバー・カテゴリの属性は、入力サーバー・カテゴリ・リストに含まれます。

  • op_statusリストには、各サーバー・カテゴリの登録操作の結果が含まれ、有効な属性は含まれません。

  • コール元は、in_entitylistを作成して移入する必要があり、op_statusリストを作成する必要があります。これらのリストは両方とも、コール元によって破棄される必要があります。

  • op_statusリストは別のAPIコールで再利用できません。これは、APIコールごとに作成して破棄する必要があります。

  • CLSCRS_FLAG_REG_UPDATEフラグを渡すことで、すでに登録済のサーバー・カテゴリの1つ以上の属性を変更できます。

  • フラグは、入力エンティティ・リストのすべてのサーバー・カテゴリに適用されます。

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をアップグレードする前にAPIを使用した場合に表示されます。

使用上のノート

  • op_statusリストには、各サーバー・カテゴリの登録解除操作の結果が含まれます。

  • コール元は、sclistを作成して移入する必要があり、op_statusリストを作成する必要があります。これらのリストは両方とも、コール元によって破棄される必要があります。

  • op_statusリストは別のAPIコールで再利用できず、APIコールごとに作成して破棄する必要があります。

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: 通信エラーが発生した場合に表示されます。

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をアップグレードする前にAPIを使用した場合に表示されます。
  • CLSCRS_STAT_INVALID_ARGS: 入力エンティティ・リストのいずれかのサーバー・カテゴリに属性がない場合に表示されます。

使用上のノート

  • サーバーの属性は、入力サーバー・リストに含まれます。

  • op_statusリストには、各サーバーの変更操作の結果が含まれますが、有効な属性は含まれません。

  • コール元は、in_entitylistを作成して移入する必要があり、op_statusリストを作成する必要があります。これらのリストは両方とも、コール元によって破棄される必要があります。

  • op_statusリストは別のAPIコールで再利用できず、APIコールごとに作成して破棄する必要があります。

ノート:

現在、Oracleではサポートされているのみであるため、CLSCRS_FLAG_REG_UPDATEフラグは常に渡される必要があります。フラグは、入力エンティティ・リストのすべてのサーバーに適用されます。

(オプション)ここで、APIまたはサブプログラムの使用に関する詳細情報を提供します。

STAT3 API

Oracle Clusterwareでは、リソースやサーバー・プールなどのいくつかのエンティティが管理されます。ただし、clscrs_stat2インタフェースでは、タイプによるエンティティの取得(読取り)のみが許可されます。つまり、1回の取得で1つのタイプのエンティティのみを返すことができます。そのため、異なるタイプのエンティティを取得する必要があったり、さらに決定を下すためにデータ構造の一貫したビューが必要なクライアントは、特殊なイベント順序IDを使用した回避策に頼ることになり、必要に応じて問合せリクエストを複数回にわたって再発行する必要があります。理論上、ソリューションなど、状態/構成が常に変化するシステムは、時間による制限を受けません。

Oracle Clusterware 12c以降のリリースでは、複数の種類のエンティティの一貫した読取りを実行するメカニズムを備えています。このメカニズムはエンティティに対して透過的に機能するため、新しい管理対象エンティティを追加してもメカニズムを変更する必要はありません。

このために使用されるのが、clscrs_stat3 APIです。

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の動作は保証されません。

その他のAPI

この項では、APIのパラメータを、入力を指定するものと、関数が正常に完了した際に情報を表示するものとに分けて説明します。

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のメモリーを割り当てます。

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回のコールで問合せとアクションを実行できます。フィルタによってすべての登録済リソースが検索されます。

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をアップグレードする前にAPIを使用した場合に表示されます。

使用上のノート

  • フラグがasyncの場合、指定したmsgfコールバック関数はコールされません。このAPIでは、Oracle Clusterwareへのコール開始後にOKステータスが返され、非同期に再起動が実行されます。

  • フラグがasync以外で、msgfがNULL以外の場合、APIでは再起動プログラムから収集された出力によってmsgfが一度に1行ずつ処理されます。オプションのeventフラグを渡すことで、これがアクションを実行するリクエストではなく、アクションがすでに開始されていることを通知するものであると示すことができます。このフラグは、共通管理対象リソースの限定的なセットのみに対して使用することをお薦めします。

  • 1つ目の引数には、リソースIDのリストまたはフィルタのいずれかを指定できます。フィルタを指定すると、1回のコールで問合せとアクションを実行できます。フィルタによってすべての登録済リソースが検索されます。

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を取りません。

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を取りません。