The message portion of the Watch for Event function has several enhancements beginning at IBM i 7.1, one of which is the support to watch for *ALL messages sent to a nonprogram message queue (such as QSYSMSG) or all messages sent to a program message queue for a job (job log).

If the QSYSMSG message queue exists and is not damaged, certain messages are directed to it instead of, or in addition to, the QSYSOPR message queue. This allows a user-written program to gain control when certain messages are sent.

The goal of this technote is to show you how to combine the best of both features through simple programming using CL.

Written by Matias Centeno Lozada

IBM® AS/400®, iSeries™, System i™, and Power Systems™ SW Support Specialist

MTS - IBM Argentina Support Center

The following two programs demonstrate how to use the New Watch for Event function for IBM® i 7.1 to monitor everything that goes to QSYS/QSYSMSG *MSGQ and send an alert by e-mail.


Program name: STRWSEM

BEGIN: PGM
/* */
MONMSG MSGID(CPC0000 CPD0000 CPF0000 MCH0000)
STRPJ SBS(QUSRWRK) PGM(QSYS/QSCWCHPS)
STRWCH SSNID(WSEM) WCHPGM(QGPL/WSEM) +
CALLWCHPGM(*WCHEVT) WCHMSG((*ALL *NONE +
*MSGDTA *ALL *GE 00)) WCHMSGQ((QSYS/QSYSMSG))
/* */
END: ENDPGM


Program name: WSEM

