4.36 Mp_ReadMsg（）関数

Systemwalker Centric Manager API・スクリプトガイド - UNIX/Windows(R)共通 -

目次索引

第2部 API

> 第4章 APIリファレンス

4.36 Mp_ReadMsg（）関数

■機能説明

【Windows版】

Mp_OpenMsg（）関数発行後、Mp_ReadMsg（）関数とMp_GetMsgMap（）関数を組み合わせて発行することにより、メッセージを1メッセージずつ読み出します。

Mp_OpenMsg（）関数直後のMp_ReadMsg（）には、すでに起動しているシステムのエージェント起動メッセージ（msgtype=OP_APIMGTYPESTAT）が、起動しているシステムの数だけ通知されます。

Mp_ReadMsg（）関数は、システム監視エージェントサービスに対して、メッセージの受信を要求し、すぐに呼び出し元に戻ります。

【UNIX版】

Mp_OpenMsg（）関数発行後、Mp_ReadMsg（）関数を発行することで、監視イベントを1イベントずつ獲得します。

■呼び出し形式

【Windows版】

  
#include <mp_opagt_api.h>
BOOL Mp_ReadMsg(fp, olr , buf);

HANDLE fp;       /* Mp_OpenMsg()で獲得したハンドルを指定する */
OVERLAPPED *olr; /* メッセージ受信の非同期I/Oで使用する      */
                 /* OVERLAPPED構造体のアドレス               */
char   *buf;     /* 受信データのヘッダ部分だけを格納する領   */
                 /* 域のアドレス                             */

【UNIX版】

   
#include <mp_opagt_api.h>
int Mp_ReadMsg(fp, hostx_flg, level, time1, node, NodeID, DatabaseID,
time2, category, msgtext, blkno, msgtype, ostype, submsgnum, voicenum,
msgcolor, backcolor, domtype, domnum, replyid, systype, ext);

int    fp;                /* Mp_OpenMsg()で獲得したファイル記*/
                          /* 述子                            */
unsigned char *hostx_flg; /* 強制表示フラグの格納領域のアドレ*/
                          /* スを指定する                    */
short *level;             /* メッセージの重要度のアドレスを指*/
                          /* 定する                          */
time_t *time1;            /* メッセージが自システムに通知され*/
                          /* た日時格納領域のアドレス        */
char *node;               /* メッセージが出力されたシステム名*/
                          /* 格納領域のアドレス              */
unsigned long *NodeID;    /* リザーブ領域                    */
unsigned long *DatabaseID;/* リザーブ領域                    */
time_t *time2;            /* メッセージが出力された日時格納領*/
                          /* 域のアドレス                    */
char *category;           /* メッセージの種別格納領域のアドレ*/
                          /* ス                              */
char *msgtext;            /* メッセージ格納領域のアドレス    */
unsigned short *blkno;    /* メッセージのブロック番号格納領域*/
                          /* のアドレス                      */
unsigned short *msgtype;  /* メッセージ種別格納領域のアドレス*/
unsigned short *ostype;   /* OS種別格納領域のアドレス        */
unsigned short *submsgnum;/* 補助説明文番号格納領域のアドレス*/
unsigned short *voicenum; /* 音声番号が格納される            */
unsigned char *msgcolor;  /* 文字色が格納される              */
unsigned char *backcolor; /* 背景色が格納される              */
unsigned short *domtype;  /* DOM種別が格納される             */
long *domnum;             /* DOM番号が格納される             */
char *replyid;            /* 返答記述子が格納される          */
unsigned char *systype;   /* 系区別が格納される              */
EXTENDDATA *ext;          /* 拡張データ格納領域のアドレス    */

■パラメタ

【Windows版】

fp:: Mp_OpenMsg（）で獲得したハンドルを指定します。
olr:: メッセージ受信の非同期I/Oで使用するOVERLAPPED構造体のアドレスを指定します。
buf:: 受信データのヘッダ部分だけを格納する領域アドレスを指定します。12バイト分呼び出し元で準備します。

【UNIX版】

fp:

Mp_OpenMsg（）で獲得したファイル記述子を指定します。

hostxflg:

リザーブ領域。
charの領域を確保し、そのアドレスを指定してください。

level:

発生したメッセージの重要度レベルが格納されます。

