MessageBox PeopleCode – Parameters and Examples

MessageBox is one of the most used PeopleCode built-in functions.

I had a look at CS Image 25 the other day and found that it was being used close to 7000 times. wow!

This easy-to-use function allows you to select a text directly from the message catalog and display it to the user in a message box window.

How to use MessageBox in PeopleCode?

Here is the quick and easy way to use MessageBox in PeopleCode.

MessageBox(0, "", 0, 0, "Basic Message - I can help you while debugging!");

I cannot count how many times I’ve used MessageBox to display the values of variables or some other text while debugging. The code above will display a message like the one below.

Now, this works equally well in Application Engines – the message gets written to the Message log.

You can always concatenate a variable or two to the text to print its value to aid your troubleshooting effort.

MessageBox(0, "", 0, 0, "The value of year is: " | &nYear);

Messagebox Syntax

Now let’s look at the syntax of the MessageBox function.

MessageBox(style, title, message_set, message_num, default_msg_txt[, paramlist]);

This function takes 5 parameters followed by an arbitrary list of bind values. We will look into each of these in detail in the next section of this article.

MessageBox Parameters

Now, let’s rewrite the year example above using a message from the Message Catalog. We’ll then use this to explain the parameters used by the MessageBox function.

MessageBox(0, "", 20000, 3, "Message not found.", &nYear);

style

The style parameter decides the contents (buttons etc.) and the behaviour of a message box. There are 6 possible values that the style parameter can take – these are explained further down. However, when displayed in PIA, this parameter is taken into account only for messages that have a severity of Message.
In the example above we’ve used the style as 0 which means that an OK button would be displayed on the message box.

title

For messages displayed on the PIA, this parameter is ignored. So we’ve not given any values for that in the example. However, for all these messages, the title is displayed as “Message”.

message_set

This is the Message Set Number (in the Message Catalog) from which the message number (fourth parameter) is selected. This plays a critical role in deciding what text is displayed to the user. If it has a value less than 1, the default text (fifth parameter) is displayed.
The example uses 20000 as the message set number.

message_num

This is the Message Number within the Message Set (third parameter) of the message to be displayed. If the system cannot find the combination of message_set and message_num in the Message Catalog, then the default message text (fifth parameter) is displayed. The example uses 3 as the message number.

default_msg_txt

This is the default text that gets displayed when the value of message_set is less than 1 or when the system cannot find a valid combination of message_set and message_num in the Message Catalog.

The example uses "Message not found." as the default message text.

paramlist

The parameter list takes relevance when the message used has placeholders (%1, %2 etc.) and we need to pass bind variables that correspond to these placeholders.
The example uses &nYear as the only parameter.

This example displays the following message box.

MessageBox styles

Following are the list of styles supported and the corresponding constants.

Value	Constant	Screenshot
0	%MsgStyle_OK
1	%MsgStyle_OKCancel
2	%MsgStyle_AbortRetryIgnore
3	%MsgStyle_YesNoCancel
4	%MsgStyle_YesNo
5	%MsgStyle_RetryCancel

MessageBox Return Values

When a message box is used for branching based on user choices, it becomes important to know what button was clicked by the user.

This can be identified by the value returned by the MessageBox function.

&nRet = MessageBox(2, "", 20000, 2, "Message not found.");

These are the values returned by MessageBox.

Message Box More Examples

Let’s look at a final example and see how bind variables are resolved.

For this, we have the following message catalog entry.

As you can see it has two placeholders – %1 which is in the Message Text and %2 in the Description.

When the following MessageBox code is executed, the placeholders get replaced by the values from the parameter list.

MessageBox(0, "", 20000, 4, "Message not found.", &nYear, &nYear - 2);

So %1 is substituted with &nYear and %2 get substituted with &nYear - 2.

And the end result is this message box.