Application Development


Chapter 26 . Displaying Messages

Panther provides commands and functions that let you display Panther messages in a window or on the status line, or as dialogs. Three-tier applications can send messages between clients and from a server to the client. You can also write a hook function that executes every time one of the error message display functions is called.

This chapter describes the different mechanisms for displaying and handling messages. For information on how to handle errors that occur on a server, refer to Chapter 37, "Processing Application Errors." For information about event processing and error handling for JetNet and Oracle Tuxedo middleware events, refer to Chapter 6, "JetNet/Oracle Tuxedo Event Processing," in the JetNet/Oracle Tuxedo Guide.


Window Versus Status Line Display

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), character-mode Panther displays messages on the status line except when these conditions occur:


Acknowledging Messages

Users can dismiss an 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 by embedding the %Mu option in the message string (refer to this section).


Disabling Messages

You can control whether the application displays error messages by setting I_NOMSG with the sm_iset function.

proc no_msg
call sm_iset(I_NOMSG, 1) //Turn off error messages
return

Setting Display Defaults

Several setup variables determine default message presentation and behavior. For more information about these variables, refer to"Message Display" in the 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. For more information on these, refer to "Setting Message Display and Behavior Options."


Message Functions

Table 26-1 describes library functions that display errors, messages, and status information. Other functions are related to message storage and retrieval. Message display functions such as sm_ferr_reset and sm_fquiet_err can either supply a string argument for the message content, or specify a message that is defined in the message file:: For example, this JPL call to sm_ferr_reset specifies the string to display in a message window:

call sm_ferr_reset (1, "ZIP CODE INVALID FOR THIS STATE.")

The next statement supplies a constant (defined in smerror.h) to invoke the application message Entry is required.

call sm_ferr_reset ( SM_RENRY, @NULL )

Application messages are defined in a binary message file and are loaded into memory at initialization. For more information about message files, refer to "Using Message Files."

Table 26-1 Message related functions

Function Description

Message display (window or status line):

sm_femsg

Displays a message and awaits user acknowledgement.

sm_ferr_reset

Identical to sm_femsg when displayed in window. When displayed on status line, puts cursor on at current widget.

sm_fqui_msg

Identical to sm_femsg except that it prepends a tag—for example, ERROR:—to the specified message. Gets the tag from the SM_ERROR entry in the message file.

sm_fquiet_err

Identical to sm_ferr_reset except that it prepends a tag —for example, ERROR:—to the specified message. Gets the tag from the SM_ERROR entry in the message file.

sm_inimsg

Creates a displayable error message on failure of an initialization function For example, if attempts to initialize a message file fail, supply sm_inimsg with the error code returned from the failed function and a description of the function itself.

sm_inimsg uses this information to return a string that you can display—for example, by passing it to sm_fqui_msg.

Dialog box display:

sm_message_box

Displays a message in a dialog box and requests the user to choose a button such as Yes/No, Abort/Retry/Cancel. Pre vents further interaction with the application until the function returns with the user's selection.

Status line display:

sm_d_msg_line

Can change display attributes of message.

sm_m_flush

Forces display of updates to the status line. Useful if you want to display the status of an operation with sm_d_msg_line without flushing the entire display (e.g., with sm_flush).

sm_msg

Merges the specified message with the current contents of the status line and displays it at the specified column.

sm_setbkstat

Saves the contents of a message for display on the status line when there is no other message with a higher priority to display.

sm_setstatus

Toggle status line flags. The alternating messages are stored in message file variables SM_READY and SM_WAIT.

Message file access:

sm_msg_get, sm_msgfind

Gets the contents of an application message. Application messages are defined in a binary message file, referenced by the application variable SMMSGS.

sm_msg_read

Reads into memory a set of application messages from the message file.

sm_msg_del

Removes from memory a set of application messages.

Notes: GUI applications should avoid posting message dialog boxes while the mouse button is down. For example, do not call sm_femsg from a widget's exit function if the user can mouse click out of that widget into a push button. Doing so can confuse Motif and cause unexpected behavior.


Broadcasting Messages

In JetNet and Oracle Tuxedo applications, two JPL commands enable transmission of unsolicited messages between clients and servers:

Messages are embedded in one of the service message data types that Panther supports, such as JAMFLEX or FML (Oracle Tuxedo only). For example, the following command broadcasts a message to a client supervisor. It uses source to identify itself as the source of the message:

broadcast CLIENT "supervisor" TYPE JAMFLEX \
({source="bcast_security", ACCOUNT=acct, DATE=date,\
SECURITY=code, MSG=message})

One message handler, installed at application scope, processes all broadcast messages, whether sent by broadcast or notify. The contract for the default message handler sm_tp_message_print_string specifies STRING-type message data; this data type is valid only in Oracle Tuxedo applications, and limits the broadcast data to a single string. To broadcast complex data, you must write and install a message handler that accepts buffer-type data; to broadcast messages in JetNet applications, this data must be of type JAMFLEX.

If your application needs to broadcast messages with variable content and handling requirements, you should write and install a message handler that receives data from a buffer-type message type such as JAMFLEX. For example, the following message handler uses the first field of a JAMFLEX message to determine the nature of the message and how to handle its contents.

// Message handler for all unsolicited messages
proc msg_handler(type, subtype)
vars source, account, date, security, message
vars companyNews, teamNews, stock, stock_quote
vars fileStream, acctMsg
// Identify message sender.
receive MESSAGE ({source})
if (source == "bcast_security")
{
// receive security violation data
receive MESSAGE ({account, date, security, message})
	// Alert the supervisor
msg emsg "%A004Security alert: " ## message ## \
"%NDate: " ## date ## \
"%NAccount No. " ## account ## \
"%NCode: " ## code
}
else if (source == "bcast_acct_data")
{
// receive account data
receive MESSAGE ({account, date, message})
acctMsg = account##" "##date##" "##message
	// write message data to log file 
fileStream = sm_fio_open("/u/acct/logfile", "a")
if fileStream > 0
{
call sm_fio_puts(acctMsg)
call sm_fio_close(fileStream)
}
}
...
else if (source == "post_comp_news")
{
// receive posted company news message data
receive MESSAGE ({ companyNews })
msg emsg "Latest company news: " ## companyNews
}
...
return 0

Status Line Usage

When running in character-mode, Panther reserves one line on the display for error and other status messages. The rightmost part of the status line can display the cursor's current screen position; this can be controlled by calls to sm_c_vis.

Message Display

Several types of messages can use the status line; they are described here in order of their priority from highest to lowest.

Error messages

Several functions can be executed to display a message on the status line, wait for acknowledgment from the operator, and then reset the status line to its previous state: sm_ferr_reset, sm_femsg, sm_fquiet_err, and sm_fqui_msg. As noted earlier, these functions display messages on the status line only under certain conditions ("Window Versus Status Line Display" ). If displayed on the status line, these functions wait for the message to be acknowledged. Messages displayed with these functions have highest precedence.

sm_d_msg_line messages

The library functions sm_d_msg_line and sm_msg cause the display attributes and message text you pass to remain on the status line until erased by another call to the same function or overridden by a message of higher precedence.

Ready/Wait

The library function sm_setstatus provides an alternating pair of background messages. Whenever the keyboard is open for input the status line displays Ready; Wait is displayed when your program is processing and the keyboard is not open. You can change (translate, rephrase, etc.) the display text by editing the SM_READY and SM_WAIT entries in the Panther message file.

Widget/Menu item status

When the status line has no higher priority text, Panther checks the current widget or selected menu item for text to be displayed on the status line. If the cursor is not in a widget or on a menu item, or if the current widget or item has no status text, Panther uses the string that is set for the screen's status_line_text property.

Screen status

When the status line has no higher priority text, Panther checks the current screen's status_line_text property for text to display on the status line. If this property is not set, Panther looks for background status text.

Background status

Background status text, the lowest priority of message display, can be set by calling the library function sm_setbkstat and passing it the message text and display attributes.

Other Status Line Information

In addition to messages, the status line can hold other information such as cursor position coordinates and debugging information.

The rightmost part of the status line can display the cursor's current screen position as, for example, C 2,18. The display is controlled by calls to sm_c_vis.

sm_fquiet_err (sm_msg_get (SM_MALLOC));

Key constants can be found in the file smkeys.h or another of the key header files.


Error Hook Function

Panther calls its installed error function whenever you call one of its error message display routines, such as sm_fquiet_err or sm_ferr_reset. You can use the error function for special error handling—for example, to write all error messages to a log file. For more information on writing and installing your own hook function, refer to "Error Function."