BEGIN: PGM PARM(&WCHOPTION &SESSIONID &ERROR &EVTDATA)
/* */
DCL VAR(&WCHOPTION) TYPE(*CHAR) LEN(10)
DCL VAR(&SESSIONID) TYPE(*CHAR) LEN(10)
DCL VAR(&ERROR) TYPE(*CHAR) LEN(10)
DCL VAR(&EVTDATA) TYPE(*CHAR) LEN(1024)
DCL VAR(&MSG) TYPE(*CHAR) LEN(173)
DCL VAR(&ALERT) TYPE(*CHAR) LEN(255)
/* */
DCL VAR(&MSGID) TYPE(*CHAR) STG(*DEFINED) LEN(7) +
DEFVAR(&EVTDATA 5)
DCL VAR(&MSGQ) TYPE(*CHAR) STG(*DEFINED) LEN(10) +
DEFVAR(&EVTDATA 13)
DCL VAR(&MSGQLIB) TYPE(*CHAR) STG(*DEFINED) +
LEN(10) DEFVAR(&EVTDATA 23)
DCL VAR(&MSGKEY) TYPE(*CHAR) STG(*DEFINED) +
LEN(4) DEFVAR(&EVTDATA 387)
/* */
DCL VAR(&MATMATR) TYPE(*CHAR) LEN(2617)
DCL VAR(&BYTESIN) TYPE(*CHAR) STG(*DEFINED) +
LEN(4) DEFVAR(&MATMATR)
DCL VAR(&TYPE) TYPE(*CHAR) STG(*DEFINED) LEN(4) +
DEFVAR(&MATMATR 2509)
DCL VAR(&MODEL) TYPE(*CHAR) STG(*DEFINED) LEN(3) +
DEFVAR(&MATMATR 2514)
DCL VAR(&PLANT) TYPE(*CHAR) STG(*DEFINED) LEN(2) +
DEFVAR(&MATMATR 2534)
DCL VAR(&SERIAL) TYPE(*CHAR) STG(*DEFINED) +
LEN(7) DEFVAR(&MATMATR 2537)
/* */
DCL VAR(&LPARDTA) TYPE(*CHAR) LEN(368)
DCL VAR(&FORMAT) TYPE(*INT) LEN(4) VALUE(1)
DCL VAR(&LPARDTALEN) TYPE(*INT) LEN(4) VALUE(368)
DCL VAR(&EC) TYPE(*CHAR) LEN(8)
DCL VAR(&ID) TYPE(*CHAR) STG(*DEFINED) LEN(4) +
DEFVAR(&LPARDTA 41)
DCL VAR(&LPARID) TYPE(*CHAR) LEN(4)
/* */
DCL VAR(&CCSID1) TYPE(*INT) LEN(4) VALUE(1208)
DCL VAR(&ST1) TYPE(*INT) LEN(4) VALUE(1)
DCL VAR(&NAME) TYPE(*CHAR) STG(*DEFINED) +
LEN(256) DEFVAR(&LPARDTA 89)
DCL VAR(&L1) TYPE(*INT) LEN(4) VALUE(256)
DCL VAR(&CCSID2) TYPE(*INT) LEN(4)
DCL VAR(&ST2) TYPE(*INT) LEN(4) VALUE(2)
DCL VAR(&GCCASN) TYPE(*INT) LEN(4) VALUE(0)
DCL VAR(&L2) TYPE(*INT) LEN(4) VALUE(256)
DCL VAR(&LPARNAME) TYPE(*CHAR) LEN(256)
DCL VAR(&L3) TYPE(*INT) LEN(4) VALUE(0)
DCL VAR(&L4) TYPE(*INT) LEN(4) VALUE(0)
DCL VAR(&FB) TYPE(*CHAR) LEN(12)
DCL VAR(&CCSID) TYPE(*DEC) LEN(5 0)
DCL VAR(&DFTCCSID) TYPE(*DEC) LEN(5 0)
DCL VAR(&PRTTXT) TYPE(*CHAR) LEN(72)
/* */
MONMSG MSGID(CPC0000 CPD0000 CPF0000 MCH0000)
/* */
CHGVAR VAR(%BIN(&BYTESIN)) VALUE(2617)
CALLPRC PRC('_MATMATR1') PARM((&MATMATR *BYREF) +
(X'012C' *BYREF))
CALLPRC PRC('dlpar_get_info') PARM((&LPARDTA *BYREF) +
(&FORMAT *BYVAL) (&LPARDTALEN *BYVAL)) +
RTNVAL(&EC)
CHGVAR VAR(&EC) VALUE(X'0000000000000000')
CHGVAR VAR(&LPARID) VALUE(%BIN(&ID))
/* */
RTVJOBA CCSID(&CCSID) DFTCCSID(&DFTCCSID)
IF COND(&CCSID *EQ 65535) THEN(CHGVAR +
VAR(&CCSID2) VALUE(&DFTCCSID))
ELSE CMD(CHGVAR VAR(&CCSID2) VALUE(&CCSID))
CALL PGM(QTQCVRT) PARM(&CCSID1 &ST1 &NAME &L1 +
&CCSID2 &ST2 &GCCASN &L2 &LPARNAME &L3 +
&L4 &FB)
IF COND(&LPARNAME *EQ ' ') THEN(CHGVAR +
VAR(&LPARNAME) VALUE('*NONE'))
ELSE CMD(CHGVAR VAR(&LPARNAME) +
VALUE(%SST(&LPARNAME 1 50)))
CHGVAR VAR(&PRTTXT) VALUE(&TYPE |< '-' |< &MODEL |< +
'*' |< &PLANT |< &SERIAL |< '/' |< +
&LPARID |< '/' || &LPARNAME)
/* */
RCVMSG MSGQ(&MSGQLIB/&MSGQ) MSGKEY(&MSGKEY) +
RMV(*NO) MSG(&MSG)
CHGVAR VAR(&ALERT) VALUE('*MSG ' || &PRTTXT |< ': ' +
|| &MSGID || ' - ' || &MSG)
SNDDST TYPE(*LMSG) TOINTNET((centenom@ar.ibm.com +
*PRI)) DSTD('*** ALERT ***') LONGMSG(&ALERT)
/* */
END: CHGVAR VAR(&ERROR) VALUE(' ')
ENDPGM


Putting all the pieces together to make it work

Follow these instructions from an IBM i command line:

1. Use the Start Source Entry Utility (STRSEU) command to add a source member called STRWSEM to the QGPL/QCLSRC source physical file:

STRSEU SRCFILE(QGPL/QCLSRC) SRCMBR(STRWSEM) TYPE(CLP) OPTION(2) TEXT('Start WSEM')

2. Paste the CLP code example for program STRWSEM and save the member.

3. Use the Start Source Entry Utility (STRSEU) command to add a source member called WSEM to the QGPL/QCLSRC source physical file:

STRSEU SRCFILE(QGPL/QCLSRC) SRCMBR(WSEM) TYPE(CLLE) OPTION(2) TEXT('Watch for severe error messages')

4. Paste the CLLE code example for program WSEM and save the member.

5. Complete the setup by running these commands one by one:

