dbi Blog

Beside the obsolete dmbasic, the autistic dmawk, the verbose java with the DfCs, the limited iapi (for API) and idql (for DQL) command-line tools, Documentum does not offer any scripting language for the administrator and the out-of-the-box experience is quite frustrating in this respect. It has been so even before the java trend so it is not a maneuver to force the use of the DfCs or to rely on it for administrative tasks. It looks more like an oversight or like this was considered as a low-priority need.
Of course, people didn’t stop at this situation and developed their own bindings with their preferred scripting language. I found db:Documentum for perl, yours truly’s DctmAPI.py for python (refer to the article here), dmgawk for gawk (see here), and of course all the JVM-based languages that leverage the DfCs such as groovy, beanshell, jython, jruby, etc… Such JVM-based scripting languages actually only need to import the DfCs library and off they go for the next killer script. In this article, I’ll show how to set up the binding for a few of those languages under the linux O/S.

db::Documentum

This is a perl v5 module that permits access to the Documentum api from the perl interpreter. It was developed by M. Scott Roth, see here, originally only for the Windows O/S and EDMS v3.1.5. Thanks to other contributors, it is now compilable under several flavors of Unices, including Linux. It is downloadable from here.
You’ll need the GNU C compiler to generate the module. Here is a detailed, step by step description of the installation procedure.
# download the archive Db-Documentum-1.64.tar.gz from here http://www.perl.com/CPAN/modules/by-module/Db/ # decompress it in, say, db::Documentum tar -zxvf Db-Documentum-1.64.tar.gz # move to the newly created directory Db-Documentum-1.64; cd Db-Documentum-1.64 # prepare the following needed paths; # DM_HOME # path to the Documentum installation, e.g. /home/dmadmin/documentum # DM_LIB # path to the Documentum libdmcl.so library, e.g. ${DM_HOME}/product/7.3/bin # note: there is also the obsolescent libdmcl40.so but I've encountered problems with it, mostly "Segmentation fault (core dumped)" crashes, so use the JNI-based libdmcl.so instead; it starts more slowly as it uses java but it is more reliable and is still supported; # DM_INCLUDE # path to the include file dmapp.h, e.g. ${DM_HOME}/share/sdk/include # edit the linux section in Makefile.PL and provide the above paths; # also, move up the $DM_LIB initialization before the dmcl.so test and comment the line beginning with $DM_CLIENT_LIBS = # here is how that section looks like after editing it: elsif ( $OS =~ /linux/i ) { # The path to your Documentum client installation. $DM_HOME = '/home/dmadmin/documentum'; # This is kinda a gottcha, the Linux stuff is in unix/linux # You may have to tweak these. # Path to documentum client libraries. #$DM_LIB = "$DM_HOME/unix/linux"; $DM_LIB = "$DM_HOME/product/7.3/bin"; # dmcl.so file if (! -e "$DM_LIB/libdmcl.so") { warn "n*** WARNING *** Could not find $DM_LIB/libdmcl.so.nThe module will not make without " . "libdmcl.so.n"; } # Path to directory where dmapp.h lives. #$DM_INCLUDE = "-I/documentum/share/sdk/include/"; $DM_INCLUDE = "-I$DM_HOME/share/sdk/include/"; #$DM_CLIENT_LIBS = "-L$DM_LIB -ldmapi -ldmupper -ldmlower -ldmcommon -ldmupper -lcompat"; $DM_RPC_LIBS = "-L$DM_LIB -lnwrpc -lnwstcp"; $OS_LIBS = "-lsocket -lnsl -lintl"; $CPP_LIBS = "-lC"; $LD_LIBS = "-ldl"; $CPP_INC = ""; $CCFLAGS = ""; } # execute the Makefile.PL; perl Makefile.PL # if the error below occurs, you must install the perl-devel module using the native package deployment tool for your distribution, # e.g. sudo yum install perl-devel for centos: # Can't locate ExtUtils/MakeMaker.pm in @INC (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5 .) at Makefile.PL line 1. #BEGIN failed--compilation aborted at Makefile.PL line 1. # a Makefile file has been generated; correct the 2 lines below as showed; EXTRALIBS = -L/home/dmadmin/documentum/product/7.3/bin -ldmcl LDLOADLIBS = -L/home/dmadmin/documentum/product/7.3/bin -ldmcl -lc # use the newly produced Makefile; make # run some tests to check the new module; make test # the test completes successfully but, sometimes, it is followed by SIGSEGV in the JVM; # as it occurs at program termination, it can be ignored; # install the new perl module system-wide; sudo make install

