DtMsgLogMessage(library call)											     DtMsgLogMessage(library call)

NAME

       DtMsgLogMessage -- logs a message

SYNOPSIS

       #include <Dt/MsgLog.h>
       void DtMsgLogMessage(
       const char* program_name,
       DtMsgLogType msg_type,
       const char* format,
       va_list args);

DESCRIPTION

       The  DtMsgLogMessage  function  logs the given arguments in one message.  The format of the message is specified by format and thus is con-
       trolled by the application. The format of each logged entry is:

       *** <Msgtype_string>( <Msg_type>):  <Program_name>: PID	<Proc_id>:  <Date>
	<The_message>
       *** [ <Bytes_output>]

       The value of <Msgtype_string> depends on the value of msg_type. Its value is:

       INFORMATION
		 if msg_type is DtMsgLogInformation

       STDERR	 if msg_type is DtMsgLogStderr

       DEBUG	 if msg_type is DtMsgLogDebug

       WARNING	 if msg_type is DtMsgLogWarning

       ERROR	 if msg_type is DtMsgLogError

       UNKNOWN	 for all other values of msg_type

       <Msgtype_string> is prefaced with the string *** and one space character.  <Msg_type> is replaced with the value of the	msg_type  argument
       (placed	within	parentheses).	<Program_name> is replaced with the value of the program_name.	<Proc_id> is the application's process id.
       <Date> is the date and time the message is logged.  <The_message>  is  the  formatted  message  including  the  arguments.   <Bytes_output>
       (enclosed  in  brackets)  is replaced with the number of bytes output for the message and header information.  (The number of bytes printed
       for the line containing <Bytes_output> is not included.). A colon and a space (respectively) are printed after the closing parenthesis  for
       <Msg_type>, <Program_name>, and <Proc_id>.

       One  newline  is output after the date and one newline is output after the message. After the message, a line beginning with the string ***
       is output, followed by a space character, a [ character, the number of bytes printed, a ] character, and,finally, two newlines  (one  blank
       line separates messages).

       The  message  type string and date specification are localized and thus are retrieved from the current locale's message catalog.  It is the
       application's responsibility to localize the message to be logged.

       An example log entry is:

       *** WARNING(3): fontview: PID 12312: Thu Jun 13 16:51:51 1995
       The specified font 'fixed' could not be loaded.
       *** [109]

       To log a multi-line message, use a single call to DtMsgLogMessage.

       DtMsgLogMessage attempts to open the following files in the indicated sequence (by calling the fopen function with the a+ option). It  uses
       the first file that is successfully opened.

       $HOME/.dt/errorlog
		 This file is used only if the environment variable HOME is defined.

       /var/dt/tmp/$DTUSERSESSION/errorlog
		 This file is used only if the environment variable DTUSERSESSION is defined.

       <filename>/tmp/<user_name>.errorlog</filename>
		 In  this  filename, <user_name> is replaced by the user's login name. The login name is determined by using the environment vari-
		 able LOGNAME, if it is defined, or USER, if LOGNAME is not defined. If neither variable is defined, DtMsgLogMessage uses the get-
		 pwuid function to determine <user_name>.

       DtMsgLogMessage calls DtMsgLogOpenFile to determine where to log the message. If DtMsgLogOpenFile returns NULL, DtMsgLogMessage will output
       the message to stderr.

ARGUMENTS

       program_name
		 Specifies a string "tag" to identify the application issuing the message. This is generally an application's argv[0] so the  mes-
		 sage can be traced to an executable program.

       msg_type  Specifies the DtMsgLogType structure that defines the message type. See "Structures" in this man page.

       format	 Specifies the sprintf format of the message.

       args	 Specifies the variable number of arguments needed by format.

STRUCTURES

       The msg_type argument is specified as a DtMsgLogType enumeration data type, with the following members:

       DtMsgLogInformation
		 Designates  informational messages that do not have to be brought to the user's immediate attention (for example, status informa-
		 tion).  It is acceptable to not present messages of this type to the user.

       DtMsgLogDebug
		 Designates debugging messages written by the application (for example, via a -debug command line option).

       DtMsgLogStderr
		 Designates messages that an application produces to log the stderr from a child process.

       DtMsgLogWarning
		 Designates messages for errors that are not severe enough to cause program termination.

       DtMsgLogError
		 Designates messages for fatal errors that require program termination.

RETURN VALUE

       None.

ENVIRONMENT VARIABLES

       The values of the following environment variables determine which file is opened by DtMsgLogMessage: HOME, LOGNAME,  USER,  and	DTUSERSES-
       SION.  See "Description" in this man page for more information.

       Because	DtMsgLogMessage  calls the catopen function, it is indirectly influenced by the environment variables that affect catopen, such as
       LANG, and NLSPATH.  See catopen(3) for more information.

RESOURCES

       None.

ACTIONS
/MESSAGES
       The default mechanism to view the message log is to invoke the Watch Errors action which is located  in	the  Application  Manager's  Desk-
       top_Tools folder.

ERRORS
/WARNINGS
       None.

EXAMPLES

       The following code fragment illustrates how to log a localized warning message:

       #include <nl_types.h>

       char *s1, *s2; /* temp strings - catgets may return
			 a pointer to a static buffer */
       nl_catd catd = catopen ("app.cat", 0);
       s1	    = strdup (catgets (catd, 4, 10, "string 1"));
       s2	    = strdup (catgets (catd, 4, 10, "string 2"));
       DtMsgLogMessage (argv[0],
	     DtMsgLogWarning,
	     "%s %s",
	     s1, s2);

FILES

       See DtMsgLogOpenFile(3).

SEE ALSO

       DtMsgLogOpenFile(3), DtMsgLogSetHandler(3)

														     DtMsgLogMessage(library call)