CRTCLPGM PGM(QGPL/STRWSEM) SRCFILE(QGPL/QCLSRC) OPTION(*NOSRC) USRPRF(*OWNER) LOG(*NO) ALWRTVSRC(*NO) REPLACE(*YES)

CHGPGM PGM(QGPL/STRWSEM) OPTIMIZE(*YES) RMVOBS(*ALL)

CHGOBJOWN OBJ(QGPL/STRWSEM) OBJTYPE(*PGM) NEWOWN(QSYS)

GRTOBJAUT OBJ(QGPL/STRWSEM) OBJTYPE(*PGM) USER(*PUBLIC) AUT(*EXCLUDE)

GRTOBJAUT OBJ(QGPL/STRWSEM) OBJTYPE(*PGM) USER(*PUBLIC) AUT(*OBJMGT *OBJOPR *READ *EXECUTE)

CRTBNDCL PGM(QGPL/WSEM) SRCFILE(QGPL/QCLSRC) OUTPUT(*NONE) USRPRF(*OWNER) LOG(*NO) ALWRTVSRC(*NO) REPLACE(*YES)

CHGPGM PGM(QGPL/WSEM) OPTIMIZE(*YES) RMVOBS(*ALL)

CHGOBJOWN OBJ(QGPL/WSEM) OBJTYPE(*PGM) NEWOWN(QSYS)

GRTOBJAUT OBJ(QGPL/WSEM) OBJTYPE(*PGM) USER(*PUBLIC) AUT(*EXCLUDE)

GRTOBJAUT OBJ(QGPL/WSEM) OBJTYPE(*PGM) USER(*PUBLIC) AUT(*OBJMGT *OBJOPR *READ *EXECUTE)

CRTDUPOBJ OBJ(QSTRUPJD) FROMLIB(QSYS) OBJTYPE(*JOBD) TOLIB(QGPL) NEWOBJ(WSEM)

CHGOBJOWN OBJ(QGPL/WSEM) OBJTYPE(*JOBD) NEWOWN(QSYS)

GRTOBJAUT OBJ(QGPL/WSEM) OBJTYPE(*JOBD) USER(*PUBLIC) AUT(*EXCLUDE)

CHGJOBD JOBD(WSEM) JOBQ(QSYS/QUSRNOMAX) TEXT('Watch for severe error messages') RQSDTA('CALL PGM(QGPL/STRWSEM)')

GRTOBJAUT OBJ(STRWCH) OBJTYPE(*CMD) USER(QPGMR) AUT(*USE)

CHGFCNUSG FCNID(QIBM_SERVICE_WATCH) USER(QPGMR) USAGE(*ALLOWED)

ADDAJE SBSD(QSYS/QUSRWRK) JOB(WSEM) JOBD(QGPL/WSEM)

CRTMSGQ MSGQ(QSYS/QSYSMSG) TEXT('MSGQ for severe error messages')

CHGOBJOWN OBJ(QSYS/QSYSMSG) OBJTYPE(*MSGQ) NEWOWN(QSYS)

GRTOBJAUT OBJ(QSYS/QSYSMSG) OBJTYPE(*MSGQ) USER(*PUBLIC) AUT(*EXCLUDE)

GRTOBJAUT OBJ(QSYS/QSYSMSG) OBJTYPE(*MSGQ) USER(*PUBLIC) AUT(*OBJOPR *ADD *READ *EXECUTE)

GRTOBJAUT OBJ(QSYS/QSYSMSG) OBJTYPE(*MSGQ) USER(QPGMR QSRV QSRVBAS QSYSOPR) AUT(*CHANGE)

ADDDIRE USRID(QPGMR QPGMR) USRD('Programmer and Batch User') USER(QPGMR)

SBMJOB JOB(*JOBD) JOBD(QGPL/WSEM) JOBQ(*JOBD) USER(*JOBD) RQSDTA(*JOBD)


How they work

The program WSEM sends an e-mail every time that a new message arrives to QSYS/QSYSMSG *MSGQ. The e-mail is sent to the address specified in the SNDDST command within program WSEM. The details of the message captured in QSYSMSG are included within the e-mail body.

For further information about the STRWCH command and the QSYSMSG message queue see the IBM i 7.1 Information Center at the following web pages:

• Start Watch (STRWCH)

http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/topic/cl/strwch.htm
• Messages sent to QSYSMSG message queue

http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/topic/rbam6/msmqu.htm