NAME

fmtmsg - Displays a message in the standard format

SYNOPSIS

#include <fmtmsg.h> int fmtmsg (
     long classification,
     const char ∗label,
     int severity,
     const char ∗text,
     const char ∗action,
     const char ∗tag );

PARAMETERS

classification
Defines the origin, type, and status of a message.  This information is not displayed to the user.   To define the origin, type, and status of a message, you must select options from the available class and/or subclasses. More than one option from a subclass can be combined with an option from a different subclass by ORing the values together.  Using two or more options from the same subclass is not allowed with the exception of options from the Display Subclass.  The following class and subclasses are available:

Major Class
Specifies the source of the condition.  The options are MM_HARD (hardware), MM_SOFT (software), and MM_FIRM (firmware). 

Message Source Subclasses
Specifies the software type that exhibits the problem.  The options are MM_APPL (application), MM_UTIL (utility), MM_OPSYS, and (operating system). 

Display Subclass
Specifies where the message is displayed.  The options are MM_PRINT (standard error) or MM_CONSOLE (system console).  Both options may be specified together. 

Status Subclass
Specifies whether the application will recover from the condition.  The options are MM_RECOVER (can recover) or MM_NRECOVER (cannot recover). 

Note that you can specify MM_NULLMC to indicate that a class is not specified for the message. 

labelSpecifies the message source.  The label format consists of two fields separated by a colon.  The first field can contain up to 10 characters.  The second field can contain up to 14 characters.  It is suggested that label contain at least the name of the application. 

severitySpecifies the severity of the condition.  The options are as follows:

MM_ERROR
Specifies that application has encountered an error. Outputs the print string ERROR. 

MM_HALT
Specifies that the application has stopped running because it has found a severe error. Outputs the print string HALT. 

MM_INFO
Displays information about a nonerror condition. Outputs the print string INFO. 

MM_NOSEV
Specifies that a severity level has not been provided for the message.

MM_WARNING
Specifies a condition that might be a problem and should be monitored. Outputs the print string WARNING. 

textDescribes the error that produced the message. The text string has no maximum length. 

actionDescribes the first action to be taken to recover from the error condition.  The fmtmsg() function prefixes every action string with the following: TO FIX:. The action string has no maximum length. 

tagPoints the user to the online documentation for the message. It is suggested that tag include the label as well as a unique identifying number. For example, a sample tag is the following: pg:002. 

DESCRIPTION

The fmtmsg function writes a formatted message to either standard error, the system console, or both.  Any message typically written to standard error (stderr) by printf can also be displayed using the fmtmsg function.  A formatted message can contain up to five fields that describe the purpose of the message.  The fields are defined by the label, severity, text, action, and tag parameters.  The classification parameter additionally defines the source of a message and directs the output of a message.  The previous section describes these parameters in detail.  You must include the <fmtmsg.h> header file in your application to define the display and format of messages. 

One or more fields may be omitted from messages by using the null value of that parameter.  The following table specifies the null value for each parameter. 

Customizing Messages

There are two environment variables, MSGVERB and SEV_LEVEL that let you optionally define the behavior of the the fmtmsg function.  These variables can be globally defined in the system’s \tc
rofile by the system administrator.  Likewise, you retain the option of overriding the system defaults by defining the variables in your .profile file, or by specifying the option through your command line interface. 

The MSGVERB (message verbose) environment variable defines which parameters are used by the fmtmsg function when writing a message to standard error (stderr).  Only the parameters that are defined and applicable are displayed.  If this variable is not set or a parameter is invalid, the fmtmsg function displays all of the available parameters by default.  The syntax is:

MSGVERB=[parameter[:parameter[: ...]]] export MSGVERB

The valid parameters are: label, severity, text, action, and tag.  These parameters may be specified in any order.  See the PARAMETERS section for parameter definitions. 

The SEV_LEVEL (severity level) environment variable lets you define, modify, or delete severity levels other than the default.  Each severity level that you define has a print string associated with it that is used by the fmtmsg function.  The syntax is:

SEV_LEVEL=[description[:description[: ...]]]
export SEV_LEVEL

The description arguments consists of three fields separated by commas as follows:

description=severity_level,level,printstring

The value of each field is:

severity_level
Specifies the severity of the level.

levelSpecifies a severity level with any positive integer except 0 to 4 (the standard severity levels). 

printstring
Specifies the severity level message used by the fmtmsg() function whenever the severity level level is used. 

If the SEV_LEVEL environment variable is not set, or it has a null value, the defaults are used. If the description is not a three-field comma is not a 3-field comma separated list as described previously or if the level field specified is not a positive integer, the SEV_LEVEL environment variable setting is ignored. 

The SEV_LEVEL environment variable can be set in the user’s shell or used in shell scripts. 

EXAMPLES

     1.The following fmtmsg() function example produces the following message in the standard message format:

fmtmsg(MM_PRINT, "pg", MM_ERROR, "invalid syntax",
cat: ERROR: invalid syntax
TO FIX: refer to manual  pg(1):002

     2.When the environment variable MSGVERB is set as follows and the Example 1 is used, the fmtmsg() function produces the following results:

MSGVERB=severity:text:action

ERROR: invalid syntax
TO FIX: refer to manual

     3.When the environment variable SEV_LEVEL is set as follows, the call to the fmtmsg() function produces the following results:

SEV_LEVEL=note, 5, NOTE

fmtmsg(MM_PRINT | MM_UTIL, "pg", 5, "cannot open file",
"specify correct file name", "pg(1):002")

cat: NOTE: cannot open file
TO FIX: specify correct file name pg(1): 002

RETURN VALUES

The fmtmsg() function returns the following values:

MM_NOCON
Unable to return a console message, but nonetheless succeeded.

MM_NOMSG
Unable to return a message on standard error, but nonetheless succeeded.

MM_NOTOK
Complete failure.

MM_OK
Successful completion.

RELATED INFORMATION

Functions: printf(3).