Users running your application expect messages to be displayed in message footers, error dialogs, or warning dialogs, with further explanations available in online help when appropriate. In some circumstances, messages may be logged that aren't necessarily displayed to users. Applications in the Common Desktop Environment follow common models for presenting and logging error messages and warnings. Because of the way message text is handled, users may not see messages from your application unless you display them in a dialog, footer, or elsewhere in the user interface. In CDE, such messages are directed to log files that a casual user may not routinely examine. Use the following rules when deciding where to tell users about warnings, messages, and error conditions: If the message is informational, display the text in the message footer of the application; for example, “MyDoc file copied.” If the message is about an error or serious warning—a problem where an operation important to the user has failed—display an error dialog or warning dialog. A good error dialog or warning dialog gives the user the following information: What happened (from the user's point of view) Why it happened, in simple language that the user can relate to the current task and environment How to fix the problem If the information cannot be presented in four or five lines of the error dialog, consider adding a help button to the dialog and link it to a topic in the help volume for your application. For more information on writing messages, see the Common Desktop Environment: Internationalization Programmer's Guide. In cases where additional background information is required, or where it takes more than four or five lines of a dialog to explain an error fully, you should add a button that links the user to online help. Adding online help for a dialog is a straightforward task. Once you have decided that a particular dialog is a candidate for online help, do the following: Choose a unique ID for the error help. This ID provides the link to the online help text. IDs should be 64 characters or less; for example, DiskSpaceError. Create the dialog and add a help callback. Use the XmCreateErrorDialog convenience function for error messages and XmCreateWarningDialog for warnings, adding the help callback as follows: XtAddCallback(dialog, XmNhelpCallback, helpfn, “ID”); In this example, helpfn is a help function you have created to manage the help dialog, and the string “ ID” is the ID you chose for the error message (for example, DiskSpaceError). In your help function, set the XmNlocationId resource to the value of ID. The /usr/dt/examples/dthelp directory contains examples of how to set up such a help function. For detailed information about creating and managing help dialog widgets, see the Common Desktop Environment: Help System Author's and Programmer's Guide. Write a corresponding help section for the error message. Document the message in the “messages” chapter of your help volume. In the help source document, you should have a separate section for each message, and the ID= attribute at the beginning of the section should match the ID you chose in your code for the error. For example, in the s1 section heading, the ID is DiskSpaceError. When the user's system has insufficient disk space, the error message the user sees from the following heading is “Could Not Save File.” <s1 ID=DiskSpaceError>Could Not Save File <\s1> Note that by convention, the text of the section heading should correspond closely to the text in the error dialog. Rebuild the help file. The new help section for the error message becomes active as soon as you rebuild the help file (using the dthelptag program) and recompile your application. For information about writing and building online help, see the Common Desktop Environment: Help System Author's and Programmer's Guide. If a recovery routine exists for an error condition, consider adding a Retry button to the dialog. For example, if a file could not be copied because the system had insufficient disk space, you might offer a Recopy option in the dialog that users could choose once they have corrected a disk space or permissions problem. error messageslogging message logginggeneral information The message logging service logs messages for CDE applications. This service provides a central location for messages that a user or system administrator can use to diagnose problems. In the desktop environment applications are started via the File Manager or Front Panel (as opposed to direct invocation from a shell). If an application writes important information to stderr, the information may be lost. For this reason, the application should use the CDE message logging service to log the information so that users can find it in the log. Libraries and applications that have no user interface also use this service to log messages. Such applications should use the message logging service instead of writing to the system console or to stderr. The message logging service supports the following types of messages: Information — informational messages to which users need not be alerted (for example, status information). It may be acceptable for the user never to see messages of this type. Stderr — if an application needs to log the stderr from a child process, the captured stderr should be logged as a Stderr message type. For example, the dtexec program uses this message type to identify the messages it logs (the stderr from command-type actions). Debug — an application's debugging messages (for example, those seen when a -debug command line option is used) should be logged as Debug type messages. Warning — this type is for errors that are not severe enough to cause application program termination. Error — this type is for fatal errors that require program termination. For daemon-type applications that have no user interface (for example, low-level services started by the inetd), it is appropriate to use the system's "syslog" service rather than the CDE message logging service. message logginglog entry format Entries in the message log are formatted as follows: *** msgtype_string (msg_type): program_name: PID proc_id: date message_text *** [bytes_output] For example, *** WARNING(3): fontview: PID 12312: Thu Jun 13 16:51:51 1995 The specified font 'fixed' could not be loaded. *** [109] One newline is output after the date, one newline after the message text, and two after the number of bytes (a blank line separates log entries). The message type string and date specification should be retrieved from the current locale's message catalog; it is the application's responsibility to localize the message to be logged. The message logging API comprises the following functions: DtMsgLogMessage — logs a message to the message log.DtMsgLogMessage DtMsgLogSetHandler — installs an alternate message logging handler that is invoked when the application calls DtMsgLogMessage. This function is optional and should be used only to override the default message logging handler.DtMsgLogSetHandler DtMsgLogOpenFile — opens a message log file.DtMsgLogOpenFile