TAA Tools
DSPERRMSG       DISPLAY ERROR MESSAGE                  TAAMSGY

The  Display  Error  Message command  can  be  helpful  in  interactive
programs  when  a  complex command  is  executed  and  fails with  some
unusual  error.    DSPERRMSG  provides  a  display  that  describes the
escape message and the previous diagnostic (if it exists).

If the user is  able to understand the  error message and knows how  to
recover, the  Enter key is described  as a Retry.   Your program should
retry the command that failed.

In  some  applications,  it  is impractical  to  code  for  every error
condition a  user may  make.   Rather than  aborting  the program,  the
user may  be able  to correct  the error after  seeing both  the escape
message  and the diagnostic.   DSPERRMSG is  a simple solution  that in
most cases will allow  the user to understand  the problem without  the
need for complex coding (e.g.  a message subfile).

Formatting of  the message text  is done using  the FMTLIN TAA  Tool so
that no words are split at the end of a workstation line.

Examples
--------

The following  is an example of  DSPERRMSG being used.  The  code is in
the  proper format to  be copied into  a CL Program.   First use CPYTAA
TAAARCMBR(DSPERRMSG) to copy  the source for this  documentation member
to QATTINFO in TAATOOL.

 ALC:        ALCOBJ     OBJ((&xxx *FILE *SHRRD)
             MONMSG     MSGID(CPF0000) EXEC(DO) /* ALCOBJ error */
             DSPERRMSG  /* TAA Tool command */
             MONMSG     MSGID(TAA9897) EXEC(GOTO CANCEL) /* F12 */
             GOTO       ALC /* Branch back to retry */
             ENDDO      /* ALCOBJ error */
                        /* If successful ... */
               .
 CANCEL:                /* Handle Cancel request */

The  ALCOBJ command  may  fail for  many  different reasons.   In  some
cases,  a diagnostic message  is sent describing  the error  and then a
standard escape message (e.g.  CPF1085).   The user would see both  the
escape  message  and  the  diagnostic  message  on  the  same  display.
Function  keys allow access  to the 2nd  level text of  either message.
From these additional  displays, the user  is allowed to  use an F  key
to access the DSPMSGD display for the messages.

The user can  use F12 to cancel  from the DSPERRMSG displays.   You can
use a  standard error handling  function for this (e.g.   CLPSTDERR TAA
Tool) or monitor for the message TAA9897.

For  example, if you have a  standard error handling routine, your code
could look like:

 ALC:        ALCOBJ     OBJ((xxxx *FILE *SHRRD)
             MONMSG     MSGID(CPF0000) EXEC(DO) /* Some error */
             DSPERRMSG  /* TAA Tool command */
             GOTO       ALC /* Branch back to retry */
             ENDDO      /* Some error */
                        /* If successful ... */

You can monitor  for certain  error conditions and  then use a  CPF0000
Monitor (or any other monitor) for unusual conditions such as:

 ALC:        ALCOBJ     OBJ((xxxx *FILE *SHRRD)
             MONMSG     MSGID(CPF1002) EXEC(DO) /* Already allocated */
               .
             ENDDO      /* Already allocated */
             MONMSG     MSGID(CPF0000) EXEC(DO) /* Some other error */
             DSPERRMSG  /* TAA Tool command */
             GOTO       ALC /* Branch back to retry */
             ENDDO      /* Some other error */
                        /* If successful ... */

DSPERRMSG can  be used effectively when command  selective prompting is
used  in a CL program.   For example, assume you  prompt for the SBMJOB
command.  The user may key  an invalid JOBQ, JOBD, etc.  DSPERRMSG  can
be used  to provide  a simple  means of  allowing the  user to  see the
error and retry the command such as:

 SBM:       ?SBMJOB     ??JOBQ() ??(JOBD) ...
             MONMSG     MSGID(CPF0000) EXEC(DO) /* Some other error */
             DSPERRMSG  /* TAA Tool command */
             GOTO       SBM /* Branch back to retry */
             ENDDO      /* Some other error */
                        /* If successful ... */

Correct coding of DSPERRMSG
---------------------------

  **   DSPERRMSG can only be used in an interactive CL program.

  **   Follow  the  command  that  may  have  an  error with  a  MONMSG
       command.  Any message  ID is valid including  CPF0000.  You  can
       monitor for  both specific  errors and  also for general  errors
       (CPF0000).

  **   Follow the  MONMSG where you need to  provide user feedback with
       DSPERRMSG.

  **   If   DSPERRMSG  completes  successfully,  provide  a  GOTO  that
       branches back to retry the command.

  **   You may choose  to monitor for  TAA9897 (F12 was pressed)  after
       DSPERRMSG or  let a standard  error handling routine  handle the
       escape message.

Comparison with the CL Program Inquiry Message CPA0701
------------------------------------------------------

  **   The  CL Program Inquiry  message allows a  Cancel, Ignore, Dump,
       or Retry option.   The Ignore option can  impact the logic of  a
       program and  can sometimes  make a problem  worse.   Good coding
       practice  would  be to  try  and avoid  the  user  from entering
       'Ignore'.

       DSPERRMSG lets the user  see the problem and  does not allow  an
       'Ignore' option.

  **   If  a generalized  escape  message occurs  such  as provided  by
       CPYF  or  ALCOBJ  where the  escape  message  only  refers to  a
       preceding  diagnostic  message, the  CPA0701 Inquiry  message is
       not very effective.  The  user sees only the description  of the
       escape message ID.   If the cursor is placed  on the message and
       Help  is pressed, the specific error text  can be displayed.  In
       the case of  a generalized escape message,  the user cannot  see
       the  specific  diagnostic  that  occurred prior  to  the  escape
       message from the Inquiry display.

       DSPERRMSG shows both messages on the initial display.

  **   The  CPA0701 message  describes the  program name  that received
       the escape message.   If observability  exists for the  program,
       the CPA0701  Inquiry message will  also describe the  CL Program
       statement where the error occurred.

       DSPERRMSG  provides the program  name where the  error occurred,
       but  not the  statement number.   However,  DSPERRMSG allows you
       to add  your own text  to the display  to describe the  function
       that  is being performed.   This  can be  a lot  more meaningful
       than the statement number.

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

   TEXT          Up  to 3 lines of text (lines  3-5 on the display) may
                 be entered to  describe what the  display is and  what
                 the user should do.

                 The  default  is  *DFT  which  causes  standard  text.
                 This  includes   the  program  name  where  the  error
                 occurred and tells  the user that  if the problem  can
                 be corrected to do  so and then use the  Retry option.

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

  **   The command  can only be used  in a CL program  when executed in
       the interactive environment (not valid in batch).

  **   You  must code  for the  'Retry' option  when the user  ends the
       DSPERRMSG display normally.

  **   DSPERRMSG  can  only  be   used  when  an  escape  message   has
       occurred.  A diagnostic message occurrence is optional.

  **   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.

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

The following TAA Tools must be on your system:

      FMTLIN        Format line

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   DSPERRMSG     *CMD                   TAAMSGY       QATTCMD
   TAAMSGYC      *PGM       CLP         TAAMSGYC      QATTCL
   TAAMSGYD      *FILE      DSPF        TAAMSGYD      QATTDDS
					

Added to TAA Productivity tools May 1, 1996


Home Page Up to Top