TAA Tools

 RMVMSGKEY       REMOVE MESSAGE KEY                     TAAMSJP

 The  Remove Message  Key  tool  provides  two commands  (RTVMSGKEY  and
 RMVMSGKEY)  which  should be  bracketed  around  commands that  produce
 messages  (including low  level messages) that  need to  be cleaned up.
 When developing  CL  programs,  it  is desirable  to  cleanup  messages
 produced by  functions within the  program.  Many system  commands send
 messages  to  low  level  programs that  cannot  be  removed  by RMVMSG
 CLEAR(*ALL).     Low  level   messages  can   also   occur  from   user
 programming.

 The  definition of  a  low level  message  is  one that  is  sent to  a
 program  that is inactive  (no longer in  the program stack).   You can
 determine this by using  F1 on a  message and then F9  to see the  name
 of the TOPGMQ.

 Most messages  are  sent to  the previous  program  message queue  (the
 calling  program's  message queue)  and  can be  removed  by RCVMSG  or
 RMVMSG  CLEAR(*ALL).   If the  messages you want  to remove  are all in
 the current  program message  queue, you  should use  RCVMSG or  RMVMSG
 CLEAR(*ALL) as these are more efficient.

 RMVMSG  PGMQ(*ALLINACT) could  be used  to remove  low  level messages,
 but  this removes all  messages in the  job log  from inactive programs
 thus destroying any audit trail.

 A typical  situation  where  RMVMSGKEY  can  be of  value  is  where  a
 GRTOBJAUT command is  entered in a CL  program.  Assume you  entered in
 a CL program:

              GRTOBJAUT   OBJ(ABC) OBJTYPE(*PGM)
                           USER(&USER) AUT(*USE)

 Two messages are produced:

        CPI2201  *INFO   Describes the authority granted
                           - One message occurs for each named user
                           - Sent to the QSYGRAUT program which is
                              no longer active

        CPC2201  *COMP   Summary completion message
                           - Sent to TOPGMQ(*PRV)

 Assuming  the GRTOBJAUT command  had been run  in a CL  program, RMVMSG
 CLEAR(*ALL) will remove  the *COMP message  because it is  sent to  the
 program  message queue  that  issued  GRTOBJAUT.   However,  the  *INFO
 message (one  per user) cannot  be cleaned up  because it is  sent to a
 program message queue of a program that is no longer active.

 The  use of  RTVMSGKEY and  RMVMSGKEY will  cleanup the messages.   The
 typical use would be:

             DCL         &MSGKEY *CHAR LEN(4)
              .
             RTVMSGKEY   MSGKEY(&MSGKEY)
                         /*                                          */
                         /* Commands that produce messages           */
                         /*                                          */
             RMVMSGKEY   MSGKEY(&MSGKEY)

 The RTVMSGKEY command uses SNDPGMMSG  to send a message to the  job log
 and retrieves  the message key in  the &MSGKEY parameter.   One or more
 commands  may  then  be  used that  produce  messages.    The RMVMSGKEY
 command begins by  using SNDPGMMSG  and receives back  the message  key
 of the sent  message.  This becomes the  'To' key.  A  loop then occurs
 where  messages are  read  using the  QMHRCVPM API  beginning  with the
 &MSGKEY value (the 'From'  key).  Any messages  read are removed  until
 the message with the 'To' key has been read.

 RTVMSGKEY escape messages you can monitor for
 ---------------------------------------------

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

 RMVMSGKEY escape messages you can monitor for
 ---------------------------------------------

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

 RTVMSGKEY Command parameters                          *CMD
 ----------------------------

    MSGKEY        The message key  to be used on the  RMVMSGKEY command.
                  This  is  a required  return  parameter  that must  be
                  specified as *CHAR LEN(4).


 RMVMSGKEY Command parameters                          *CMD
 ----------------------------

    MSGKEY        The   message  key  to  be  used  as  the  'From'  key
                  retrieved by the RTVMSGKEY command.


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

 The commands may only be used in a CL program.

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

 The following TAA Tools must be on your system:

      SNDESCINF       Send escape information
      SNDESCMSG       Send escape message

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

 None, the tool is ready to use.

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

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

    RTVMSGKEY     *CMD                   TAAMSJP       QATTCMD
    RMVMSGKEY     *CMD                   TAAMSJP2      QATTCMD
    TAAMSJPC      *PGM       CLP         TAAMSJPC      QATTCL
    TAAMSJPC2     *PGM       CLP         TAAMSJPC2     QATTCL

 Structure
 ---------

 RTVMSGKEY   Cmd
    TAAMSJPC   CL pgm

 RMVMSGKEY   Cmd
    TAAMSJPC2   CL pgm

Added to TAA Productivity Tools April 15, 2011


Home Page

Last modified on November 19, 2014 © 1995, 2014 - TAA Tools, Inc.