MPOP_RE_SPEMG :: 最重要
MPOP_RE_EMG :: 重要
MPOP_RE_WARN :: 警告
MPOP_RE_NOTICE: 通知
MPOP_RE_MSG :: 一般
なお、メッセージ種別(msgtype)が、OP_APIMSGTYPESTAT,OP_APIMSGTYPESTOP,OP_APIMSGTYPECHNGのときは、必ずMPOP_RE_MSGが格納されます。

time1:

メッセージがメッセージログに格納された日時が格納されます。Mp_OpenMsg（）直後に通知されるシステム監視エージェント起動メッセージの場合は、システム監視エージェントがMp_ReadMsg（）に通知した日時が格納されます。

日時が正しく獲得できなかったときは、以下の値が設定されています。

日付、時刻とも獲得できない場合:

0x00FFFFFF

日付だけ獲得できない場合:

0x00hhmmss

hh: 時（0x00 ～0x17）

mm: 分（0x00 ～0x3B）

ss: 秒（0x00 ～0x3B）

node:

メッセージが発生したシステムのホスト名が格納されます。
MPOP_NODENAMELENバイト分呼び出し元で準備します。

NodeID:

リザーブ領域。

DatabaseID:

リザーブ領域。

time2:

nodeで示されたシステムで、メッセージが出力された日時が格納されます。Mp_OpenMsg（）直後に通知されるシステム監視エージェント起動メッセージの場合は、システム監視エージェントがMp_ReadMsg（）に通知した日時が格納されます。

日時が正しく獲得できなかったときは、time1と同様の設定となります。

category:

発生したメッセージの監視イベント種別が格納されます。
MPOP_CATEGORYLENバイト分呼び出し元で準備します。

msgtext:

発生したメッセージテキストが格納されます。
2048バイト分呼び出し元で準備します。
メッセージ長が2047バイトを超える場合は、2047バイト以降は破棄されます。

blkno:

（GEE/DSの場合に“OP_APIMSGTYPENORM”以外の値の場合あり）
マルチラインメッセージのように、複数のメッセージで意味をもつ場合に、複数メッセージをブロック化の番号が格納されます。
単一メッセージの場合は、OP_ONLYBLK（0x0000）が格納され、マルチラインメッセージの場合は、0x0001～0xFFFFが格納されます。
ブロックの最後のメッセージには、必ずOP_MLTBLK_END（0xFFFF）が格納されます。

msgtype:

発生したメッセージのメッセージ種別が格納されます。
メッセージ種別を以下に示します。

OP_APIMSGTYPENORM:: 通常メッセージ
OP_APIMSGTYPEREP:: 返答要求メッセージ（GEE/DS）
OP_APIMSGTYPEHB:: 高輝度メッセージ（GEE）
OP_APIMSGTYPEDEL:: メッセージ削除データ（以下、DOMデータという）
これは実際にはメッセージではなく、返答要求メッセージや高輝度メッセージが対処されたことを通知するための情報データです。
OP_APIMSGTYPESTAT:: システム監視エージェント起動メッセージ
このメッセージは、システムが監視状態であることを通知するメッセージです。
接続形態が常時接続で接続中か、接続形態が必要時接続、またはRAS接続として登録されていることを示します。
OP_APIMSGTYPESTOP:: システム監視エージェント停止メッセージ
このメッセージは、システムが監視状態でなくなったことを通知するメッセージです。
接続形態が常時接続のシステムが切断されたか、接続形態が必要時接続、またはRAS接続として登録されていたシステムが削除されたことを示します。
OP_APIMSGTYPECHNG:: システム状態変更メッセージ
（GEE）このメッセージは、ホットスタンバイの系区別が変更されたことを通知するメッセージです。

ostype:

発生したメッセージのOS種別が格納されます。
OS種別を以下に示します。

