acfsplugin

目的

acfspluginアプリケーション・プログラミング・インタフェース(API)は、アプリケーション・プラグイン・モジュールのローカル・プラグインが有効なOracle ACFSドライバに対してメッセージを送受信します。

構文

sb8 acfsplugin_metrics(ub4 metric_type,
  ub1 *metrics,
  ub4 metric_buf_len,
  oratext *mountp );

説明

Oracle ACFSプラグインAPIは、Oracle ACFSドライバからメトリックを受信するために、Oracle ACFSアプリケーション・プラグイン・モジュールによって使用されます。acfsutil plugin enableコマンドを使用して、プラグイン通信のためにまずOracle ACFSドライバを有効にする必要があります。選択したアプリケーション・プラグイン・メトリック・タイプ・モデルは、Oracle ACFSのプラグイン有効化コマンドで定義されたプラグイン構成と一致する必要があります。acfsutil plugin enableコマンドの詳細は、「acfsutil plugin enable」を参照してください。アプリケーションには、「Oracle ACFSの事前定義済のメトリック・タイプ」で説明しているメトリック構造を格納するのに十分なバッファのサイズが提供される必要があります。

指定されたバッファがNULLで、metric_buf_len = 0の場合、戻り値は、現在収集されたすべてのメトリックを保持するために必要なサイズになります。アプリケーションは、まずOracle ACFSに問い合せて、必要なバッファの大きさを参照してから、Oracle ACFSに戻すのに必要なサイズのバッファを割り当てることができます。

参照するプラグインが有効なOracle ACFSファイルシステムを特定するには、マウント・パスをAPIに指定する必要があります。

成功すると、負ではない値が戻されます。収集するメトリックがない状態で成功した場合は0、使用可能なメトリックがあることを示す場合は1、間隔の間に収集された新しいメトリックがないことを示す場合は2が戻されます。エラーの場合、負の値が戻され、Linux環境の場合はerrnoが設定され、WindowsではSetLastErrorがコールされます。

プラグインが有効なOracle ACFSファイルシステム・ドライバに対してメッセージを送受信するには、システム管理者またはOracle ASM管理者の権限が必要です。

アプリケーションの書込み

プラグインAPIを使用するには、APIファンクションおよび構造を定義するCヘッダー・ファイルacfslib.hをアプリケーションに含める必要があります。

#include <acfslib.h>

アプリケーションの実行可能ファイルを作成する場合、アプリケーションは、acfs12ライブラリにリンクされている必要があります。定義する必要がある環境変数の詳細は、プラットフォーム固有のドキュメントを参照してください。次に例を示します。

export LD_LIBRARY_PATH=${ORACLE_HOME}/lib:$
{LD_LIBRARY_PATH}

リンクを行う場合、-lacfs12フラグを追加します。

例

例18-1では、コマンドは、プラグイン・サービス用に/humanresourcesにマウントされたOracle ACFSファイルシステムを有効にします。

例18-1 記憶域の可視性のためのアプリケーション・プラグイン: ポーリング・モデル

$ /sbin/acfsutil plugin enable -m acfsmetric1 -t HRDATA /humanresources

このコマンドの場合、アプリケーション・プラグインは、HRDATAでタグ付けされたファイルに関連付けられたサマリー・メトリックの、Oracle ACFSプラグインが有効なドライバをポーリングします。アプリケーション・コードは次のようになります。

#include <acfslib.h>
...
/* allocate message buffers */
ACFS_METRIC1 *metrics = malloc (sizeof(ACFS_METRIC1));
/* poll for metric1 data */
while (condition) {
  /* read next summary message from ACFS driver */
   if ((rc = acfsplugin_metrics(ACFS_METRIC_TYPE1,(ub1*)metrics,sizeof(*metrics),
        mountp)) < 0) {
        perror("….Receive failure … ");
        break;
   }
   /* print message data */
   printf ("reads %8llu ", metrics->acfs_nreads);
   printf("writes %8llu ", metrics->acfs_nwrites);
   printf("avg read size %8u ", metrics->acfs_avgrsize);
   printf("avg write size %8u ", metrics->acfs_avgwsize);
   printf("min read size %8u ", metrics->acfs_minrsize);
   printf("max read size %8u ", metrics->acfs_maxrsize);
   ...
   sleep (timebeforenextpoll);
}

例18-2では、コマンドは、プラグイン・サービス用に/humanresourcesにマウントされたOracle ACFSファイルシステムを有効にします。

例18-2 ファイル・コンテンツのためのアプリケーション・プラグイン: ポスト・モデル

$ /sbin/acfsutil plugin enable -m acfsmetric1 -t HRDATA -i 5m /humanresources

このコマンドの場合、5分ごとに、Oracle ACFSプラグインが有効なドライバは、HRDATAでタグ付けされたファイルに関連付けられたファイル・コンテンツ・メトリックをポストします。アプリケーション・コードでは、メトリックがポストされるまで、acfsplugin_metrics()へのコールはブロックされます。アプリケーション・コードは次のようになります。

#include <acfslib.h>
...
 ACFS_METRIC1 *metrics = malloc (sizeof(ACFS_METRIC1));
 
 /* Wait for metric Data */
  while (condition) {
    /* Wait for next file content posting from ACFS driver */
    rc = ACFS_PLUGIN_MORE_AVAIL;
    /* A return code of 1 indicates that more metrics are available
    * in the current set of metrics.
    */
    while( rc == ACFS_PLUGIN_MORE_AVAIL) {
      /* This call blocks until metrics are available. */
      rc = acfsplugin_metrics(ACFS_METRIC_TYPE1,(ub1*)metrics,sizeof(*metrics),
           mountp);
      if (rc < 0) {
        perror("….Receive failure … ");
        break;
      } else if (rc == ACFS_PLUGIN_NO_NEW_METRICS) {
        printf("No new metrics available.");
        break;
     }
     if (last_seqno != metrics->acfs_seqno-1 ) {
       printf("Warning: Unable to keep up with metrics collection.");
       printf("Missed %d sets of posted metrics.",
              (metrics->acfs_seqno-1)-last_seqno);
     }

      /* print message data */ 
      printf ("reads %8llu ", metrics->acfs_nreads);
      printf("writes %8llu ", metrics->acfs_nwrites);
      printf("avg read size %8u ", metrics->acfs_avgrsize);
      printf("avg write size %8u ", metrics->acfs_avgwsize);
      printf("min read size %8u ", metrics->acfs_minrsize);
      printf("max read size %8u ", metrics->acfs_maxrsize);
      ...
 
      last_seqno = metrics->acfs_seqno;
    }
  }
 
  free(metrics);