Now that we have the module, let’s use it in a simple test case: dump of all the dm_sysobject linked in cabinet /dmadmin (its id is 0c00c35080000105) in the out-of-the box dmtest repository.

vi cat my-test.pl 
#!/usr/bin/perl

use Db::Documentum qw(:all);
use Db::Documentum::Tools qw(:all);

# print version
Db::Documentum::version;

$docbase = "dmtest";
$username = "dmadmin";
$password = "dmadmin";

# connect;
$result = dm_Connect($docbase, $username, $password) || die("could not connect in " . $docbase . " as " . $username . " with password " . $password);

# run the query;
$status = dmAPIExec("execquery,c,,select r_object_id, r_object_type, object_name from dm_sysobject where folder(ID('0c00c35080000105'))");
if (1 != $status) {
   $err_mess = dmAPIGet("getmessage,c");
   print $err_mess;
   die();
}
$query_id = dmAPIGet("getlastcoll,c");
printf "%-16s  %-20s  %sn", "r_object_id", "r_object_type", "object_name";
while (dmAPIExec("next,c," . $query_id)) {
   $r_object_id = dmAPIGet("get,c," . $query_id . ",r_object_id");
   $r_object_type = dmAPIGet("get,c," . $query_id . ",r_object_type");
   $object_name = dmAPIGet("get,c," . $query_id . ",object_name");
   printf "%16s  %-20s  %sn", $r_object_id, $r_object_type, $object_name;
}
dmAPIExec("close,c," . $query_id);

# disconnect;
dmAPIExec("disconnect,c");
exit;

The script is very trivial and needs little explanation. Note the new functions dm_Connect, dmAPIExec and dmAPIGet. dmAPISet, dmAPIInit and dmAPIDeInit are also available but the last two don’t need to be invoked explicitly for they are automatically at module load-time.
Example of execution:
perl my-test.pl Perl version: 5.016003 Db::Documentum version: 1.64 DMCL version: 7.3.0000.0205 r_object_id r_object_type object_name 0800c3508000019b dm_job dm_PropagateClientRights 0800c3508000019c dm_job dm_PostUpgradeAction 0800c35080000408 dmc_wfsd_type_info integer 0800c35080000409 dmc_wfsd_type_info boolean 0800c3508000040a dmc_wfsd_type_info double 0800c3508000040b dmc_wfsd_type_info string 0800c3508000040c dmc_wfsd_type_info date 0800c3508000040d dmc_wfsd_type_info repeating integer 0800c3508000040e dmc_wfsd_type_info repeating boolean 0800c3508000040f dmc_wfsd_type_info repeating double 0800c35080000410 dmc_wfsd_type_info repeating string 0800c35080000411 dmc_wfsd_type_info repeating date 0800c35080000426 dm_sysobject dm_indexAgentAcquireLock 0800c35080000587 dm_client_rights dfc_localhost_c0XP4a 0800c35080001065 dm_jms_config JMS dmtest:9080 for dmtest.dmtest 0800c35080001066 dm_jms_config JMS localhost.localdomain:9080 for dmtest.dmtest 0b00c35080000233 dm_folder Workspace Customizations 1700c3508000015d dm_outputdevice Default LP Printer 3a00c3508000013f dm_location storage_01 3a00c35080000140 dm_location common 3a00c35080000141 dm_location events 3a00c35080000142 dm_location log 3a00c35080000143 dm_location config 3a00c35080000144 dm_location dm_dba 3a00c35080000145 dm_location auth_plugin 3a00c35080000146 dm_location ldapcertdb_loc 3a00c35080000147 dm_location temp 3a00c35080000148 dm_location dm_ca_store_fetch_location 3a00c35080000153 dm_location convert 3a00c35080000154 dm_location dsearch 3a00c35080000155 dm_location nls_chartrans 3a00c35080000156 dm_location check_signature 3a00c35080000157 dm_location validate_user 3a00c35080000158 dm_location assume_user 3a00c35080000159 dm_location secure_common_area_writer 3a00c3508000015a dm_location change_password_local 3a00c3508000015b dm_location thumbnail_storage_01 3a00c3508000015c dm_location streaming_storage_01 3a00c35080000226 dm_location replicate_location 3a00c35080000227 dm_location replica_storage_01 3e00c35080000149 dm_mount_point share 6700c35080000100 dm_plugin CSEC Plugin 6700c35080000101 dm_plugin Snaplock Connector
Now, the power of perl and its more than 25’000 modules are at our fingertips to help us tackle those hairy administrative tasks !

