H Oracle Clusterware C Application Program Interfaceエージェント・フレームワーク

Oracle Clusterwareは、リソースとしてOracle Clusterwareに登録されたアプリケーションを管理し、特定のリソースを起動、停止および監視できるアプリケーション独自のプリミティブに対するアクセス権限を持つ必要があります。Oracle Clusterwareでは、リソース固有のすべてのコマンドはエージェントと呼ばれるエンティティを介して実行されます。

エージェントは、リソースを管理するためのエージェント・フレームワークおよびユーザー・コードを含むプログラムです。エージェント・フレームワークは、アプリケーション固有のコードを組み込んで、カスタマイズされたアプリケーションを管理できるCライブラリです。アプリケーションの起動、停止、状態のチェックなど、CまたはC++での実際のアプリケーション管理機能のすべてをエージェントにプログラムします。これらの機能はエントリ・ポイントと呼ばれます。Oracle Clusterwareにかわって、エージェント・フレームワークによりこれらのエントリ・ポイント機能が起動されます。エージェントの開発者は、これらのエントリ・ポイントを使用して、リソースの起動、停止および監視方法に関する、機能を特定のリソースに必要な機能を組み込むことができます。エージェントで複数のリソースを管理できます。

この付録の内容は次のとおりです。

• エージェント・フレームワークのデータ型

• エージェント・フレームワークのコンテキストの初期化および永続性

• CおよびC++エントリ・ポイント機能のプロトタイプ

• CおよびC++エントリ・ポイント・タイプおよびコード

• CおよびC++エントリ・ポイント・ファンクションの戻り値

• マルチスレッドに関する注意事項

• 非推奨となったAPI

• APIリファレンス

• エージェントの例

H.1 エージェント・フレームワークのデータ型

Oracle Clusterwareエージェント・フレームワークは、Oracleが定義したポータブル・データ型を使用して文字列および数字を表します。これらのデータ型を使用することで、複数のプラットフォームでエージェント・プログラムを作成および実行できます。表H-1では、エージェント・フレームワークで使用されるOracleデータ型について説明しています。

表H-1 エージェント・フレームワークで使用されるOracleデータ型

Oracleデータ型	説明
ub4	符号なしの32ビット整数
sb4	符号付き32ビット整数
oratext*	CスタイルのNULLで終了する文字列で、char *に明示的にキャストする必要があります

エージェント・フレームワークAPIによって戻されるclsagfwret型のステータス値は、次のとおりです。

• CLSAGFW_SUCCESS: 関数が正常に完了しました。
• CLSAGFW_FAIL: パラメータ内または関数の実行でエラーがありました。

APIによって戻された文字列値は、現在のコマンド・エントリ・ポイントの範囲のみでアクセスできます。エージェントは戻された文字列値をエージェント独自のバッファにコピーして値を保持できます。

H.2 エージェント・フレームワークのコンテキストの初期化および永続性

エージェント・フレームワークは、clsagfw_init()ファンクション・コールによって初期化されます。維持する必要があるコンテキストはありません。アクション・エントリ・ポイント・ファンクションは、エージェント・フレームワーク・コンテキスト(type clsagfw_aectx)のポインタに渡されます。このコンテキストは、コールされているエントリ・ポイントに固有のもので、エントリ・ポイントの範囲を超えて使用することはできません。その他のエージェント・フレームワークAPIは、このコンテキスト・ポイントをパラメータとみなします。これは、エージェント・フレームワークが維持する不透明なデータ構造ですが、明示的に初期化されたり破壊されることはありません。

H.3 CおよびC++エントリ・ポイント機能のプロトタイプ

エージェントはリソース管理コマンドにエントリ・ポイント・ファンクションを実装し、エージェント・フレームワークにこれらのファンクションを登録します。エージェント・フレームワークは、エントリ・ポイント・ファンクションをコールし、リソース上でコマンドやアクションを実行します。エントリ・ポイント・ファンクションは、次のプロトタイプおよび規則に従う必要があります。

typedef ub4 (*clsagfw_action_entry) (const clsagfw_aectx *aectx)

エントリ・ポイント・ファンクションは、エージェント・フレームワークが維持するコンテキスト・エリアへのポインタを使用してコールされます。このファンクションは、エントリ・ポイントの実行ステータスを示す値を戻します。CHECKエントリ・ポイントの場合、ファンクションはリソースの現在の状態を戻します。

C++を使用してエージェントを作成する場合、extern 'C'キーワードを使用してエントリ・ポイント・ファンクション・プロトタイプを宣言します。

H.4 CおよびC++エントリ・ポイント・タイプおよびコード

