MESSAGE statement

Displays messages in the message area at the bottom of the window or in an alert box (or in an output stream—see the Notes section). By default, an area at the bottom line of the window is reserved for ABL system messages. An area above that is reserved for messages you display with the MESSAGE statement.

Syntax

MESSAGE [ COLOR `color-phrase` ] { `expression` \| SKIP [ ( `n` ) ] } ... [ VIEW-AS ALERT-BOX [ `alert-type` ] [ BUTTONS `button-set` ] [ TITLE `title-string` ] ] [ { SET \| UPDATE } `field` { AS `datatype` \| LIKE `field` } [ FORMAT `string` ] [ AUTO-RETURN ] ] [ IN WINDOW `window` ]

MESSAGE 
  [ COLOR color-phrase ] 
  { expression | SKIP [ ( n ) ] } ...  
  [ VIEW-AS ALERT-BOX 
      [ alert-type ] 
      [ BUTTONS button-set ]  
      [ TITLE title-string ] 
  ] 
  [ { SET | UPDATE } field 
        { AS datatype | LIKE field }  
        [ FORMAT string ] 
        [ AUTO-RETURN ] 
  ] 
  [ IN WINDOW window ]

COLOR color-phrase

Displays a message using the color you specify with the COLOR phrase.

NORMAL \| INPUT \| MESSAGES \| `protermcap-attribute` \| `dos-hex-attribute` \| { [ BLINK-] [ BRIGHT- ] [ `fgnd-color` ] [ `bgnd-color` ] } \| { [ BLINK-] [ RVV- ] [ UNDERLINE- ] [ BRIGHT- ] [ `fgnd-color` ] } \| VALUE ( `expression` )

   NORMAL 
|  INPUT 
|  MESSAGES 
|  protermcap-attribute 
|  dos-hex-attribute 
|  { [ BLINK-] [ BRIGHT- ] [ fgnd-color ] [ bgnd-color ] } 
|  { [ BLINK-] [ RVV- ] [ UNDERLINE- ] [ BRIGHT- ] 
         [ fgnd-color ] } 
|  VALUE ( expression )

For more information on color-phrase, see the COLOR phrase reference entry.

Note: The COLOR phrase does not have any effect in a Windows environment.

expression

An expression (a constant, field name, variable name, or expression) whose value you want to display in the message area. If expression is not character, it is converted to character before it is displayed. If you do not use this option, you must use either the SET or UPDATE option.

SKIP [ ( n ) ]

Indicates a number (n) of blank lines to insert into the message. The value of n can be 0. If you do not specify n, or if n is 0, a new line is started unless the current position is already the start of a new line.

You can only use this option with the VIEW-AS ALERT-BOX option.

VIEW-AS ALERT-BOX [ alert-type ]

Specifies that the message is displayed in an alert box rather than in the window message area. The value of alert-type determines the type of alert box. The possible values are:

MESSAGE

QUESTION

INFORMATION

ERROR

WARNING

The type of alert box affects the visual representation of the box.

BUTTONS button-set

Specifies what sets of buttons are available within the alert box. The possible button sets are as follows:

YES-NO

YES-NO-CANCEL

OK-CANCEL

RETRY-CANCEL

The name of each button set indicates the buttons in that set. For example, YES-NO contains two buttons labeled YES and NO; YES-NO-CANCEL contains three buttons labeled YES, NO, and CANCEL; OK contains a single button labeled OK. If you do not specify a button set, the default is OK.

TITLE title-string

Specifies a value to display in the title bar of the alert box.

SET field

Displays the expression you specified and SETs the field or variable you name. (It prompts the user for input and assigns the value entered to the field or variable.) You cannot test the field with the ENTERED function or the NOT ENTERED function.

UPDATE field

Displays the expression you specified and updates the field or variable you name. (It displays the current value of the field or variable, prompts for input, and assigns the value entered in the field or variable.) You cannot test the field with the ENTERED function or the NOT ENTERED function. For an alert box, field must be a LOGICAL variable. It sets the default button and returns the user’s choice. If the alert box has two buttons, they represent the values TRUE and FALSE, respectively. If the alert box has three buttons, they represent the values TRUE, FALSE, and the Unknown value (?), respectively.

AS datatype

Defines field as a variable of type datatype. You must use this option or the LIKE option if field has not been previously defined.

LIKE field

Defines the field specified in SET or UPDATE as a database field or a previously defined variable.

FORMAT string

The format that you want to use to display the field used in the SET or UPDATE option.

For more information on display formats, see OpenEdge Getting Started: ABL Essentials.

If you do not use the FORMAT option, ABL uses the defaults shown in Table 44.

