TAA Tools
RCVMSGKEY       RECEIVE MESSAGE KEY                    TAAMSJQ

The Receive  Message Key command  receives a message  from the job  log
(intended  for  a low  level  message).   You  must  run the  RTVMSGKEY
command  (part of  the RMVMSGKEY  tool) to  set a  mark in the  job log
prior  to  and  after  running  a  function  that  produces  low  level
messages.   Then RCVMSGKEY  may be  used to  receive either  a specific
message ID  or a loop may be written  to receive more than one message.

RCVMSGKEY may  also be used  for any  message in  the job  log, but  is
intended  for low  level  messages created  by  programs  which are  no
longer active.

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.

If  a single  low level  message is  to be  received  and the  MSGID is
known, the following would be typical code:

             DCL        &MSGKEY *CHAR LEN(4)
             DCL        &ENDKEY *CHAR LEN(4)
             DCL        &MSG *CHAR LEN(512)
              .
             SNDPGMMSG  MSG('Dummy to establish a msgkey')
                        TOPGMQ(*SAME)
             RTVMSGKEY  MSGKEY(&MSGKEY)
                        /*                                 */
                        /* Some function that causes a low */
                        /*   level message                 */
                        /*                                 */
             RTVMSGKEY  MSGKEY(&ENDKEY)
             RCVMSGKEY  MSGKEY(&MSGKEY) MSGID(xxxxxxx) +
                           ENDKEY(&ENDKEY) MSG(&MSG)

If  only  a single  message exists  and the  message  ID is  not known,
specify MSGID(*ALL).

Additional parameters  exist on  RCVMSGKEY  such as  message data,  the
message type, etc.

To  receive  all  messages  from  a  function  that  causes  low  level
messages,  the  following  approach  should  be  used  which  uses  the
RTNMSGKEY value as the  next MSGKEY to use  after the first message  is
received:

             DCL        &MSGKEY *CHAR LEN(4)
             DCL        &ENDKEY *CHAR LEN(4)
             DCL        &RTNMSGID *CHAR LEN(7)
             DCL        &MSG *CHAR LEN(512)
             DCL        &RTNMSGKEY *CHAR LEN(4)
              .
             RTVMSGKEY  MSGKEY(&MSGKEY)
                        /*                                          */
                        /* Some function that causes one or         */
                        /*   more low level messages                */
                        /*                                          */
             RTVMSGKEY  MSGKEY(&ENDKEY)
 LOOP:       RCVMSGKEY  MSGKEY(&MSGKEY) MSGID(*ALL) ENDKEY(&ENDKEY) +
                          RTNMSGKEY(&RTNMSGKEY) +
                          RTNMSGID(&RTNMSGID) MSG(&MSG)
             MONMSG     MSGID(TAA9891) EXEC(DO) /* No more messages */
                        /*                                          */
                        /*  Your code to handle the end of the      */
                        /*    messages.                             */
                        /*                                          */
             ENDDO      /* No more messages */
                        /*                                          */
                        /*  Your code to process a single message   */
                        /*                                          */
             CHGVAR     &MSGKEY &RTNMSGKEY
             GOTO       LOOP

RCVMSGKEY escape messages you can monitor for
---------------------------------------------

      TAA9891    The message ID was not found if a specific
                   message ID was requested or no more messages
                   exist if *ALL was requested.

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

RCVMSGKEY Command parameters                          *CMD
----------------------------

   MSGKEY        The message  key retrieved from the  RTVMSGKEY command
                 (part  of  the RMVMSGKEY  tool).    RTVMSGKEY must  be
                 issued prior  to using  a function  which creates  low
                 level  messages.   A  *CHAR  LEN(4) variable  must  be
                 used.

   MSGID         The  message ID  to  be received.   If  only  a single
                 message  is  to  be  received and  the  message  ID is
                 known, specify  it.   If  a single  message  is to  be
                 received  and the  message  ID is  not known,  specify
                 *ALL.

                 If  a series  of messages is  to be  received, see the
                 example in the  tool documentation for  how to code  a
                 loop.

   ENDKEY        The message  key retrieved  from RTVMSGKEY  that marks
                 the  end of the messages  that should be  received.  A
                 *CHAR LEN(4) variable must be used.

   MSGTYPE       The type of  message that  was received.   This is  an
                 optional  return  variable   that  if  used   must  be
                 specified as *CHAR LEN(2).

                 To see  the meaning of the return  values, use the TAA
                 DSPMSGTYP command.

   RTNMSGKEY     The  message  key of  the  message that  was received.
                 This  is needed  if  you  are receiving  more  than  a
                 single  message  ID.   See  the  example  in the  tool
                 documentation.   This  is an optional  return variable
                 that if used must be specified as *CHAR LEN(4).

   RTNMSGID      The message  ID  of  the message  that  was  received.
                 This  is an  optional  return  variable that  if  used
                 must be specified as *CHAR LEN(7'.

   MSG           The  first level  text  of the  message.   This  is an
                 optional  return  variable  that   if  used  must   be
                 specified as *CHAR LEN(512).

                 If an  impromptu message exists,  the message  text is
                 returned in the MSGDTA parameter.

   MSGDTA        The  message  data  of   the  message.    This  is  an
                 optional   return  variable  that   if  used  must  be
                 specified as *CHAR LEN(512).

   MSGF          The message file  that was used  to send the  message.
                 This  is  an optional  return  variable  that if  used
                 must be specified as *CHAR LEN(10).

   MSGFL         The  message file  library that  was used to  send the
                 message.   This is  an optional  return variable  that
                 if used must be specified as *CHAR LEN(10).

   SNDPGM        The  name of  the  sending program  that  was used  to
                 send  the   message.    This  is  an  optional  return
                 variable that  if  used  must be  specified  as  *CHAR
                 LEN(12).

   DATESENT      The date the  message was sent  in CYMD format.   This
                 is an  optional return variable  that if used  must be
                 specified as *CHAR LEN(7).

   TIMESENT      The  time  the  message  was  sent  in  HHMMSS format.
                 This  is an  optional  return  variable that  if  used
                 must be specified as *CHAR LEN(6).

   SENTTYPE      The type  of the sender.   This is an  optional return
                 variable  that  if  used must  be  specified  as *CHAR
                 LEN(1).

                 For a  full  explanation  see  the QMHRCVPM  API.    A
                 brief explanation is:

                   0 = OPM or SLIC program
                   1 = Procedure within an ILE Program
                   2 = Procedure within an ILE Program with a long name
                   3 = SLIC program 13 or more character name

   RCVTYPE       The  type  of  the  receiving program.    This  is  an
                 optional   return  variable  that  if   used  must  be
                 specified as *CHAR LEN(1).

                 For a  full  explanation  see the  QMHRCVPM  API.    A
                 brief explanation is:

                   0 = OPM or SLIC program
                   1 = Procedure within an ILE Program
                   2 = Procedure within an ILE Program with a long name

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

Because the command  returns variables, RCVMSGKEY  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
   ------        ----    ---------      ----------    ----------

   RCVMSGKEY     *CMD                   TAAMSJQ       QATTCMD
   TAAMSJQC      *PGM       CLP         TAAMSJQC      QATTCL
					

Added to TAA Productivity tools April 15, 2011


Home Page Up to Top