Ruby C interface for Documentum, Peter Vanbroekhoven(peter at xaop.com)and Stijn Van Vreckem(svv at xaop.com)

Ruby C interface for Documentum, Peter Vanbroekhoven(peter at xaop.com) and Stijn Van Vreckem(svv at xaop.com)

iv

Table of ContentsDocument Info ................................................................................................................... v

1. Intended Audience .................................................................................................. v2. History .................................................................................................................. v

1. Introduction ................................................................................................................... 11. Why would you use this ? ........................................................................................ 12. Summary ............................................................................................................... 13. Usage ................................................................................................................... 14. License ................................................................................................................. 25. Warranty ............................................................................................................... 2

2. Installation ..................................................................................................................... 41. Compilation on Solaris (SunOS) +GCC ...................................................................... 42. Complilation on Windows + Cygwin .......................................................................... 4

v

Document Info1. Intended Audience

The intended audience of this document are Documentum developers who want to use Ruby.

2. HistoryRevision HistoryRevision 1.0 24/07/2007 SVVFirst draftRevision 1.1 25/07/2007 SVVPre-release informationRevision 1.2 25/01/2008 SVVPre-release information

1

Chapter 1. Introduction1. Why would you use this ?

The Ruby C implementation can be used to easily do migrations of Documentum systems. You can alsomake use of Documentum within your Rails web applications.

XAOP [http://www.xaop.com] has used this library to write migration software for our clients and to createan activedctm library. This activedctm library has not been released yet.

2. SummaryWe had the choice of creating a RubyC or a JRuby interface. We have created and tested both interfaces.This document only describes the second RubyC based interface.

1. DMCL - DFC - JRuby

Don't hesitate to contact us for more info about this implementation.

Note

The advantage of this approach is that you stay in line with the Documentum Java strategyfor future releases.

2. DMCL - custom Ruby C extension - Ruby

This interface is lightweight but can be deprecated in future releases of Documentum.

It is very similar to the implementation of the Documentum Perl library [http://search.cpan.org/~briansp/Db-Documentum-1.3/Documentum.pm]

Warning

A Ruby interface to the client API libraries for the Documentum EnterpriseDocument Management System. You must have already obtained the necessarylibraries and purchased the necessary licenses from EMC|Documentum before youcan build this module. For more information on Documentum EDMS, see http://www.documentum.com/ [http://www.emc.com]

This RubyC interface uses the API commands APIExec, APISet and APIGet. You can check theDocumentum documentation(API reference on how to use this.)

Warning

By using these API commands you will bypass the DFC-BOF layer. Therefore, custombehaviour defined in type based objects(TBO) will not be executed.

3. UsageYou can use the following example(with minor changes) when you have succesfully installed the library :

require 'documentum/c_interface'

Introduction

2

DI = Documentum::Internal

def get_groups coll = DI.get("query,c,select group_name from dm_group") res = [] while DI.exec("next,c,#{coll}") res << DI.get("get,c,#{coll},group_name") or raise end resend

def show_groups(label) puts "-" * 10 + label + "-" * 10 puts get_groupsend

DI.init or raisebegin sid = DI.get("connect,<docbase>,<username>,<password>") or raise begin show_groups("BEFORE") gr = DI.get("create,c,dm_group") or raise DI.set("set,c,#{gr},group_name", "xaop_reviewers") or raise DI.set("set,c,#{gr},globally_managed", "F") or raise DI.exec("save,c,#{gr}")

show_groups("AFTER CREATE")

raise "group not created" unless get_groups.include? "xaop_reviewers"

DI.exec("destroy,c,#{gr}") or raise

show_groups("AFTER DELETE")

raise "group not deleted" if get_groups.include? "xaop_reviewers" ensure DI.exec("disconnect,#{sid}") endensure DI.deinit or raiseend

4. LicenseThis RubyC interface for Documentum is open source software and released under the terms of the Rubylicense.

5. WarrantyThere is no warranty.

Introduction

3

Warning

If you use this and if it breaks something you get no support.

Use this library at your own risk.

We have only tested this on Sun Sparc Solaris 10, Linux and Windows.

4

Chapter 2. InstallationInstalling dctmruby can be as simple as running the following command in the distribution's root directory:

rake

Unless specified otherwise, the Documentum header files and libraries are looked for in the directories$DM_HOME/include and $DM_HOME/lib respectively.

If they are in different locations, you can specify the correct locations by setting CONFIGURE_ARGSwhich is passed as arguments to the configuration script.

The switches are as follows:

--with-dctm-include=/path/to/headers --with-dctm-lib=/path/to/libs

Currently, the only header file is dmapp.h. The library varies by platform (see below.)

Warning

The C compiler and linker that will be used in building the dctmruby library are taken fromRuby's memory about how it itself was compiled. It is possible that the compiler and linkercannot be found in your path, or are called differently from how Ruby remembers it (usuallybecause Ruby was compiled on another machine with a different build environment.)

The C compiler can be specified through the CC environment variable. The linker can be specified throughthe LDSHARED environment variable. Be sure to include any flags to enable linking of shared libraries,for instance under Linux using GCC, set LDSHARED to "cc -shared".

1. Compilation on Solaris (SunOS) +GCCThe build environment is pretty standard. In our particular case, the configure script uses cc by default,which was available as executable name, and the linker was not in the PATH.

The library file under Unix is called dmcl40.so. The header and library files were not in the standardlocations here either.

The following sequence of commands worked for us:

LIB=/export/home/documentum/product/5.3/unix/solaris INC=/export/home/documentum/shared export CC=gcc export LDSHARED="/usr/ccs/bin/ld -G" export CONFIGURE_ARGS="--with-dctm-lib=$LIB --with-dctm-include=$INC" rake

Note

The flag for linking shared libraries is -G in this setup.

2. Complilation on Windows + CygwinCygwin provides a pretty standard build environment, so all that needs to be set is the paths to the headerand library files. The library file required for compilation under Windows is called dmcl40.lib.

Installation

5

Warning

We have encountered a problem with this file, so using this file will require editing it a little.

The problem is that one symbol,?DMCL40_NULL_THUNK_DATA in our case, includesa control character at the start. Because this symbol is not used, you can just replace thecontrol character with a non-control character like an underscore. Note that only deleting thecharacter corrupts the file, it needs to be replaced by a single other character.

The following sequence of commands worked for us to compile dctmruby:

LIB=/cygdrive/c/dctm/documentum/clients/win/32 INC=/cygdrive/c/dctm/documentum/sdk/include export CONFIGURE_ARGS="--with-dctm-lib=$LIB --with-dctm-include=$INC" rake

Note

Note that to be able to actually use the dctmruby library, dmcl40.dll needs to be somewherein the PATH or otherwise Windows cannot load it.