groovy

Being a JVM-based language, groovy runs on top of a JVM, and therefore benefits of all its advantages such as automatic garbage collection (although this is not an exclusivity of java) and portability (ditto), and can tap into the uncountable existing JAVA libraries (ditto).
groovy is used in Documentum’s xPlore.
groovy is a powerful, yet easy to learn, programing language still actively maintained by the Apache foundation, cf. here. Similar to java but without its verbosity, it should instantly appeal to java developers doing Documentum administrative tasks.
groovy comes with groovysh, a comfortable and powerful interactive shell for trying out statements and experimenting with the language.
By importing the DfCs, we can use groovy to access Documentum repositories. Knowledge of the DfCs are required of course.
To install groovy, use the distribution’s package manager; e.g. on my Ubuntu, I’ve used:
sudo apt-get install groovy
while on Centos, the following command will do it:
sudo yum install groovy
To test it, let’s use the same program as for perl, but rewritten a la groovy:

#! /usr/bin/groovy

import System.*;
import java.io.*;

import com.documentum.fc.client.*;
import com.documentum.fc.common.*;

   static void main(String[] args) {
      docbroker = "dmtest";
      docbase = " dmtest";
      username = "dmadmin";
      password = "dmadmin";
   
      println("attempting to connect to " + docbase + " as " + username + "/" + password + " via docbroker " + docbroker);
   
      try {
         client = DfClient.getLocalClient();
      
         config = client.getClientConfig();
         config.setString ("primary_host", docbroker);
      
         logInfo = new DfLoginInfo();
         logInfo.setUser(username);
         logInfo.setPassword(password);
         docbase_session = client.newSession(docbase, logInfo);
      
         if (docbase_session != null) {
            println("Got a session");
      
            // do something in the session;
            folderId = new DfId("0c00c35080000105");
            folder = docbase_session.getObject(folderId);
            attrList = "r_object_id,r_object_type,object_name";
            coll = folder.getContents(attrList);
      
            while (coll.next())
               System.out.printf("ObjectId=%-16s r_object_type=%-20s ObjectName=%sn",
                                 coll.getString("r_object_id"),
                                 coll.getString("r_object_type"),
                                 coll.getString("object_name"));
            println("Finished");
            docbase_session.disconnect();
         }
         else
            println("Didn't get a session");
      }
      catch (e) {
         println("Exception was: " + e);
      }
   }

