E-Police home | Easy400 | System i home
Public-Source
 
Introduction
Program Error Monitor
Receive Message queue
Mandatory Activities
Command EDBG
 
Download
 
 

 
 
Receive Message Queue
by Giovanni B. Perotti (Italy)
There are installations that are regularly bothered by system messages requiring actions (expecially from message queue QSYSOPR).
In most cases, the causes of the messages are very well known, and the actions are always the same.
Then, why not an automat taking care of these cases and documenting what was done?
1- The Receive Message Queue command
does the job. For a given message queue (usually QSYSOPR) you may
  • define the message IDs that the automat should process
  • define a match pattern on the message data, in order to process only given messages
  • define an answer for inquiry messages
  • run a set of commands, before and/or after a reply (if needed)
  • notify a given user profile - through a break message - of what happened
  • notify a given e-mail address about the actions taken
2- Things to do before running the command
Before running command RCVMSGQ, you need to provide some setup by entering data in some files of library EPOLICEDTA. To make that easy, a special setup menu has been provided. You call that menu with command EPOLICE/UPDMSGQ.
Here is the menu:

                Update command RCVMSGQ control files (UPDMSGQ)                 
                                                               
 Type option, press Enter.

 1. UPDMSGQ1 - "MessageQueue_Name" control file
     (messages to be intercepted)
 
 2. UPDMSGQ2 - "SENDERMAIL" control file
     (information about the sender of e-mail messages)

 3. UPDMSGQ3 - "USRPRFMAIL" control file
     (information about the receivers of e-mail messages)

 Option:  _



 F3/F12=End

Each option provides its own menu.
Help text is available to explain what you are supposed to do.

Some further explanations follow here.

  1. EPOLICEDTA/"MessageQueue_Name" control file.
    A control file is needed for each message queue you want to control. Such control file must have the same name as the message queue to be controlled.
    In most cases one would need to control the system operator message queue, QSYSOPR. A control file named QSYSOPR is already available in library EPOLICEDTA.
    Should you however need to control another message queue, the related control file would be automatically created when you, by selecting option 1 in the menu above, are prompted command UPDMSGQ1 and specify a message queue different from QSYSOPR.
    For each message - from that message queue - that you want be intercepted by command RCVMSGQ, you will be asked to specify:
    • a message id
      the message ID that the automat should process.
      This is the ID of the message sent to the message queue (QSYSOPR), NOT the message ID of an error message. Run command DSPMSG QSYSOPR and use option 5 to display the correct message ID.
    • a sequence number
      different cases are possible depending on different match patterns (see next).
      This field is used to sequence the possible cases for a given message ID.
    • The following 3 fields are optional.
      • compare data
        If needed, type a match pattern (string) to be found in the message text
      • compare data position
        If you specified some compare data, you may specify the starting position of such compare-data string in the message text. If you omit this piece of information, the starting position is not checked.
      • compare data length
        If you specified some compare data, you may specify the length of the compare-data string (this is may be needed, if the compare data includes some trailing blanks). If you omit this piece of information, trailing blanks in the compare-data string are ignored.
    • a message reply
      the reply that should be given to an inquiry message (usually a single character)
    • commands before/after reply
      (optional) commands that should be run.
      For an inquiry message it is possible to run commands before and/or after the reply.
      Commands are mandatory for non-inquiry messages (in this case, specifying them in the "before" or "after" field is the same).
      In these two fields you may enter a sequence of individual commands each ending with character ';' .
    EXAMPLE- Let us assume that you want to intercept error message CPA0701 and provide an 'I' reply if the error message is caused by program MYPGM. The error message looks like
    CPFxxxx received by MYPGM at nnn00. (C D I R).
    You should do the following:
    • enter command DSPMSGD CPA0701
    • select option 1 (Display message text); you would read the following:
      &3 received by &1 at &4. (C D I R)
      Now you know that the message variable containing the value "MYPGM" is &1.
    • select option 2 (Display field data); you would read the following:
      Field Data Type Length
      &1*CHAR10
      &2*CHAR10
      &3*CHAR7
      &4*CHAR10
      &5*CHAR132
    • you may then conclude that
      • the compare data length is 10
      • the compare data offset is 1.
  2. "EPOLICEDTA/SENDERMAIL" control file
    This file is used only if you need that an e-mail message should be sent to some people for notyfing them about the action taken over an intercepted message.
    This file contains the sender's data: senders first name, last name and e-mail address.
  3. "EPOLICEDTA/USRPRFMAIL" control file
    This file is used only if you need that an e-mail message should be sent to some people for notyfing them about the action taken over an intercepted message.
    Records in this file do describe the e-mail addresses of given user profiles.
    When command EPOLICE/RCVMSGQ is run, any time an automated reply is processed, the job user profile is searched vs file EPOLICEDTA/USRPRFMAIL.
    An e-mail message is then sent for any record matching the job user profile as search key (this means that you can have multiple people made aware of the actions taken by a reply-message-queue job).
    For each record you are requested to specify:
    • User profile
      the user profile matching the user profile of the RCVMSGQ job that will be submitted
    • First name / Last name
      of the person supposed to receive these e-mail messages
    • E-mail address
      of the person supposed to receive these e-mail messages.
    • if you want to use the MMAIL SMS support, the person ID as specified in the MMAIL SMS phone book MMAILDATA/CLICKABOOK (see this page).