Table 44: Default display formats
Type of expression	Default format
Field	Format from schema
Variable	Format from variable definition
Constant character	Length of character string
Other	Default format for the data type of the expression

Table 45 shows the default formats for the Other expression.

Table 45: Default data type display formats
Data type	Default display format
CHARACTER	x(8)
CLASS¹	N/A
DATE	99/99/99
DATETIME	99/99/9999 HH:MM:SS.SSS
DATETIME-TZ	99/99/9999 HH:MM:SS.SSS+HH:MM
DECIMAL	->>,>>9.99
HANDLE²	>>>>>>9
INT64	->,>>>,>>9
INTEGER	->,>>>,>>9
LOGICAL	yes/no
MEMPTR³	See the footnote at the end of the table.
RAW³	See the footnote at the end of the table.
RECID	>>>>>>9
ROWID³	See the footnote at the end of the table.

¹For a class instance, ABL automatically invokes the ToString( ) method (provided by the Progress.Lang.Object class) on the object reference. Instead, you can also first explicitly convert the object reference to a displayable type using the INT64 function, the INTEGER function, or the STRING function.

²To display a HANDLE, you must first convert it using either the INT64 or INTEGER function and display the result.

³You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, “0xhexdigits,” where hexdigits is any number of characters “0" through “9" and “A” through “F”. A MEMPTR or RAW value converts to decimal integer string.

AUTO-RETURN

Performs a carriage return when the field that is SET or UPDATEd is full.

IN WINDOW window

Specifies the window in which the message is displayed.

Examples

In this procedure, if you enter the number of a Customer that does not exist, the procedure displays a message telling you the Customer does not exist. If the Customer does exist, the procedure displays the Name and SalesRep of the Customer.

r-msg.p
REPEAT: PROMPT-FOR Customer.CustNum. FIND Customer USING Customer.CustNum NO-ERROR. IF NOT AVAILABLE Customer THEN DO: MESSAGE "Customer with CustNum " INPUT Customer.CustNum " does not exist. Please try another". UNDO, RETRY. END. ELSE DISPLAY Customer.Name Customer.SalesRep. END.

r-msg.p

REPEAT: 
  PROMPT-FOR Customer.CustNum. 
  FIND Customer USING Customer.CustNum NO-ERROR. 
  IF NOT AVAILABLE Customer THEN DO: 
    MESSAGE "Customer with CustNum " INPUT Customer.CustNum 
      " does not exist.  Please try another". 
    UNDO, RETRY. 
  END. 
  ELSE 
    DISPLAY Customer.Name Customer.SalesRep. 
END.

The following example uses two alert boxes:

r-altbox.p
DEFINE VARIABLE cust-list AS CHARACTER NO-UNDO VIEW-AS SELECTION-LIST SINGLE SIZE 50 BY 10 LABEL "Customers". DEFINE VARIABLE ok-status AS LOGICAL NO-UNDO FORM cust-list WITH FRAME sel-frame. ON DEFAULT-ACTION OF cust-list DO: MESSAGE "You have chosen to delete" cust-list:SCREEN-VALUE + "." SKIP(1) "Do you really want to delete this customer?" VIEW-AS ALERT-BOX QUESTION BUTTONS YES-NO-CANCEL TITLE "" UPDATE lChoice AS LOGICAL. CASE lChoice: WHEN TRUE THEN /* Yes / DO: FIND Customer WHERE Customer.Name = cust-list:SCREEN-VALUE EXCLUSIVE-LOCK. DELETE Customer. END. WHEN FALSE THEN / No / DO: MESSAGE "Deletion canceled."* VIEW-AS ALERT-BOX INFORMATION BUTTONS OK. RETURN NO-APPLY. END. OTHERWISE /* Cancel */ STOP. END CASE. END. FOR EACH Customer NO-LOCK BY Customer.Name: ok-status = cust-list:ADD-LAST(Customer.Name). END. ENABLE cust-list WITH FRAME sel-frame. WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

r-altbox.p

DEFINE VARIABLE cust-list AS CHARACTER NO-UNDO 
  VIEW-AS SELECTION-LIST SINGLE SIZE 50 BY 10 LABEL "Customers". 
DEFINE VARIABLE ok-status AS LOGICAL   NO-UNDO 
FORM cust-list 
  WITH FRAME sel-frame. 
