Programming Guide

Displays an error message and awaits user acknowledgement

void sm_femsg(int msg_num, char *message);

msg_num

A Panther message number. If you supply a string value for message, Panther ignores this parameter.

message

The error message to display. To use the msg_num-specified message, set this parameter to NULL.

sm_femsg displays the specified message either on the status line or in a popup window and awaits user acknowledgement. This function also calls the error event function if one is installed.

By default, GUI versions of Panther always display messages in a popup window with an OK button. Character-mode Panther always 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), Panther displays messages on the status line except when these conditions occur:

• The message overflows the status line. Note that Panther prevents the message from overlapping the cursor row/column display, if it is turned on.

• The message wraps to multiple lines.

• You specify window display with the %W format option.

  Note: You can force display of a message to the status line on all GUI and character-mode platforms, regardless of MESSAGE_WINDOW's setting, if the message contains the %Mu option, or the behavior variable ER_KEYUSE is set to ER_USE.

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, space bar—can be set through the behavior 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.

Several behavior variables determine default message presentation and behavior. For more information about these variables, refer to Chapter 2, "Application Variables," 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.

%Aattr-value

Change the display of the subsequent string to the attr-value-specified attribute, where attr-value is a four-digit hexadecimal value. If the string to get the attribute change starts with a hexadecimal digit (0...F), pad attr-value with leading zeros to four digits. refer to Table 45-2 in the 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 with sm_bel before the message displays. This option must be at the beginning of the message.

%Kkey-logical

Display key label for logical key, where key-logical is a logical key constant. When Panther displays the message, it replaces key-logical 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 constant remains. Key constants 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 behavior variable ER_SP_WIND is set. The %Md option corresponds to the default message behavior when behavior variable ER_KEYUSE is set to ER_NO_USE.

This option must precede the message text.

%Mt[time-out]

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)


where 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:

err = sm_femsg(0, "%Mt(20)Changes 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.

%Mu

Force message display to the status line and permit any keypress to serve as both error acknowledgment and data entry. Panther processes the key that is pressed. This option must precede the message text. This option corresponds to default message behavior when behavior variable ER_KEYUSE is set to ER_USE.

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 by pressing the acknowledgement key or space bar. Panther then discards any keyboard input used to dismiss the message.

%N

Insert a line break and force display of the message in a window.

%W

Force display of the message in a window. This option must be at the beginning of the message.

sm_ferr_reset, sm_fqui_msg, sm_fquiet_err

---

---