現在、エージェント・フレームワークは、リソース管理コマンドおよびリソース上で実行される操作に相当する7つのエントリ・ポイントを定義します。エージェントは、START、STOP、CHECKおよびCLEANコマンドのエントリ・ポイントを登録する必要があります。その他のコマンド・エントリ・ポイントはオプションです。エージェントは、各リソース・タイプおよびコマンドにclsagfw_set_entrypoint() APIをコールすることでエントリ・ポイントを登録します。表H-2では、エントリ・ポイント・タイプおよびそれらに相当する型コードについて説明しています。

表H-2 エントリ・ポイント・タイプ

名前	説明	型コード
START	リソースを起動しオンラインにします	CLSAGFW_ACTION_START
STOP	リソースを停止しオフラインにします	CLSAGFW_ACTION_STOP
CLEAN	リソース上でコマンドが失敗した後にクリーンアップします	CLSAGFW_ACTION_CLEAN
CHECK	リソースの状態を確認します	CLSAGFW_ACTION_CHECK
ABORT	時間切れになった実行中のコマンドを終了します	CLSAGFW_ACTION_ABORT
DELETE	リソースは削除されます	CLSAGFW_ACTION_RES_DELETED
MODIFY	リソースは変更されます	CLSAGFW_RESATTR_MODIFIED
ACTION	リソース上のカスタム・アクションを起動します	CLSAGFW_RES_ACTION

関連項目:

エントリ・ポイントの詳細は、「Oracle Clusterwareリソースおよびエージェント」を参照してください。

H.5 CおよびC++エントリ・ポイント・ファンクションの戻り値

CHECKエントリ・ポイントを除くすべてのエントリ・ポイント・ファンクションは、次の値のいずれかを戻して、エントリ・ポイントの実行状態を示します。

• CLSAGFW_AE_SUCCESS: エントリ・ポイントの実行が正常に完了した場合

• CLSAGFW_AE_FAIL: エントリ・ポイントの実行が失敗した場合

エージェント・フレームワークは、CHECKエントリ・ポイント・ファンクションをコールして、リソースの状態を監視します。このファンクションは、現在のリソースの状態を表す次のいずれかの値を戻します。

• CLSAGFW_ONLINE
• CLSAGFW_UNPLANNED_OFFLINE
• CLSAGFW_PLANNED_OFFLINE
• CLSAGFW_UNKNOWN
• CLSAGFW_PARTIAL
• CLSAGFW_FAILED

関連項目:

リソースの状態の評価およびリターンの詳細は、「Oracle Clusterwareのエージェント」を参照してください。

H.6 マルチスレッドに関する注意事項

Oracle Clusterwareエージェント・フレームワークはマルチスレッド対応に設計されています。また、エージェント・コードは、新しいスレッドを起動して、外部イベント・ソースの監視などのアプリケーション独自の機能を実行できます。エージェント・フレームワークは、一度に1つのエントリ・ポイントのみを実行しますが、リソース上の現在有効なアクションを終了するために起動されるABORTエントリ・ポイントだけは例外です。CおよびC++の開発者は、すべてのエージェント・コードがマルチスレッド環境で正常に動作することを確認する必要があります。グローバル変数および他のリソースへのアクセスを、mutexesなどのロック機構を使用してシリアライズ化する必要があります。エージェントに含まれるCまたはC++の他の外部ライブラリも、マルチスレッド環境で正常に動作する必要があります。

H.7 非推奨となったAPI

表H-3は、非推奨のエージェント・フレームワークAPIおよびそれに対応するOracle Clusterwareの代替APIを説明しています。

表H-3 非推奨のエージェント・フレームワークAPI

非推奨のAPI	代替
clsagfw_exit()	clsagfw_exit2()
clsagfw_send_status()	clsagfw_send_status2()

H.8 APIリファレンス

この項では、次のファンクションについて説明しています。

• clsagfw_add_type()

• clsagfw_check_resource()

• clsagfw_create_attr_iterator()

• clsagfw_delete_cookie()

• clsagfw_exit2()

• clsagfw_get_attr_from_iterator()

• clsagfw_get_attrvalue()

• clsagfw_get_check_type()

• clsagfw_get_cmdid()

• clsagfw_get_cookie()

• clsagfw_get_request_action_name()

• clsagfw_get_resource_id()

• clsagfw_get_resource_name()

• clsagfw_get_retry_count()

• clsagfw_get_type_name()

• clsagfw_init()

• clsagfw_is_cmd_timedout()

• clsagfw_log()

• clsagfw_modify_attribute()

• clsagfw_reset_attr_iterator()

• clsagfw_send_status2()

• clsagfw_set_cookie()

