MessageBox function and statement (LotusScript® Language)

Displays a message in a message box and waits for user acknowledgment. The function form returns a value corresponding to the button the user presses.

Function Syntax

MessageBox ( message [ , [ buttons + icon + default + mode ] [ , boxTitle ] ] )

Statement Syntax

MessageBox message [ , [ buttons + icon + default + mode ] [ , boxTitle ] ]

The MessageBox function and statement are identical, except that only the function has a return value.

MsgBox is acceptable in place of MessageBox.

Elements

message

The message to be displayed in the message box (a string). The length of message is dependent on the operating system.

buttons

Defines the number and type of buttons to be displayed in the message box:

Constant name

Value

Buttons displayed

MB_OK

0

OK

MB_OKCANCEL

1

OK and Cancel

MB_ABORTRETRYIGNORE

2

Abort, Retry, and Ignore

MB_YESNOCANCEL

3

Yes, No, and Cancel

MB_YESNO

4

Yes and No

MB_RETRYCANCEL

5

Retry and Cancel

icon

Defines the icons to be displayed in the message box:

Constant name

Value

Icon displayed

MB_ICONSTOP

16

Stop sign

MB_ICONQUESTION

32

Question mark

MB_ICONEXCLAMATION

48

Exclamation point

MB_ICONINFORMATION

64

Information

default

Defines the default button in the message box. Pressing ENTER has the same effect as clicking the default button:

Constant name

Value

Default button

MB_DEFBUTTON1

0

First button

MB_DEFBUTTON2

256

Second button

MB_DEFBUTTON3

512

Third button

mode

Defines the message box modality:

Constant name

Value

Description

MB_APPLMODAL

0

Application modal. Stops the current application until the user responds to the message box.

MB_SYSTEMMODAL

4,096

System modal. Stops all applications until the user responds to the message box.

boxTitle

The string to appear in the title bar of the message box. boxTitle can be up to 128 characters in length.

Return value

The MessageBox function return value is an integer in the range of 1 to 7, inclusive. This value indicates which button the user pressed in the message box, as shown in the following table.

Return value

Button

Constant

1

OK

IDOK

2

Cancel

IDCANCEL

3

Abort

IDABORT

4

Retry

IDRETRY

5

Ignore

IDIGNORE

6

Yes

IDYES

7

No

IDNO

Usage

The valid values for the buttons, icon, default, and mode elements listed in the preceding tables are defined as constants in the file LSCONST.LSS. If you want to use the constants instead of numbers, include this file in your script.

The HCL software where you are running LotusScript® may allow longer strings than described preceding for message and boxTitle. LotusScript® will support longer strings for these items if the HCL software does.

Note: The length of message is dependent on the operating system. If you are launching applications in a mixed environment (for example, PC and Mac), keep your message length equal to or shorter than the smallest limit of the operating systems to be used.

Use the newline character to force line breaks in the message element. Or use vertical bars or braces to specify a multiline string. If you don't force line breaks, the text wraps automatically in the message box.

Note: Newline does not mean either chr(10) or chr(13) on all platforms. Newline is the character or sequence of characters that is used to mark the end of a line. This may be chr(10), or chr(13), but it may also be something else, because the actual value of newline depends on the platform. If newlines are desired in the output, it is the programmer's responsibility to ensure that the string contains the correct newline for the platform.

If you are using LotusScript® from within Notes®, note that the MessageBox function writes to:

  • A dialog box when executing in the foreground on a Notes® client. The user clicks OK, Cancel, Abort, Retry, Yes, or No to continue.
  • NOTES.LOG when executing on a Domino® server without pausing or as a scheduled agent in the Notes® client.
Note: Whenever a MessageBox function is executed in the back end, it will return zero, regardless of the defaults or modes. Only the prompt is displayed. The display goes to the server console, Notes® log, and anywhere that debugging output is redirected (DEBUG_OUTFILE) if on a server, or to the debug console if on the client. This does not appy to the MessageBox statement.

Example