NAME

DtMsgLogSetHandler — installs an alternate message logging handler

SYNOPSIS

#include &<Dt/MsgLog.h>
DtMsgLogHandler DtMsgLogSetHandler(
DtMsgLogHandler handler);

DESCRIPTION

The DtMsgLogSetHandler function installs an alternate message logging handler that will be invoked when DtMsgLogMessage is called. If handler is NULL, the default handler is installed.

DtMsgLogSetHandler is optional and should be used only to override the default message logging handler. If the handler function wants to log a message, it must use the format and file specified in DtMsgLogMessage(3) so applications can reliably parse the log file. (If the handler wants to log a message, it can obtain the byte count to output by using the return value from a call to vfprint.)

The DtMsgLogHandler handler function has the following arguments:

program_name: A string "tag" to identify the application issuing the message. This is generally an application's argv[0].
msg_type: The message type.
format: Specifies the sprintf format of the message.
args: Specifies the variable number of arguments needed by format.

The handler function should not call DtMsgLogMessage.

A sample use of the DtMsgLogSetHandler function is in an application that prints the CDE data types and actions databases. If an error occurs when the databases are loaded, the error messages are logged and the application is not able to get the messages. However, if the application installs a message logging handler, when the database loading code encounters an error, the application's installed handler will be invoked to give the application access to the database loading error messages.

ARGUMENTS

handler: Specifies a message handler function.

ENVIRONMENT VARIABLES

None.

RESOURCES

None.

ACTIONS/MESSAGES

None.

ERRORS/WARNINGS

None.

EXAMPLES

The following code installs a DtMsgLogHandler handler and then calls DtDbLoad to load the CDE data typing and action databases. If an error occurs when the databases are loaded, the handler function will be invoked. The handler writes the message to an alternate file. After the databases are loaded, the default handler is restored.

(void) DtMsgLogSetHandler (msglog_handler);
DtDbLoad ();
(void) DtMsgLogSetHandler (NULL);
void my_handler (


    const char    * prog_name,


    DtMsgLogType    msg_type,


    const char    * format,


    va_list         args)
{


   FILE	     *fp;


   fp = fopen ("/tmp/foo", "a+");


   (void) fprintf (fp, "progname = %s0tformat = %s0tmsg_type = %d0,
		prog_name, format, msg_type);


   (void) vfprintf (fp, format, args);


   (void) fprintf (fp, "0);
}

RETURN VALUE

If DtMsgLogMessage completes successfully, it returns the previously installed handler. If it fails, it returns NULL.

FILES

None.