User messages are the most important part of communication between software and its users. Messages tell users when the hardware or software cannot perform as requested. It is vital in these situations to report in accurate detail the circumstances of the problem and the path to a solution.
Silicon Graphics/Cray Research has systems installed worldwide. Our users require not only accurate message information, but also access to the messages so that they can be translated to the native language of users who do not speak English.
The Cray message system consists of tools and procedures for issuing messages to users from program code and delivering documentation on those messages in a format that is suitable for translation.
The Cray message system is based on the X/Open Native Language System specification as described in the X/Open Company Standard XPG4. Cray Research has provided extensions to the standard that include a more complete set of tools and procedures for working with messages and message explanations.
Any programmer can use the message system tools in a Cray Research UNICOS or UNICOS/mk environment or in a Silicon Graphics IRIX environment. This manual explains how the message system is designed to work and how you can use it from your programs. The examples in this document assume that you are using the C language; however, any language that can call C library functions can use the Cray message system.
 | Warning: Sites using the Cray ML-Safe configuration of the UNICOS or UNICOS/mk operating systems or the Trusted IRIX operating system can use the information and procedures outlined in the following sections to change or add messages. However, for changed messages, you must not alter the original, underlying meaning of the message. |
The message system includes the following features, which aid in improving error reporting and problem resolution:
message catalogs, located separately from the program code, which contain the text of the messages issued at run time
explanation catalogs, located in the same directory as the message catalogs, which contain a discussion of the problem and suggested solutions
Online access to message explanations through the explain(1) command
User control of the message format through the MSG_FORMAT environment variable
User control of the language of the message text (where translated messages are supplied) through the LANG environment variable
Message and explanation text source files distributed with the release to allow local modifications of the message or explanation text
Published guidelines for writing good messages and good message documentation
Each chapter of this document discusses an aspect of the message system.
Chapter 2, “Message System Design”, describes each part of the message system and the purpose it serves.
Chapter 3, “Using the Message System”, provides a sample procedure for converting an existing piece of software to use the message system.
Appendix A, “Guidelines for Messages and Explanations”, is an appendix that lists guidelines for writing effective messages and usable message explanations.