• clsagfw_set_entrypoint()

• clsagfw_set_exitcb()

• clsagfw_set_resource_state_label()

• clsagfw_startup()

H.8.1 clsagfw_add_type()

エージェントが管理するリソース・タイプを登録します。

構文

clsagfwret clsagfw_add_type(const oratext *type_name);

入力

type_name: エージェントが管理するリソース・タイプの名前です。

使用上の注意

起動時に、エージェントは管理するすべてのリソース・タイプを登録する必要があります。1つのエージェントで、複数のリソース・タイプおよび複数のリソースを管理できます。

H.8.2 clsagfw_check_resource()

特定のリソースに対してチェック・アクションを開始します。

構文

void clsagfw_check_resource(const oratext *pResId)

入力

pResId: リソースのID

使用上の注意

エージェントは、エントリ・ポイントまたは他のバックグラウンド・スレッドでこのファンクションを使用して、特定のリソースでチェック・アクションを開始できます。エージェント・フレームワークは、他のスレッドのチェック・アクションをスケジュールして実行します。このファンクションは、CHECKエントリ・ポイントから起動された場合、何の影響も与えません。

H.8.3 clsagfw_create_attr_iterator()

現在のリソースのすべての属性にアクセスするためのイテレータを作成します。

構文

clsagfwret clsagfw_create_attr_iterator(const clsagfw_aectx *pAeCtx,
                                        clsagfw_ai_flags    flags);

入力

• pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

• flags:

  CLSAGFW_ALL_ATTRS: リソースのすべての属性

  CLSAGFW_MODIFIED_ATTRS: 変更された属性のみ

使用上の注意

エージェントはこのファンクションをコールしてイテレータを作成し、リソースのすべての属性にアクセスします。これは、エージェントが異なるタイプの複数のリソースを管理する場合に役立ちます。イテレータは、エージェント・フレームワーク・コンテキストに維持される内部イテレータです。各属性は、clsagfw_get_attr_from_iterator() APIをコールすることで取得されます。変更された属性はMODIFYエントリ・ポイント以外ではアクセスできません。エントリ・ポイントは指定のタイミングでイテレータを1つのみ作成できます。続いてイテレータの作成を試みると、ポインタはいずれの場合も、すでに作成されているイテレータになります。

H.8.4 clsagfw_delete_cookie()

エージェント・フレームワークに格納されているクッキーを削除します。

構文

clsagfwret clsagfw_delete_cookie(const oratext *key);

入力

key: Cookieのキーで、NULLで終了する文字列

使用上の注意

このファンクションは、Cookieを削除し、Cookieおよびその値が使用するすべてのメモリを開放します。

H.8.5 clsagfw_exit2()

リソース再試行フィードバックを使用してエージェント・プロセスを終了します。

構文

void clsagfw_exit2(const oratext *rid, sb4 exitCode, bool retry);

入力

• rid: 回復不能なエラーの発生原因であるリソースのリソースID

• exitCode: プロセス終了コード

• retry: リソースを再試行するオプション

使用上の注意

リソースにエントリ・ポイントを実行すると、エージェントにリカバリ不能なエラーが発生し、現在のプロセスを終了しなくてはならない場合があります。エージェントはこのAPIを使用してエージェント・プロセスを終了し、リカバリ不能なエラーの原因となっているエージェント・フレームワークにフィードバックを提供できます。再試行パラメータをtrueに設定すると、エージェント・プロセスが再起動したときに、リソースの現在のコマンド,が再試行されます。パラメータをfalseに設定すると、現在のリソースのコマンドは再試行されず、リソースの監視は無効になります。このオプションは、特定のリソースが、繰り返し発生するエージェントの失敗の原因である場合に使用できます。失敗する頻度が多い場合、Oracle Clusterwareサーバーは、エージェントが終了して自動的に無効になるリソースの記録を取ります。失敗する頻度が多いために無効化されるリソースを最有効化するには、リクエストを明示的に発行してリソースを起動する必要があります(たとえば、CRSCTLを使用します)。

Oracle Clusterwareサーバーはエージェントを再起動して、エージェントが管理するリソースの監視を続行します。

H.8.6 clsagfw_get_attr_from_iterator()

作成されたイテレータから次の属性名と値を戻します。

構文

clsagfwret clsagfw_get_attr_from_iterator(const clsagfw_aectx *pAeCtx,
                                          const oratext **argName,
                                          const oratext **argValue);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

戻り値

• argname: 属性名

• argValue: 属性値

使用上の注意

