TAA Tools
DSPPGMSTMT      DISPLAY PROGRAM STATEMENT              TAAPGNP

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
					

Added to TAA Productivity tools October 15, 2003


Home Page Up to Top