TAA Tools
MONMSGQ         MONITOR MESSAGE QUEUE                  TAAMSJB

The  Monitor  Message  Queue  tool  provides   a  simple  solution  for
monitoring a  message queue for specific message IDs  so that an action
may  be performed.  For example, you may  want to call a program when a
specific message arrives on  a message queue such  as QSYSMSG.  To  use
MONMSGQ, see the 'Getting started' instructions.

The  MSGCTL and  CHKSYSCND tools  provide more  sophisticated solutions
for monitoring message queues.

SBMMONMSGQ   submits  a   never  ending   batch  job  which   wakes  up
periodically and checks  the specified  message queue  for message  IDs
that match  the list  you have  provided.  A  special value  of *ANYINQ
may be  used for any Inquiry type message  (see the discussion with the
sample entries).

Getting started with MONMSGQ
----------------------------

A special data  area must be  created to contain the  message IDs  that
you want  to monitor for.   A good  technique would be  to give  it the
same name as  the message queue you want to  monitor.  In the following
examples, QSYSMSG is used.

             CRTMONMSGQ  DTAARA(QGPL/QSYSMSG)
                           TEXT('Used by TAA MONMSGQ for QSYSMSG')

The  list of  messages that you  want to invoke  a program  for must be
placed in the data area: Enter:

             EDTCONARR   DTAARA(QGPL/QSYSMSG)

An entry display appears which  allows the entry of a message ID  and a
qualified  program name  to be  called  if the  message ID  is sent  to
QSYSMSG.

A typical entry display would appear as:

******************************************************************

    Edit Constant Array - TAA MONMSGQ for QSYSMSG

 Type new/changed information, press Enter.
   To add an entry, type a value in both entries.
   To remove an entry, blank out both entries.
   To change positions of an entry, type new sequence number.


  Sequence   Message ID   Len =  7       Pgm/Lib      Len = 20
    010      CPF0927                     PGM1      LIB1
    020      CPF1393                     PGM2      LIB1
    030      CPF2456                     PGM3      LIB1
    040      *ANYINQ                     PGM4      LIB1
    050
    060
    070
    080
    090
               Any value                   Qualified object

                                                   More ...
  F12=Cancel     Enter=Update or refresh (if any changes occur)

******************************************************************

  **   Note  that the  message ID  and program/library must  be entered
       in upper case.

  **   Up to 45 message IDs may be monitored for.

  **   There is no check made on  the message ID to ensure it is  valid
       or is sent  by the system.   The program and library  names must
       be a  valid syntax, but no  check is made to  see if they exist.
       The library name may be *LIBL or *CURLIB.

  **   The special  value  *ANYINQ  specifies  that  any  Inquiry  Type
       message (message return type  '05') will invoke a program.   The
       message  IDs in  the data  area are  checked  in the  order they
       appear.    Therefore,  if  you  have a  message  ID  that  is an
       Inquiry type  that you want  to handle  before the program  that
       handles  *ANYINQ, it should  be specified  before *ANYINQ.   The
       entry  of *ANYINQ  may  be specified  as the  only entry  in the
       data area.

       For  a list  of  typical  messages  that  the  system  sends  to
       QSYSMSG, see the CHKSYSCND tool section on 'Implementation'.

  **   The SBMMONMSGQ  command submits  the MONMSGQ function  to batch.

          SBMMONMSGQ    MSGQ(QSYSMSG) DTAARA(QGPL/QSYSMSG)
                          JOB(MONQSYSMSG)

  **   The  default is  to submit  to  the QSYSNOMAX  job queue  with a
       wakeup time of 60 seconds  meaning every 60 seconds the  QSYSMSG
       message queue would be read.

  **   Only 'new'  messages  are processed.   This  means  that once  a
       message  is read,  it is  considered an  'old' message  and will
       not be processed again.

  **   The  batch  program does  not  adopt its  owner's  authority and
       will  run  under  the   authority  of  the  user   that  entered
       SBMMONMSGQ.

  **   The  processing  program  that   you  provide  must  accept  two
       parameters:

                 MSGID    *CHAR  LEN(7)
                 MSGDTA   *CHAR  LEN(100)

       Use  DSPMSGDTA for  the message  ID you are  interested in.   It
       will describe  the  message text  and  what variables  are  used
       (such as &1 and  &2) that exist in the MSGDTA.   For example, if
       you  want to  know the user  profile name  that was  disabled by
       message CPF1393, enter:

                 DSPMSGDTA   CPF1393

       The first  level  text  describes that  user  &2  was  disabled.
       Rollup to the  section on 'Message  data fields'.   It describes
       that the  &2 field is in positions 11-20  of the MSGDTA.  Assume
       your  CL program  will only  process the  CPF1393 message.   The
       beginning code would be:

             PGM        PARM(&MSGID &MSGDTA)
             DCL        &MSGID *CHAR LEN(7)
             DCL        &MSGDTA *CHAR LEN(100)
             DCL        &USRPRF *CHAR LEN(10)
              .
             CHGVAR     &USRPRF %SST(&MSGDTA 11 10)
                        /* Your processing */

  **   A single  program can  be used  for  every message.   You  would
       need to determine the MSGID for unique processing.

  **   You can place the SBMMONMSGQ command in a start up job.

