インクルード・ファイル

コンポーネント MIB とインターフェイスを目的として記述されたアプリケーション・プログラムには、一定のヘッダ・ファイルをインクルードする必要があります。<fml32.h> は、FML32 型付きバッファのアクセスおよび更新に必要なマクロ、構造体、および関数のインターフェイスを定義します。<fml1632.h> は、汎用 FML インターフェイスのマクロ、構造体、および関数から FML32 バージョンへのマッピングを定義します。このヘッダ・ファイルのインクルードは任意です。<tpadm.h> は、このリファレンス・ページに含まれている FML32 フィールド名を定義します。さらに、任意のコンポーネント MIB 固有ヘッダ・ファイルをインクルードして、そのコンポーネント MIB 固有の FML32 フィールド定義にアクセスできるようにする必要があります。

例:

#include <fml32.h>
#include <tpadm.h>
#include <cmib.h>  /* コンポーネント MIB ヘッダ */

バッファの割り当て

コンポーネント MIB と相互作用するには、FML32 型付きバッファから該当するサービスに要求を送る必要があります。ATMI 関数 tpalloc() は、FMLTYPE32 (<fml32.h> で定義) を使用してバッファを type 引数の値に割り当てます。FML32 バッファにはサブタイプがないため、tpalloc() の subtype 引数は NULL にできます。FML32 バッファのデフォルトの最小サイズは 1024 バイトです。tpalloc() の size 引数に 0 を指定すると、最小サイズのバッファが割り当てられます。より大きなバッファが必要な場合には、システム最小値より大きな値を size に指定して割り当てることができます。

例:

rqbuf = tpalloc(FMLTYPE32, NULL, 0);

MIB 要求の作成

FML32 型付きバッファを割り当てたら、ユーザはそのバッファに汎用 MIBフィールドの値とコンポーネント MIB 固有の値を格納する必要があります。要求バッファへの値の追加に使用する最も一般的なインターフェイスは Fadd32() および Fchg32() です。要求バッファがいっぱいでフィールドを追加できない場合は、ATMI 関数 tprealloc() を使用してバッファを再割り当てする必要があります。

例:

/*
 * エラー処理は含まない。bigger_size はシステム側で提供されるのではなく、
 * ユーザ側で指定。バッファを再利用する場合は、Fchg32 を使用して
 * フィールド・オカレンス 0 に設定する。
 */
if (Fchg32(rqbuf, TA_MIBFIELD, 0, "ABC", 0) == -1) {
  if (Ferror32 == FNOSPACE) {
    rqbuf = tprealloc(rqbuf, bigger_size);
    Fchg32(rqbuf, TA_MIBFIELD, 0, "ABC", 0);
  }
}

MIB 要求の制御

各コンポーネント MIB に固有の属性のほかに、コンポーネント MIB から要求された操作を制御する必須および任意の属性があります。これらの属性はこのリファレンス・ページに定義されています。

必須の汎用属性は TA_OPERATION と TA_CLASS の 2 つです。

TA_OPERATION は、アクセスする MIB 上で実行する操作を指定します。有効な操作は GET、GETNEXT 、および SET です。

TA_CLASS は、アクセスする MIB クラスを指定します。クラス名はコンポーネント MIB のリファレンス・ページで定義されています。TA_OPERATION が GETNEXT の場合には、TA_CURSOR 属性も指定する必要があります。TA_CURSOR は、直前の GET または GETNEXT 操作で返されたフィールドです。このフィールドは、以降の要求時に検索位置を調べるために使用します。

任意属性の TA_OCCURS、TA_FLAGS、TA_FILTER、TA_MIBTIMEOUT、および TA_CURSORHOLD は、要求をさらに細かく指定するときに、必須属性に加えて使用することができます。

例:

/* 最初の 5 オブジェクトを取得 (GET) */
Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "classname", 0);
n = 5;
Fchg32(rqbuf, TA_OCCURS, 0, n, 0);
/* 要求を作成、後述の「MIB 要求の送信」を参照 */
/* 応答は rpbuf に格納。カーソルも含まれる。 */
/*
 * 次の5 オブジェクトを取得 (GETNEXT)。rpbuf から TA_CURSOR を転送。
 * すでに生成した rqbuf を再利用。要求後にスナップショットを破棄 
 * (TA_CURSORHOLD を0 に設定)。
 */