このファンクションを使用して、エージェント・フレームワーク・コンテキストにイテレータを作成した後に属性を取得します。このファンクションが値を戻すと、イテレータは次の属性に進みます。APIがCLSAGFW_FAILを戻した場合、取得する属性はリソースにこれ以上ありません。

H.8.7 clsagfw_get_attrvalue()

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

構文

void clsagfw_get_attrvalue(const clsagfw_aectx *pAeCtx,
                           const oratext *pAttrName,
                           const oratext **pAttrValue);

入力

• pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

• pAttrName: 取得する属性の名前

戻り値

pAttrValue: 指定した属性の値

使用上の注意

エージェントはこのAPIを使用して、現在のコマンド・リソースの属性1つの値を取得します。

H.8.8 clsagfw_get_check_type()

現在実行されているチェック・コマンドのタイプを戻します。

構文

clsagfw_checktype
clsagfw_get_check_type(const clsagfw_aectx *pAeCtx);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

使用上の注意

エージェント・フレームワークは、複数の条件でのリソースのCHECKエントリ・ポイントを起動します。このファンクションを使用することで、エージェントは現在のCHECKエントリ・ポイントの正確な条件を識別し、適切なアクションを実行します。

使用可能な条件は次のとおりです。

• CLSAGFW_INITIAL_CHECK: Oracle Clusterwareサーバーを起動または再起動したときに、最初のプローブ・ステージの一部として起動されるエントリ・ポイントを確認します。

• CLSAGFW_CHECK_AFTER_CMD: アクションが実行された後、結果のリソースを確認するために、起動されるエントリ・ポイントを確認して、以前のアクション(起動または停止など)を確認します。

• CLSAGFW_PERIODIC_CHECK: エージェント・フレームワークが定期的に起動するエントリ・ポイントを確認して、リソースの状態を監視します。時間間隔は、リソースのCHECK_INTERVAL属性で指定します。

• CLSAGFW_EXTERNAL_CHECK: CRSCTLなどの外部エンティティからの明示的な確認リクエストを受け取ると、エージェント・フレームワークが起動するエントリ・ポイントを確認します。

• CLSAGFW_CHECKFROM_EP: clsagfw_check_resource() APIをコールして、エージェントが開始するアクションを確認します。

H.8.9 clsagfw_get_cmdid()

エントリ・ポイントが起動されるコマンドのタイプを戻します。

構文

clsagfw_aecode clsagfw_get_cmdid(const clsagfw_aectx *pAeCtx);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

使用上の注意

エージェントは、ABORTエントリ・ポイントでこのAPIをコールして、中断されているリソース・コマンドを判断できます。

H.8.10 clsagfw_get_cookie()

エージェント・フレームワークに格納されているクッキーの値を取得します。

構文

clsagfwret clsagfwret clsagfw_set_cookie(const oratext *key,
                                         const void **value);

入力

key: Cookieのキーで、NULLで終了する文字列

Value: クッキーの値を指すポインタ

H.8.11 clsagfw_get_request_action_name()

リソースで実行されるカスタム・アクションの名前を戻します。

構文

const oratext *
clsagfw_get_request_action_name(const clsagfw_aectx *pAeCtx);

入力

pAeCtx: ユーザーのエントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト

使用上の注意

このファンクションをACTIONエントリ・ポイントでコールすると、リクエスト・アクション・コマンドで指定したアクション名が取得されます。リソースのACTION属性に、リソースに対するアクションのリストを構成します。

H.8.12 clsagfw_get_resource_id()

エントリ・ポイントが実行されているリソースのIDを取得します。

構文

const oratext* clsagfw_get_resource_id(const clsagfw_aectx *pAeCtx);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

使用上の注意

このファンクションは、Oracle Clusterwareが生成するリソースIDを戻します。リソースのパブリックな表示名を取得するには、clsagfw_get_resource_name() APIを使用します。

H.8.13 clsagfw_get_resource_name()

現在のコマンドのリソース名を取得します。

構文

const oratext*
  clsagfw_get_resource_name(const clsagfw_aectx *pAeCtx);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

使用上の注意

このファンクションは、現在のコマンドおよびエントリ・ポイントを実行するリソースの名前を取得します。

H.8.14 clsagfw_get_retry_count()

現在のコマンドの再試行回数を取得します。

構文

ub4 clsagfw_get_retry_count(const clsagfw_aectx *pAeCtx)

入力

pAeCtx: ユーザーのエントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

使用上の注意

