TAA Tools

The Send  Program Message  3 command  allows a *DIAG,  *COMP, or  *INFO
message to be  sent to the caller from a sub  or sub-sub program.  This
can  provide better feedback when the  sub program needs to communicate
to the caller  of a  program.  The  QMHSNDPM API is  used to allow  the
message to be sent up the stack.

To send  an escape message up  the stack, see the  SNDESCMSG5 TAA tool.

The  system SNDPGMMSG  command will  allow a  message to  be sent  to a
specific program message queue.   SNDPGMMSG3 allows sending to a  prior
program message queue without knowing the name.

A typical SNDPGMMSG3 command would be:

             SNDPGMMSG3  MSG('Member xxx was in use') STKCNT(3)

The message  would be sent  using the  MSGDTA parameter of  the CPF9898
message from QCPFMSG in QSYS.

Assume  the PGMA program is  to be called from  a command entry display
which calls a sub  program (PGMB) to  process a list  of members.   You
want PGMB  to complete the  list even  if an error  occurs and PGMA  to
send an  escape message if any  error was found during PGMB.   You want
to provide feedback from PGMB for any specific errors.

It  is easy  to monitor for  an error in  PGMB (set an  error flag) and
continue processing.   You can return  the error flag  to PGMA so  that
an escape  message is  sent.   But how  do you inform  the user  of the
error  or errors that PGMB encountered?   You can leave the messages in
the program message queue,  but this can cause  confusion as there  may
be many  messages sent to PGMB.   You can  send a message from  PGMA to
PGMB,  but there may  be many messages  generated by PGMA  which can be
also be  confusing if  the messages  are left  in  the program  message
queue.  It  is usually best to clean  up any messages so that  the user
sees only the important information.

The  ideal solution  is to  send  a message  from PGMB  to  the command
entry  display (or  the function  that invoked  PGMA).   SNDPGMMSG will
only allow a message to be  sent to the previous caller.   However, the
QMHSNDPM API  will let you  send messages from  deep in the stack  to a
prior  program  message queue.    SNDPGMMSG3 uses  the API  to  allow a
simple command interface to do this.

Determining the Stack Counter value

If PGMA calls PGMB  and PGMB uses SNDPGMMSG3 to  send a message to  the
caller  of PGMA,  you need  STKCTR(3).   A value  of 1  is the  current
program,  a value  of 2  is the caller,  and 3  is the  program message
queue prior for the caller of PGMA.

If PGMA  calls  PGMB  and  PGMB  calls  PGMC  which  wants  to  send  a
diagnostic message to the caller of PGMA, use STKCTR(4).

If ILE  programs are used,  you need to  increase the stack  counter to
account for the ILE primary program.

For either OPM  or ILE programs, if a  program calls other programs and
remains in the stack, you must account for them also.

SNDPGMMSG3 escape messages you can monitor for

None.  Escape messages from based on functions will be re-sent.

Using SNDPGMMSG3 from a HLL program

You can use SNDPGMMSG3 from a HLL program such as from RPG:

     I              'TAATOOL/TAAMSJTC'    C         DIAG

     C                     MOVEL'xxx'     MSGTXT           Message text
     C                     CALL DIAG                       SNDPGMMSG3
     C                     PARM           MSGTXT256        Message text
     C                     PARM 3         STKCTR  20       Stack cntr
     C                     PARM '*DIAG'   MSGTYP  5        Msg type

RPGLE code would look as follows:

      * Prototype for using SNDPGMMSG3 from RPGLE
     D SndPgmMsg3      pr                  extpgm('TAATOOL/TAAMSJTC')
     D   MsgTxt                     256    const
     D   StkCtr                       2p 0 const
     D   MsgTyp                       5    const

     C                   callp     SndPgmMsg3('The message text':
     C                               3:'*DIAG')

SNDPGMMSG3 Command parameters                         *CMD

   MSG           The  message text to be sent as  a message.  Up to 256
                 bytes may be sent.

   STKCTR        The program message queue  to be sent to prior  in the
                 stack.  It must be in a range of 1 to 99.

                 3 is  the default  meaning it is  sent to  the program
                 message  queue that is 3 higher  in the program stack.

                 A value  of 1  is  the program  message queue  of  the
                 current program  (the one  that uses  SNDPGMMSG3).   A
                 value  of 2 is  the program message  queue that called
                 the program that  uses SNDPGMMSG3.   A value  of 3  is
                 the program message queue of the prior program.

   MSGTYPE       The message  type to be  sent.   *DIAG is the  default
                 for a diagnostic type.

                 *INFO  (information)  or *COMP  (completion)  may also
                 be used.




The following TAA Tools must be on your system:

     RTVVALA         Retrieve value attributes
     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message


None, the tool is ready to use.

Objects used by the tool

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

   SNDPGMMSG3    *CMD                   TAAMSJT       QATTCMD
   TAAMSJTC      *PGM       CLP         TAAMSJTC      QATTCL

Added to TAA Productivity tools July 15, 2011

Home Page Up to Top