The Display Program Statement command is intended as a debugging aid
when an error has occurred and the MI instruction number is known,
but the HLL source sequence number is not. By entering the program
name and the MI instruction number, DSPPGMSTMT displays a spooled
file with the HLL source sequence number and statement. Only CLP and
RPG OPM program types are supported. The source for the program must
exist.
The program must be able to be created in QTEMP. This means that any
externally described files must exist on the library list.
A typical command would be:
DSPPGMSTMT PGM(xxx) MI(yyyy)
A display would appear with the HLL statement and its source sequence
number. Optionally included are the MI statements that are used to
run the HLL statement.
If the last source change date/time does not agree between the
program object and the source member, special text occurs on the
listing and in the completion message as the information provided may
not be valid.
CL Program Error Handling
-------------------------
If a typical CL program encounters an escape message, the CPA0701
inquiry message occurs describing the condition and allows a
responses of Cancel, Ignore, Dump, or Retry. The inquiry message
includes the CL statement number where the error occurred.
Therefore, if CPA0701 occurred, there is little need for the
DSPPGMSTMT command.
The TAA Tools prior to Sept 2003 predominantly used the standard
error handling approach provided by the DUPSTDSRC TAA Tool (TAASTDAC
member). This monitors for all conditions which prevented the the
CPA9701 Inquiry message. The advantage of the standard error
handling routine is that users do not get a chance to say 'Ignore'
which is the typical human response. In addition, if the error
occurs in batch, the job is aborted and does not hold the job queue
waiting for a response to the inquiry message.
The standard error handling code 'bubbles up' the escape message and
a prior diagnostic to the calling program. If the calling program is
from a command line, you see the error messages as if they had
occurred from entering the command that failed.
There were two disadvantages to the TAASTDAC code.
** If a program deep in the stack has an error, the bubbling up
of messages prevents the program that first encountered the
message from being known.
** If a program failed on a command like CHKOBJ and there were
multiple CHKOBJ commands within the program, it could not be
determined which one had failed.
In most cases, the error condition was fairly obvious and the
advantages of the standard error handling approach outweighed the
disadvantages. However, as more complex tools were written, the
disadvantages began to appear more frequently.
Accessing the MI instruction number of the CL command in error
--------------------------------------------------------------
When a standard error handling routine takes charge of an error, it
uses RCVMSG to receive the escape message so it can be resent. The
RCVMSG command provides a return parameter for SENDER information.
This SENDER information includes the MI instruction number. There is
a *SHORT (default) and *LONG form of SENDER information on RCVMSG.
The *SHORT form has 80 bytes and includes other information besides
the MI instruction number.
The new standard error handling code (used by many TAA Tools as of
Sept 2003) uses the SENDER information and the SNDESCINF TAA command
to format a message that is placed in the job log. The message
includes both the program name that encountered the error and the MI
instruction number. Knowing this information allows the use of
DSPPGMSTMT to determine the HLL statement and source sequence number
that caused the error.
The new source member TAASTDAC provided for DUPSTDSRC now includes
accessing the SENDER information and the new SNDESCINF command.
It is not necessary to use SNDESCINF. You could use your own
solution to capture the program and MI instruction number to allow
the use of DSPPGMSTMT.
RPG Error handling
------------------
RPG in general will describe the HLL statement that is in error.
This occurs regardless of whether observability has been removed from
the program.
Therefore, although DSPPGMSTMT may used on an RPG program, it is
normally not needed because the job log typically contains the HLL
statement number.
DSPPGMSTMT escape messages you can monitor for
----------------------------------------------
TAA9891 Only CLP and RPG OPM programs are supported
TAA9892 No source information available
TAA9893 The program failed to create in QTEMP
Escape messages from based on functions will be re-sent.
Command parameters *CMD
------------------
PGM The qualified name of the program to retrieve
information from. Only CLP and RPG OPM programs
(attribute CLP or RPG) are valid. The library value
defaults to *LIBL. *CURLIB may also be used.
MI The MI instruction number to be searched for.
LISTMI A *YES/*NO value that determines if the MI
statements that are used to run the HLL statement
should be listed. *NO is the default which prevents
the listing of the MI statements.
*YES may be specified to list the MI statements.
OUTPUT How to output the results. * is the default to
display the spooled file if the command is entered
interactively. The spooled file is deleted after it
is displayed. The command always sends a completion
message describing the HLL statement where the MI
instruction was found.
If the command is entered in batch or *PRINT is
specified, the spooled file is output and retained.
DLTCRTLIST A *YES/*NO parameter for whether to delete the
compiler listing which is generated for the program
created in QTEMP. *YES is the default to delete the
listing.
*NO may be specified to retain the listing which
contains the generated MI instructions. The
generation is caused by specifying GENOPT(*LIST) on
the CRTxxxPGM command.
SRCFILE The source file used to create the program in QTEMP.
The default is *PGM meaning to use the same source
file name as was originally used to create the
program.
A qualified library name may be entered along with
*PGM or a specific source file name to use a
different library.
If a specific name is entered (not *PGM) a specific
library must be entered.
Note that the name of the source member must be the
same as that used when the program was originally
created.
Restrictions
------------
Only OPM programs of type CLP or RPG are supported.
The program is re-created in QTEMP. Therefore, any external file
descriptions must exist on the library list.
If the last source change date/time does not agree between the
program object and the source member, special text occurs on the
listing and in the completion message as the information provided may
not be valid.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKOBJ3 Check object 3
CVTDAT Convert date
CVTTIM Convert time
HLRMVMSG HLL Remove message
RTVPGMA Retrieve program attributes
RTVSPLFID Retrieve spooled file ID
RTVSYSVAL3 Retrieve system value 3
SNDCOMPMSG Send completion message
SNDESCINF Send escape information
SNDESCMSG Send escape message
SNDSTSMSG Send status message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
DSPPGMSTMT *CMD TAAPGNP QATTCMD
TAAPGNPC *PGM CLP TAAPGNPC QATTCL
TAAPGNPR *PGM RPG TAAPGNPR QATTRPG
|