エージェントは、エントリ・ポイントでこのファンクションをコールして、現在のコマンドが再試行されているか確認できます。リソースでコマンドを実行している途中に、エージェント・プロセスまたはOracle Clusterwareサーバー・プロセスを終了できます。Oracle Clusterwareは、エージェントまたはサーバー・プロセスが再起動したときに、失敗したコマンドを再試行します。コマンドは、前回の試行で正常に実行された場合と一部しか実行されていない場合があります。エージェントは、Oracle Clusterwareがコマンドを再試行するときに、再開またはクリーンアップ・アクションを実行できます。コマンドを再試行できる回数はOracle Clusterwareの内部パラメータです。

H.8.15 clsagfw_get_type_name()

エントリ・ポイントが実行されているリソースのタイプ名を取得します。

構文

const oratext* clsagfw_get_type_name(const clsagfw_aectx *pAeCtx);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

使用上の注意

このファンクションは、Oracle Clusterwareが生成するリソースIDを戻します。リソースのパブリックな表示名を取得するには、clsagfw_get_resource_name() APIを使用します。

H.8.16 clsagfw_init()

エージェント・フレームワークを初期化します。

構文

clsagfwret clsagfw_init(sb4 argc,
                        oratext **argv,
                        ub4 flags,
                        const oratext *logName,
                        void *reserved);

入力

argc: エージェント処理に渡されたコマンドライン引数の数

argv: エージェント処理に渡されたコマンドライン引数

flags:

logName: 対象エージェントに対するログ・ファイルの名前

reserved: NULLを渡します

使用上の注意

リソースでアクションを実行する必要がある場合、Oracle Clusterwareは、リソースに構成されたエージェントを自動的に起動します。起動時、エージェント・プロセスは最初にこのファンクションをコールして、エージェント・フレームワーク・ランタイムを初期化します。Oracle Clusterwareサーバーによってエージェント・プロセスに渡されるコマンドライン引数は、clsagfw_init()に渡される必要があります。初期化が完了すると、エージェントは、エージェントが管理するリソース・タイプを登録できます。

H.8.17 clsagfw_is_cmd_timedout()

ABORTエントリ・ポイントの原因を戻します。

構文

bool clsagfw_is_cmd_timedout(const clsagfw_aectx *pAeCtx);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

使用上の注意

エージェントは、ABORTエントリ・ポイントでこのファンクションを使用して、ABORTエントリ・ポイントの起動の原因を特定できます。ABORTエントリ・ポイントは、コマンドの実行時間がそのタイムアウト値を超過した場合か、Oracle Clusterwareの管理者がコマンドを中断した場合のいずれかの場合に起動できます。

H.8.18 clsagfw_log()

エージェント・ログ・ファイルの診断メッセージを出力します。

構文

void clsagfw_log(const clsagfw_aectx *pAeCtx,
                const ub4 log_level,
                const oratext *fmtp, ...);

入力

pAeCtx: ユーザーのエントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト

log_level: 1から5までの範囲のメッセージのログ・レベル

fmtp: 標準Cライブラリ・プリント仕様に基づくメッセージ・フォーマット文字列

...: フォーマット文字に対応する変数パラメータ

使用上の注意

エージェントは、このファンクションをコールして、エージェント実行のデバッグや理解に役立つ診断メッセージのログを記録します。LOG_LEVELパラメータを使用して、ログ・メッセージの量を制御できます。CRSCTLを使用して現在のロギング・レベルを次のように構成できます。

$ crsctl set log level res "myResource1=3"

誤用のログは、TODOディレクトリのエージェント・ログ・ファイルに記録されます。デフォルトでは、ログ・ファイルの名前は、エージェント実行ファイル名と同じです。これを変更するには、logNameパラメータをclsagfw_init() APIに渡します。

H.8.19 clsagfw_modify_attribute()

現在のリソースの属性を変更します。

構文

void clsagfw_modify_attribute(const clsagfw_aectx *pAeCtx,
                              const oratext *pAttrName,
                              const oratext *pAttrValue);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

pAttrName: 変更対象の属性の名前

pAttrValue: 属性の新しい値

使用上の注意

エージェントは、APIをコールすると、現在のコマンド・リソースの属性の値を変更できます。リソースの変更リクエストは、検証のためにOracle Clusterwareサーバーに送信され、更新された属性値は、Oracle Clusterwareサーバーが確認するまでエージェントに反映されません。このファンクションのコール元はSTART、STOPおよびCLEANエントリ・ポイントのみです。

H.8.20 clsagfw_reset_attr_iterator()

属性イテレータをリセットします。

構文

clsagfwret clsagfw_reset_attr_iterator(const clsagfw_aectx *pAeCtx,
                                       clsagfw_ai_flags    flags);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

flags: アクセス対象の属性

CLSAGFW_ALL_ATTRS: リソースのすべての属性

CLSAGFW_MODIFIED_ATTRS: 変更された属性のみ

