プライマリ・コンテンツに移動
Oracle® Clusterware管理およびデプロイメント・ガイド
11gリリース2 (11.2)
B56289-08
  目次へ移動
目次		 索引へ移動
索引
前
前 		 次
次		  

F Oracle Clusterware C Application Program Interface

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


関連項目:

Oracle Clusterwareを使用したアプリケーションの高可用性の実現の詳細は、第6章「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クライアント・インストール・メディアからインストールできます。

使用上の注意

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

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

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_res: リソース・インスタンス(res)はOracle Clusterwareエンティティを示し、このエンティティには、名前、およびOracle Clusterwareエンティティが使用されるコンテキストに適した追加データが含まれます。リソース・インスタンスには、Oracle Clusterwareエンティティの属性データが含まれる場合もあれば、操作に関するステータスおよび戻りメッセージが示される場合もあります。シングル・リソース・インスタンスは、1つのclscrs_reslistのみのメンバーの場合もあります。

  • clscrs_reslist: リソース・リスト(reslist)は、clscrs_resの0(ゼロ)個以上のインスタンスが含まれるデータ構造です。APIで、リソースをリソース・リストに追加したり、リストから削除すること、またはリソースを繰り返し適用することができます。

メモリー管理

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

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

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

clscrs_sp_create()
clscrs_res_create()
clscrs_serverpool_create()
clscrs_type_create()
clscrs_splist_create()
clscrs_reslist_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_reslist *in_reslist, uword flags,
                                       clscrs_msgf2 msgf, void *msgarg,
                                       clscrs_reslist *op_status);

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

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

  3. 以前のOracle Clusterwareリリースでは、APIに、op_statusリストの一部としてOracle Clusterwareエンティティの各操作の結果も含まれていました。次のAPIを使用してその情報にアクセスできます。

    clscrsret clscrs_res_get_op_status(clscrs_res *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: メッセージのタイプ(エラー、警告または進捗)

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

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

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

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

例F-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

例F-3に、対話形式CLSCRS APIでのフィルタの使用を示します。

例F-3 対話形式CLSCRS APIのフィルタ

clscrs_start_resource2(myCompFilter, NULL,
                       env, msgf2, NULL,
                       0, pOpStatus);

スクリプト・エージェントの使用方法

スクリプト・エージェントのエントリ・ポイントでCLSCRS APIを使用する場合は、次の点を考慮してください。

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

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


関連項目:

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

ヘルプ・インタフェース

crsapp.cと呼ばれるデモと併用することで、$ORA_CRS_HOME/crs/demo/clscrsx.hファイルで、それぞれの使用方法を含め、CLSCRS APIのリスト全体を検索できます。

非推奨のCLSCRS API

表F-1に非推奨のCLSCRS APIおよびそれに対応するOracle Clusterware 11gリリース2(11.2)の新しいAPIを示します。

表F-1 非推奨のCLSCRS API

非推奨コマンド 代替 
clscrs_register_resource

clscrs_register_resource2

clscrs_start_resource

clscrs_start_resource2

clscrs_stat

clscrs_stat2

clscrs_stop_resource

clscrs_stop_resource2

clscrs_check_resource

clscrs_check_resource2

clscrs_relocate_resource

clscrs_relocate_resource2

clscrs_unregister_resource

clscrs_unregister_resource2

clscrs_msgf

clscrs_msgf2

clscrs_fail_resource

代替はありません。

対話形式CLSCRS API

表F-2に示すAPIは、コマンドを実行するために、クラスタ・レディ・サービス・デーモン(crsd)のコールを作成します。これらのAPIが機能するには、crsdが起動され、実行されている必要があります。

表F-2 Oracle Clusterwareの対話形式CLSCRS APIのサマリー

C API 説明 
clscrs_register_type

入力リソース・リストにリソース・タイプを登録します。

 
clscrs_register_serverpool

サーバーの入力リストに使用するサーバー・プールを登録します。

 
clscrs_register_resource2

入力リソース・リストにリソースを登録します。

 
clscrs_start_resource2

名前が指定されたリソース・セットを起動するようにOracle Clusterwareに通知します。

 
clscrs_stat2

rqlistに指定されたエンティティに関する情報を取得します。

 
clscrs_stop_resource2

名前が指定されたリソース・セットを停止するようにOracle Clusterwareに通知します。

 
clscrs_check_resource2

指定されたリソースのチェック・エントリ・ポイントを実行するようにOracle Clusterwareに通知します。

 
clscrs_relocate_resource2

リソース識別子のリストを再配置します。

 
clscrs_unregister_resource2

リソース名の入力リストのリソースを登録解除します。

 
clscrs_unregister_type

入力リストのリソース・タイプを登録解除します。

 
clscrs_unregister_serverpool

指定されたサーバー・プールを登録解除します。

 
clscrs_relocate_server

サーバーのリストを再配置します。

非対話形式CLSCRS API

コンテキストの初期化、対話形式APIのリクエスト・ペイロードの準備、対話形式APIの処理後の出力などの機能には、非対話形式CLSCRS APIを使用できます。非対話形式CLSCRS APIはcrsdをコールしません。

コールバック・エラーのレポート・メカニズムは、非対話形式CLSCRS APIでは使用できません。clscrs_stat2を除くすべての対話形式CLSCRS APIでは、このコールバック・メカニズムが使用されます。これらのAPIのクライアントは、コールバック・メカニズムを使用して、エラー、警告および進捗メッセージをcrsdから受信します。

フィルタを使用して、CRSエンティティのリストを減らすこともできます。また、対話形式APIのフィルタを使用して、CRSエンティティのリストを減らすこともできます。

スレッド・セーフティ

APIデータ構造の管理のために提供されるルーチンは、複数のスレッドの同じAPIコンテキストで同時に使用できませんが、クライアント側でのスレッド・アフィニティは必要ありません。各インスタンスで個別のAPIが使用されている場合は、このプロセスにより、複数のスレッドでこれらのルーチンが起動する可能性があります。


関連項目:

詳細は、「エラーの処理およびトレース」、「コールバック・メカニズム」および「フィルタ」を参照してください。

表F-3に、非対話形式CLSCRS APIを示します。

表F-3 非対話形式CLSCRS API

C API 説明 
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_is_crs_admin

ユーザーがOracle Clusterware管理者かどうかをチェックします。

 
clscrs_res_attr_count

リソースの属性数を取得します。

 
clscrs_res_create

新しいリソースを作成します。

 
clscrs_res_destroy

リソースのメモリーを解放します。

 
clscrs_res_get_attr

リソースのリソース属性を取得します。

 
clscrs_res_get_attr_list

リソースの属性リストを取得します。

 
clscrs_res_get_name

リソース名を取得します。

 
clscrs_res_get_op_status

エンティティの操作のステータスを取得します。

 
clscrs_res_get_registered

リソースの登録ステータスを取得します。

 
clscrs_res_get_reslist

リソースのリソース・リストを取得します。

 
clscrs_res_set_attr_list

リソースの属性リストを設定します。

 
clscrs_res_set_reslist

リソースのリソース・リストを設定します。

 
clscrs_reslist_append

リソース・リストにリソースを追加します。

 
clscrs_reslist_count

リソース・リストのリソースの数をカウントします。

 
clscrs_reslist_create

新しいリソース・リストを作成します。

 
clscrs_reslist_delete_res

リソース・リストのリソースを削除します。

 
clscrs_reslist_destroy

リソース・リストのメモリーを解放します。

 
clscrs_reslist_find

リソース・リストのリソースを検索します。

 
clscrs_reslist_first

リソース・リストの最初のリソースを取得します。

 
clscrs_reslist_next

リソース・リストから現行の次のリソースを取得します。

 
clscrs_sp_get

文字列ペアの名前要素および値要素を取得します。

 
clscrs_sp_set

文字列ペアの値の部分を変更します。

 
clscrs_splist_append

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

 
clscrs_splist_create

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

 
clscrs_splist_delete_sp

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

 
clscrs_splist_first

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

 
clscrs_splist_replace

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

 
clscrs_term_crs

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

 
clscrs_type_create

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

 
clscrs_type_get_attr

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

 
clscrs_type_set_attr

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

 
clscrs_compfilter_create

2つの値を比較する簡易フィルタを構成します。

 
clscrs_entity_id_create

リソース、リソース・タイプ、サーバー・グループなどのCRSエンティティを識別するエンティティ識別子を作成します。

 
clscrs_register_serverpool

サーバーの入力リストに使用するサーバー・プールを登録します。

 
clscrs_register_type

入力リソース・リストにリソース・タイプを登録します。

 
clscrs_relocate_server

サーバーのリストを再配置します。

 
clscrs_res_get_node_list

リソースを現在ホスティングしているノード・リストを取得します。

 
clscrs_res_set_attr

リソースのリソース属性を設定します。

 
clscrs_sp_get_value

文字列ペアの値要素を取得します。

 
clscrs_splist_count

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

 
clscrs_splist_create_and_set

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

 
clscrs_splist_destroy

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

 
clscrs_splist_find

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

 
clscrs_splist_next

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

 
clscrs_stat2

rqlistに指定されたエンティティに関する情報を取得します。

  前
前 		 次
次
  目次へ移動
目次		 索引へ移動
索引