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