Fchg32(rqbuf, TA_OPERATION, 0, "GETNEXT", 0);
Fchg32(rqbuf, TA_CURSOR, 0, Ffind32(rpbuf, TA_CURSOR, 0, NULL), 0);
n = 0;
Fchg32(rqbuf, TA_CURSORHOLD, 0, n, 0);
/* 要求を作成。後述の「MIB 要求の送信」を参照。 */

コンポーネント MIB フィールド

GET または GETNEXT で指定したコンポーネント MIB キー・フィールドは、オブジェクトの集合を選択する際に使用します。キー・フィールド以外のフィールドは、コンポーネント MIB では無視されます。

SET 操作で指定したコンポーネント MIB キー・フィールドは、更新する特定のオブジェクトを識別するために使用します。キー・フィールド以外のフィールドは、キー・フィールドで指定されたオブジェクトの更新値として処理されます。ユーザは、更新 (SET) が許可される前に、現在のオブジェクト・イメージと一致する必要のあるプレイメージを指定することもできます。ユーザは、要求の TA_FLAGS 属性の MIB_PREIMAGE ビットをセットすることでプレイメージを提供することを示します。更新するオブジェクトを指定するキー・フィールドは、プレイメージ (フィールド・オカレンス0) から取得されます。キー・フィールドがポストイメージにも指定されている場合には、それらのフィールドが正確に一致している必要があります。一致していない場合は要求が失敗します。プレイメージのマッチングで考慮されるのは、クラスの一部であり、かつ入力バッファで指定された 2 つの属性値をもつ属性のみです。1 つの値しかもたない属性は、指定されたクラス・オブジェクト用に設定する新しい値として処理されます。

例:

Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "classname", 0);
Fchg32(rqbuf, TA_MIBKEY, 0, "keyvalue", 0);
n = 1;
Fchg32(rqbuf, TA_OCCURS, 0, n, 0); /* 最初に一致したオカレンスを取得 (GET)。*/
/* 要求を作成。後述の「MIB 要求の送信」を参照。応答は rpbuf に格納。*/
/* rpbuf をプレイメージとして使用し、一致する場合は 
 * TA_MIBFIELD の値を更新。
 */
Fcpy32(newrq, rpbuf);
Fconcat32(newrq, rpbuf);   /* 2 番目に一致したコピーを追加。*/
Fchg32(newrq, TA_OPERATION, 0, "SET", 0);
n = MIB_PREIMAGE;
Fchg32(newrq, TA_FLAGS, 0, n, 0);
Fchg32(newrq, TA_MIBFIELD, 1, "newval", 0); /* ポストイメージ*/
/* 要求を作成。後述の「MIB 要求の送信」を参照。*/

MIB 要求の送信

例:

/* 上記に従って要求を作成。*/
/* 要求を送信し、応答を待機。*/
flags = TPNOTRAN | TPNOCHANGE | TPSIGRSTRT;
rval = tpcall(".TMIB", rqbuf, 0, rpbuf, rplen, flags);
/* 要求を送信し、記述子を取得。*/
flags = TPNOTRAN | TPSIGRSTRT;
cd = tpacall(".TMIB", rqbuf, 0, flags);
/* キューから要求を取り出す。qctl は設定済みと仮定。*/
flags = TPSIGRSTRT;
rval = tpenqueue("queue", ".TMIB", qctl, rqbuf, 0, flags);

MIB 応答の受信

コンポーネント MIB からの応答は、元の要求がどのように生成されたかに応じて 3 通りの方法で受信できます。元の要求が tpcall() で生成された場合、tpcall() が正常に終了すると、応答が受信されたことを示す値を返します。元の要求が tpacall() で生成された場合は、tpgetrply() を使用して応答を受信できます。元の要求が tpenqueue() で生成され、かつキュー制御構造体で応答キューが指定されている場合は、tpdequeue() を使用して応答を受信できます。これらの呼び出しでサポートされているフラグを適宜使用できます。

