EMC White Paper

Method Server essentials

Soumya Mitra

Abstract: This document highlights the technically obscure areas of Content Server to facilitate
Developer Support assignments.

Date 3/15/2007
Copyright © 2007 EMC Corporation. All rights reserved.
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without
notice.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO
REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION,
AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE.
Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
EMC2, EMC, and EMC Documentum product names are trademarks of EMC Corporation. All other trademarks used herein are the
property of their respective owners. All other brand names are trademarks or registered trademarks of their respective owners.

Method Server essentials 2

Introduction to Method Servers
Content server provides very powerful server side scripting features through its method server architecture.
It is somewhat analogous to Common Gateway Interface or CGI feature of a Webserver. Likewise in
Content Server, methods are run as executable scripts or programs in separate external processes. The
figure below illustrates how different components interact in a Content Server environment.

The Content Server process orchestrates the entire function of repository. When a client invokes a method
server call, it delegates the call (based on the method) to appropriate execution agents. The Content Server
version 5.2.5 and 5.3 has three execution agents:-
1) Content Server
2) Docbasic method server
3) Java method server

The methods can be a Docbasic script, Java class or a self executable program written in another
programming language such as C++.

For every method, we have to create a method object of type dm_method. The attributes of that method
object will define arguments and the execution parameters. Methods are executed by issuing a
DO_METHOD administration method or using a job. Using a DO_METHOD allows you to execute the
method on demand. Using a job allows you to schedule the method for regular, automatic execution.

Method Server essentials 3

Content Server & Docbasic Method Server
There are only two Documentum supported languages used for cross-platform development of dm_method
content. These languages are GAWK and Docbasic. Since these languages are interpreted and limited in
some ways, it might be desirable to forgo the cross platform advantage and use a compiled language. On
the NT platform, a customer might want to develop an executable in Visual Basic 5, and use it as
dm_method content. The figure below shows how a DmBasic method needs to be setup in the method
object.

Not just any Visual Basic application can run as method. The rules are the same for development in Visual
Basic as well as Docbasic or GAWK. You can NOT have any graphical user interface in a method. The
process runs on the server host and there is no way to interact with it from the client. Also, you must make
the program a command line executable that accepts the necessary parameters at the start of execution.

Skeleton of a DmBasic Method

'####################################################################
'
' A skeleton of a DmBasic Method
'
'####################################################################
'
' Entry_Point is the entry point for this script. It retrieves
'

Method Server essentials 4

Sub Entry_Point _
(objId As String, _
docBase As String, _
userName As String, _
ticket As String)

' Connect with Docbase

buff = "connect," & docBase & "," & UserName & "," & ticket
sess_id = dmAPIGet(buff)
' If any error occues then: Call Connect_Handler()

End Sub

'
' Handle and report any errors
'
Sub Error_Handler (sess As String)
buff$ = "getmessage," & sess
mesg$ = dmAPIGet(buff$)
print "Message: ";mesg$
Stop
End Sub

'
' Retrieve any connection related information
'
Sub Connect_Handler ()
buff$ = "getmessage,a"
mesg$ = dmAPIGet(buff$)
print "Message: ";mesg$
Stop
End Sub

Java Method Server

Documentum provides a customized version of Apache Tomcat to execute Documentum Server Java
methods. It gets installed along with the Content Sever in the same box. In addition to Tomcat,
Documentum provides a servlet called DO_METHOD to execute Documentum Server methods. The
compiled servlet code is found in mthdservlet.jar located on the same host as Content Server. This jar file
contains the IDmMethod class.

Method Server essentials 5

Technically all Documentum Java Sever methods are simple java classes, which implements IDmMethod
interface. When a DO_METHOD method directed to the Java method server is issued (with the Java
method class name and parameters), it generates an internal HTTP_POST request. The Java method server
invokes the do_method servlet to service the request.

Why Java method server?

Content Server execution agent can launch any executable program, including a JVM running a Java
application. So one can raise the question if CS can lunch a Java program, then why Documentum provides
a separate Java method server? There are number of good reasons for this design:-

The java methods are executed as Servlets under Tomcat Application Server. So we can invoke many
instances of the method without spawing multiple instances of JVM process, each of which running an
instance of the method. This will save lot of memory and processing resources and provide performance
benefits. The benefits are same like running a Servlet instead of running a CGI application.

Java method server runs as an independent process. It can be stopped or started without recycling the
content server. In Windows platform, method server can be run as a Windows service or as a process.

CLASSPATH must include $DOCUMENTUM_SHARED/dctm.jar,

$DM_HOME/dctm_server.jar, $DOCUMENTUM_SHARED/tcf/config, and
$DOCUMENTUM_SHARED/tcf/lib/tcf-engine.jar

A common mistake
The Tomcat provided with Content Server to run Java method is not a full blown Tomcat. It has been
customized by eliminating many features, so it is not suitable to work as a generic Servlet container. Often,
a customer may deploy a WDK application on this Tomcat and run into issues. Such deployment will not
work and unsupported by Documentum.

Anatomy of a Java Server method

It is same as any Java class with some specific guidelines:-
1. Always implement the IDmMethod interface in your class,
2. Implement the method execute(),
3. Obtain a Docbase session using newSessionManager()
4. Throw an exception instead of using 'exit',
5. Release your session after use.

A typical skeleton of a Java Server Method will look like this

import java.util.*;
import java.io.OutputStream;
import com.documentum.mthdservlet.IDmMethod;
import com.documentum.fc.client.*;
import com.documentum.fc.common.*;

public class MyServerMethod implements IDmMethod

{
public void execute(Map params, OutputStream ostream) throws Exception {

// Log on the to docbase and get a session manager like this

// IDfSessionManager sessionMgr = dfClient.newSessionManager();
// and get a session from the session manager

Method Server essentials 6

 // Add your business logic here ...

} catch (DfException e) {
ostream.write("A DfException occurred".getBytes());
ostream.write(e.getMessage().getBytes());
e.printStackTrace();
// spit out to stderr as well throw e;

} finally {

// If session is not null release the session to the

// session manager here.

}
}

How to deploy a Java server method?

The following instructions provide the main steps to deploy a Java server method

1) Compile the Java method. Note that if you make changes to the workflow method, you must re-
compile the method and restart the Java Method Server for the changes to take effect.
2) Stop Tomcat, if it’s already running.
3) Start Windows Explorer and change to the following directory:
%DOCUMENTUM%\dba\java_methods. This directory represents the location for all java
methods that you develop, and which are executed by a Documentum supplied servlet called
DO_METHOD on the application server.
4) Copy the java method class to deploy into this folder.
5) Restart the Tomcat application server.
6) Connect to your Docbase using Documentum Administrator.
7) Click Administration > Job Management > Methods in the left pane.
8) Click File > New > Method from the drop-down menu to create a new method.
9) In the Name field, enter your custom method name Do not use the format dm_methodname to
name the method. This naming convention is reserved for default Documentum objects.
10) In the Verb field, enter DmSampleMethod. Note: The method_verb attribute must correspond
to the same Java class used in Tomcat. For other type of methods, the method verb is the
command-line name of the procedure or the name of the interpretive language that will execute the
program file. It is a good practice to specify the fully-qualified class name of the Java class as the
command verb. If your class is contained with a jar file then you must specify the fully-qualified
class name. For example;
com.documentum.bpm.bpsintegration.bps.DmBPSHTTPIntegration
11) Select java as the Method Type.
12) Check Run As Server. If checked, it indicates that you want the method to run as the installation
owner account, with the installation owner’s privileges. Otherwise, the method runs as the user
creating the method, with that user’s privileges. The default is unchecked. Run as Server must be
checked to execute a method on the method server or application server.
13) UnCheck Launch Direct. This controls whether the program is executed by the operating
system’s system or exec API call. If checked, the server uses the exec call to execute the

Method Server essentials 7

 procedure. In such cases, the method_verb must be a fully qualified path name. If unchecked, the
server uses the system call to execute the procedure.
14) Check Use Method Server.
15) When done, click the Finish button to return back to the Methods page.

The figure below shows a typical entry in method object for a Java method

How to trace method servers

To trace method execution in the method server or Content Server, set the trace_method_server server
flag. You can set this flag using the SET_OPTIONS administration method or on the server startup
command line:

-otrace_method_server

Tracing information generated by Content Server is stored in the server log file. Tracing information
generated by the method server is stored in the method server log file. The log file is stored in

%DOCUMENTUM%\dba\log\<repository_id>\MethodServer\MethodServer\server_config_name.log
or
$DOCUMENTUM/dba/log/<repository_id>/MethodServer/MethodServer/server_config_name.log

Method Server essentials 8

The log file is created when the method server is started. If a method server log file currently exists, it is
saved with a time stamp and a new log file is started. To trace method execution on the Java method server,
set the trace parameter in the web.xml file to true. For example:

<init-param>
<param-name>trace</param-name>
<param-value>t</param-value>
</init-param>
The web.xml file is found in %DM_HOME%\tomcat\webapps\DmMethods\WEB–INF\web.xml
($DM_HOME/tomcat/webapps/DmMethods/WEB–INF/web.xml).

The log files generated by the Java method server are stored in
%DM_HOME%\tomcat\logs ($DM_HOME/tomcat/logs).

Manually starting the method server

For Windows: Click Start-->Programs-->Administrative Tools-->Services.and run start.bat
For Unix: Navigate to the $DM_HOME/tomcat/bin/ directory and run startup.sh java method server

Server and Method Server startup order

1) Docbroker - Independent of any other application
2) Repository - Dependent on Docbroker
3) Java Method Server - Dependent on Docbroker and Repository
4) Index server - Independent of any other application
5) Index agent - Dependent on Index server

Order of starting index sever and java method server do not matter. For shutdown, follow the
reverse order.

How to check if method server is running?

Check if your java method server is up and running. Try accessing the following url
http://<hostname>:9080/DmMethods/servlet/DoMethod
It should show "Documentum Java Method Server".

If not restart it. Navigate to the $DM_HOME/tomcat/bin/ directory and run startup.sh script for UNIX.
For windows
Click Start-->Programs-->Administrative Tools-->Services.and start java method server

Method Server essentials 9

Known issues with Java method server
Some time some custom application can cause Method Server to put heavy load on the content server. On
further investigation we have found that if the application uses asynchronous server method invocations,
then execution agent can potentially launch hundred or more external method processes. This causes a very
high load on the content server and Oracle.

The Tomcat server used for the method server can be configured to reduce the number of simultaneous
threads active. This could theoretically provide some flow control by limiting the number of methods that
can simultaneously be executed. Unfortunately it appears error handling in the Content Server for
asynchronous methods is rather weak. If the Java Method Server is already processing all the simultaneous
methods that it is capable of, all new requests get discarded. The application never knows that its method
requests were discarded.

Please note asynchronous method execution can overload the server and may cause substantial delay in
execution of the method.

When switching to synchronous method execution there are still problems. Under heavy load the
"DO_METHOD" calls will fail with a rather vague error message. It is up to the application to decide that
the server is under heavy load and therefore should just keep retrying the method submission until the
server has bandwidth to service it. As it stands now the user requests simply fail when the server gets busy.

Challenge Questions

1) What is a Documentum Server Methods?

2) How many types of Server Methods are supported?
3) Who executes the Server Method?
4) What interface does a Java Server Method need to implement?
5) How to check if a method server is running?

Method Server essentials 10

About EMC
EMC Corporation (NYSE: EMC) is the world leader in information storage systems, software, networks,
and services, providing automated networked storage solutions to help organizations get the maximum
value from their information, at the lowest total cost, across every point in the information lifecycle.
Information about EMC’s products and services can be found at www.EMC.com

About Documentum Software from EMC

EMC Documentum software includes enterprise content management solutions that enable organizations to
unite teams, content, and associated business processes. With a single platform, EMC Documentum
software enables people to collaboratively create, manage, deliver, and archive the content that drives
business operations, from documents and discussions to e-mail, Web pages, records, and rich media. The
Documentum enterprise content management platform makes it possible for companies to distribute all of
this content in multiple languages, across internal and external systems, applications, and user
communities. As a result of deploying Documentum, thousands of the world’s most successful
organizations are harnessing corporate knowledge, accelerating time to market, increasing customer
satisfaction, enhancing supply chain efficiencies, reducing operating costs, and improving their overall
competitive advantage.

For more information about Documentum enterprise content management, visit

www.emc.com/documentum or call 800.607.9546 (outside the U.S.: +1.925.600.5802).

Method Server essentials 11