xHarbour Reference Documentation > Command Reference

INIT LOG

Initializes the Log system and opens requested log channels.

Syntax

INIT LOG ;
[CONSOLE(...)] ;
  [DEBUG(...)] ;
  [EMAIL(...)] ;
   [FILE(...)] ;
[MONITOR(...)] ;
 [SYSLOG(...)] ;
   [NAME <cExeName> ] ;

Arguments

(...)

The INIT LOG command opens one or more log channels to receive log messages via the LOG command. Each log channel can be configured using a list of additional parameters enclosed in parentheses. The first parameter for all log channel options defines the priority a log message must have at minimum for a log channel to receive the message. #define constants are available in the file HbLogDef.ch that can be used for the priority:

Log channel priorities

Constant	Value	Description
HB_LOG_DEFAULT	-1	All messages are logged
HB_LOG_CRITICAL	1	Critical log messages
HB_LOG_ERROR	2	Error log messages
HB_LOG_WARNING	3	Warning messages
HB_LOG_INFO *)	4	Informational messages
HB_LOG_DEBUG	5	Debug messages
*) default

A log channel created with the priority HB_LOG_WARNING receives log messages of priority HB_LOG_DEFAULT, HB_LOG_CRITICAL, HB_LOG_ERROR and HB_LOG_WARNING, but it does not receive log messages of priority HB_LOG_INFO or HB_LOG_DEBUG. Thus, different log channels can receive log messages of different priority.

CONSOLE( [<nPrioCon>] )

Log messages are displayed on the console. This option accepts only the priority level as additional parameter.

DEBUG( [<nPrioDbg>], [<nMaxPrio>] )

This option opens a log channel which sends received log messages to a system debugger. If there is no system debugger, this log channel does nothing. <nPrioDbg> is the priority of the log channel, while <nMaxPrio> is an optional upper limit for the log message priority to be sent to the debugger.

EMAIL( [<nPrioMail>],[<cHelo>],<cServer>,<cMailTo>,[<cSubj>],[<cFrom>] )

This log channel sends log messages per eMail and accepts the most additional parameters. The configuration parameters for the eMail log channel are as follows.

Configuration of the eMail log channel

Parameter		Description
<nPrioMail>	optional	Numeric priority level of log channel
<cHelo>	optional	Character string sent with the HELO command of the SMTP protocol.
<cServer>	required	Character string specifying the mail server.
<cMailTo>	required	Character string specifying the mail address of the receipient.
<cSubject>	optional	Character string specifying the subject line of the eMail.
<cFrom>	optional	Character string specifying the mail address of the sender.

FILE( [<nPrioFile>],<cFileName>,[<nFileSize>],[<nBackups>] )

This opion defines <cFileName> as the name of a log file where log messages are written into. Optionally, the size of the log file can be restricted to a maximum file size (numeric <nFileSize>). If a log file grows beyond <nFileSize>, it is renamed, and a new file <cFileName> is created. The renamed file receives an extension made up of digits from .001 to .999, so that existing log files are not overwritten. In addition, the number of automatically created backup files is limited to <nBackups> files, if this numeric parameter is given.

MONITOR( [<nPrioMon>],[<nPort>] )

This option creates a log channel that sends log messages to an IP port, so that a remote monitoring process can receive log messages. By default, xHarbour applications using this option listen on <nPort> for incoming connections and send a log message via this port to a remote process. The default port <nPort> used by this log channel is 7761. That is, a remote process must connect to the message sending process using the same port number. Refer to INetRecv() for more information on how to obtain the messages sent via the MONITOR log channel in a remote monitoring process.

SYSLOG( [<nPrioSys>], <nSysID> )

With this option, a log channel is created that sends log messages to the operating system's log file. The log channel must be created with a unique numeric <nSysID>.

NAME <cExeName>

This is an optional character string holding the name of the EXE file creating log messages.

Description

INIT LOG is a powerful command initializing xHarbour's Log system and creating up to six different log channels. After initilization, the LOG command is used to send log messages to all open log channels, each of which serves its own output device or communication channel. This allows for displaying log messages on the screen (CONSOLE), collecting them in a local file (FILE) or the system log file (SYSLOG), posting them to a system debugger (DEBUG), sending them per eMail (EMAIL), or monitoring them from a remote process via TCP/IP (MONITOR).

The first log message is created by INIT LOG. It simply indicates that logging has started so that the application NAME appears as first entry in the log. Subsequent log messages must be created with the LOG command. The last log entry is created by the CLOSE LOG command, after which the Log system becomes unavailable. After CLOSE LOG is executed, INIT LOG must be called again to reinitialize the Log system.

Log messages can be formatted to include default information, such as date and time stamps of the log entry. Several output formats for a log entry are predefined and can be selected using the SET LOG STYLE command.

Info

See also:	CLOSE LOG, LOG, SET LOG STYLE, SET TRACE, TraceLog()
Category:	Log commands , xHarbour extensions
Header:	hblog.ch, hblogdef.ch
Source:	rtl\hblog.prg, rtl\hblognet.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Examples

// The example opens three log channels and logs entered
// data to the console, a local file and a remote monitoring
// process.

   #include "Inkey.ch"
   #include "Hblog.ch"

   PROCEDURE Main
      LOCAL cData

      INIT LOG Console() ;
               Monitor() ;
                  File( NIL, "Testlog.log" )

      DO WHILE .T.
         CLS

         // let the user enter some data
         cData := Space(80)
         @ 2,2 SAY "Enter a string:" GET cData PICTURE "@S30"
         READ

         IF Lastkey() == K_ESC
            EXIT
         ENDIF

         CLS
         LOG Trim(cData)
         WAIT "Press a key..."

         IF Lastkey() == K_ESC
            EXIT
         ENDIF
      ENDDO

      CLOSE LOG
   RETURN

Monitoring log messages

// This example implements a simple monitoring process for
// log messages created in the first example.

   #include "Inkey.ch"

   PROCEDURE Main( cServerIPAddress )
      LOCAL pSocket, cData, nBytes

      IF Empty( cServerIPAddress )
         // IP address of the local station
         cServerIPAddress := "127.0.0.1"
      ENDIF

      INetInit()
      CLS

      ? "Connecting..."

      DO WHILE Inkey(1) <> K_ESC
         // connect to log message server on the default port 7761
         pSocket := INetConnect( cServerIPAddress, 7761 )

         IF INetErrorCode( pSocket ) <> 0
            ? "Socket error:", INetErrorDesc( pSocket )
            ?? " press ESC to quit"
            LOOP
         ENDIF

         EXIT
      ENDDO

      IF Lastkey() == K_ESC
         QUIT
      ENDIF

      ? "Log monitor up and running"

      DO WHILE Inkey(.1) <> K_ESC
         // wait 2 seconds for incoming data
         IF InetDataReady( pSocket, 2000 ) > 0
            cData := Space(4096)
            nBytes:= INetRecv( pSocket, @cData, Len( cData ) )
         ELSE
            nBytes := 0
         ENDIF

         IF nBytes > 0
            // a log message is received
            ? Left( cData, nBytes )

         ELSEIF INetErrorCode( pSocket ) <> 0
            ? "Socket error:", INetErrorDesc( pSocket )

            IF INetErrorCode( pSocket ) == -2
               // Connection closed on remote site
               EXIT
            ELSE
               ?? " press ESC to quit"
            ENDIF

         ELSE
            // Indicate that I'm still alive
            ?? "."
         ENDIF
      ENDDO

      // disconnect from server
      INetClose( pSocket )

      INetCleanUp()
   RETURN