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
|
