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:

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.

Notes: You can force display of a message to the status line on all GUI and character-mode platforms, regardless of the MESSAGE_WINDOW setting, if the message contains the %Mu option, or the setup variable ER_KEYUSE is set to ER_USE. Also, the setbkstat and d_msg modes always display messages on the status line.

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:

broadcast sends a message to all clients that match the specified criteria, or to all clients. Both clients and servers can broadcast messages.
notify sends a message to the client whose service request the server is currently processing. Only servers can use notify to send messages.

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.

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."