使用上の注意

このファンクションはエージェント・フレームワーク・コンテキストのイテレータをリセットするため、エージェントは属性のナビゲーションを再起動できます。

H.8.21 clsagfw_send_status2()

Oracle Clusterwareサーバーとユーザーに、進捗、警告およびエラー・メッセージをレポートします。

構文

void clsagfw_send_status2(const clsagfw_aectx* pAeCtx,
                          const oratext*       pResId,
                          clsagfw_status_type type,
                          const oratext* fmtp,...);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

pResId: メッセージが報告されているリソース

type: 次に続くメッセージのタイプの内の1つ

CLSAGFW_STATUS_PROGRESS: 進捗メッセージ

CLSAGFW_STATUS_WARNING: 警告メッセージ

CLSAGFW_STATUS_ERROR: エラー・メッセージ

fmtp: メッセージ・フォーマット文字列

...: フォーマット文字列内の位置に対応する変数

使用上の注意

エージェントは、コマンドを実行している間、リソースで操作を実行しているOracle Clusterwareサーバーおよびユーザーに情報メッセージを送信できます。これらのメッセージで、ユーザーに実行の進捗状況および警告やエラーの有無を通知することができます。

H.8.22 clsagfw_set_cookie()

クッキーとその値をエージェント・フレームワークに格納します。

構文

clsagfwret clsagfwret clsagfw_set_cookie(const oratext *key,
                                         const void *value);

入力

key: Cookieのキーで、NULLで終了する文字列

Value: 格納対象のクッキーの値を指すポインタ

使用上の注意

clsagfw_get_cookie()をコールすると、保存されたCookieの値を後で取得できます。

H.8.23 clsagfw_set_entrypoint()

リソースに対する特定のアクションについてC/C++エントリ・ポイント・ファンクションが実行されるように設定します。

構文

void clsagfw_set_entrypoint(const oratext *type_name,
                            clsagfw_action_entry action_entry,
                            clsagfw_aecode action_entrycode)

入力

key: Cookieのキーで、NULLで終了する文字列

Value: 格納対象のクッキーの値を指すポインタ

使用上の注意

clsagfw_get_cookie()をコールすると、保存されたCookieの値を後で取得できます。

H.8.24 clsagfw_set_exitcb()

エージェント・プロセスの終了時に呼び出されるファンクションを登録します。

構文

typedef void (*clsagfw_exit_callback) (sb4 exitCode);
void clsagfw_set_exitcb(clsagfw_exit_callback exit_func)

入力

exit_func: エージェント・プロセスが終了すると起動されるファンクション

使用上の注意

エージェントは、エージェント・フレームワークがエージェント・プロセスを終了すると、コールバック・ファンクションを登録して起動することができます。コールバック・ファンクションは、エージェントがインスタンス化した内部リソースを適切にクリーンアップできます。エージェント・プロセスがリカバリ不能なエラーから修復するために終了する場合、Oracle Clusterwareサーバーは、古いインカネーションが終了するまでエージェントを再起動しません。

H.8.25 clsagfw_set_resource_state_label()

現在のリソースにカスタム・ラベルを設定します。

構文

void clsagfw_set_resource_state_label(const clsagfw_aectx *pAeCtx,
                                      const oratext *pLabel);

入力

pAeCtx: エントリ・ポイントに渡されるエージェント・フレームワーク・コンテキスト・ポインタ

pLabel: リソースに関連付けるラベルで、NULLで終了する文字列

使用上の注意

エージェントはこのファンクションを使用して、リソースの状態に関連付けられた説明ラベルを設定できます。このラベルはリソースのSTATE_DETAILS属性にレポートされます。

H.8.26 clsagfw_startup()

エージェント・フレームワークを起動します。

構文

clsagfwret clsagfw_startup(void)

使用上の注意

エージェント・フレームワークが初期化され、これらのエントリ・ポイントが登録された後、エージェントはこのAPIをコールしてエージェント・フレームワークを起動し、次にこれにより、マルチスレッド・インフラストラクチャが起動され、リソースのアクションが監視および実行されます。

成功すると、このファンクションがコール中のスレッドに戻ることはありません。リソース・アクションのエントリ・ポイントを起動する必要がある場合は、エージェント・フレームワークを使用します。

H.9 エージェントの例

H-1は、ファイルを表すリソースを管理するためのエージェント実装の詳細を説明しています。

例H-1 demoagent1.cpp

/* Copyright (c) 2004, 2012, Oracle and/or its affiliates.
All rights reserved. */

