Interacting with the user

IBM® products lend themselves to building interactive applications, applications that incorporate user input and prompt the user to perform particular tasks. While each individual IBM® software application provides its own user interface for interacting with scripts, LotusScript® supplies some fundamental tools that you can use with any IBM® software.

• InputBox function

  The InputBox function displays a dialog box with the prompt you specify, a text box, and OK and Cancel buttons. You can also specify a title, a default value, and a position on the screen for the input box.

  The user enters characters in the text box and clicks OK. InputBox returns the string the user entered. You can use the data type conversion functions (DateValue, CBool, CByte, CCur, CDat, CDbl, CInt, CLng, CSng, CVar) to convert the input to a numeric, date/time, or Variant value. If you are converting to a nonstring value, you can include some error handling in case the user enters a string that cannot be converted. "XYZ," for example, cannot be converted to a numeric value.

• Print statement or the MessageBox function or statement

  The Print statement displays a message in the current output window, which varies depending on the IBM® software application in which you are working. MessageBox displays a message box, which contains an optional title, the message, an optional icon, and one or more command buttons.

  If you want to display a message, use a MessageBox statement and include an OK button (the default). The user reads the message, clicks OK, and the script proceeds to the next statement.

  To offer the user two or more options, use the MessageBox function and include two or more command buttons. For example, you can include OK and Cancel buttons. You can use an If statement or Case statement to respond to the user's response accordingly.

This example uses the InputBox function to get monthly revenue and expenses from the user, converting strings to Currency.

The script computes the balance, then uses a MessageBox statement to display the balance, formatted as Currency.

Sub CalcBalance
   Dim revenue As Currency, expenses As Currency, balance _
     As Currency
   revenue@ = CCur(InputBox("How much did we make" & _
    " this month?"))
   expenses@ = CCur(InputBox("How much did we spend?"))
   balance@ = revenue@ - expenses@
   MessageBox "Our balance this month is " _
      & Format(balance@, "Currency")
End Sub

The two input boxes with sample entries and the resulting message box are:

If the user enters a string that the CCur function cannot convert to Currency, an error condition occurs. You can use an On Error statement to branch to an error-handling routine in such a case.

This expanded version of the example uses the MessageBox function to ask the user whether to try again. The second message box also contains a question mark icon, specified by MB_ICONQUESTION (32). To use constants rather than the numbers to which they correspond as MessageBox arguments, you must include the file that defines these constants, LSCONST.LSS, in the module declarations.

%Include "LSCONST"
Sub CalcBalance
   Dim revenue As Currency, expenses As Currency, balance _
     As Currency
   EnterValues:
   On Error GoTo BadCur:
   revenue@ = CCur(InputBox("How much did we make" & _
    " this month?"))
   expenses@ = CCur(InputBox("How much did we spend?"))
   balance@ = revenue@ - expenses@
   MessageBox "Our balance this month is " _
      & Format(balance@, "Currency")
   Exit Sub
   BadCur:
   If MessageBox("Invalid entry! Do you want to try again?", _
      MB_YESNO + MB_ICONQUESTION) = IDYES Then GoTo _
      EnterValues
   Exit Sub
End Sub

When the user enters an invalid entry, a message box offers the option of making another entry.

For more information about error processing, see the chapter "Error Processing."

MessageBox on Notes® server context

When you run LotusScript® agents on the Notes® server, the commands MessageBox, Inputbox, and Print redirect the output to the log.

For HTTP servers, these commands redirect the output to the browser. You can create HTML pages using these commands to serve to any browser.