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)
Table of Contents
Document Info ................................................................................................................... v
1. Intended Audience .................................................................................................. v
2. History .................................................................................................................. v
1. Introduction ................................................................................................................... 1
1. Why would you use this ? ........................................................................................ 1
2. Summary ............................................................................................................... 1
3. Usage ................................................................................................................... 1
4. License ................................................................................................................. 2
5. Warranty ............................................................................................................... 2
2. Installation ..................................................................................................................... 4
1. Compilation on Solaris (SunOS) +GCC ...................................................................... 4
2. Complilation on Windows + Cygwin .......................................................................... 4

iv
Document Info
1. Intended Audience
The intended audience of this document are Documentum developers who want to use Ruby.

2. History
Revision History
Revision 1.0 24/07/2007 SVV
First draft
Revision 1.1 25/07/2007 SVV
Pre-release information
Revision 1.2 25/01/2008 SVV
Pre-release information

v
Chapter 1. Introduction
1. Why would you use this ?
The Ruby C implementation can be used to easily do migrations of Documentum systems. You can also
make 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 create
an activedctm library. This activedctm library has not been released yet.

2. Summary
We 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 strategy
for 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 Enterprise
Document Management System. You must have already obtained the necessary
libraries and purchased the necessary licenses from EMC|Documentum before you
can 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 the
Documentum documentation(API reference on how to use this.)

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

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

require 'documentum/c_interface'

1
 Introduction

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
res
end

def show_groups(label)
puts "-" * 10 + label + "-" * 10
puts get_groups
end

DI.init or raise
begin
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}")
end
ensure
DI.deinit or raise
end

4. License
This RubyC interface for Documentum is open source software and released under the terms of the Ruby
license.

5. Warranty
There is no warranty.

2
 Introduction

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.

3
Chapter 2. Installation
Installing 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_ARGS
which 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 from
Ruby's memory about how it itself was compiled. It is possible that the compiler and linker
cannot be found in your path, or are called differently from how Ruby remembers it (usually
because 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 through
the 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) +GCC

The 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 standard
locations 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 + Cygwin

Cygwin provides a pretty standard build environment, so all that needs to be set is the paths to the header
and library files. The library file required for compilation under Windows is called dmcl40.lib.

4
 Installation

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, includes

a control character at the start. Because this symbol is not used, you can just replace the
control character with a non-control character like an underscore. Note that only deleting the
character 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 somewhere
in the PATH or otherwise Windows cannot load it.