DtMsgLogSetHandler(library call)           DtMsgLogSetHandler(library call)




 NAME    [Toc]    [Back]
      DtMsgLogSetHandler - installs an alternate message logging handler

 SYNOPSIS    [Toc]    [Back]
      #include <Dt/MsgLog.h>
      DtMsgLogHandler DtMsgLogSetHandler(
      DtMsgLogHandler handler);

 DESCRIPTION    [Toc]    [Back]
      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    [Toc]    [Back]
      handler   Specifies a message handler function.

 ENVIRONMENT VARIABLES    [Toc]    [Back]
      None.

 RESOURCES    [Toc]    [Back]




                                    - 1 -       Formatted:  January 24, 2005






 DtMsgLogSetHandler(library call)           DtMsgLogSetHandler(library call)




      None.

 ACTIONS/MESSAGES
      None.

 ERRORS/WARNINGS
      None.

 EXAMPLES    [Toc]    [Back]
      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 = %s0format = %s0msg_type = %d0,
                prog_name, format, msg_type);
         (void) vfprintf (fp, format, args);
         (void) fprintf (fp, "0);
      }

 RETURN VALUE    [Toc]    [Back]
      If DtMsgLogMessage completes successfully, it returns the previously
      installed handler.  If it fails, it returns NULL.

 FILES    [Toc]    [Back]
      None.

 SEE ALSO    [Toc]    [Back]
      DtMsgLogMessage(3), DtMsgLogOpenFile(3)


                                    - 2 -       Formatted:  January 24, 2005