The Copy  Program  Message Queue  Message command  copies  one or  more
messages from  the current job's  program message queue  to an external
message  queue.  You must  use RTVMSGKEY to mark  the boundary of where
messages should  begin  to be  sent  from.   CPYPGMQM  may be  used  in
special debugging  situations or on  a normal basis to  capture problem
determination information instead of the entire job log.

A typical series of commands would be:

             DCL        &MSGKEY *CHAR LEN(4)
              .
             RTVMSGKEY  MSGKEY(&MSGKEY)
                        /*  One or more commands that cause */
                        /*  messages to the job's program   */
                        /*  message queue.                  */
             CPYPGMQM   MSGKEY(&MSGKEY) TOMSGQ(xxx)

The  RTVMSGKEY  command  marks  the  beginning  place  in  the  program
message queue  where  messages  should  be  sent.   One  or  more  user
commands may then  be issued which cause messages.   This could include
escape messages which are monitored for.

The  CPYPGMQM command begins by  also using RTVMSGKEY to  mark the last
message key  to  be retrieved.    CPYPGMQM then  accesses  the  program
message queue  beginning at  the &MSGKEY  value and  sends messages  to
the  named external  message queue  using SNDMSG.   Only  messages with
data  are sent.  The messages are  not removed from the program message
queue.

A completion  message  is sent  by CPYPGMQM  describing  the number  of
messages that were sent.

If  no messages  exist  to be  copied,  TAA9891 is  sent  as an  escape
message and may be monitored for.

If  any  messages are  to  be sent  to  the external  message  queue, a
beginning message  is sent  which describes  that  CPYPGMQM is  sending
the messages.   An ending  message also occurs  after the  last message
is sent.

Any  retrieved messages  with a message  type of  *EXCP are  changed to
*ESCAPE types.  This does not cause  an error when sent to an  external
message queue.

CPYPGMQM escape messages you can monitor for
--------------------------------------------

      TAA9891    No messages exist to be resent

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

CPYPGMQM Command parameters                           *CMD
---------------------------

   MSGKEY        The message key  retrieved from the  RTVMSGKEY command
                 (part  of  the   RMVMSGKEY  tool).    A  *CHAR  LEN(4)
                 variable must be used.

   TOMSGQ        The  qualified  name  of  the  message  queue  to send
                 messages to.   The  library value  defaults to  *LIBL.
                 A specific library or *CURLIB may also be used.


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

None.

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

The following TAA Tools must be on your system:

     CHKOBJ3         Check object 3
     EDTVAR          Edit variable
     RSNLSTMSG       Resend last message
     RCVMSGKEY       Receive message key
     RTVMSGTYPD      Retrieve message type description
     SNDCOMPMSG      Send completion message
     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
   ------        ----    ---------      ----------    ----------

   CPYPGMQM      *CMD                   TAAMSKD       QATTCMD
   TAAMSKDC      *PGM       CLP         TAAMSKDC      QATTCL