RTVDIAGMSG      RETRIEVE DIAGNOSTIC MESSAGE            TAAMSGX

 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

Added to TAA Productivity Tools May 1, 1996


Home Page

Last modified on March 10, 2014 © 1995, 2014 - TAA Tools, Inc.