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_WINDOWSSV2008WEBSV:: Windows(R) Web Server 2008

OP_HVSV2008:: Microsoft(R) Hyper-V Server 2008

OP_WINDOWSSV2008FD:: Windows Server(R) 2008 Foundation

OP_WINDOWS7:: Windows(R) 7

OP_WINDOWS7UL:: Windows(R) 7 Ultimate

OP_WINDOWS7ENT:: Windows(R) 7 Enterprise

OP_WINDOWS7PRO:: Windows(R) 7 Professional

OP_WINDOWS7HP:: Windows(R) 7 Home Premium

OP_WINDOWS7STNOTE:: Windows(R) 7 Starter for Small Notebook PCs

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)        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を参照してください。

復帰値

【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版、Linux for Intel64版を除く)の場合】

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) 7(注)
クライアント:
Windows(R) 2000/Windows NT(R)/Windows(R) XP/Windows Vista(R)/Windows(R) 7(注)
注)システム監視エージェントインストール選択時