PeopleCode | Using the extended options of the MessageBox function
A. The Basic Version
The ‘MessageBox’ function is such a handy piece of code for troubleshooting that you often find yourself using the ‘basic version’ without giving much thought to how the statement really works:
MessageBox(0, "", 0, 0, "Display message here");
This post will take a closer look at some of the additional features of ‘MessageBox’, beyond its basic usage above. In particular, we consider each of the parameters in more detail.
B. Parameter 1: Message Type
The first parameter specifies the type of message you wish to display. In most cases, the parameter is set to a value of ‘0’, which displays a message with an ‘OK’ button only. However, the function comes with a number of other options for setting the message type. These can be entered as either a numeric value (‘0’) or a constant (‘%MsgStyle_OK’):
0 – %MsgStyle_OK
1 – %MsgStyle_OKCancel
2 – %MsgStyle_AbortRetryIgnore
3 – %MsgStyle_YesNoCancel
4 – %MsgStyle_YesNo
5 – %MsgStyle_RetryCancel
This means ‘MessageBox’ is a great option if you want to ask the user a basic question, without having to go to the bother of creating a new page. Simply enter the question into a ‘MessageBox’ statement, setting the appropriate parameter for whichever buttons you require. A Yes/No response, for instance, would require value 4 (%MsgStyle_YesNo):
MessageBox(%MsgStyle_YesNo, "", 0, 0,
"Are you sure you want to delete the record?");
Once the user has clicked the appropriate button, you can then write code to process the user’s response. Similar to the message types, each response is coded with its own numeric value and constant:
-1 – %MsgResult_Warning
1 – %MsgResult_OK
2 – %MsgResult_Cancel
3 – %MsgResult_Abort
4 – %MsgResult_Retry
5 – %MsgResult_Ignore
6 – %MsgResult_Yes
7 – %MsgResult_No
Tying all of this together, here’s some code to pose a question to the user, and then process the response:
&response = MessageBox(%MsgStyle_YesNo, "", 0, 0,
"Are you sure you want to delete the record?");
If &response = %MsgResult_Yes then
/* User has clicked Yes - Continue with delete */
Else
/* User has clicked No – don’t delete */
End-If;
C. Parameter 2: Title
The second parameter to the ‘MessageBox’ function holds the message title. However, as this is ignored entirely by the system, the parameter serves little purpose:
MessageBox(0, "Useless Title Goes Here", 0, 0,
"Display message here");
D. Parameters 3 and 4: Message Set and Message Number
The next two parameters – 3 and 4 – work in combination. To avoid hard-coding a message string, you can instead use an entry from the Message Catalog. If your code is intended to run in a production environment, the Message Catalog should be used wherever possible, since it allows an end user to update the message directly without having to involve a developer. Therefore, in the ‘MessageBox’ statement, set parameters 3 and 4 equal to the message set and message number.
If the stored message happens to contain both a ‘Text’ and an ‘Explanation’, both pieces of text will be displayed in the message window.
E. Parameter 5: Message Text
Even if you do specify a message set and number, you can continue to enter a message text as parameter 5. This will be used if the message set and number do not exist:
MessageBox(0, "", 30000, 1, "Optional text if message does not exist");
Some developers are fond of entering ‘message not available’ for the default text:
MessageBox(0, "", 30000, 1, "Message not Available");
While this might seem unhelpful, such a message displayed to an end user is often a sign that the migration or development is incomplete. If the message is missing, it might suggest that other objects (or other messages) are also missing. Therefore, if a user complains about receiving such a ‘Message not Available’, it’s a useful cue to go back and double-check your project. Therefore, my preference is to use ‘Message not Available’ whenever a message set and number are being entered in the ‘MessageBox’ statement. However, this is certainly not a hard-and-fast rule, so go with whatever approach you prefer.
F. Additional Parameters
Finally, if you are using ‘MessageBox’ with a stored message, there’s a chance that the message contains a number of run-time parameters (%1, %2, etc). The values for these fields must also be passed in as parameters to the ‘MessageBox’ statement:
MessageBox(0, "", 30000, 1, "Message not Available",
"Parameter 1", "Parameter 2");
See Also:
Tip 001: %PerfTime (Performance Time)
Tip 025: Forcing an Error
Tip 045: Introduction to Tracing