Description

Displays dynamically constructed system messages.

Syntax

variablereturn = Msg(ownerwindow, msgstructure, msgname, reserved, parameters)

Parameters

The Msg function has the following parameters.

ParameterDescription
OwnerwindowMsg requires a parent window.

Note: When using an MDIFrame, the ownerwindow will always be the frame regardless of the value passed to the variable. To display a message without being in event context (for example, if code is executed from the system editor) use the Windows API function MessageBox. This requires SYSTEM MODAL to be set and all string parameters to be terminated with char(0).

An older version of Msg did not require a parent window. This older version is still shipped with OpenInsight in order to support existing software but has been renamed as Msg2. Msg2() is automatically called if the message is displayed outside of event context.

MsgstructureContains the message definition. This structure is detailed table below. If msgname is passed, the message details that are passed in msgstructure are used to override the corresponding parts of the message definition stored in the repository.
MsgnameTo display a message stored in the repository, pass either the name of the message or the message's entity id.
ReservedThis value is reserved; pass "".
ParametersAn @fm-delimited list of substitutable parameter values. Within the message text, the string "%1%" is replaced with the first substitutable parameter, "%2%" is replaced with the second, and so forth.

Remarks

Note: The Msg function resets the Set_Status() code to zero (0).

Use Msg either for display messages (i.e. error handling) or use it for gathering very small scale user input, as for example with Continue? Yes No situations.

The return value depends on the value passed for the type field of the msgstructure argument.

Note: If you are trying to use the MSG function and the variable you are trying to display contains any system delimiters it may not display correctly. (for example, a message box or button may display with garbled text or won't function properly) What you need to do is use either the CONVERT or SWAP statements.

For example:

CONVERT @fm to ',' in VarName

-or-

SWAP @fm with ', ' in VarName

Your message box should now display correctly.

Message Structure

Use the MSG_EQUATES insert record for access to the values in the following table.

Field PositionNamePurpose
1text" (the vertical bar) or @tm. Default is null.
2typeMessage types:

Information Types

TypesButtons Displayed on Message
BOOK
BOCOK/Cancell
BNYYes/No
BNYCYes/No/Cancel
BRCRetry/Cancle
BARAbort/Retry
BARIAbort/Retry/Ignore
B{LIST}User defined buttons, where {LIST} is a comma-delimited list of button text, e.g. "BStop,Continue"

Response Types

TypesDescription
RResponse message, returning default input if escape pressed.
RCSame as R, but converting response to upper case.
RCESame as RE, but converting response to upper case.
REResponse message, returning Char(27) if escape pressed.

Timed Types

TypesDescription
T{n}Timed message of n seconds, eg. "T2.5".
TA{n}Asyncronous timed message (splash screen) of n seconds, eg. "TA10".

Note: The message will not close until the engine is idle unless the Yield() function is called.

Processing Types

TypesDescription
UDisplays the message and returns immediately (see example below).
DCloses a processing message; the return value from a U-type message is a D-type message structure which will close the message.

Miscellaneous Types

TypesDescription
NPrefixing any of the message types with "N" suppresses the message display, returning the message's default value. This can be used to change messages from interactive to non-interactive for batch processes; for example, instead of "BARI", pass "NBARI" (meaning don't display the abort/retry/ignore message)
3modality
ValueDescription
WWindow. The message's parent window is disabled while the message is displayed.
AApplication. The OpenInsight application is disabled while the message is displayed.
SSystem. All windows from all applications are disabled while the message is displayed.
4icon

The image to display on the Msg.

ValueDescription
NullNone
*Asterisk (Info)
?Question
!Warning
HHalt
BUser-specified bitmap (specified in the bitmap field)
5default button1, 2, or 3 depending on number of actual buttons. Response messages don't have a default button; the edit control has the focus. Default is 1.
6colx position to place the dialog box.

A value of -1 centers within the message's parent window. A value of -2 centers with respect to the screen. If either col or row is -1 or -2, then the message is centered accordingly, both horizontally and vertically.

7rowy position to place the dialog box.

A value of -1 centers within the message's parent window. A value of -2 centers with respect to the screen. If either col or row is -1 or -2, then the message is centered accordingly, both horizontally and vertically.

8justification

Message text justification.

JustificationDescription
TText (default). Text Formatting with word wrap.
LLeft
RRight
CCenter
9bkcolor@VM-delimited list specifying R,G,B background color.

For example: "255:@VM:255:@VM:255" is White, "255:@VM:0:@VM:0" is Red.

Default is white.

10fgcolor@VM-delimited list specifying R,G,B foreground color. Default, "0:@VM:0:@VM:255", is blue.
11text widthThe message width; for response messages, this specifies the response field width.
12captionDialog box caption text. Default is "Message."
13validationValidation pattern to check response message return values against with IN.VALUE. Default is null.
14default inputDefault input to be put into edit control in a response message. (Default is null.)
15mask input

A boolean value used to determine if the input should be masked with asterisks? This is used for password entry.