ON DEFAULT-ACTION OF cust-list DO: 
  MESSAGE "You have chosen to delete" cust-list:SCREEN-VALUE + "." SKIP(1) 
    "Do you really want to delete this customer?" 
    VIEW-AS ALERT-BOX QUESTION BUTTONS YES-NO-CANCEL 
    TITLE "" UPDATE lChoice AS LOGICAL. 
  CASE lChoice: 
    WHEN TRUE THEN /* Yes */ DO: 
      FIND Customer WHERE Customer.Name = cust-list:SCREEN-VALUE 
        EXCLUSIVE-LOCK. 
      DELETE Customer. 
    END. 
    WHEN FALSE THEN /* No */ DO: 
      MESSAGE "Deletion canceled." 
        VIEW-AS ALERT-BOX INFORMATION BUTTONS OK. 
      RETURN NO-APPLY. 
    END. 
    OTHERWISE /* Cancel */ STOP. 
  END CASE. 
END. 
FOR EACH Customer NO-LOCK BY Customer.Name: 
  ok-status = cust-list:ADD-LAST(Customer.Name). 
END.  
ENABLE cust-list WITH FRAME sel-frame. 
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

In r-altbox.p, each time you select an item from the selection list, the procedure displays an alert box to ask if you want to delete the customer. If you choose the No button, then another alert box informs you that the record was not deleted.

Notes

The MESSAGE statement always sends messages to the current output destination. If the INPUT source is the terminal, the AVM displays messages in the window and also sends them to the current output destination. Compiler error messages also follow this convention.

If you don’t want messages sent to the current output destination, redirect the output to a named stream. The AVM never writes messages to a named stream.

If you want to send output to a destination other than the terminal, and you do not want messages to appear on the terminal (and if you are not using the terminal as an input source), use one of the statements in Table 46.

Table 46: Suppressing messages to the terminal
Operating system	Input from
UNIX	INPUT FROM /dev/null
Windows	INPUT FROM NUL

Be sure to use the INPUT CLOSE statement to close the input source.

The AVM automatically clears messages after any user interaction, such as a SET, UPDATE, or PAUSE statement, but not after a READKEY statement.

In Microsoft Windows, the message text in VIEW-AS ALERT-BOX is limited to 511 bytes. If the text is longer than 511 bytes, it is truncated.

When you use the MESSAGE SET or MESSAGE UPDATE statement to update a field, the AVM does not process any validation criteria defined for that field in the database. For example, if the validation criteria for the customer.name field is as follows:


Valexp: name BEGINS "a"

Use this statement:


MESSAGE UPDATE name

The AVM lets you enter any data, including data that does not start with the letter a, into the name field.

Use the MESSAGE statement to display a message, but use the SET statement or UPDATE statement to let the user change the data in a frame rather than in the message area.

If you are displaying a message to the message line and the combination of the text and field you name in a MESSAGE UPDATE statement exceeds the length of the message line, the AVM truncates the text to fit on the message line. For example:


DEFINE VARIABLE myvar AS CHARACTER NO-UNDO FORMAT "x(60)". MESSAGE "abcdefghijklmnopqrstuvwxyz" UPDATE myvar.

Here, the combination of the message text and the myvar variable exceeds 80 characters, so the AVM truncates the message text.

Using the MESSAGE statement to display decimal values results in truncating the nonsignificant zeros to the right of the decimal point. For example:


DEFINE VARIABLE amt AS DECIMAL NO-UNDO FORMAT ">>9.99" INITIAL 1.20. MESSAGE "Total" amt.

The previous procedure displays the following message:


"Total 1.2"

Use functions such as STRING and DECIMAL to control the format of a display.

If the APPL-ALERT-BOXES attribute of the SESSION system handle is TRUE, then all your messages are displayed in alert boxes. You can also direct all system messages to alert boxes by setting the SYSTEM-ALERT-BOXES attribute of the SESSION system handle to true. You can remove the message area for a window by setting its MESSAGE-AREA attribute to FALSE before it is realized.

If you use the SET or UPDATE options in a graphical environment, the AVM automatically displays the message as an alert box.

By default, all text in an alert box is displayed on a single line. If you want to break lines within the text, you must explicitly insert SKIP options into the message.

If you use the OUTPUT TO statement to divert ABL error and warning messages to an output stream, ABL also diverts messages from the MESSAGE statement the same way. For more information, see the OUTPUT TO statement reference entry.

The MESSAGE statement does not raise ERROR if the AVM fails to resolve an output expression. Instead, the empty string will be displayed at the specified output location. However, if the block containing the MESSAGE statement contains a CATCH block, then the MESSAGE statement will raise ERROR and you can handle that error with a compatible CATCH block.

You can use the MESSAGE statement with an object reference for a class instance. In this case, the MESSAGE statement implicitly calls the ToString( ) method of the class to convert the specified object reference to a character value before it displays the result.

For SpeedScript, the only valid options are: expression and SKIP.