OP_UXPDS:: UXP/DS
OP_SOLARIS1:: Solaris1.x系
OP_SOLARIS2:: Solaris2.x系
OP_HPUX10:: HP-UX
OP_AIX:: AIX
OP_MVS:: MVS
OP_LINUX:: Linux
OP_UXPM:: UXP/M
OP_UXPVPP:: UXP/VPP
OP_WINDOWS2000:: Windows(R) 2000
OP_WINDOWSNT:: Windows NT(R)
OP_WINNTSERVER:: Windows NT(R) Server
OP_WINNTWS:: Windows NT(R) Workstation
OP_WINDOWS31:: Windows(R) 3.1, Windows(R) 3.11, Windows(R) 3.11 WorkGroup
OP_WINDOWS95:: Windows(R) 95
OP_WINDOWS98:: Windows(R) 98
OP_WINDOWSXP:: Windows(R) XP
OP_WINDOWSXPPRO:: Windows(R) XP Professional
OP_WINDOWSXPHOME:: Windows(R) XP Home Edition
OP_SXO:: SXO
OP_SYMFOWAREPS:: Symfoware(R) Parallel Server
OP_RAID:: RAID
OP_MSPE20:: MSP E20
OP_MSPAF2:: MSP AFII
OP_XSPAF2:: XSP AFII
OP_AVMEX:: AVM/EX
OP_FTOPS2:: FTOPS-II
OP_MVSG:: MVS 系（IBMおよび他社互換機）
OP_ASP:: ASP
OP_WINDOWSSV2003 :: Windows Server(R) 2003
OP_WINDOWSSV2003STD :: Windows Server(R) 2003,Standard Edition
OP_WINDOWSSV2003ENT :: Windows Server(R) 2003,Enterprise Edition
OP_WINDOWSSV2003DATA :: Windows Server(R) 2003,Datacenter Edition
OP_WINDOWSSV2003WEB :: Windows Server(R) 2003,Web Edition
OP_WINDOWSVISTA:: Windows Vista(R)
OP_WINDOWSVISTAUL:: Windows Vista(R) Ultimate
OP_WINDOWSVISTAENT:: Windows Vista(R) Enterprise
OP_WINDOWSVISTABIZ:: Windows Vista(R) Business
OP_WINDOWSVISTAHP:: Windows Vista(R) Home Premium
OP_WINDOWSVISTAHB:: Windows Vista(R) Home Basic
OP_WINDOWSSV2008:: Windows Server(R) 2008
OP_WINDOWSSV2008STD:: Windows Server(R) 2008 Standard
OP_WINDOWSSV2008ENT:: Windows Server(R) 2008 Enterprise
OP_WINDOWSSV2008DATA:: Windows Server(R) 2008 Datacenter
OP_WINDOWSSV2008STDWOHV:: Windows Server(R) 2008 Standard without Hyper-V
OP_WINDOWSSV2008ENTWOHV:: Windows Server(R) 2008 Enterprise without Hyper-V
OP_WINDOWSSV2008DATAWOHV:: Windows Server(R) 2008 Datacenter without Hyper-V
OP_WINDOWSSV2008ITANIUM:: Windows Server(R) 2008 for Itanium-Based systems
OP_OS_UNKNOWN:: 不明

submsgnum

GEEおよびUNIX版集中監視マネージャのGS連携オプションが使用する、メッセージの補助説明文の番号が格納されます。

voicenum

通報番号が格納されます。

msgcolor

[Systemwalkerコンソール]の[監視イベント一覧]に表示する、メッセージの文字の色が格納されます。
文字色の種類を以下に示します。

OP_COLOR_BLACK:: 黒色
OP_COLOR_WHITE:: 白色
OP_COLOR_RED:: 赤色
OP_COLOR_GREEN:: 緑色
OP_COLOR_BLUE:: 深緑色
OP_COLOR_YELLOW:: 黄色
OP_COLOR_LIGHTBLUE:: 明青色
OP_COLOR_PURPLE:: 紫色
OP_COLOR_DARKGRAY:: 濃い灰色
OP_COLOR_ORANGE:: 黄緑色
OP_COLOR_SKYBLUE:: 水色
OP_COLOR_PINK:: ピンク色
OP_COLOR_PALEGREEN:: 青緑色
OP_COLOR_BROWN:: 茶色
OP_COLOR_GRAY:: 淡い灰色
OP_COLOR_CREAM:: 黄土色
OP_COLOR_DEF:: 標準色
なお、メッセージ種別(msgtype)が、OP_APIMSGTYPESTAT, OP_APIMSGTYPESTOP,OP_APIMSGTYPECHNGのときは、必ずOP_COLOR_DEFが格納されます。

backcolor:

[Systemwalkerコンソール]の[監視イベント一覧]に表示する、メッセージの背景色が格納されます。
文字色の種類は、msgcolorと同じです。
なお、メッセージ種別(msgtype)が、OP_APIMSGTYPESTAT, OP_APIMSGTYPESTOP, OP_APIMSGTYPECHNGのときは、必ずOP_COLOR_DEFが格納されます。

domtype:

返答要求メッセージ、および高輝度メッセージの種類が格納されます。
これは、返答要求メッセージ、高輝度メッセージ、およびDOM対応メッセージとDOMデータとの対応をとるために使用します。
DOM種別を以下に示します。

