|
Getting the Message, Part 2
Published: October 21, 2009
by Paul Tuohy
In Part 1 of this series, we saw the definition of a number of message routines (clearMessages(), addMessage(), messageCount(), and getMessage()). In this article, we will see how the routines may be used in both an RPG and a PHP environment. We will also look at another couple of message routines that may be useful.
Remember, a library containing the code used in these articles may be downloaded here.
A Test Procedure
Figure 1 shows a small subprocedure (fillMessages()) used to demonstrate that messages may be added/stored at any level in the job. The subprocedure simply adds a filler message the number of times requested on the passed parameter.
p fillMessages B Export
D PI
D timesToSend 10i 0 Const
D i s 10i 0
/free
for i = 1 to timesToSend;
addMessage(APP_FILLER : 'FILL' : %char(i));
endFor;
/end-Free
p E
Figure 1: Test procedure fillMessages().
In RPG
Figure 2 shows an RPG program used to demonstrate the message routines. The program performs the following:
- Calls clearMessages() to clear any stored messages.
- Calls addMessage() twice to add two messages (note the use of the named constants to identify the required message IDs).
- Calls fillMessages() to add three filler messages.
- Based on the value returned by messageCount(), the program loops through calls to getMessage() and display the message text returned for each message.
/Copy QCpySrc,StdHSpec
// To create the program...
// Current library set to MESSAGES
// CRTBNDRPG PGM(SHOWMSGS)
/Copy QCpySrc,BaseInfo
D message DS LikeDS(Def_MsgFormat)
D i s 10i 0
/free
clearMessages();
addMessage(ERR_NOTFOUND : 'TEST1');
addMessage(ERR_CHANGED : 'TEST2');
fillMessages(3);
for i = 1 to messageCount();
getMessage(i : message);
dsply %subst(message.msgText :1 :40);
endFor;
*InLR = *on;
/end-Free
Figure 2: Program SHOWMSGS demonstrates the use of message procedures in RPG.
The expected results from SHOWMSGS are shown in Figure 3:
DSPLY An expected record was not found for upd
DSPLY Record already altered. Update/Delete ig
DSPLY This is filler message 1
DSPLY This is filler message 2
DSPLY This is filler message 3
Figure 3: Result of calling SHOWMSGS.
Of course, this program simply shows the format of the calls. The real key is what the program wants to do with the messages it retrieves.
If this were a green-screen program, the returned messages could be sent to a message subfile. If it were a CGIDEV2 program, the returned messages might be used to populate message information on a Web page.
For example, when I am using CGIDEV2, I identify errors on a Web page using two divisions/variables. ERRTEXT contains the message text to be display and ERRVARS (a non-display division on the page) contains the names of the fields in error. A Javascript routine that runs on page load uses the contents of ERRVARS to highlight the fields in error. Figure 4 shows the setCGIMessages() routine used to set the errors on a Web page.
P setCGIMessages B Export
D PI
D i s 10i 0
D msgFormat DS LikeDs(Def_MsgFormat)
D errVars s 32767a Varying
D errText s 32767a Varying
/free
errVars = ' ';
errText = ' ';
if messageCount() > 0;
for i = 1 to messageCount();
getMessage(i:msgFormat);
if (i > 1);
errVars = errVars + '%%';
errText = errText + '<br />';
endIf;
errVars = errVars + %Trim(msgFormat.ForField);
errText = errText + %Trim(msgFormat.MsgText);
endFor;
endIf;
updHTMLvar( 'ErrVars': errVars);
updHTMLvar( 'ErrText': errText);
/end-Free
P E
Figure 4: Setting errors with CGIDEV2.
In PHP
Let me start by saying that I am still finding my way with PHP, so those of you who know better, please don't be too harsh on my attempts.
Since I am running this on my i, of course I am using ZendCore to do all the hard work for me.
Whenever one decides to interface between two technologies, there is always a little bit of work to be done, and PHP is no exception. The key point to remember is that no changes are made to the underlying subprocedures.
The first issue with the PHP routines is that they have issues calling subprocedures that don't accept parameters. For that reason, I wrote a wrapper routine (php_clearMessages()), shown in Figure 5, that accepts a dummy parameter and issues a call to the original clearMessages() subprocedure.
P php_clearMessages...
P B Export
D PI
D dummy 1a
/free
clearMessages();
/end-Free
P E
Figure 5: Wrapper subprocedure for call to clearMessages() from PHP.
The next step was to write PHP functions that would issue calls to the corresponding subprocedures in the UTILITY service program. Figure 6 shows the source of func_messages.php. Each of these functions is simply a PHP function that issues a call to the corresponding subprocedure in the UTILITY service program. In other words, these are PHP wrappers to call the RPG subprocedures.
<?php
define('APP_ERR_NOTFOUND','ALL9001');
define('APP_ERR_CHANGED','ALL9002');
define('APP_ERR_DUPLICATE','ALL9003');
define('APP_ERR_CONSTRAINT','ALL9004');
define('APP_ERR_TRIGGER','ALL9005');
define('APP_ERR_UNKNOWN','ALL9006');
define('APP_ERR_NOT_NUMBER','ALL9007');
define('APP_ERR_NOT_DATE','ALL9008');
function clearMessages($conn) {
$desc = array (array ("name" => "dummy", "io" => I5_INOUT,
"type" => I5_TYPE_CHAR, "length" => "1" ) );
$prog1 = i5_program_prepare ( "MESSAGES/UTILITY(php_clearMessages)",
$desc, $conn );
if (! $prog1) {
die ( "Prepare for clearMessages() did not work" );
}
$parameter = array ("dummy" => " " );
$parmOut = array ("dummy" => "dummy" );
if (! i5_program_call ( $prog1, $parameter, $parmOut )) {
die ( "Call to clearMessages() did not work" );
}
i5_program_close ( $prog1 );
}
function addMessage($conn, $msgId, $forField = " ", $msgData = " ") {
$desc = array (array ("name" => "msgId", "io" =>
I5_INOUT,
"type" => I5_TYPE_CHAR, "length" => "7" ),
array ("name" => "forFieldIn", "io"
=> I5_INOUT,
"type" => I5_TYPE_CHAR, "length" => "25" ),
array ("name" => "msgData", "io"
=> I5_INOUT,
"type" => I5_TYPE_CHAR, "length" => "500" ) );
$prog1 = i5_program_prepare ( "MESSAGES/UTILITY
(addMessage)",
$desc, $conn );
if (! $prog1) {
die ("Prepare for addMessage() did not work");
}
$parameter = array ("msgId" => $msgId,
"forFieldIn" => $forField,
"msgData" => $msgData );
$parmOut = array ("msgId" => "msgId",
"forFieldIn" => "forField",
"msgData" => "msgData" );
if (! i5_program_call ( $prog1, $parameter, $parmOut ) ) {
die ("Call to addMessage() did not work");
}
i5_program_close ( $prog1 );
}
function messageCount($conn) {
$desc = array (
array ("name"=>"numMessages", "io"=>I5_INOUT,
"type"=>I5_TYPE_LONG, "length"=>"4"),
);
$prog1 = i5_program_prepare("MESSAGES/UTILITY(php_messageCount)",
$desc, $conn);
if (!$prog1) {
die("Prepare for messageCount() did not work");
}
$parameter = array("numMessages"=>0);
$parmOut = array("numMessages"=>"msgCount");
if (! i5_program_call($prog1, $parameter, $parmOut)){
die("Call to messageCount() did not work");
}
i5_program_close ( $prog1 );
return $msgCount;
}
function getMessage($conn, $forMessage, $forField=" ", $msgId=" ",
$help=" ", $severity=0) {
$desc = array (
array ("name"=>"forMessage", "io"=>I5_INOUT,
"type"=>I5_TYPE_LONG, "length"=>"4"),
array("DSName"=>"msgFormat", "DSParm"=>array(
array("Name"=>"msgId", "IO"=>I5_INOUT,
"Type"=>I5_TYPE_CHAR, "Length"=>"7"),
array("Name"=>"msgText", "IO"=>I5_INOUT,
"Type"=>I5_TYPE_CHAR, "Length"=>"80"),
array("Name"=>"severity", "IO"=>I5_INOUT,
"Type"=>I5_TYPE_LONG, "Length"=>"4"),
array("Name"=>"help", "IO"=>I5_INOUT,
"Type"=>I5_TYPE_CHAR, "Length"=>"500"),
array("Name"=>"forField", "IO"=>I5_INOUT,
"Type"=>I5_TYPE_CHAR, "Length"=>"25"))
)
);
$prog1 = i5_program_prepare("MESSAGES/UTILITY(getMessage)",
$desc, $conn);
if (!$prog1){
die("Prepare for getMessage() did not work");
}
$parameter = array("forMessage"=>$forMessage,
"msgFormat"=>array("msgId"=>" "));
$parmOut = array("forMessage"=>"forMessage",
"msgFormat"=>"msgFormat");
if (! i5_program_call($prog1, $parameter, $parmOut)){
die("Call to getMessage() did not work");
}
i5_program_close($prog1);
$forField = $msgFormat["forField"];
$msgId = $msgFormat["msgId"];
$help = $msgFormat["help"];
$severity = $msgFormat["severity"];
return $msgFormat["msgText"];
}
function fillMessages($conn, $numMessages) {
$desc = array (
array ("name"=>"numMessages", "io"=>I5_INOUT,
"type"=>I5_TYPE_LONG, "length"=>"4"),
);
$prog1 = i5_program_prepare("MESSAGES/UTILITY(fillMessages)",
$desc, $conn);
if (!$prog1) {
die("Prepare for fillMessages() did not work");
}
$parameter = array("numMessages"=>$numMessages);
$parmOut = array("numMessages"=>"msgCount");
if (! i5_program_call($prog1, $parameter, $parmOut)){
die("Call to fillMessages() did not work");
}
i5_program_close ( $prog1 );
return;
}
?>
Figure 6: PHP functions, func_messages.php.
Note that each of the functions is passed a parameter ($conn), which identifies the connection to be used on the call to the subprocedure. This parameter identifies the job that actually calls the subprocedures. Also note the definition of constants for the message IDs.
Figure 7 shows the PHP script phpmessage.php that corresponds to the SHOWMSGS program. The script performs the following:
- Makes a connection to the i ($conn) .
- Calls clearMessages() to clear any stored messages.
- Calls addMessage() twice to add two messages (note the use of the named constants to identify the required message IDs).
- Calls fillMessages() to add three filler messages.
- Based on the value returned by messageCount(), the script loops through calls to getMessage() and display the message text returned for each message.
- Closes the connection to the i.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Playing with PHP Program Calls</title>
</head>
<body>
<h1>Playing with PHP Messages</h1>
<p>This example demonstrates use of the message routines</p>
<?php
ini_set('display_errors', 1);
error_reporting(E_ALL & ~E_NOTICE);
require 'func_messages.php';
($conn = i5_pconnect("localhost", "", "",array("I5_OPTIONS_JOBNAME"
=>"PAULPHP")))
or trigger_error("Could not make connection", E_USER_ERROR);
echo "Clear Messages <br />";
clearMessages($conn);
echo "Add Messages <br />";
addMessage($conn, APP_ERR_NOTFOUND, 'TEST1');
addMessage($conn, APP_ERR_CHANGED, 'TEST2');
echo "Fill 3 Messages <br />";
fillMessages($conn, 3);
echo "Get Message count <br />";
$msgCount = messageCount($conn);
echo "Returned message count is ".$msgCount." <br />";
echo "Get Messages <br />";
for ($i = 1; $i <= $msgCount; $i++) {
echo getMessage($conn, $i)." <br />";
}
i5_close($conn);
?>
<p> Page complete </p>
</body>
</html>
Figure 7: Script phpmessage.php, use of message procedures in PHP.
The expected results from phpmessage.php are shown in Figure 8:
Figure 8: Result of calling phpmessage.php.
Other Message Subprocedures
But we don't have to stop with just these subprocedures. Figure 9 lists some other message subprocedures that you might find useful:
- addMessageText() allows you to directly store message text as opposed to using a message ID/message file.
- setMessageFile() allows you to change the default message file and/or library being used.
- sendFileError() sends file messages based on a status code passed as a parameter. This subprocedure would be called based on an I/O error being received on a file operation and being trapped with an error extender.
P addMessageText B Export
D PI
D msgText 80a Const
D forFieldIn 25a Const
D Options(*Omit:*NoPass)
D severity 10i 0 Const
D Options(*NoPass)
D forField S like(forFieldIn)
/free
msgCount += 1;
messages(msgCount).msgText = msgText;
if %Parms() > 2;
messages(msgCount).severity = severity;
endIf;
if %Parms()> 1;
if %Addr(forFieldIn) <> *Null;
forField = forFieldIn;
endIf;
endIf;
messages(msgCount).forField = forField;
/end-Free
P E
P setMessageFile...
P B Export
D PI
D newMsgf 10A Const
D newMsgLib 10A Const
D Options(*NoPass)
/free
msgFile = newMsgF;
if %Parms()> 1;
msgFileLib = newMsgLib;
endIf;
return;
/end-Free
P E
P sendFileError B Export
D PI n
D status 5i 0 Const
/free
select;
// Duplicate
when status = STAT_DUPLICATE;
addMessage(ERR_DUPLICATE);
// Referential Constraint
when status = STAT_CONSTRAINT_1 or
status = STAT_CONSTRAINT_2;
sendConstraintMsg();
// Trigger
when status = STAT_TRIGGER_1 or
status = STAT_TRIGGER_2;
addMessage(ERR_TRIGGER);
// Other
other;
addMessage(ERR_UNKNOWN);
return *On;
endSl;
return *Off;
/end-Free
P E
Figure 9: Some other useful message procedures.
There You Have It
Hopefully these two articles have given you some food for thought. Remember that your RPG code does not have to be confined to RPG-only applications. All that great code can be opened up to wider use.
Paul Tuohy is CEO of ComCon, an iSeries consulting company, and is one of the co-founders of System i Developer, which hosts the RPG & DB2 Summit conferences. He is an award-winning speaker who also speaks regularly at COMMON conferences, and is the author of "Re-engineering RPG Legacy Applications," "The Programmers Guide to iSeries Navigator," and the self-study course called "iSeries Navigator for Programmers." Send your questions or comments for Paul to Ted Holt via the IT Jungle Contact page.
RELATED STORY
Getting the Message, Part 1
 Post this story to del.icio.us
 Post this story to Digg
 Post this story to Slashdot
|
