(Author's Note: This week's article is an excerpt from my upcoming book RPG TNT: 101 Dynamite Tips and Techniques for RPG IV Programmers.)
The CL language offers some easy commands to send program messages. To accomplish this in RPG IV requires either calling an API or using a CL program wrapper with the SNDPGMMSG command. The complexity of the APIs often keeps people away from using them, particularly since IBM put a level between the API caller and the previous program/procedure queue.
The solution is the Call-Stack Entry parameter of the QMHSNDPM API combined with the Relative Invocation parameter. The Call-Stack Entry parameter can be set to *, *CTLBDY or *EXT. The relative invocation parameter is normally set to one higher than you think it should be.
The API is a bit complex, but we can wrap in a subprocedure to perform a basic SNDPGMMSG to *PRV.
Here’s the QMHSNDPM API Pprototype:
/include QSYSINC/QRPGLESRC,QUSEC
D QMHSNDPM PR ExtPgm('QMHSNDPM')
D szMsgID 7A Const
D szMsgFile 20A Const
D szMsgData 6000A Const OPTIONS(*varsize)
D nMsgDataLen 10I 0 Const
** Message Type may be one of the following:
** *COMP - Completion
** *DIAG - Diagnostic
** *ESCAPE - Escape
** *INFO - Informational
** *INQ - Inquiry.
** (Only used when ToPgmQ(*EXT) is specified).
** *NOTIFY - Notify
** *RQS - Request
** *STATUS - Status
D szMsgType 10A Const
** Call Stack Entry may be one of the following:
** * - *SAME
** *EXT - The external message queue
** *CTLBDY - Control Boundary
D szCallStkEntry...
D 10A Const
D nRelativeCallStkEntry...
D 10I 0 Const
D szRtnMsgKey 4A
D apiErrorDS LikeDS(QUSEC)
D OPTIONS(*VARSIZE)
A simple subprocedure wrapper for this API can be a bit daunting. With programs consisting of modules and subprocedures, setting the correct parameter values can be challenging.
The subprocedure wrapping I want would allow me to send an impromptu message from within RPG IV, using parameters similar to those of the SNDMSG CL command. Here is the syntax for this subprocedure:
The message text parameter can be any text up to 1024 bytes in length and is required.
The msgtype (message type) parameter may be any of the available message types (in all uppercase), such as *INFO, *COMP, *DIAG, *ESCAPE, or *STATUS. The default, if not specified, is *INFO.
The topgmq (to program queue) parameter identifies the relative program queue to which the message is sent. If unspecified, its default is *SAME (which is represented internally as '*').
The following call to SNDMSG displays a status message on the screen until it is cleared or another status message is displayed.
Unlike native RPG IV built-in functions, subprocedures don't have the luxury of being able to specify user-written special values for parameters. When '*STATUS' is needed for this subprocedure, the value must be enclosed in quotes and specified in all uppercase.
One thing I like to use this routine for is to write information to the joblog at runtime, thus eliminating some debugging. For example:
if NOT %Found();
sndmsg('Customer ' + %char(custno) + ' Not found.');
endif;
This code logs the message to the joblog at the same invocation level as the caller of the SNDMSG procedure.
There are a couple of additional features. The TOPGMQ parameter allows you to specify *PRV or *PRVPGM. Specifying *PRV sends the message to the caller of the procedure that is running SNDMSG. When *PRVPGM is specified, the message is sent to the previous program. This is important when using RPG IV with modules and procedures, as using SNDMSG('hellow' : '*INFO' : '*PRV') from within the mainline calculations of an RPG IV program will cause the message to be sent to the current program's program entry procedure (PEP), not to the previous program. Use *PRV PGM to send it to the previous program.
The source code for the sndmsg() example subprocedure is shown below. It will also be in RPG TNT: 101 Dynamite Tips and Techniques for RPG IV Programmers and will be posted within a few weeks on rpgiv.com/downloads.
// © 2001 by Robert Cozzi, Jr. All Rights reserved.
// Origin: RPG xTools
// Permission to use is hereby granted provided this
// notice is included in its entirety.
/IF DEFINED(*CRTBNDRPG)
H DFTACTGRP(*NO)
/ELSE
H NOMAIN
/ENDIF
// TODO: Include the QMHSNDPM API Prototype here
D SndMsg PR 4A
D szMsg 1024A Const Varying
D szMsgType 10A Const
D OPTIONS(*NOPASS)
D szToPgmQ 10A Const
D OPTIONS(*NOPASS)
/IF DEFINED(*CRTBNDRPG)
/free
sndmsg('Hello World!' );
eval *INLR = *ON;
return;
/end-free
/ENDIF
P SndMsg B Export
*******************************************
** Send an impromptu message to a pgmq
*******************************************
// © 2006 by Robert Cozzi, Jr. All Rights reserved.
// Origin: RPG xTools
// Permission to use is hereby granted provided this
// notice is included in its entirety.
D SndMsg PI 4A
D msg 1024A Const Varying
D szMsgType 10A Const
D OPTIONS(*NOPASS)
D szToPgmQ 10A Const
D OPTIONS(*NOPASS)
*******************************************
/include qsysinc/qrpglesrc,qusec
*******************************************
** Local variables.
D msgType S Like(szMsgType) Inz('*INFO')
D toPgmQ S Like(szToPgmQ) Inz('*')
D msgid S 7A Inz('CPF9897')
D msgf DS 21
D MsgFile 10A Inz('QCPFMSG')
D MsgLib 10A Inz('*LIBL')
D
D msgData S 1024A
D nDataLen S 10I 0 Inz(0)
D nRelInv S 10I 0 Inz(1)
D nIncInv S 10I 0 Inz(1)
D RtnMsgKey S 4A
D myAPIErrorDS DS LikeDS(QUSEC)
C eval myApiErrorDS = *ALLX'00'
C if %Parms()>=2
C eval msgType = szMsgType
C if %subst(msgType:1:1)<>'*'
C eval msgType = '*' + %TrimL(msgType)
C endif
C endif
C if %Parms()>= 3
C if szToPgmQ <> *BLANKS
C eval toPgmQ= szToPgmQ
C endif
C if toPgmQ = '*SAME'
C eval toPgmQ = '*'
C endif
C endif
// Status messages always go ToPgmQ(*EXT)
C if msgType = '*STATUS'
C eval toPgmQ = '*EXT'
C endif
C if msgType = '*'
C eval msgType = '*INFO'
C endif
// Get the length of the message to be sent.
C eval msgData = %Trim(msg)
C eval nDataLen = %len(%Trim(msg))
C Select
** *SAME
C when toPgmQ = ' '
C or toPgmQ = '*SAME'
C or toPgmQ = '*'
C eval toPgmQ = '*'
C eval nRelInv = 0
C eval nIncInv = 1
** *PRV, *PRVPRC or *PRVPROC
C when toPgmQ = '*PRVPRC'
C or toPgmQ = '*PRVPROC'
C or toPgmQ = '*PRV'
C eval toPgmQ = '*'
C eval nRelInv = 1
C eval nIncInv = 1
** *PRVPGM
C When toPgmQ = '*PRVPGM'
C eval toPgmQ = '*CTLBDY'
C eval nRelInv = 0
C eval nIncInv = 1
** *CTLBDY
C when toPgmQ = '*CTLBDY'
C eval nIncInv = 2
** *EXT
C when toPgmQ = '*EXT'
C eval nRelInv = 0
C endsl
** Since we're a relative invocation, and we are
** one-level deep, we need to bump up the relative
** invocation by the calculated increment.
C eval nRelInv = nRelInv + nIncInv
C callp(e) QMHSNDPM(msgid : msgf :
C msgData : nDataLen :
C msgType :
C toPgmQ :
C nRelInv :
C rtnMsgKey :
C myAPIErrorDS)
C return rtnMsgKey
P SndMsg E
LATEST COMMENTS
MC Press Online