Chilkat Log Tutorial

Saving to XML
Accessing as XML
Clearing the Log
Understanding the Log
Log Entries: Messages vs Data
Formatting Log Messages
Adding Your Own Content
Associating Messages with Keywords
Named Message Formats

*Send questions to: support@chilkatsoft.com

Chilkat ActiveX controls use the Chilkat Log component for logging error information. This component is automatically installed on your system when you install a Chilkat ActiveX, such as Chilkat Mail or Chilkat XML.

Getting the Chilkat Log Object

Each Chilkat ActiveX has a GetLog method that returns the Chilkat Log object:

Dim WithEvents xmlObject As ChilkatXml
Set xmlObject = New ChilkatXml
' Do not forget to unlock the component, if the component requires this.
xmlObject.UnlockComponent "unlock-code"
Dim logObject As ChilkatLog
Set logObject = xmlObject.GetLog()

Saving the Log to an XML File

You can easily save the entire log to an XML file by calling SaveXML. The first argument controls whether date-timestamps are included in the output file. (True = include timestamps, False = do not include timestamps)

logObject.SaveXML False, "log.xml"

Accessing the XML Content

You can access the XML directy from your program by using the GetXML method. Similar to SaveXML, the True/False argument controls whether timestamps are included:

Dim logContent As String
longContent = logObject.GetXML False

Clearing the Log

The log can be cleared of all data and messages by calling ClearLog. Another method, CheckHighWater, can be called to clear the log if the number of messages exceeds a high-water mark, which is 500 messages by default. All methods in Chilkat ActiveX controls, unless otherwise stated, call CheckHighWater automatically, so applications do not necessarily need to be concerned with the log size growing out of control.

' This clears the log
logObject.ClearLog

logObject.HighWaterMark = 1000
' This clears the log if the high-water mark is exceeded.
logObject.CheckHighWater

Understanding the Log Content

In this tutorial, we will use Chilkat Mail and show the contents of the log after doing the following:

1. Send an email.
2. Try adding a file attachment that cannot be found on the disk, causing an error.
3. Remove all the recipients and try sending the email, which will result in an error.

Here is what the entire log would contain, comments are in red:

<ChilkatLog>      *This is always the top-level node.

   * Each method of a Chilkat ActiveX control creates  a new context  having the
      same name as the method itself.  All data and messages are logged within
      that context.   Below, we can see that the method AddTo has logged two pieces
      of data within the AddTo context.  This makes it easy to identify the method calls
      within the log.  If the context is empty, it is automatically removed from the log.  

    * Here is the ChilkatMail.AddTo method call. 
       ChilkatEmail.AddTo calls ChilkatLog.EnterContext("AddTo",True) to create the context.
       It then calls ChilkatLog.LogData to log the name and address.
    <AddTo> 
        <name>John Smith</name>   
        <address>jsmith@chilkatsoft.com</address>
    </AddTo>
    * Here is the ChilkatMailMan.SendEmail  method call. 
    <SendEmail>
        * Sometimes you will find information grouped together within sub-contexts in the log.  
           In this case, the SMTP connection information is placed in the "SMTP_Connect"
           sub-context.
        <SMTP_Connect>
            <info>Connecting to SMTP server smtp.mail.yahoo.com:25</info> 
            <smtp_host>smtp.mail.yahoo.com</smtp_host>
            <smtp_port>25</smtp_port>
            <smtp_user>chilkat_software</smtp_user>
            <login_method>LOGIN</login_method>
            <info>CONNECTED to ESMTP server smtp.mail.yahoo.com:25</info>
        </SMTP_Connect>
        * The SendEmail method logs other information...
        <subject>This is the email subject</subject>
        <from>chilkat_software@yahoo.com</from>
       * The recipient list is placed within a "recipients" sub-context.  In this case there is only
          one recipient. 
       <recipients>
            <to>admin@chilkatsoft.com</to>
        </recipients>
        <email_size>425</email_size>
        * Finally, the success or failure message is added to the log.
        <info>Mail sent</info>
    </SendEmail>
    * This is the AddFileAttachment method call, and we can see that it failed,
       why it failed, and what file it was trying to attach.  The goal of ChilkatLog is to
       immediately answer the first one or two questions the developer will have
       when a failure occurs.  In this case, the question is "what file is trying to be attached,
       and why did it fail?".
    <AddFileAttachment>
        <filename>sample.jpg</filename>
        <fail_reason>The system cannot find the file specified.</fail_reason>
        <error>File does not exist, or cannot open file.</error>
    </AddFileAttachment>
    * Here is the second ChilkatMailMan.SendEmail  method call, but it fails because there 
      are no recipients.
    <SendEmail>
        <SMTP_Connect>
            <info>Connecting to SMTP server smtp.mail.yahoo.com:25</info>
            <smtp_host>smtp.mail.yahoo.com</smtp_host>
            <smtp_port>25</smtp_port>
            <smtp_user>chilkat_software</smtp_user>
            <login_method>LOGIN</login_method>
            <info>CONNECTED to ESMTP server smtp.mail.yahoo.com:25</info>
        </SMTP_Connect>
        <error>Invalid email object, no recipients</error>
        <error>Send failed.</error>
    </SendEmail>
</ChilkatLog>

When you retrieve the log in XML format, you get the entire log. In fact, this is the only way to get the data entries of the log (i.e. entries that were logged with ChilkatLog.LogData and ChilkatLog.LogDataLong). Of course, with XML you are free to format the log using XSL in any way you choose.

Message vs. Data Log Entries

Message entries are created by the LogError, LogInfo, and LogDebug methods. Data entries are created by LogData and LogDataLong. Message entries are returned by the GetDebugEntries, GetInfoEntries, and GetErrorEntries methods as follows:

GetDebugEntries: Retrieves message entries of all types.
GetInfoEntries: Retrieves only informational and error entries, excluding debug entries.
GetErrorEntries: Retrieves only error message entries.

Formatting Log Messages

The formatting of messages is easily customizable. This is useful because different environments require different message formats. For example, in ASP a line ending might be a <br> tag, whereas in Visual Basic it might be a vbCRLF.

The default formatting of messages is:

mon/day/year hour:min (ERROR|INFO|DEBUG) <Message Text>\r\n

An example is shown below:

02/25/2002 16:44 INFO:  Connecting to SMTP server smtp.mail.yahoo.com:25
02/25/2002 16:44 INFO:  CONNECTED to ESMTP server smtp.mail.yahoo.com:25
02/25/2002 16:44 INFO:  Mail sent
02/25/2002 16:44 ERROR: File does not exist, or cannot open file.
02/25/2002 16:44 INFO:  Connecting to SMTP server smtp.mail.yahoo.com:25
02/25/2002 16:44 INFO:  CONNECTED to ESMTP server smtp.mail.yahoo.com:25
02/25/2002 16:44 ERROR: Invalid email object, no recipients
02/25/2002 16:44 ERROR: Send failed.

Each error message is formatted according to the LineFormat property, which contains special keywords that are replaced by the message content. The default format is "__STANDARD_\r\n" which provides for CRLF line-endings that are friendly to Visual Basic programs. The "_STANDARD_" is a keyword that is replaced with the message data in a standard format.

The valid keywords are listed below:

 

_STANDARD_

Generates the date & time, severity, and message text in this format:
mon/day/year hour:min (ERROR|INFO) <Message Text>

_MDY_

Replaced with the mon/day/year of when the message was logged.

_DMY_

Replaced with the day/month/year of when the message was logged.

_HMS_

Replaced with the hour:minute:second of when the message was logged.

_KEYWORD_

Replaced with the message's associated keyword, if any.

_MESSAGE_

Replaced with the message text .

_STATUS_

Replaced with either "ERROR", "INFO", or "DEBUG" depending on the severity of the message.

Here are some examples:

 

"_STANDARD_<br>"

If your component is used within Active Server Pages, this is an easy way to produce simple HTML.

"<b>_MDY_ _HMS_</b><font face="Tahoma">_MESSAGE_ </font><br>"

A more customized way to create an HTML error log.

"My App Name: _MDY_ -- _MESSAGE_" + vbCRLF

Formats the message to include the date, the message text, along with the application's name and ending with a carriage-return/line-feed.

Adding Your Own Content to the Log

You can easily add your own content to the log. There are 4 types of content:

1. Debug Message
2. Informational Message
3. Error Message
4. Data

To add a debug message, call LogDebug:

This method call:
LogDebug "This is a debug message"

Generates this:
<debug>This is a debug message</debug>

To add an informational message, call LogInfo:

This method call:
LogInfo "This is an informational message"

Generates this:
<info>This is an informational message</info>

To add an error message, call LogError:

This method call:
LogError "This is an error message"

Generates this:
<error>This is an error message</error>

To add data, call LogData:

This method call:
LogData "data_tag", "This is data"

Generates this:
<data_tag>This is data</data_tag>

You can also add numeric (integer) data by calling LogDataLong:

This method call:
LogDataLong "data_tag", 99

Generates this:
<data_tag>99</data_tag>

You can also put messages in a context. For example, the following series of calls:

EnterContext "my_context", False <-- This indicates whether error reports should be generated for errors occuring within the context.
LogInfo "This is an informational message"
LogDataLong "junk", 101
LogError "This is an error"
LeaveContext

Generates this in the log:

<my_context>
    <info>This is an informational message</info>
    <junk>101</junk>
    <error>This is an error</error>
</my_context>

Associating Messages with Keywords

Messages can be associated with a keyword when added to the log. This makes it possible to retrieve all the messages associated with a particular keyword. (The messages produced from within the Chilkat ActiveX controls are not associated with any keywords however.)

There are many potential uses for a features such as this. For example, you might build a Web application that requires users to login. If the application logged messages using the login name as the keyword, then it would be possible to retrieve all the log messages associated with a particular user.

The Chilkat Log methods that use keywords are:

LogDebug2(message as String, keyword as String)
LogInfo2(message as String, keyword as String)
LogError2(message as String, keyword as String)

LogDebug3(message as String, keyword as String, formatName as String)
LogInfo3(message as String, keyword as String, formatName as String)
LogError3(message as String, keyword as String, formatName as String)

To retrieve only the messages associated with a given keyword, call:

GetKeywordEntries(keyword as String) as String

Named Message Formats

You can create any number of named message formats, and then associate a message with the named format when you log it. Below is an example of creating a new format, and then adding a message with that format:

'This will be the default format for messages:
logObject.LineFormat = "__MESSAGE__<br>"
'This will be the format for critical messages:
logObject.SetNamedFormat "critical", "<b>__MESSAGE__</b><br>"
'Log a message having the "critical" format:
logObject.LogError3 "This is a critical message", Null, "critical"