Content Manager Library Server Tracing

Abstract

Using Library Server tracing with the Library Server log file is an important asset in resolving Library Server issues. Reasons for not being able to create an item type or unacceptable query performance can be determined by inspecting the Library Server log file. This document describes how to configure Library Server tracing, the available trace levels, and the log file structure.

Contents


The Library Server configuration allows you to control the level and location of Library Server tracing.

To go to the configuration screen, do the following:
    1. Start the Content Manager System Administration Client.
    2. From the left side panel, expand the Library Server database (usually it is ICMNLSDB).
    3. Expand Library Server Parameters, and click Configurations.
    4. From right side panel, double-click Library Server Configuration, and select Log and Trace tab.

Library Server Configuration panel

You can choose various trace levels. Specifically, this window allows you to choose between specific trace levels: Basic, detailed, data, and performance. The level that you select specifies the maximum level of tracing that a client can request. Note that tracing is only done when requested by client applications. When you change the trace level from the Library Server configuration window, the TRACELEVEL value in the ICMSTSYSCONTROL table is updated to a corresponding number.

The valid trace level values are as follows:


Trace level

Description

0

No trace

1

Basic trace: Program flow is logged

2

Detail trace: Both program flow and data are logged

4

Data trace

8

Performance trace

15

All of the above

16

Build/parse

31

All of the above

32

Memory management

63

All of the above

256

Cache trace

512

Cache allocation

1024

Cache management

The TRACELEVEL options shown in the Library Server configuration window do not represent all possible options. Higher levels of tracing are set by updating the TRACELEVEL value in the Library Server database table named ICMSTSYSCONTROL.

A positive TRACELEVEL value enables the Content Manager Windows client actions to be traced. When a positive number is set, tracing is not enabled for the Content Manager System Administration Client. To force Content Manager to trace the System Administration Client actions (and all connections), you must set the tracing level to a negative value (such as -15), which can only be performed by manually updating the database table.

The output of the trace is stored in the ICMSERER.LOG file. If you have a custom client, you need to request tracing to be enabled for your client; merely setting the trace level to a positive number does not enable tracing for your client.

To determine what level of tracing the Library Server is currently set to you can issue the following commands from a DB2 command window, replacing the database name, user ID and password with your values, if different from the default:
    db2 connect to <db name> user <user ID> using <password>
    db2 select tracelevel from icmstsyscontrol
Where:
    <db name> is the Library Server database name. By default, it is icmnlsdb.
    <user ID> is the user ID with appropriate rights.
    <password> is the password for the user ID.

The following shows a sample output that you should expect.
Viewing the Library Server trace level using DB2 Command Window:
------------------------------------------------------------------------------------------
C:\>db2 connect to icmnlsdb user icmadmin using icmadmin
Database Connection Information
Database server = DB2/NT 8.1.0
SQL authorization ID = ICMADMIN
Local database alias = ICMNLSDB
C:\>db2 select tracelevel from icmstsyscontrol
TRACELEVEL
------------
-15
1 record(s) selected.
C:\>
------------------------------------------------------------------------------------------

To set the Library Server trace level from a DB2 Command Window use the following commands:
    db2 connect to <db name> user <user ID> using <password>
    db2 update icmstsyscontrol set tracelevel=<tracelevel>
Where:
    <tracelevel> represents a value from the table shown earlier.

By default, the Library Server traces are placed in the C:\ICMSERVER.LOG file on Windows and /tmp on UNIX. The name and location of this file can also be changed from the Library Server configuration window. Depending on the trace level value, the ICMSERVER.LOG file contains different levels of information. In all cases, however, the structure of the log file remains the same.

The following is an excerpt of the ICMSERVER.LOG during access module generation.

Excerpt of ICMSERVER.LOG

This is an example of what you see in the Library Server log when an item type is created. In this particular example, the trace level is set to -15. This is a very small section of the overall log file, but shows a very important phase of the item type creation process: Access module generation. A C++ compiler is used by the Library Server to dynamically generate access modules for item types and static queries. This example not only shows that the access module generation was successful, but also shows the compile and link commands used to build the dynamic link library (DLL) file.

Note: Failing to generate access modules is a very common problem and is usually a result of wrongly configured INCLUDE, LIB, and PATH environment variables on Windows, and failing to license the C++ compiler correctly on UNIX. For information on setting the correct environment variables for Windows, refer to IBM Content Manager for Multiplatforms - Planning and Installing Your Content Management System, GC27-1332.

Each log entry consists of a stored procedure module name, DB2 stored procedure name, program line number, date and time the log entry was made, the process ID (useful when cross referencing DB2 logs), and the description. The point at which a stored procedure is called is logged with an Entry message. Likewise, the point at which the stored procedure exits is logged with an Exit message. Also note that the return code (rc) is shown when the stored procedure exits. The stored procedure has exited successfully when the return code is equal to zero (rc=0).

The Library Server log file is an important asset in resolving Library Server issues. Reasons for not being able to create an item type or unacceptable query performance can be determined by inspecting the Library Server log file. The maximum trace level is not always needed to investigate a problem. Instead, you should use the minimum trace level that gives you enough information to determine the cause of the problem. Doing so keeps you from having to parse through extraneous and unrelated log information.

Special Notices

This material has not been submitted to any formal IBM test and is published AS IS. It has not been the subject of rigorous review. IBM assumes no responsibility for its accuracy or completeness. The use of this information or the implementation of any of these techniques is a client responsibility and depends upon the client's ability to evaluate and integrate them into the client's operational environment.

Profile

Publish Date
18 December 2003


Rating: Not yet rated


Author(s)

IBM Form Number
TIPS0346