/*
 * NAME
 * Demoagent1.cpp: Demonstrates agent to monitor a file
 *
 * DESCRIPTION
 * This is a sample program that demonstrates an agent to monitor
 * a file. The agent has the following tasks:
 *  - On startup         : Create the file.
 *  - On shutdown        : Delete the file.
 *  - On check command   : Detect whether the file is present or not.
 *  - On clean command   : Delete the file.
 * This program can be used as a basis to build up more complicated
 * agents that manage real-world resources.
 *


#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <clsagfw.h>

エージェント・フレームワークclsagfw.hヘッダー・ファイルを含めます。

#define TEST_TYPE1                   (oratext *) "HOTFILE_TYPE"
#define TEST_PATHNAME_ATTR           (oratext *) "PATH_NAME"


/*
 * NAME
 *    test_agent_exit
 * DESCRIPTION
 *    Function to clean up, called by framework whenever the agent
 *    process is about to terminate
 * PARAMS
 *    exitCode, which is an sb4 describing the reason for exit.
 * RETURNS
 *    void
 */
void
test_agent_exit(sb4 exitCode)
{
  clsagfw_log(NULL, 1, (oratext *)"Demo Agent is exiting..\n");
}

エージェント・フレームワークに登録されているコールバック・ファンクションを終了します。

/*
 * NAME
 *    type1_start
 * DESCRIPTION
 *    Action entry point for the 'start' command. Creates the file for
 *    monitoring.
 * PARAMS
 *    Pointer to the agent framework context
 * RETURNS
 *    ub4 which could be CLSAGFW_AE_FAIL or CLSAGFW_AE_SUCCESS
 *    depending on whether the action failed or succeeded.
 */
