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
|
