Programming Guide

msg

Writes a message to the terminal

Synopsis

msg mode message

Arguments

mode
Specifies the message's format and behavior with one of these arguments:

emsg
Displays message as an error message and awaits user acknowledgement.

err_reset
Identical to emsg except when the message is displayed on the status line: in that case, err_reset forces the cursor on at its current position.

qui_msg
Displays message as an error message and awaits user acknowledgement. message is preceded by the SM_ERROR string from the message file–for example, ERROR. In GUIs, the SM_ERROR text is also preceded by the stop icon.

quiet
Identical to qui_msg except when the message is displayed on the status line: in that case, quiet forces the cursor on at its current position.

setbkstat
Installs message as the background status line, which displays when no other message is active.

d_msg
Displays message arguments on the status line and leaves it there until cleared or replaced by another message. Text displayed using d_msg is buffered. You can clear the buffer by another msg d_msg command that supplies an empty string(""). msg d_msg displaces the status line message displayed by msg setbkstat.

message
One or more comma-delimited arguments that comprise the message to display. Each argument can be a string or numeric constant, or a variable. Note that msg query allows only one argument. All other arguments for mode allow multiple arguments.

Description

The msg command displays messages on the status line or in a popup window in one of several modes. Each mode correspond to a Panther library function. To display messages in a dialog box with standard command buttons, call sm_message_box.

Window versus Status Line Display

By default, GUI versions of Panther always display messages in a popup window with an OK button. Character-mode Panther displays messages in a window only if the configuration variable MESSAGE_WINDOW is set to ALWAYS. If you set this variable to WHEN_REQUIRED (the default), character-mode Panther displays messages on the status line except when these conditions occur:

Message Acknowledgment

Users can dismiss the error message by pressing the acknowledgement key. In a window-displayed message, OK and space bar also serve to dismiss the error message. The acknowledgement key (by default, spacebar) can be set through the setup variable ER_ACK_KEY. If the user acknowledges the message through the keyboard, Panther discards the key. You can modify this behavior for individual messages through the %Mu option, described later.

Message Appearance and Behavior

Several setup variables determine default message presentation and behavior. For more information about these variables, refer to "Message Display" on page 2-20 in Configuration Guide. You can change these defaults at runtime through sm_option.

You can change message behavior and appearance for individual messages by embedding percent escape options in the message text. Use these options after the call to sm_initcrt; otherwise, the percent characters appear as literals.

%AattrValue
Change the display of the subsequent string to the attrValue-specified attribute, where attrValue is a four-digit hexadecimal value. If the string to get the attribute change starts with a hexadecimal digit (0...F), pad attrValue with leading zeros to four digits. Refer to Table 45-2 in Application Development Guide for valid attribute values.

This option is valid only for messages that display on the status line. Panther ignores this option if the message displays in a window.

%B
Beep the terminal before the message displays. This option must precede the message text.

%KkeyLogical
Display key label for logical key, where keyLogical is a logical key mnemonic or hex value. When Panther displays the message, it replaces keyLogical with the key label string defined for that key in the key translation file. If there is no label, the %K is stripped out and the mnemonic remains. Key mnemonics are defined in smkeys.h

Note: If %K is used in a status line message, the user can push the corresponding logical key onto the input queue by mouse-clicking on the key label text.

%Md
Force the user to press the acknowledgment key (ER_ACK_KEY) in order to dismiss the error message. Panther discards the key that is pressed. If the user presses any other key, Panther displays an error message or beeps, depending on how setup variable ER_SP_WIND is set. The %Md option corresponds to the default message behavior when setup variable ER_KEYUSE is set to ER_NO_USE.

This option must precede the message text.

%Mt[timeOut]
Force temporary display of message to the status line. Panther automatically dismisses the message after the specified timeout elapses and restores the previous status line display. Timeout specification is optional; the default timeout is one second. You can specify another timeout in units of 1/10 second with this syntax:

#(n)
n is a numeric constant that specifies the timeout's length. If n is more than one digit, the value must be enclosed with parentheses. For example, this statement displays a message for 2 seconds: 
msg emsg "%Mt(20) Changes have been saved to database."
The user can dismiss the message before the timeout by pressing any key or mouse clicking. Panther then processes the keyboard or mouse input.

If the message is too long to fit on the status line, Panther displays the message in a window. In this case, users can dismiss the message only by choosing OK or pressing the acknowledgement key. Panther then discards any keyboard input.

This option must precede the message text. It is ignored by setbkstat and d_msg modes.

%Mu
Force message display to the status line and permit any keyboard or mouse input to serve as error acknowledgment. Panther then processes the keyboard or mouse input.

If the message is too long to fit on the status line, Panther displays the message in a window. In this case, users can dismiss the message only by choosing OK or pressing the acknowledgement key. Panther then discards any keyboard input.

This option must precede the message text. It is ignored by setbkstat and d_msg modes.

%N
Insert a line break. This option is invalid for setbkstat and d_msg modes.

%W
Forces display of the message in a window. This option is ignored by setbkstat and d_msg modes.

Example

// Indicate that the entry to the field state is invalid.
msg err_reset ':state is not a U.S. state'
 
// Indicate that the current entry is being processed.
// Note that d_msg overrides delayed write and immediately
// flushes text to the screen.
msg d_msg 'Processing :name'
 
// Ask whether the user wants to quit the current screen.
vars quit
 
quit = sm_message_box \
	('Are you ready to quit?' ,"",SM_MB_OKCANCEL,"")
 
if quit = SM_ID_OK
  return 0
 
vars field1 message
field1 = "message"
message = "Quick brown fox"
 
// This will display 'message' on the status line.
msg emsg field1
 
// This will also display 'message'.
msg emsg ":field1"
 
// This will display 'field1'.
msg emsg "field1"
 
// This will display 'Quick brown fox'.
msg emsg :field1
 
// These messages use percent escapes.
// Print message in red
msg emsg "%A004Stop now."
 
msg emsg "The menu toggle is %KMTGL"
msg emsg "Enter value.%NPress XMIT."
msg qui_msg "%WInvalid password."
msg err_reset "%MdPlease enter a positive value."

See Also

sm_message_box