OP_NORMDOM:: 返答要求メッセージ、高輝度メッセージ、およびDOM対応メッセージ以外。
OP_NIPDOM:: MSP、またはXSPのNIP時の返答要求メッセージ、およびDOMデータです。
OP_MSPDOM:: MSPのNIP時以外の返答要求メッセージ、高輝度メッセージ、およびDOMデータです。
OP_XSPDOM:: XSPのNIP時以外の返答要求メッセージ、高輝度メッセージ、およびDOMデータです。
OP_WORKITDOM:: BS*NET/WORKITが通知する返答要求メッセージ、およびDOMデータです。
OP_ASPDOM:: ASPが通知する返答要求メッセージ、高輝度メッセージ、およびDOMデータです。
OP_APLDOM:: Systemwalker Centric Managerアプリケーションが通知するDOM対応メッセージ、およびDOMデータです。
OP_WTORDOM ：: 返答メッセージ機能が通知するDOM対応メッセージ、およびDOMデータです。

domnum:

返答要求メッセージ、高輝度メッセージ、およびDOM対応メッセージの場合に、メッセージとDOMデータの対応をとるための番号が格納されます。
この番号は、メッセージ発生システム内でDOM種別ごとに一意です。

replyid:

返答要求メッセージに対して、コマンドで返答するときの、メッセージを識別する文字列が格納されます。9バイト分呼び出し元で準備します。

systype:

（GEE以外では“OP_SYSTYPE_NORM”が設定される）
ホットスタンバイシステムの場合に、メッセージが発生した時点での運用系、待機系の区別が格納されます。
系区別を以下に示します。

OP_SYSTYPE_NORM:: ホットスタンバイシステムではない。
または、ホットスタンバイシステムですが、運用系、待機系がまだ決定していない。
OP_SYSTYPE_MAIN:: ホットスタンバイシステムの運用系です。
OP_SYSTYPE_SUB:: ホットスタンバイシステムの待機系です。
OP_SYSTYPE_WP:: Windows NT(R)のマイクロソフトクラスタシステム運用です。

ext:

発生したメッセージの拡張データが格納されます。

■構造体の説明【UNIX版】

◆拡張データ（EXTENDDATA）の形式

  
  /*
   * EXTEND DATA
   */
typedef struct _EXTENDDATA{
    unsigned short  protype;
    unsigned char   conntype; 
    char            rsv1[1]; 
    char            jobnum[MPOP_JOBNUMLEN];
    char            rsv2[3]; 
    char            runtype[MPOP_RUNTYPELEN];
    char            rsv3[3];
    unsigned char   mailmsgflg;
    char            rsv4[3]; 
    char            domkey[MPOP_DOMKEYLEN]; 
    char            rsv5[3];
    unsigned int    IPaddr;
    unsigned int    DMInstallType;
    unsigned int    JMInstallType;
    unsigned int    MW_DM_vl; 
    char            MW_DM_suffix[MPOP_SUFFIXLEN];
    char            MW_DM_updatenum[MPOP_UPDATENUMLEN];
    char            rsv6[2];
    unsigned int    MW_JM_vl;
    char            MW_JM_suffix[MPOP_SUFFIXLEN];
    char            MW_JM_updatenum[MPOP_UPDATENUMLEN]; 
    unsigned char   auttrbtkt;
    char            rsv7[1]; 
}EXTENDDATA;

protype:

リザーブ領域

conntype:

リザーブ領域

jobnum:

リザーブ領域

runtype:

メッセージが発生したシステムの運用形態名が格納されます。

mailmsgflg:

発生したメッセージのメール連携フラグが格納されます。

domkey:

DOM拡張キーが格納されます。
DOM拡張キーがない場合は、NULLが格納されます。

IPaddr:

メッセージが発生したシステムのIPアドレスが格納されます。
IPアドレスがない場合は、0が格納されます。

DMInstallType:

メッセージが発生したシステムのSystemwalker Centric Managerのインストールタイプが格納されます。

JMInstallType:

メッセージが発生したシステムのSystemwalker Operation Managerのインストールタイプが格納されます。

MW_DM_vl:

メッセージが発生したシステムのSystemwalker Centric Managerのメジャーバージョン、マイナーバージョン、メジャーレベルが格納されます。

  
０ｘ００００００００       a) メジャーバージョン
        ←→←→←→       b) マイナーバージョン
         a)  b)  c)        ｃ) メジャーレベル

MW_DM_suffix:

