DFC README
==========
Alpha Release 2
December 4, 2000

QUICK INSTALL
=============
1. Install Documentum Desktop Client 4.1
2. Install a JDK (1.3 prefered)
3. Install JPL
4. Install DFC.pm and associated files.

ABSTRACT
=========
DFC.pm is a Perl 5 module that enables the use of Documentum's Foundation
Classes (DFC) in Perl.

1. JPL
======
JPL (Java-Perl Lingo) is a Perl 5 module that enables the use of Java classes
in Perl.  JPL is a critical part of DFC.pm since the DFC is a collection of
Java classes.  All interaction with the DFC is through JPL.

1.1 GET JPL
===========

1.1.1  CVS
==========
The latest version of the JPL module can be obtained from the CVS archive.
Free CVS clients can be downloaded from www.cyclic.com.  The latest version
of JPL in CVS has been updated to operate with Sun's JDK 1.3.  If you don't
have a Java Developer's Kit (JDK) installed, download one from www.javasoft.com.

You can check out the latest version of JPL with the following CVS settings:

  set CVSROOT=:pserver:anoncvs@as220.org:/home/cvsroot
  cvs login    # use blank password
  cvs checkout jpl

You can check out the previous version of JPL with the following CVS settings:

  export CVSROOT=:pserver:anoncvs@as220.org:/home/cvsroot
  cvs login    # use blank password
  cvs checkout -rsnap-10212000 jpl

1.1.2 PPM VERSION
=================
I have created a PPM installable version of JPL and hosted it at:

http://www.erols.com/theroths/perl_stuff.html

This version was created on NT 4, using JDK 1.3 and Perl 5.6.  You can install it
by typing:

  ppm install JPL-Class.ppd
  ppm install JNI.ppd
  
1.2 INSTALL JPL
===============
Follow the directions packaged with JPL to install it.  We are particularlly
interested in the JNI (Java Native Interface) portion of the installation.
I will warn you, this install is not trivial!  Make sure you set jpldebug = 0
in the JNI.xs file or you will get lots of debug stuff on STDOUT.

2. DM_CASTER
============
The dm_Caster java file included with DFC.pm must be compiled and installed in
the same directory as DFC.pm.  To compile it, type:

  javac dm_Caster

Examine this java file -- you may need/want to modify it.  It's purpose is to cast
IDfPersistentObjects to subtypes.  For example, to create a new dm_document, the
DFC forces you to create a DfPersistentObject and then cast it to an IDfDocument.

In Java:

  IDfDocument document = null;
  document =(IDfDocument)session.newObject("dm_document");
  document.setObjectName( "doc1" );

This type of casting is not possible in Perl, yet is necessary because the setObjectName
method is only available through the IDfDocument interface.  session.newObject() returns
an IDfPersistentObject by default, regardless of what object type you pass to it.

In Perl:

  $doc = $session->newObject("dm_document");
  $doc = castToIDfDocument($doc);
  $doc->setObjectName("doc1");

castToIDfDocument is a method of dm_Caster.  A dm_Caster is instantiate automatically by
DFC.pm and makes all of its "cast" methods avialble through the dm_Caster object.  This is
awkward but mirrors the java implementation of the DFC.

3. DFC.PM
=========
The DFC.pm consists of 86 perl module (.pm) files.

3.1 INSTALL DFC.PM
==================
After installing JPL, to the usual to install Db::DFC:
  perl makefile.pl
  nmake
  nmake test  (** you will need to edit the test script to insert your Docbase, user and password)
  nmake install
  
3.2 USING DFC.PM
================
To use DFC.PM, simply use it in your Perl program.

Example:

  use DFC;
  $dfclient = DfClient->new();
  $client = $dfclient->getLocalClient();

  $logininfo = DfLoginInfo->new();
  $logininfo->setUser('user');
  $logininfo->setPassword('password');
  $logininfo->setDomain('DOMAIN');

  $DOCBASE="X";
  $session = $client->newSession($DOCBASE,$logininfo);

  $query = DfQuery->new();
  $query->setDQL("select object_name from dm_document where owner_name = user");
  $col = $query->execute($session,0);
  while ($col->next()) {
      my $row = $col->getTypedObject();
      print $row->getString("object_name") . "\n";
  }

  $col->close();
  $session->disconnect();

3.3 OBJECT/METHOD SUMMARY
=========================
A summary of the objects and methods implemented by this version of DFC.pm can
be found in the perl-dfc.html file included with this archive.  This module was
created with DFC v4.1.0.59.  Most classes and methods have been implemented.  

3.4 KNOWN ISSUES
================
The only real issue I know of right now is the inability to catch the Java exceptions
thrown by Documentum.  I'm working on this but it might take a change to JPL to
actually make it happen.

4.0 SUPPORT
===========
DFC.pm is authored and support by me, M. Scott Roth (michael.s.roth@saic.com).  Please
feel free to contact me.