Other comments
--------------

  **   Each  time  that the  MONMSGQ  job  wakes  up, it  extracts  the
       current   information   from   the   data   area   described  on
       SBMMONMSGQ.  This means you  can use EDTCONARR to add or  change
       the  list of  messages and  the changes  will be  picked up  the
       next time a 'wake up' occurs.

  **   Unlike the  MSGCTL or CHKSYSCND tools, MONMSGQ  does not place a
       lock  on  the  message  queue.    You  cannot  use  MONMSGQ   in
       conjunction with MSGCTL  or CHKSYSCND nor any program  placing a
       lock on the same message queue.

  **   You  can use  DSPMSG to the  message queue  while MONMSGQ  is in
       operation.

  **   You  can end the MONMSGQ job with  the ENDJOB command or from an
       option on a display such as WRKACTJOB.

  **   The MONMSGQ job may  be seen using WRKACTJOB.  The  program will
       be TAAMSJBC11.   It will normally  appear with a status  of DLYW
       and  the  Function  will  describe  DLY-nnn  for  the wait  time
       specified.

  **   If a program you specified  to process a MSGID fails, the  batch
       job will  continue to run.   A message  will be sent  to QSYSOPR
       explaining the condition.  A job log is forced in this case.

  **   More  than one SBMMONMSGQ  command may  be entered for  the same
       message queue.  A unique data  area should be created for  each.

MONMSGQ escape messages you can monitor for
-------------------------------------------

None.  Escape messages from based on functions will be re-sent.

SBMMONMSGQ Command parameters                         *CMD
-----------------------------

   MSGQ          The message  queue to be  monitored for.   The library
                 qualifier  defaults to *LIBL.   A specific  library or
                 *CURLIB may also be used.

   DTAARA        The  data area that was  created by CRTMONMSGQ and has
                 data placed  into  it using  EDTCONARR.   The  library
                 qualifier defaults  to *LIBL.   A specific  library or
                 *CURLIB may also be used.

   WAIT          The  wait time  in seconds  that the MONMSGQ  job will
                 wait  before  waking  up  and  checking  the   message
                 queue.   The default  is 60 seconds.   The  value must
                 be between 3 and 99999 seconds.

   JOB           The  name  of  the  submitted  job.   The  default  is
                 MONMSGQ.

   JOBQ          The job queue to  submit the job to.   The default  is
                 QSYSNOMAX in *LIBL.

   JOBD          The job  description to  be used  when submitting  the
                 job.   The  default  is *USRPRF.   If  a  specific job
                 description  is  named  and the  library  qualifier is
                 blank, *LIBL will be used.


CRTMONMSGQ Command parameters                         *CMD
-----------------------------

   DTAARA        The data  area  that will  hold  the message  IDs  and
                 corresponding program  names to be  called.  EDTCONARR
                 must  be used to  enter the data.   A specific library
                 must be entered.

   AUT           The authority given  to the  data area.   *USE is  the
                 default.  *CHANGE may also be entered.

   TEXT          The  text description  of the  data  area.   Up to  30
                 bytes may be entered.


Restrictions
------------

No other job may place a lock on the message queue being monitored.

Prerequisites
-------------

The following TAA Tools must be on your system:

     CRTCONARR       Create constant array
     RSNLSTMSG       Resend last message
     SNDCOMPMSG      Send completion message
     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message

Implementation
--------------

See the previous section on 'Getting started'.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   SBMMONMSGQ    *CMD                   TAAMSJB       QATTCMD
   CRTMONMSGQ    *CMD                   TAAMSJB2      QATTCMD
   TAAMSJBC      *PGM       CLP         TAAMSJBC      QATTCL
   TAAMSJBC2     *PGM       CLP         TAAMSJBC2     QATTCL
   TAAMSJBC11    *PGM       CLP         TAAMSJBC11    QATTCL

Structure
---------

SBMMONMSGQ  Cmd
   TAAMSJBC   CL pgm
      Submits  TAAMSJBC11 CL program

CRTMONMSGQ  Cmd
   TAAMSJBC2  CL pgm
					

Added to TAA Productivity tools May 15, 2008


Home Page Up to Top