hpux man page for dtmsglogsethandler

DtMsgLogSetHandler(library call)										  DtMsgLogSetHandler(library call)

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 han-
       dler 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 = %sformat = %smsg_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.

SEE ALSO
       DtMsgLogMessage(3), DtMsgLogOpenFile(3)

														  DtMsgLogSetHandler(library call)