例:

/* 上記に従って要求を作成。 */
/* 要求を送信し、応答を待機。 */
flags = TPNOTRAN | TPNOCHANGE | TPSIGRSTRT;
rval = tpcall(".TMIB", rqbuf, 0, rpbuf, rplen, flags);
/* 呼び出し記述子を使用して応答を受信。 */
flags = TPNOCHANGE | TPSIGRSTRT;
rval = tpgetrply(cd, rpbuf, rplen, flags);
/* TPGETANY を使用して応答を受信。バッファ・タイプの変更が必要な場合もある。 */
flags = TPGETANY | TPSIGRSTRT;
rval = tpgetrply(rd, rpbuf, rplen, flags);
/* キューから要求を取り出す。qctl は設定済みと仮定。 */
flags = TPNOCHANGE | TPSIGRSTRT;
rval = tpdequeue("queue", "replyq", qctl, rpbuf, rplen, flags);

MIB 応答の解釈

管理要求に対しては、コンポーネント MIB 固有の属性のほかに、特定の汎用 MIB フィールドが返されることがあります。これらの追加属性は、元の要求の結果の特徴を示すもので、必要に応じて後続の要求で使用できる値を提供します。

GET または GETNEXT 操作が正常に終了すると以下の値が返されます。

SET 操作が正常に終了すると以下の値が返されます。

操作が失敗すると、すべてのタイプで以下の値が返されます。

制限事項

フィールドの複数のオカレンスをもつ FML32 バッファでは、オカレンスのシーケンス内に空のフィールドをもつことはできません。たとえば、オカレンス 1 の値をセットし、オカレンス 0 が存在していない場合、FML32 は FML32 定義の NULL 値でオカレンス 0 を自動的に作成します。FML32 定義の NULL 値は、数値フィールドに対しては 0、文字列フィールドに対しては長さゼロの (NULL) 文字列、文字フィールドに対しては文字 '0' になります。このような制約があるため、異なる属性の集合をもつオブジェクトが返されることのある GET 操作では、オブジェクトの状態を正確に反映しない NULL の FML32 フィールドが含まれないよう、ユーザに返されたオブジェクトの集合を人為的に分割することがあります。

DOS、Windows、および OS/2 上のワークステーション・クライアントは、64K の FML32 バッファにリンクされています。このため、戻りバッファのサイズは、バッファあたり 64K に制限されています。

COBOL では FML32 バッファ・タイプが限定的にしかサポートされていないため、COBOL バージョンの ATMI では管理 API にアクセスできません。

汎用 MIB フィールドとコンポーネント MIB のフィールド識別子は 6,000 〜 8,000 の範囲で割り当てられます。したがって、管理アクションとユーザ・アクションの両方を行うアプリケーションでは、フィールド識別子を適切に割り当てる必要があります。

クラスの説明

各クラスの説明セクションには、次の 4 つのサブセクションがあります。

属性表の形式

前述のように、各クラスは 4 つの部分に分けて定義されています。その 1 つが属性表です。属性表はクラス内の属性のリファレンス・ガイドであり、管理者、オペレータ、一般ユーザがそれらの属性を使用してアプリケーションと対話するための方法を説明しています。属性表の各属性の説明には、5 つの構成要素 (名前、タイプ、パーミッション、値、デフォルト) があります。各要素については、以下を参照してください。

TA_STATE の構文

TA_STATE 属性フィールドは、定義された各クラスのメンバです。この属性の意味はクラスごとに定義されています。TA_STATE 値は、多くの場合 3 文字の簡略名で指定できます。TA_STATE 値の完全名を表示する場合は、3 文字の簡略名を大文字で、残りの文字を小文字で示します。TA_STATE 値は、簡略名でも完全名でも入力できます。大文字/小文字は区別されません。TA_STATE 値の出力は常に大文字の完全名です。以下に、TA_STATE 属性の使用例を示します。

完全名  : ACTive 
簡略名  : ACT
出力値 : ACTIVE
有効な入力値 : ACT、act、AcTiVe、active