Lines 6 & 7 import the DfC so don’t forget to add them to the CLASSPATH; normally they are because the execution environment is a Documentum client, e.g.:
export JAVA_HOME=/home/dmadmin/documentum/shared/java64/1.8.0_77 export CLASSPATH=/home/dmadmin/documentum/shared/dfc/dfc.jar export PATH=$JAVA_HOME/bin:$PATH
Line 15 & 38 show that besides its own built-in functions, groovy can also use equivalent functions from the java libraries.
To invoke the script:
groovy tgroovy.gry # or make it executable and call it: chmod +x tgroovy.gry ./tgroovy.gry
Here is its output:
attempting to connect to dmtest as dmadmin/dmadmin via docbroker dmtest Got a session ObjectId=0800c3508000019b r_object_type=dm_job ObjectName=dm_PropagateClientRights ObjectId=0800c3508000019c r_object_type=dm_job ObjectName=dm_PostUpgradeAction ObjectId=0800c35080000408 r_object_type=dmc_wfsd_type_info ObjectName=integer ObjectId=0800c35080000409 r_object_type=dmc_wfsd_type_info ObjectName=boolean ObjectId=0800c3508000040a r_object_type=dmc_wfsd_type_info ObjectName=double ... ObjectId=3a00c35080000227 r_object_type=dm_location ObjectName=replica_storage_01 ObjectId=3e00c35080000149 r_object_type=dm_mount_point ObjectName=share ObjectId=6700c35080000100 r_object_type=dm_plugin ObjectName=CSEC Plugin ObjectId=6700c35080000101 r_object_type=dm_plugin ObjectName=Snaplock Connector Finished

jython

jython is a python implementation written in java, see here.
A such, it offers most of the features of the powerful python language although it stays behind the latest python version (v2.5.3 vs. 3.7).
Like java, groovy, jruby, scala, etc …, jython runs inside a JVM and can use all the java libraries such as the DfCs and become a Documentum client with no changes except adding the DfCs to the $CLASSPATH.
jython appeals especially to people who already know python; like for groovy, a basic level knowledge of the DfCs is required.
To install jython, use your distribution’s package manager, e.g.
# for ubuntu: sudo apt-get install jython
Make sure the DfCs are present in $CLASSPATH, otherwise add them:
export CLASSPATH=/home/dmadmin/documentum/shared/dfc/dfc.jar:
When runing the test script below, the DfCs complain about a bad date format:
20:42:05,482 ERROR [File Watcher] com.documentum.fc.common.DfPreferences - [DFC_PREFERENCE_BAD_VALUE] Bad value for preference "dfc.date_format", value="M/d/yyyy, h:mm:ss a" com.documentum.fc.common.DfException: Illegal syntax found in the date format 'M/d/yyyy, h:mm:ss a'. The default localized short date format will be used. at com.documentum.fc.common.DfException.newIllegalDateFormatException(DfException.java:109)
Evidently, they are unhappy with the default date format. The work-around is to force one in the dfc.properties file by adding the line below (choose a date format that best suits you):
dfc.date_format=dd.MM.yyyy HH:mm:ss
Since the error did not occur with groovy (nor in the provided JNI-enabled command-line tools such as iapi, idql and dmawk), it is not the DfCs per se that have this problem but the combination of java + jython + DfCs.
Here comes the test script:

#!/usr/bin/env jython

# install jython via your O/S package manager;
# export CLASSPATH=/home/dmadmin/documentum/shared/dfc/dfc.jar:$CLASSPATH
# edit the documentum/shared/config/dfc.properties and add a dfc.date property, e.g.:
# dfc.date_format=dd.MM.yyyy HH:mm:ss
# execute:
#   jython test.jy
# or:
#   chmod +x test.jy; ./test.jy
# can also be execute interactively as follows:
# start jython:
#    jython
# call the test script;
#    execfile("/home/dmadmin/test.jy")

import traceback
import com.documentum.fc.client as DFCClient
import com.documentum.fc.common as DFCCommon