ub4
type1_start(const clsagfw_aectx *ectx)
{
    ub4  ret = CLSAGFW_AE_FAIL;
    const oratext   *pResName  = NULL;
    const oratext   *pPathName = NULL;
    FILE *fp;

    clsagfw_log(ectx, 1, (oratext *)"Start action called..");

    /* Try to read the resource name */
    if (clsagfw_get_attrvalue(ectx, (oratext *)"NAME", &pResName) !=
            CLSAGFW_SUCCESS)
    {
      goto done;
    }

    /* Try to read the PATH_NAME attribute */
    if (clsagfw_get_attrvalue(ectx, TEST_PATHNAME_ATTR, &pPathName) !=
            CLSAGFW_SUCCESS)
    {
      goto done;
    }

clsagfw_get_attrvalue()を使用してリソース名およびPATH_NAME属性の名前を取得します。

    clsagfw_log(ectx, 1,
                (oratext *)"Start action arguments: resName = %s,
                pathName = %s", pResName, pPathName);

    /* Try to create the file */
    fp = fopen((char *)pPathName, "w");

    if(!fp)
    {
      /* Could not create the file */
        clsagfw_log(ectx, 1, (oratext *) "START action for resource %s:
                    FAILED\n", pResName);
        ret = CLSAGFW_AE_FAIL;
    }
    else
    {
      /* Created the file successfully */
        clsagfw_log(ectx, 1, (oratext *) "START action for resource %s: 
                    SUCCESS\n", pResName);
        ret = CLSAGFW_AE_SUCCESS;
      fclose(fp);
    }

done:
    return ret;
}

clsagfw_log()をコールすると、診断メッセージおよびエラー・メッセージのログがエージェント・ログ・ファイルに記録されます。

/*
 * NAME
 *    type1_stop
 * DESCRIPTION
 *    Action entry point for the 'stop' and 'clean' commands. Deletes
 *    the file being monitored.
 * PARAMS
 *    Pointer to agent framework context
 * RETURNS
 *    ub4 which could be CLSAGFW_AE_FAIL or CLSAGFW_AE_SUCCESS
 *    depending on whether the action failed or succeeded.
 */
ub4
type1_stop (const clsagfw_aectx *ectx)
{
    ub4             ret = CLSAGFW_AE_FAIL;
    const oratext   *pResName  = NULL;
    const oratext   *pPathName = NULL;

    clsagfw_log(ectx, 1, (oratext *)"Stop action called..");

    /* Try to read the resource name */
    if (clsagfw_get_attrvalue(ectx, (oratext *)"NAME", &pResName) !=
            CLSAGFW_SUCCESS)
    {
      clsagfw_log(ectx, 1, (oratext *)"STOP action: %s: Could not
                  read attribute\n", pResName);
      goto done;
    }

    /* Try to read the PATH_NAME attribute */
    if (clsagfw_get_attrvalue(ectx, TEST_PATHNAME_ATTR, &pPathName) !=
            CLSAGFW_SUCCESS)
    {
        pPathName = pResName;
    }

    clsagfw_log(ectx, 1,
                (oratext *)"Stop action arguments: resName = %s,
                pathName = %s", pResName, pPathName);

    /* Try to delete the file */
    if (remove((char *)pPathName))
    {
      /* Could not delete the file */
      clsagfw_log(ectx, 1, (oratext *)"STOP action for resource %s:
                  FAILED\n", pResName);
      ret = CLSAGFW_AE_FAIL;
    }
    else
    {
      /* Deleted the file successfully */
      clsagfw_log(ectx, 1, (oratext *)"STOP action for resource %s:
                  SUCCESS\n", pResName);
      ret = CLSAGFW_AE_SUCCESS;
    }

done:
    return ret;
}

/*
 * NAME
 *    type1_check
 * DESCRIPTION
 *    Action entry point for the 'check' command. Determines if the
 *    file exists.
 * PARAMS
 *    Pointer to agent framework context.
 * RETURNS
 *    ub4 which gives the status of the resource. Check the
 *    agent framework reference for details on this function's
 *     return codes.
 */
ub4 
type1_check(const clsagfw_aectx *ectx)
{
    ub4             ret = CLSAGFW_UNKNOWN;
    const oratext   *pResName  = NULL;
    const oratext   *pPathName = NULL;
    FILE *fp;

    clsagfw_log(ectx, 1, (oratext *)"Check action called..");

    /* Try to read the resource name */
    if (clsagfw_get_attrvalue(ectx, (oratext *) "NAME", &pResName) !=
            CLSAGFW_SUCCESS)
    {
      goto done;
    }

    /* Try to read the PATH_NAME attribute */
    if (clsagfw_get_attrvalue(ectx, TEST_PATHNAME_ATTR, &pPathName) !=
            CLSAGFW_SUCCESS)
    {
      clsagfw_log(ectx, 1, (oratext *)"CHECK action: %s: Could not
                  read attribute\n", pResName);
      goto done;
    }

    clsagfw_log(ectx, 1,
                (oratext *)"Check action arguments: resName = %s,
                pathName = %s", pResName, pPathName);

    /* Check if the file is accessible */
    fp = fopen((char *)pPathName, "r");
    if (!fp)
    {
      /* Could not open file */
      clsagfw_log(ectx, 1, (oratext *)"CHECK action: %s status –
                  UNPLANNED_OFFLINE\n", pResName);
      ret = CLSAGFW_UNPLANNED_OFFLINE;
    }
    else
    {
      /* Opened file successfully */
      clsagfw_log(ectx, 1,(oratext *)"CHECK action: %s status –
                  ONLINE\n", pResName);
      fclose(fp);
      ret = CLSAGFW_ONLINE;
    }

done:
    return ret;
}

/*
 * Initialization of the agent framework and registration of types is
 *  done in main.
 */
int main(sb4 argc, oratext **argv)
{
    clsagfw_log(NULL, 1, (oratext *)" *** Agent Framework Demo Agent
                Started *** \n");

    /*
     * Initialize the agent framework
     */
    if (clsagfw_init(argc, argv, 0, NULL, 0)
        != CLSAGFW_SUCCESS)
    {
      clsagfw_log(NULL, 1, (oratext *)"Failed to initilize the agent
                  framework\n");
      clsagfw_exit(-1);
    }

    /*
     * Set the exit callback function
     */
    clsagfw_set_exitcb(test_agent_exit);

    /*
     * Add the type definition to the framework
     */ 
    if (clsagfw_add_type(TEST_TYPE1) != CLSAGFW_SUCCESS)
    {
      clsagfw_log(NULL, 1,(oratext *)"Failed in adding type %s to the
                  framework\n", TEST_TYPE1);
      clsagfw_exit(-1);
    }


    /*
     * Set all entry points for for HOTFILE_TYPE
     */
    clsagfw_set_entrypoint(TEST_TYPE1, type1_start,
                           CLSAGFW_ACTION_START);
    clsagfw_set_entrypoint(TEST_TYPE1, type1_stop,
                           CLSAGFW_ACTION_STOP);
    clsagfw_set_entrypoint(TEST_TYPE1, type1_check,
                           CLSAGFW_ACTION_CHECK);
    clsagfw_set_entrypoint(TEST_TYPE1, type1_stop,
                           CLSAGFW_ACTION_CLEAN);

    clsagfw_log(NULL, 1, (oratext *)"Added resource type [%s] to the
                agent framework\n", TEST_TYPE1);

    /*
     * All set to go, Start the framework. This function does not
     * return if the framework starts successfully.
     */
    clsagfw_startup();

    /*** NOT REACHED **/

    return 0;
}