3- Command EPOLICE/RCVMSGQ
Once entered, this command will start an endless job in subsystem QSYSWRK.
It is up to you to establish how to have this enabled permanently, via an AJE, a scheduled job entry, or anything similar.
Command parameters:
  • Message queue
    the qualified name of the message queue messages should be received from.
    It defaults to QSYS/QSYSOPR.
    However, other message queues can be handled, see topic 2.1 above.
  • Workstn to receive messages
    Device name of the workstation device that should also receive a break message any time an automated reply is processed.
    Special values:
    • *CURRENT
      the name of the workstation submitting the request from the interactive environment
    • *NONE
      do not use this feature

WARNINGS
  • Before running command EPOLICE/RCVMSGQ make sure that the message queue (example: QSYSOPR) is not EXCL held by any job (example: check by command WRKOBJLCK OBJ(QSYSOPR) OBJTYPE(*MSGQ) ).
  • Only messages sent from jobs with INQMSGRPY(*RQD) can be replied from pgm EPOLICE/RCVMSGQ. Messages from jobs with INQMSGRPY(*DFT) or INQMSGRPY(*SYSRPYL) receive their replies directly from the system before pgm EPOLICE/RCVMSGQ can reply.
4- Testing command EPOLICE/RCVMSGQ
If you like, you may test command EPOLICE/RCVMSGQ in the following way:
  1. Run command RCVMSGQ MSGQ(EPOLICE/TESTMSGQ) WRKSTN(*CURRENT)
    This commans submits a job, named TESTMSGQ, which listens on message queue EPOLICE/TESTMSGQ.
  2. Run command CALL PGM(EPOLICE/TESTRCVMSG)
    This program generates a message in message queue EPOLICE/TESTMSGQ.
    As a result, job TESTMSGQ (listening on this message queue) will
    • send a message to the *CURRENT user profile
    • send an e-mail message to appropriate e-mail addresses specified in file EPOLICEDTA/USRPRFMAIL. The sender will be the one specified in file EPOLICEDTA/SENDERMAIL.
5- Note on e-mail messages
Some recipient e-mail boxes may reject messages sent from the EPOLICE/RCVCMSGQ command. Major reject reasons could be:
  • The sender's e-mail address has no corresponding mail-box (the sender's e-mail address does not exist)
  • The domain of the sender's e-mail address is not the same as the domain of the sending computer.
GMAIL receiving mail boxes are the most critical in receiving messages.
    Contact