docbroker = "dmtest"
docbase = " dmtest"
username = "dmadmin"
password = "dmadmin"
print("attempting to connect to " + docbase + " as " + username + "/" + password + " via docbroker " + docbroker)
try:
  client = DFCClient.DfClient.getLocalClient()

  config = client.getClientConfig()
  config.setString ("primary_host", docbroker)

  logInfo = DFCCommon.DfLoginInfo()
  logInfo.setUser(username)
  logInfo.setPassword(password)
  docbase_session = client.newSession(docbase, logInfo)

  if docbase_session is not None:
    print("Got a session")
    # do something in the session;
    folderId = DFCCommon.DfId("0c00c35080000105");
    folder = docbase_session.getObject(folderId);
    attrList = "r_object_id,r_object_type,object_name";
    coll = folder.getContents(attrList);
    while(coll.next()):
       print("ObjectId=" + "%-16s" % coll.getString("r_object_id") + 
             " r_object_type=" + "%-20s" % coll.getString("r_object_type") +
             " ObjectName=" + coll.getString("object_name"));
    print("Finished");
    docbase_session.disconnect()
  else:
    print("Didn't get a session")
except Exception:
    print(Exception)

Execution:
jython test.jy WARNING: An illegal reflective access operation has occurred WARNING: Illegal reflective access by org.python.core.PySystemState (file:/usr/share/java/jython-2.5.3.jar) to method java.io.Console.encoding() WARNING: Please consider reporting this to the maintainers of org.python.core.PySystemState WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations WARNING: All illegal access operations will be denied in a future release attempting to connect to dmtest as dmadmin/dmadmin via docbroker dmtest Got a session ObjectId=0800c3508000019b r_object_type=dm_job ObjectName=dm_PropagateClientRights ObjectId=0800c3508000019c r_object_type=dm_job ObjectName=dm_PostUpgradeAction ObjectId=0800c35080000408 r_object_type=dmc_wfsd_type_info ObjectName=integer ObjectId=0800c35080000409 r_object_type=dmc_wfsd_type_info ObjectName=boolean ObjectId=0800c3508000040a r_object_type=dmc_wfsd_type_info ObjectName=double ... ObjectId=3a00c35080000227 r_object_type=dm_location ObjectName=replica_storage_01 ObjectId=3e00c35080000149 r_object_type=dm_mount_point ObjectName=share ObjectId=6700c35080000100 r_object_type=dm_plugin ObjectName=CSEC Plugin ObjectId=6700c35080000101 r_object_type=dm_plugin ObjectName=Snaplock Connector Finished
Ironically, the jython’s launcher is a perl script; it basically initializes java and python environment variables such as classpath, java options and jython home and path. If the initial WARNINGs are disruptive, edit that script and correct the problem or just redirect the stderr to null, e.g.:
jython test.jy 2> /dev/null

So, which one to choose ?

To summarize, the decision tree below may help choosing one scripting language among the preceding ones.
DfCs knowledge ?: java proficiency ?: choose groovy with the DfCs else python proficiency ?: choose jython with the DfCs else select one of the following ones: get acquainted with one of the above languages | choose another JVM-based language | give up the DfCs and use DQL/API with perl, python of gawk instead (see below) else perl proficiency ?: choose db::Documentum else python proficiency ?: choose python and DctmAPI.py else nawk/gawk proficiency ? choose gawk and dmgawk binding else select one of the following: learn one of the above scripting languages | develop a Documentum binding for your preferred scripting language not in the list | hire dbi-services for your administrative tasks or projects ;-)
DfCs are clearly indicated to java programmers. They are still supported and new features are always accessible from them. There are tasks which cannot be done through the API or DQL and only through the DfCs, but generally those are out of the scope of an administrator. Note that even the non java and DfCs languages still finish up invoking the DfCs in the background because they are linked with the libdmcl.so library and that one makes JNI behind-the-scene calls to the DfCs for them, thus hiding their complexity. Hopefully, this shared library will stay with us still for some time otherwise our scripting language choice will be seriously restricted to JVM-based languages and the DfCs.

Post Views: 2,051

A few scripting languages for Documentum

db::Documentum

groovy

jython

So, which one to choose ?

Cesare Cervini

Leave a Reply:

Related blog articles

db::Documentum

groovy

jython

So, which one to choose ?

Cesare Cervini

Leave a Reply:

Related blog articles

Keep your data sorted with AI

Alfresco – A never ending transformation

M-Files January Release 2024

Why businesses – regardless of their size – have an interest in using an ECM/IIM solution?