WinMessage

Syntax

WinMessage(message [, style] [, title])

Description

See .

Use the WinMessage function to display a message in a message box.

Use the WinMessage for simple informational display, where the end user reads the message, then clicks an OK button to dismiss the message box. WinMessage can also be used for branching based on end user choice, in which case the message box contains two or more buttons (such as OK and Cancel or Yes, No, and Cancel). The value returned by the function tells you which button the end user clicked, and your code can branch based on that value.

If WinMessage displays more than one button, it causes processing to stop while it waits for user response. This makes it a "user think-time" function, restricting its use in certain PeopleCode events.

The contents of the message displayed by WinMessage can be passed to the function as a string, but unless you are using the function for testing purposes you should always retrieve the message from the Message Catalog using the MsgGet or MsgGetText function. This has the advantage of making the messages much easier to localize and maintain.

Note that if you pass a string to the WinMessage function (or a Warning or Error function) instead of using a Message Catalog function, the explanation text from the last call to the Message Catalog may be appended to the message. This can cause unexpected results.

The Message Catalog functions MsgGet, MsgGetText, and MessageBox retrieve and store two text strings in memory: the message text and the explanation text. The MsgGetExplainText function retrieves and stores only the explanation text. When these strings are displayed by a WinMessage, MessageBox, Error or Warning dialog, the buffers are reinitialized.

If a Message Catalog function is called without displaying the text, for instance to populate a variable or record field, the message text and the explanation text remain in memory.

If a subsequent call passes a string to a WinMessage, Warning, or Error function before the buffers are reinitialized, the explanation text remains in memory and is appended to the message.

The following example shows one way this could occur.

Image: Example of a Message Catalog entry with message text and explanation text

The Message Catalog might contain an entry such as this:

MsgGetText is used to assign the Message Catalog entry to a variable for further processing.

&PartDesc = MsgGetText(30000, 5, "Amana Radar Range");
/** Process order **/
WinMessage("Your Kitchen Upgrade Order has been processed");

Image: Example of a WinMessage dialog with explanation text appended

The WinMessage dialog displays the explanation text appended to the intended message:

This example shows a simple workaround to clear the buffers using MsgGet.

&PartDesc = MsgGetText(30000, 5, "Amana Radar Range");
/** Process order **/
&Dummy = MsgGet(0,0, " ");
WinMessage("Your Kitchen Upgrade Order has been processed"); 

Parameters

Returns

If the style parameter is provided, WinMessage optionally returns a Number value. If the style parameter is omitted, WinMessage optionally returns a Boolean value: True if the OK button was clicked, otherwise it returns False.

The return value is zero if there is not enough memory to create the message box.

If the style parameter is provided, WinMessage returns one of the following Number values: