Configuring logging for the Loader package

To configure logging in the Loader package you specify where log files should be written, and change the values in the WCALoggerConfig.xml file.

Each command utility in the Loader package creates log messages to indicate success, failure, and errors as well as to provide program trace information.

The utilities in the Loader package reference the WCALoggerConfig.xml file.

AIXLinuxSun Solaris Operating EnvironmentWindows This file exists in a directory specified in the classpath system-environment variable. It can also be specified by the com.ibm.wca.logging.configFile Java systems property.

iSeries This file is located in the /instroot/xml/loader directory.

WCALoggerConfig.xml determines what logging information each utility provides and where the information is displayed or stored. You can customize this file and specify what types of logs are created as well as what types of messages are logged.

Loader package logs are located in the messages.txt file in the following directories:

To customize logging, do the following:

  1. Ensure that you have configured the Loader package.
  2. Configure logging in your environment, by doing either of the following:
    • Set the classpath variable

      If the WCALoggerConfig.xml file is in the directory WC_installdir\xml\loader on a Windows machine, for example, you can use the following statement to set the classpath variable:

      SET CLASSPATH=%CLASSPATH%;D:\Program Files\WebSphere\
      CommerceServer55\xml\loader

    • Specify the com.ibm.wca.logging.configFile system property

      To specify the com.ibm.wca.logging.configFile system property, use the -D option when invoking the Java interpreter, for example:

      java -Dcom.ibm.wca.logging.configFile=d:\ice_tea\src\classlib\logger\xml\WC.xml com.ibm.wca.DTDGenerator.GenerateDTD

  3. Optional, specify the directory in which the Loader and ID Resolver will report errors.

    By default, the exception document is written to the following directory:

    • AIXLinuxSun Solaris Operating EnvironmentWindows the directory where the input document resides
    • iSeries /instroot/logs

    To specify the directory to which the exception document is written, use the Java property com.ibm.wcm.ErrorReporterDir. An example for the Loader in a Windows environment would begin as follows:

      java -Dcom.ibm.wcm.ErrorReporterDir=d:\massloaderrors\ 
      com.ibm.wca.MassLoader.MassLoad -dbname . . .
    
  4. Change the following file:
    • AIXLinuxSun Solaris Operating EnvironmentWindowsWC_installdir\xml\loader\WCALoggerConfig.xml file.
    • iSeries  /instroot/logs

    This file contains one or more component tags, <component name="DTDGenerator"> for example. Within each of these tags, you can add loggers and handlers. You should not alter the utility and logger tags provided with the system, but you can add handler tags to the loggers. For information about what you can include in this file, see the WCALogger.dtd file.

    1. Add a handler. Use the following XML snippet as your guide, the following example adds a handler of the type "database" to a logger:
    2.   <handler type="database" brand="DB2" maxRows="50">
         <jdbc url="jdbc:db2:wcm"
            table="wcm.log"
            userid= "wasuser"
            password="123456"/>
         <filter type="Any">
           <messageType name="FATAL"/>
           <messageType name="ERROR"/>
           <messageType name="WARNING"/>
         </filter>
        </handler>
      

      You can add more than one handler to a logger. Note that each handler has its own attributes and subordinate tags that do not necessarily apply to other handlers. Handler types include the following:

      console
      Sends messages to standard output, typically the command line
      file
      Stores messages in a text file. You must add <filePath>log path</filePath> to this handler as subordinate tagging.
      multifile
      Creates a circular log of files

      You must specify <filePath>log path</filePath>. Log files 1 through n are created. You can add the following attributes:

      MaxFiles
      Integer indicating how many log files to use before erasing the first log file
      MaxKBFileSize
      Integer indicating the maximum number of kilobytes to store in each log file
      AIXLinuxSun Solaris Operating EnvironmentWindows database
      Stores messages in a DB2 table in a circular log. You can add the following attributes:
      brand
      Database brand name. DB2 is the only database currently supported.
      maxRows
      Maximum number of records to store in a table before erasing the oldest entry
      You can include <jdbc/> as a subordinate tag and include the following attributes:
      url
      URL used in JDBC to access a database (for example, Jdbc:db2:wcm, where wcm is the name of the database). The database must exist before you run the utility.
      table
      Name of the database table where messages will be logged. It must be created with the following DB2 statement:

      CREATE TABLE tablename (KEY char(13) FOR BIT DATA NOT NULL, COMPONENTNAME VARCHAR(30), ENTRY VARCHAR(2000), PRIMARY KEY(key))

      userid
      Database user name. The user must be assigned permissions to update the table. The following DB2 statement will do this:

      GRANT SELECT, UPDATE, INSERT, DELETE ON TABLE tablename TO USER userid

      password
      Database password for the user name specified
    3. Filters can be added to or removed from handlers to include and exclude message types. If a logger has no filters, no messages are logged. Each filter tag has a subordinate messageType tag that lists the message type, which is typically one of the following:

      • INFO
      • ERROR
      • FATAL
      • WARNING

      Other message types are listed in the WCALogger.dtd file, but most are generally not used with this package.

      Filter types include the following:

      Any
      Includes in the log file any message flagged as one of the messageType types specified

      For example, if the messageType list includes ERROR and the application generates an ERROR type message, the message is logged.

      All
      Requires that a message have all specified messageType type attributes before it is included in a log
      Exclude
      Logs all messages not specified in the in list of messageType tags

      The following example of adding a filter to a handler allows FATAL as well as ERROR message types to be logged and other messages to be ignored:

    4. Add a format. Use the following XML snippet as your guide.
      <handler type="file">
          <filter type="Any">
          <messageType name="FATAL"/>
          <messageType name="ERROR"/>
          </filter>
          </handler>
      

      You can specify one of two formatter types for message formatting:

      safe
      Prevents an exception from being set if a message cannot be found in a properties file

      This formatter creates a message indicating that the resource is missing.

      xml
      Formats the message in XML format

      If a message cannot be found, this formatter also writes a message instead of setting an exception.

    5. If you will use the Loader to load large documents, turn of trace logging.
        <logger type="trace">
           <handler type="file">
             <filePath>MassLoadTrace.log</filePath>
              <filter type="Any">
                   <messageType name="PUBLIC" />
              </filter>
           </handler>
        </logger>
      

      to:

        <logger type="trace">
           <handler type="file">
             <filePath>MassLoadTrace.log</filePath>
              <filter type="Any">
              </filter>
           </handler>
        </logger>