DUMP AND LOAD A DOCBASE

http://www.bluefishgroup.com/library/2003/dump-and-load-a-docbase/
December 21, 2003 - Article by Richard Rans

A brief introduction to the concepts of Documentum’s dump and load feature, as well as an example of performing a dump and load.
– Table of Contents

    * Introduction
    * How to Perform a Dump
    * How to Perform a Load
    * Fundamental Concepts
    * What if I Have a Problem

Introduction

Dump and load is a feature built into Documentum. It allows you to take the entire contents of your docbase, and write them out to a single file. This can be done not only for content, but for users, groups, acls, etc. The file that gets written out is in a proprietary format, so the only thing you can do with it is load it into another docbase, thus “dump and load”. However, this feature is often used for:

    * Backing up your docbase (although you will still probably want a more reliable backup process, like a file system backup).
    * Moving or copying your docbase to a new machine or environment (ie, creating a test docbase from your production docbase).
    * It is also frequently the recommended upgrade path when moving to a new version of Documentum’s server product.

How to Perform a Dump

The most common method for performing this is using Documentum’s API interface. On the server that Documentum is installed you will find a file called iapi32.exe. Look in your Documentum server directory under product\4.x\bin. Run this application from a DOS window. It will prompt you for the docbase you wish to connect to, as well as a username and password. Connect to the docbase you wish to dump.

You will soon be at an api command prompt. From this prompt, you can issue any of Documentum’s api commands. In this case we will be issueing the command to create a dump file from the docbase you are currently connected to. In most cases, the following set of commands will dump all of your relevant information out of your docbase. It will extract all of your content objects (and their content), as well as your formats and users:

               
create,c,dm_dump_record
set,c,l,file_name
c:\temp\adump.new
set,c,l,include_content
T


append,c,l,type
dm_sysobject
append,c,l,predicate
1=1

append,c,l,type
dm_format
append,c,l,predicate
1=1

append,c,l,type
dm_user
append,c,l,predicate
1=1

save,c,l
getmessage,c

           

This script dumpts all dm_sysobject objects, dm_format objects, and dm_user objects from you docbase. Also the content of these objects will be included. You will notice that for each object type we append a predicate of “1=1″. Since the predicate is required, this is a way of tricking Documentum into exporting all objects. You could have used other criteria, such as:

    * object_name=’abcd1′
    * folder(’/abcd1′,descend)

Once the dump is complete, you will have a file c:\temp\adump.new that contains all of your docbase information. This file can then be loaded into a new docbase of your choice.

There are additional DFC classes and methods that support XML in Documentum Applications (IDfXMLDocType, DfXmlQuery) that this article doesn’t address, but that hopefully future articles will.
How to Perform a Load

The load process is very similar to the dump process. First, you will probably want to create a brand new docbase. It is possible to load into an existing docbase, but depending on what is in your dump file, you may end up with conflicts in your docbase. You will then want to move your dump file onto the same server as your new docbase (in our case, adump.new). This will reduce network traffic and speed up your load process.

The first step in actually performing the load, is to run “preload”. This is another utility program that should be located on your Documentum server. It can be executed from the following command line:

                preload -dump_file -script_file -U -P

           

This performs several checks on your docbase. It may produce a script that you will need to modify and run. If so, the script is well commented and tells you what edits to make. Next, run the iapi32 application again, this time connecting to your new docbase. The following script, when executed, will perform the load process.

               
create,c,dm_load_record
set,c,l,file_name
c:\temp\adump.new
save,c,l

           

Fundamental Concepts

When attempting a dump and load process, there are certain concepts you should understand during the process:

    * A dump operation will perform a series of Documentum calls. Each of these calls, in turn, make calls to the underlying database and retrievals from your Documentum filestore(s). This may put unusual strain on your servers. You should be prepared for this and perform you dump and loads during periods when users are not accessing the system. In addition, you need to make sure you have adequate space allocated in your database log and redo files.
    * Documentum does not overwrite objects during the load process. It is therefore possible that you will have duplicate objects in you docbase after a load. This is common for generic objects that are created with every docbase (such as templates). It can also occur if you perform two loads from dump files that contain the same objects. There is no real way to avoid this. Your only option is to manually delete the unwanted duplicates.
    * In our example, we specified how to set parameters on what objects are dummped from your source docbase. if you intend to perform a full docbase dump, it is recommended that you use the following syntax:

                             
      set c,l,dump_operation
      full_docbase_dump

                         

    * Registered tables are not included in your dump (or load) process. You must manually move and re-register these in your new docbase.

What if I Have a Problem

Occasionally dump or the load will fail. That is why this isn’t the most highly recommended way to perform docbase backups. A detail description of all of the ways to fix a broken dump and load is out of scope of this document. Your best bet is to contact Documentum’s technical support or your system’s integrator. That being said, here as some of the things that you can expect to hear, or that may be causing your problem:

    * Did you perform dmclean prior to creating your dump file? This may clean up your docbase and fixes many dump and load issues. See your adminstrators guide for more details.
    * Do you have a single folder with thousands of objects in it? Dump and load frequently has problems if there are a tremendous number of documents in a single folder. Try deleting some of your documents that are no longer required, and re-do your dump file. Or, you my be able to execute multiple dumps into separate files by setting a different predicate each time.
    * Do you have a single object with thousands of versions? This is common with some of Documentum’s automatically created report files. If you can clean up those objects, it may resolve your issue. You can also configure Documentum to not create or save those reports as frequently. See your adminstrators guide for more details.
    * Are you performing a full docbase dump. If not, you may be experiencing a relationship integrity problem. Try a full docbase dump and see if that resolves your issue.
    * Add a trace command to your dump script: “apply,c,NULL,SQL_TRACE,LEVEL,I,1″. This may provide some clues as to why the dump is failing.
    * Frequently, due to the amount of database activity occuring, your database log files may fill up. You can work with your DBA to increase the size of these files, or even reduce logging during the process.
    * Do both of your docbases have the same docbase ID? If so, your load process will fail.
    * You have the option of reverting or restarting a load process. To do this, you must make note of the load’s object ID. This object ID will be displayed immediately after you enter the “create,c,dm_load_record” command. To revert the load, issue the following command:

                             
      fetch,c,{loadobjectID}
      revert,c,l   (or issue save,c,l to restart the load)