DISPLAY MESSAGE BOX

Format 15

DISPLAY MESSAGE BOX creates a simple message box 

DISPLAY MESSAGE BOX

 { text } . . .

Remaining phrases are optional and may be used in any order. 

TITLE {IS} title
      {= }

TYPE {IS} type
     {= }

ICON {IS} icon
     {= }

DEFAULT {IS} default
        {= }

{GIVING   } value
{RETURNING}

Syntax Rules

  1. text is a literal or data item.
  2. title is an alphanumeric literal or data item.
  3. type, icon, and default are numeric literals or data items.
  4. value is a numeric data item.

General Rules

  1. Format 15 (DISPLAY MESSAGE BOX) creates a simple modal pop-up window with a title-bar, a text message, an icon (on some systems) and one or more push buttons. It then waits for the user to push one of the buttons and returns the results. The window is then destroyed. Message boxes come in OK and Yes/No formats, with an optional Cancel button in each format. Message boxes are a programming convenience when you need to create a simple dialog box that can fit one of these predefined formats.
  2. Text forms the body of the message box. It is the string of text that the user will see. When more than one text item is specified, they are concatenated together to form a single string that the user sees. The limit on the length of the message string is host dependent. The host system wraps the text as needed to fit the message box. If you want to force the text to a new line, you can embed an ASCII line-feed character (h"0A" in COBOL) where you want the new line to start. For example, the following code produces a message box with two lines of text: 
    78  NEWLINE      VALUE H"0A".

DISPLAY MESSAGE BOX, 
   "This is line 1", NEWLINE, 

   "and this is line 2" .
  3. When text is numeric, it is converted to a text string using the CONVERT phrase rules. Leading spaces in the resulting string are suppressed in the message. When text is numeric-edited, leading spaces are suppressed in the message, and the rest of the item is displayed without modification. For all other data types, text is displayed without modification.
  4. Title is displayed in the message box's title bar. If title is omitted, the message box displays the same title as the application's main window.
  5. Type, icon, default and value use a set of constants to describe the type of message box and the buttons it contains. These constants have level 78 definitions for them in the COPY library "acugui.def" supplied with the compiler. These constants are as follows: 
    78  MB-OK               VALUE 1.
78  MB-YES-NO           VALUE 2.
78  MB-OK-CANCEL        VALUE 3.
78  MB-YES-NO-CANCEL    VALUE 4.
78  MB-YES              VALUE 1.
78  MB-NO               VALUE 2.
78  MB-CANCEL           VALUE 3.
78  MB-DEFAULT-ICON     VALUE 1.
78  MB-WARNING-ICON     VALUE 2.
78  MB-ERROR-ICON       VALUE 3.
  6. Type describes the set of buttons contained in the box. The possible values are:
    Type Value Buttons
    MB-OK "OK" button
    MB-YES-NO "Yes" and "No" buttons
    MB-OK-CANCEL "OK" and "Cancel" buttons
    MB-YES-NO-CANCEL "Yes", "No" and "Cancel" buttons

    If type is omitted, or if it contains an invalid value, then MB-OK is used. The text that appears on the buttons is set by the current language installed for Windows. For non-Windows systems, the text is configurable by the TEXT configuration entry.

  7. Icon describes the icon that will appear. The icon appears only under Windows. On other systems, the icon selected is ignored. If icon is set to MB-ERROR-ICON, then a stop icon is shown. If icon is set to MB-WARNING-ICON, then an exclamation icon displays. If icon is set to MB-DEFAULT-ICON, then boxes with OK buttons will display an information icon, and boxes with Yes/No buttons will display a question mark icon. If icon is omitted or contains an invalid value, then MB-DEFAULT-ICON is used.
  8. Default describes which button will be the default button (i.e., the button used if the user simply presses Return). The possible values are:
    Value Button
    MB-OK "OK" button
    MB-YES "Yes" button
    MB-NO "No" button
    MB-CANCEL "Cancel" button

    If default is omitted, or contains an invalid value, then the default button will be the OK button or the "Yes button.

  9. Value will contain the identity of the button the user pressed to leave the message box. It uses the same values as default does, described above. For example, if the user presses the No button, then value will contain MB-NO.
    Note: For each invocation of the message box, only one keystroke entry is picked up. If you want to drive the message box from your defined keystroke file (or from the COPY library acugui.def), make sure that you make this one entry a valid character for the message box, such as Y or N for a message requiring a Yes or a No response.
Parent topic: DISPLAY Statement