The Retrieve Diagnostic Message command is designed to assist in
retrieving the diagnostic message which immediately precedes some
escape messages.
RTVDIAGMSG can be helpful when you want to handle certain error
situations where the escape message is general purpose and the
immediately preceding diagnostic explains the specific error
condition.
To use RTVDIAGMSG, you would normally know the general escape message
ID and the diagnostic message ID that you are looking for.
For example, ALCOBJ sends escape message CPF1002 when an object is
already allocated and the lock cannot be achieved. For most other
typical error conditions (e.g. no such object exists, the system
does not support the object for ALCOBJ), the system sends a specific
diagnostic message followed by a generalized escape message
(CPF1085).
Assume you are attempting to allocate an object, but do not know the
object type is actually valid for ALCOBJ. If you attempt to allocate
a non Data Base file, a diagnostic (CPF0984) stating that the file
type is invalid will be issued before the CPF1085 escape message.
The following shows how to code RTVDIAGMSG:
DCL &DIAGMSGID *CHAR LEN(7)
.
ALCOBJ OBJ((&xxx *FILE *EXCLRD)
MONMSG MSGID(CPF1085) EXEC(DO) /* Some error */
RTVDIAGMSG DIAGMSGID(&DIAGMSGID)
IF (&DIAGMSGID *EQ 'CPF0984') DO /* Invalid */
.
. /* Your code to handle invalid type */
.
ENDDO /* Invalid type */
.
. /* Your code to handle other CPF1085 */
. /* error conditions */
.
ENDDO /* Some error */
You may also choose to monitor for other conditions on ALCOBJ such as
CPF1002 (object is already allocated).
You can monitor for CPF0000 and use DSPERRMSG for any error
condition. For example, SBMJOB sends a CPF1139 diagnostic message
when the JOBD is invalid and then follows it with the CPF1138
generalized escape message ('Errors in SBMJOB'). If you had special
processing for the CPF1139 case, your code could look like:
DCL &DIAGMSGID *CHAR LEN(7)
.
SBMJOB JOBD(xxx) ...
MONMSG MSGID(CPF0000) EXEC(DO) /* Some error */
RTVDIAGMSG DIAGMSGID(&DIAGMSGID)
IF (&DIAGMSGID *EQ 'CPF1139') DO /* Bad JOBD */
.
. /* Your code to handle bad JOBD */
.
ENDDO /* Bad JOBD */
.
. /* Your code to handle any other */
. /* SBMJOB error */
.
ENDDO /* Some SBMJOB error */
Accessing an escape without a diagnostic
----------------------------------------
It is possible to use RTVDIAGMSG when no diagnostic message exists.
For example, you could monitor for CPF0000 and then use RTVDIAGMSG to
return the escape and the diagnostic if it exists.
Blanks will be returned for all of the diagnostic return variables if
no diagnostic message exists. Optional return parameters exist for
the escape message information.
Other comments
--------------
If no escape message exists, TAA9891 is sent from RTVDIAGMSG as an
escape message.
You should not attempt to use RCVMSG on the escape or diagnostic
message before or after the use of RTVDIAGMSG. The CPP for
RTVDIAGMSG does a RCVMSG of the escape and diagnostic message from
your program's message queue. The messages are left the program
message queue, but since they have been received, they cannot be
re-received by your program.
Command parameters *CMD
------------------
All of the parameters are return variables. The diagnostic return
variables will be blank if no diagnostic message exists.
DIAGMSGID The diagnostic message ID. This is a required
return variable and must be declared as *CHAR
LEN(7).
DIAGMSGDTA The diagnostic message data. This is an optional
return variable. If used, it must be declared as
*CHAR LEN(512).
DIAGMSGF The diagnostic message file. This is an optional
return variable. If used, it must be declared as
*CHAR LEN(10).
DIAGMSGFL The diagnostic message file library. This is an
optional return variable. If used, it must be
declared as *CHAR LEN(10).
DIAGMSG The diagnostic message text. This is an optional
return variable. If used, it must be declared as
*CHAR LEN(512).
DIAGMSG2 The diagnostic message 2nd level text. This is an
optional return variable. If used, it must be
declared as *CHAR LEN(512).
ESCMSGID The escape message ID. This is a required return
variable and must be declared as *CHAR LEN(7).
ESCMSGDTA The escape message data. This is an optional return
variable. If used, it must be declared as *CHAR
LEN(512).
ESCMSGF The escape message file. This is an optional return
variable. If used, it must be declared as *CHAR
LEN(10).
ESCMSGFL The escape message file library. This is an
optional return variable. If used, it must be
declared as *CHAR LEN(10).
ESCMSG The escape message text. This is an optional return
variable. If used, it must be declared as *CHAR
LEN(512).
ESCMSG2 The escape message 2nd level text. This is an
optional return variable. If used, it must be
declared as *CHAR LEN(512).
Restrictions
------------
** Since the command returns variables, it can only be used in a
CL program.
** An escape message must exist. A diagnostic message may not
exist.
** The immediately preceding diagnostic message from the last
escape is retrieved. If multiple diagnostics exist, only the
first is retrieved.
** It is possible to receive misleading information if the last
message in the program message queue is a diagnostic and an
escape message is sent without a diagnostic.
** You should not attempt to use RCVMSG on the escape message or
the diagnostic message in your program either before or after
RTVDIAGMSG.
** It is possible to send a diagnostic message without using a
message in a message file. You can normally determine that
this has occurred by checking the MSG return variable for
non-blanks and the MSGF return variable for blanks. It is
also possible to send a diagnostic message without any data.
This occurrence cannot be distinguished as all of the
diagnostic return variables will be blank.
Prerequisites
-------------
The following TAA Tools must be on your system:
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVDIAGMSG *CMD TAAMSGX QATTCMD
TAAMSGXC *PGM CLP TAAMSGXC QATTCL
|