メッセージが発生したシステムのSystemwalker Centric Managerのサフィックスが格納されます。

MW_DM_updatenum:

メッセージが発生したシステムのSystemwalker Centric Managerのアップデートパック修正番号が格納されます。

MW_JM_vl:

メッセージが発生したシステムのSystemwalker Operation Managerのメジャーバージョン、マイナーバージョン、メジャーレベルが格納されます。形式は、MW＿DM＿vlと同様です。

MW_JM_suffix:

メッセージが発生したシステムのSystemwalker Operation Managerのサフィックスが格納されます。

MW_JM_updatenum:

メッセージが発生したシステムのSystemwalker Operation Managerのアップデートパック修正番号が格納されます。

Auttrbtkt:

リザーブ領域。

■実行に必要な権限/実行環境

【Windows版】

運用管理サーバ/部門管理サーバ/業務サーバでは、Administrator権限/DmAdmin権限/DmOperation権限/DmReference権限が必要です。
運用管理クライアント/クライアントでは、一般ユーザ権限で実行可能です。
運用管理サーバ/部門管理サーバ/業務サーバで実行可能です。
運用管理クライアント/クライアントでは、[イベント監視]を選択インストールしたとき実行可能です。

【UNIX版】

運用管理サーバ/部門管理サーバ/業務サーバではシステム管理者(スーパーユーザ)権限が必要です。
運用管理クライアント/クライアントでは、一般ユーザ権限で実行可能です。
運用管理サーバ/部門管理サーバ/業務サーバで実行可能です。
運用管理クライアント/クライアントでは、[イベント監視]を選択インストールしたとき実行可能です。

■参照

以下のシステム監視のAPIを参照してください。

Mp_OpenMsg（）関数
Mp_CloseMsg（）関数
Mp_GetMsgMap（）関数【Windows版】

■復帰値

【Windows版】

ReadFile（）関数の復帰情報がそのまま応答されます。

詳細なエラーコードは、GetLastError（）で取得してください。

【UNIX版】

0:: 正常終了。メッセージを正常に受信。
－1:: 異常終了。詳細なエラーコードは、errnoに設定されます。
errnoには、システムのエラーコード（/usr/include/sys/errno.hに定義）、または/opt/systemwalker/include/mp_operr_api.hに定義されている値が設定されます。

■API格納場所

“監視メッセージのAPI”を参照してください。

■注意事項

msgtypeがOP_APIMSGTYPENORM(通常メッセージ)、およびOP_APIMSGTYPEHB(高輝度メッセージ)以外のメッセージについては、制御用メッセージのため、OS種別が設定されないことがあります。

また、msgtypeがOP_APIMSGTYPENORM(通常メッセージ)、およびOP_APIMSGTYPEHB(高輝度メッセージ)で他製品との連携時に送付されたメッセージでは、OS種別としてOP_OS_UNKNOWN(不明)が取得されることがあります。

【Windows版】

呼び出し元は、Mp_ReadMsg（）関数の第4パラメタの、OVERLAPPED構造体を利用して、イベント受信のオーバラップ処理を完了し、Mp_GetMsgMap（）関数を呼び出してください。

【UNIX版(Linux for Itanium版を除く)の場合】

UTF-8環境で本APIを使用する場合、以下の注意事項があります。

監視イベント種別(category)
獲得できる監視イベント種別が16バイトになります。17バイト目以降が削除されます。このため、以下のように対応してください。
- APIを使用するサーバ
  [イベント監視の条件定義]に、17バイト以上の監視イベント種別を16バイト以下に変更する定義を実施してください。
- 運用管理サーバ
  この定義を実施した場合、定義した16バイト以下の監視イベント種別を[サーバ環境定義]に追加してください。
DOM拡張キー(domkey)
獲得できるDOM拡張キーが80バイトになります。81バイト目以降が削除されます。このため、Systemwalkerスクリプトのメッセージ監視アクション型スクリプトにおいて、復旧キーに、文字コードUTF-8に変換したときに80バイト以内となるキーを指定してください。

■動作環境による差異

以下のインストール種別で使用可能です。

運用管理サーバ
部門管理サーバ
業務サーバ
運用管理クライアント:Windows(R) 2000/ Windows NT(R)/ Windows(R) XP(注)/ Windows Vista(R)
クライアント　　　　:Windows(R) 2000/ Windows NT(R)/ Windows(R) XP(注)/ Windows Vista(R)
注)システム監視エージェントインストール選択時

目次索引