ValueDescription
0No masking
1Masked
16bitmapName of a bitmap registered in the Repository. Used when icon is set to "B".
17clip bitmapBoolean value, true to clip bitmaps, false to resize; see the IMAGECLIP property for more detail.
18fontFont structure for the text of the message; see the FONT property for more detail.
19literal functionBoolean value. When TRUE the Msg() function assumes that the default value is the name of a function which returns the default value for the message.

For example, if you wrote a function called CURRENTUSER which returned the user name of the current user, you could specify CURRENTUSER as the default value (MDEFINPUT$) and set MLITERAL$ to true, so that the current user name would be the default value for the message; parameters are passed to the specified function depending on the number of parameters that are supported by the function

# of ParamsValues Passed in Parameter
0None
1MsgName
2+MsgName, MsgStructure
20help

Used to add a Help button the message. The structure of the field is an @vm-delimited array of Help information.

PositionDescription
<20,1>

Help Type

TypeDescriptionSpecifier
QQuickHelpName of the APPNOTE entitiy.
MMessageName of the MSG entity
HWinHelpHelpFile, HelpId
SStored ProcedureProcedure Name[, param1..]
<20,2>Help specifier that is specific to the above Help Types.
<20,3>Button text. Defaults to "&Help".

Note: Specify the AppNote, Message, HelpFile, or ProcName as it appears in the repository outliner. For example, the OINSIGHT.HLP file is registered as OINSIGHT, so specify the HelpFile as "OINSIGHT" (look in the outline under "General", "Windows Components", "Help Files")

21requiredBoolean value specifying whether a response-type message requires a response; false allows nulls (default) while true doesn't.
22beepAn integer value specifying a system beep. For more information, see MessageBeep in the Windows API.

Returns

Msg() return values are indicated in the following table.

Message TypeReturn Value
BOReturns null if OK clicked, Char(27) if escape pressed.
BOCReturns null if OK clicked, Char(27) if escape pressed or cancel clicked.
BNYReturns 1 if yes clicked, 0 if no clicked, Char(27) if escape pressed.
BNYCReturns 1 if yes clicked, 0 if no clicked, Char(27) if cancel clicked or escape pressed.
BRCReturns 2 if RETRY clicked, Char(27) if Cancel clicked or ESCAPE pressed
BARReturns 1 if ABORT clicked, 2 if RETRY clicked, Char(27) if ESCAPE pressed.
BARIReturns 1 if ABORT clicked, 2 if RETRY clicked, 3 if IGNORE clicked, Char(27) if ESCAPE pressed.
B{list}1, 2, or 3 for the first, second, or third button (from left to right), Char(27) if ESCAPE pressed.
RReturns entered value if OK pressed, default response if CANCEL clicked or ESCAPE pressed.
REReturns entered value if OK pressed, Char(27) if CANCEL clicked or ESCAPE pressed.
RC, RCEReturns the same as R and RE, except that the response is converted to uppercase.
UReturns a D-type msgstructure that can be passed to a subsequent call of Msg() to take down the processing message.

Examples

Example 1

* request the user's password (and return it uppercased)
 
Def = ""
 
Def<MTEXT$> = "Enter your password:"
 
Def<MTYPE$> = "RCE"
 
Def<MICON$> = "?"
 
Def<MMASKINPUT$> = TRUE$
 
 
 
Password = Msg(@window, Def)
 
if Password = char(27) then
 
   * user escaped from the message
 
end else
 
   * user supplied password (which could be null) and pressed enter
 
end

Example 2

* display a message stored in the repository as "ERROR_MESSAGE"
 
Text = "An error occurred opening the table for processing."
 
Msg(@window, Text, "ERROR_MESSAGE")

Example 3

* display a message while batch processing
 
Def = ""
 
Def<MTEXT$> = "Processing..."
 
Def<MTYPE$> = "U"
 
* display the processing message and do the processing
 
MsgUp = Msg(@window, Def)
 
gosub BatchProcess
 
* take down the processing message
 
Msg(@window, MsgUp)

Example 4

/* display a gas gauge to show progress while processing 1000 orders */
 
$insert msg_equates
 
OrderCnt = 1000
 
Def = ""
 
Def<MCAPTION$> = "Processing Orders..."
 
Def<MTYPE$   > = "GC"
 
Def<MEXTENT$ > = OrderCnt
 
Def<MTEXTWIDTH$ > = 400
 
MsgUp = Msg(@window, Def)
 
for Order = 1 to OrderCnt
 
    /*  process the order */
 
    * update the gauge and check if cancel was pressed
 
while Msg(@window, MsgUp, Order, MSGINSTUPDATE$)
 
next Order
 
/*  we are done, take down the gas gauge */
 
Msg(@window, MsgUp)         ;* take down the gauge

Example 5

* logon processing with a batch screen
 
Def = ""
 
Def<MTYPE$> = "TA5"
 
* display 5-second splash-screen while performing login processing
 
Msg(@window, Def, "SPLASHSCREEN")
 
gosub Logon_Process
 
* allow the message to close if 5 seconds have elapsed
 
Yield()
 
gosub Setup
  • No labels