9.146 MESSAGE_BOX_SHOW

Note: Built-In Function Rules     Usage Options

Causes a standard MS Windows message box to be displayed. It then waits until the user clicks one of a specified set of buttons in the message box before returning control to the application.

Arguments

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Opt Specifies the button(s) to be displayed in the message box. This value should be specified as: 'ABORTRETRYIGNORE' 'OK' 'OKCANCEL' 'RETRYCANCEL' 'YESNO' 'YESNOCANCEL' If this argument is not specified or is invalid it will be set to 'OK'.  1 20     2 A Opt Specifies which of the enabled buttons is to be the default button. This value should be specified as: 'ABORT' 'RETRY' 'IGNORE' 'OK' 'CANCEL' 'YES' 'NO' If this argument is not specified or is invalid it will be set to the first button specified by argument 1. If argument 1 is also not specified or invalid it this argument will be set to OK. 1 20     3 A Opt Icon to be displayed in message box. This value should be specified as: 'EXCLAMATION' ' WARNING' 'INFORMATION' ' ASTERISK' ' QUESTION' 'STOP' 'ERROR' 'HAND' 'NONE' If this argument is not specified or it is invalid this argument will be set to 'NONE'.  1 20     4 u Opt Message Box Title. If  this argument is not specified this argument defaults to the description of the application that is using the Built-In Function.  1 256     5 U Opt Overriding message text. This value will override and replace any text currently in the message box assembly area.  This argument allows simple messages to be presented without having to use using the ADD and APPEND Built-In Functions. 1 256

Return Values

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Opt Button used to close the message box window. This will be returned as: 'ABORT' 'RETRY' 'IGNORE' 'OK' 'CANCEL' 'YES' 'NO' The exception to this rule is when this Built-In Function is used in a non-Windows environment. In this case the return value is the default value specified by argument 2 (regardless of its validity). 1 20

Technical Notes

• The message assembly area is cleared at completion of this Built-In Function.

• If invoked in an appropriate environment (eg: batch task, non-Windows environment) no message window is displayed and the default button value is returned.  The value returned is the default value specified in argument 2.

• You should ensure that the default button, when specified, is valid and appropriate for all situations. 

Examples

Present the simplest possible message box:

USE BUILTIN(MESSAGE_BOX_SHOW)

Present a message box enabling the OK and Cancel buttons (with Cancel as the default), title "HELLO", the question icon and text "Do you want to do your backups now?".

USE BUILTIN(MESSAGE_BOX_SHOW) WITH_ARGS(OKCANCEL CANCEL QUESTION HELLO 'Do you want to do your backups now?') to_get(#std_codel)

if '#std_codel *eq CANCEL'

Return

endif

Format some details of an employee into the message box assembly area as individual lines and then display them with just an OK button. 

use message_box_add ('Employee Number:' #empno)

use message_box_add ('Name:' #givename #surname)

use message_box_add ('Department:' #deptment)

use message_box_add ('Section:' #section)

use message_box_add ('Salary:' #salary '(monthly =' #mnthsal ')' )

use message_box_show