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
