Introduction

Tracing in Documentum can be a useful way to track down errors or unexpected behavior and is also a good
way to spot areas for code optimization. There are many types and levels of tracing within the Documentum
suite of products. The eContent server and most client products have their own separate tracing
configurations. Generally, the procedure for setting up tracing for a product is to turn tracing “On”, set
the path to the log file, and then specify the tracing or verbosity level (the level of detail to display in the
trace log).

Documentum trace files can grow very large in a short amount of time, especially at high
tracing levels. You should always turn tracing back off when you are done troubleshooting to prevent
disk space issues. Tracing also slows performance because of the time it takes to create
the log entries.

Desktop Client Tracing

The Documentum Desktop Client offers eight categories of client-side tracing, each with its own verbosity level
and trace log. Starting with version 4.1 of the client there is a special dialog for configuring tracing that
can be accessed by right-clicking the blue and black Desktop Client icon in Windows Explorer or on the Windows
Desktop and then selecting “Properties”. Choose the “Advanced” tab on the properties dialog to set up tracing
(see figures 1 and 2 below).

Figure 1:
Selecting a category of client-side tracing

Once you have selected the category of tracing you want to configure, select a trace level for the category. Then,
in the “Path:” box, specify the path and file name of the log file you want to be created on the client machine.
Finally, hit “Apply” and then “OK” to close the dialog. You’ll have to restart the client for the settings
to take effect.

Figure 2:
Setting the trace level for shell tracing

DMCL Tracing (API Tracing)

Use the ‘DMCL’ category to configure tracing of API calls made from the Desktop Client.

Example API Trace:

                
API> get,s0,090f47ba80000268,acl_name
# Network Requests: 408
# Time:        0.000 sec  'dm_450f47ba80000102'
API> get,s0,090f47ba80000268,acl_domain
# Network Requests: 408
# Time:        0.000 sec  '/articles/dmin'
API> get,s0,090f47ba80000268,acl_name
# Network Requests: 408
# Time:        0.000 sec  'dm_450f47ba80000102'
API> get,s0,450f47ba80000102,object_name
# Network Requests: 408
# Time:        0.000 sec  'dm_450f47ba80000102'
API> get,s0,450f47ba80000102,description
# Network Requests: 408
# Time:        0.000 sec  'dm_450f47ba80000102'
API> get,s0,450f47ba80000102,owner_name


            

DFC Tracing

Use the ‘DFC’ category to configure tracing of DFC calls made by the Desktop Client.

Example DFC Trace:

                
DFC 0> DfClientX@250::getLocalClient()
	DFC> DfClient::getLocalClient()
# DfDMCLCLient@75
# DfDMCLCLient@75
DFC 0> DfDMCLCLient@75::findSession( "USER=/articles/dmin;DOCBASE=bf_demo;KEY=Login Manager;TYPE=1;" )
# com.documentum.fc.client.DfSession@d0
DFC 0> DfSession@d0::lock( 0 )
# true
DFC 0> DfSession@d0::getDocbaseName()
	DFC 0> DfSession@d0::getDocbaseConfig()
	# DfTypedObject@346
	DFC 0> DfTypedObject@346::getString( "object_name" )
	# "bf_demo"
# "bf_demo"
DFC 0> DfSession@d0::unlock()

            

Other Desktop Client Tracing Categories

Listed below are the other tracing categories available from the ‘Advanced’ tab on the
Desktop Client properties dialog. I could not find documentation for these.

• DcFolder
• Shell
• Login Manager
• Notifier
• Virtual Document Editor
• Workflow Manager

The Trace API Command

In order to see the activity for a particular Documentum server facility in the session or server logs you must
turn on tracing for the facility and set the trace level. This can be done by issuing an API command through the interactive
message tester. You can access the interactive message tester in the Desktop Client by holding
down the cntrl key while selecting Help->Documentum Help
(see figure 4 below). When you use the trace API command you are configuring tracing only
for the current session. Use the apply API command with “SET_OPTIONS” and an option argument to configure tracing
for all future sessions.

The Documentum eContent server creates a log file by default for every session. Session logs are stored on the server
in the following directory:

                
<documentum_root>dbalog<my_docbase_id>username


            

The server also writes to a server log named <my_server_name>.log. When
the server starts a new log it renames the old log
<my_server_name>.log.save.<timestamp>. The server logs can be found in the following directory:

                
<my_documentum_root>dbalog

            

Figure 3:
Turning on SQL tracing for the current session through the interactive message tester in Desktop Client

This is the syntax for the trace API command:

                
trace,<session>,<trace_level>,<trace_file_path>,<facility> or <option> or "all"

            

Tracing Facilities (5th parameter in the trace API command):

• DM_API (default) – Configures tracing of API calls from the client. Unless you specify otherwise (in parameter 4) the trace will be written to a file called “api.log” on the server. For Desktop Client API tracing it may be easier to just configure the ‘DMCL’ category in the tracing configuration dialog explained in the previous section.
• DM_DUMP – Configures tracing for dump progress written to the session log. See Dump and Load Tracing.
• DM_FULLTEXT – Configures tracing for full-text index progress written to the server log.
• DM_LOAD – Configures tracing for load progress to the session log.
• DM_QUERY – Enables query tracing in the session log.
• SQL_TRACE – Configures tracing for RDBMS SQL commands to the session log. The trace_file_path parameter is ignored
  with SQL_TRACE.
• DM_SYSOBJECT – Configures tracing for system object activity to the session log.

Trace Levels (these are additive):

• 0 – Tracing off
• 1-8 – Increasing tracing levels (decreasingly severe)
• 8 – Dump and Load tracing
• 10 – Tracing of timing information (written on object loads)
• 11 – Tracing for load operation

Using the Apply API Command for Persistent Tracing Configuration

If you want to set up tracing for longer than just the current session, you can configure tracing for all
future sessions by issuing the “Apply” API command with the “SET_OPTIONS” parameter:

                
apply,c,NULL,SET_OPTIONS,OPTION,S,<my_option>,VALUE,B,[T or F (for On/Off)]

            

Example API command to turn on SQL tracing:

                
apply,c,NULL,SET_OPTIONS,OPTION,S,sqltrace,VALUE,B,T

            

Trace Options (4th parameter of the apply with SET_OPTIONS command):

• debug – Configures tracing for session debug messages
  during shutdown, launches, forks, and change checks
• docbroker_trace – Configures docbroker tracing
• lock_trace – Configures tracing for Windows NT locking
• net_ip_addr – Configures tracing of IP addresses used by the client
  and server for authentication
• nettrace – Configures tracing for remote procedure calls
  (including calls to Netwise). Shows the connection ID, client host address and host name
• sqltrace – Configures tracing of RDBMS SQL commands (during future sessions)
• trace_authentication – Configures tracing of authentication

Example RDBMS SQL Trace:

                
SELECT * FROM dmi_dd_type_info_rv UE_ , dmi_dd_type_info_sv TE_  WHERE
 (TE_.R_OBJECT_ID=:handle AND TE_.R_OBJECT_ID=UE_.R_OBJECT_ID) ORDER BY
 UE_.R_OBJECT_ID,UE_.I_POSITION
:handle = 690f481d80000d0d
 SELECT J_.I_TYPE FROM bf_demo.dmi_object_type J_ WHERE J_.R_OBJECT_ID=
:handle
:handle = 090f481d80002980
select user_name, message, priority, oneshot, sen/articles/il, event, is_audittrail,
 registered_id from dmi_registry_s where (event = 'dm_setfile' or event = 'all')
 and registered_id ='090f481d80002980'
select s.group_name from dm_group_s s where s.group_name = :p0
:p0 = docu

            

WebPublisher RightSite Tracing

The Rightsite Support Tool is a little-known utility that installs with WebPublisher. You
can use it to trace DFC or DMCL information for the Rightsite session by going to the event you
want to trace in Web Publisher and then opening a new browser window
and modifying the URL so that the page is trace.htm or tracedfc.htm.

Rightsite DFC Tracing

1. Go to the client web page immediately before the operation you want to trace
2. Open a new browser window (File->New Window)
3. In the new window, change the last part of the URL so that the page is tracedfc.htm
4. The Rightsite Support Tool will open (figure 4). Click “Trace On”
5. Change over to the other window an complete the client operation
6. Change back to the Rightsite Support Tool and click “Trace Off” – the log will display

Rightsite DMCL Tracing

1. Go to the client web page immediately before the operation you want to trace
2. Open a new browser window (File->New Window)
3. In the new window, change the last part of the URL so that the page is trace.htm
4. The Rightsite Support Tool will open. Click “Trace On”
5. Change over to the other window an complete the client operation
6. Change back to the Rightsite Support Tool and click “Trace Off” – the log will display

Figure 4:
The Rightsite Support Tool Showing a WebPublisher DFC Trace (Click to Enlarge)

WebPublisher Editor Tracing

WebPublisher Editor Server-Side Tracing

1. Open WebPublisher and complete the editor operation you want to trace
2. Open a new browser window (File->New Window)
3. In the new window, change the URL so that the page (the part of the URL after the last”/”) is
   xml_template_server.htm?action=getmessages

WebPublisher Editor Client-Side Tracing

1. Immediately before completing the editor operation you want to trace, edit the file DocumentumRightSiteapplicationswcmproductoperationsccc_checkoutstart.htm
   and make the following change: Change <DMW_DECLARE NAME="XML_CLIENT_DEBUG" VALUE="false" SCOPE="REQUEST>
   to <DMW_DECLARE NAME="XML_CLIENT_DEBUG" VALUE="true" SCOPE="REQUEST>
2. Complete the operation in the editor
3. In the browser, open the Java console to see the client-side editor trace

Example WebPublisher Server-Side Editor Trace:

                
[000.000] First request received in Docbase Server [000.000]
Server version = 4.2.4 [000.016] WCM defaults enabled [000.016]
Found override for APPLET_WIDTH = 95% [000.016]
Using default for HTML_RENDITION_ON_SAVE [000.016] 
Using default for VERSION_ON_OPEN [000.016]
Using default for RETAIN_LOCK_ON_CLOSE [000.016]
Found override for APPLET_HEIGHT = 85% [000.016] 
Using default for VERSION_ON_CLOSE [000.016]
Found override for APPLET_NAME = com.documentum.webclient.xmledit.client
 .main.TemplateEditor.class [000.016] 
Using default for DELETE_TEMP_FILES [000.016]
Using default for HTML_RENDITION_ON_CLOSE [000.016]
Using default for VERSION_ON_SAVE [000.016] 
Debug value is <TRUE>[000.016]

            

Intranet Client Plugin Tracing

The Smartspace Intranet Client plugin has a tracing mode that can be activated by adding a new key to the
Windows registry on the client machine. The traces are shown in pop-up windows
during the client session.

Instructions for Turning On Intranet Client Plugin Tracing:

1. Kill all browser instances and run regedit
2. Add this key to the registry (if its not already there): HKEY_LOCAL_MACHINE/SOFTWARE/Documentum/RightSite
3. Add this value under the key in step 2: HKEY_LOCAL_MACHINE/SOFTWARE/Documentum/RightSite/DWPLUGIN_VERBOSE
4. Set the string value to TRUE.
5. Open a new browser instance and use the plugin.

Docbroker Tracing

In addition to using the apply SET_OPTIONS API with the “docbroker_trace” option
(see section on “Server-Side Session Tracing”), you can also set three environment
variables that affect the level of logging in the docbroker trace file. The docbroker
trace file can be found by opening Documentum Server Manager, selecting the docbroker
tab and then hitting the “View log” button. You can set the environment variables using
the Windows Environment Variables dialog (Right-Click MyComputer->Properties->Advanced->Environment Variables).

These are the environment variables that configure tracing for the Docbroker:

                
DM_DEBUG_BROKER
DM_DOCBROKER_TRACE
DM_TRANS_LOG

            

Set the appropriate variables to a value between 1 and 10. Simply delete an environment variable to
disable that kind of tracing. Be sure you create the environment variables for the SYSTEM context
and not for a particular user. You must reboot the machine for the settings to take effect.

Example Docbroker Log:

                
Documentum DocBroker 4.2.1.18 Win32
    (c) Copyright Documentum, Inc., 1994-1997
Sun Dec 23 08:38:44 2001 324000 [DM_DOCBROKER_I_START]info:
  "Docbroker has started.  Process id: 472"
Sun Dec 23 08:38:45 2001 256000 [DM_DOCBROKER_I_REGISTERED_PORT]info:
  "The Docbroker registered using port (1489)."
Sun Dec 23 08:38:45 2001 256000 [DM_DOCBROKER_I_LISTENING]info:
  "The Docbroker is listening on network address: (INET_ADDR:
 family: 2, port: 1489, host: HOMER (127.0.0.1, 7f000001))"

            

Dump and Load Tracing

The dump and load process is often problematic and tracing can help you figure out where a
crash is occurring. You can set up your dump process to write its progress to the session log
by adding the following line at the beginning of your dump api script:

                
trace,c,10,,DM_DUMP

            

Also, be sure to issue the following command at the end of your dump process to check for errors that
occurred during the dump:

                
getmessage,c

            

You can set up your load process to write its progress to the session log
by adding the following line at the beginning of your load api script:

                
trace,c,10,,DM_LOAD

            

Also, be sure to issue the following command at the end of your dump process to check for errors that
occurred during the dump:

                
getmessage,c,1

            

See the section in this document called ‘The Trace API Command’ for more information on the trace API command.

Example Dump Trace:

                
Thu Dec 27 18:12:55 2001 921000 [DM_DUMP_T_REPL_5]info:  
  "Starting dump: mode=regular, object count=0"
Thu Dec 27 18:12:55 2001 921000 [DM_DUMP_T_LOG_TYPE]info:  
  "Writing type information into the dump file."
Thu Dec 27 18:12:55 2001 921000 [DM_DUMP_T_TYPE_NAME]info:  
  "Dumping type, name = dm_sysobject"
 SELECT I_.I_TYPE FROM ipms_dev.dmi_object_type I_ WHERE I_.R_OBJECT_ID=:handle
:handle = 2e0f462880000105
 SELECT * FROM dmi_type_info_rv EB_ , dmi_type_info_sv DB_  WHERE 
 (DB_.R_OBJECT_ID=:handle AND DB_.R_OBJECT_ID=EB_.R_OBJECT_ID) ORDER 
 BY EB_.R_OBJECT_ID,EB_.I_POSITION :handle = 2e0f462880000105
 SELECT I_.I_TYPE FROM ipms_dev.dmi_object_type I_ WHERE I_.R_OBJECT_ID=:handle
:handle = 2e0f462880000105
Thu Dec 27 18:12:56 2001 031000 [DM_DUMP_T_TYPE_NAME]info:  
  "Dumping type, name = dmi_type_info"
 SELECT I_.I_TYPE FROM ipms_dev.dmi_object_type I_ WHERE I_.R_OBJECT_ID=:handle
:handle = 2e0f462880000003

            

Brute Force Tracing

By turning on DMLC tracing in the dmcl.ini file, you can trace almost any application that calls the DCML to talk to the docbase. This includes custom applications, jsp pages in the WDK, etc. To do this, add the following lines
to the dmcl.ini file on the client machine or to the server.ini file on the server:

                
trace_file = [full path and file name of trace file]
trace_level = [integer value from 1 - 10]

            

After you add the lines, restart the server (or client) to start tracing.

Writing Custom Messages to the Session Log

You can write your own messages to the session log by using the apply API call
with the STAMP_TRACE argument. The log entry will be a time stamp followed by your message.

Example of an API call to write a custom message:

                
apply,c,NULL,STAMP_TRACE,MESSAGE,S,This is my message

            

In your custom DocBasic methods you can send tracing messages to the server log simply by printing
to standard out (using the Print statement). All info directed to stardard out gets captured in the
normal server log file.

                
Print "My message - " & now()