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)
MSGTYPE(*DIAG)
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.
Restrictions
------------
None.
Prerequisites
-------------
The following TAA Tools must be on your system:
RTVVALA Retrieve value attributes
SNDESCINF Send escape information
SNDESCMSG Send escape message
Implementation
--------------
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
|
