Introduction

There are four basic options when it comes to moving a docbase:

• Documentum dump and load
• Third party move applications
• Complete file system move
• Database extract and Docbase content move

Each method has its advantages, disadvantages and constraints. Here is a general listing of things you should consider when planning your docbase move.

Dump and Load

This is the most standard and highly recommended way to perform a docbase move. It is Documentum’s built in functionality for extracting all of a docbase’s meta-data and content files to a single file system file (a dump file). This file can then be loaded into the docbase of choice. The process itself is well documented in the Documentum eContent Server Administrator’s Guide – Dumping and Loading a Docbase.

Occasionally, you will not be able to dump and load a docbase. Sometimes this is due to a known documented constraint in the dump and load process (such as a 2 gig limit). In other instances, the dump and load process just simply fails. Documentum support can often help you through these situations, as well as performing some database maintenance tasks such as running dm_clean. If that fails, or for other reasons, you may want to look at some of the other options for moving a docbase.

The advantages of dump and load are that it is a simple and highly effective way of moving a docbase. It turns your entire docbase into a single file that can be easily moved or archived. Some of the disadvantages are that it has some known limitations, and on occasion fails to complete the dump or the load process. It also can be slower than some of the other methods because it writes the docbase to a proprietary formats, and then reads from that when it loads back into the docbase.

Third Party Migration Utilities

There are some existing and it is possible to create your own utilities for moving a docbase. At Blue Fish, we have created a utility like this called DIXI – Documentum Import eXport Interface. The advantages and disadvantages of these tools will obviously vary depending on what you select. However, there are some common constraints that can’t be worked around:

• They will modify your documents r_modifier and r_modified_date attributes. They may also change the document owner. This is because they usually make a connection to your new docbase as dmadmin and import the files using that connection. Also, Documentum does not provide them with a means to go back and manually set these system attributes, therefore, they are automatically set when the utility performs the import into the new docbase.
• Additional cost. Needless to say, these tools are not included in your basic Documentum installation, and therefore include additional licensing or service costs.

File System Backup and Restore

This method, is simply a file system backup and restore of your database and Documentum files. This is a quick and effective method if you have system administrators who are capable of perform the file transfer. However, it has a couple limitations:

• It copies your install as is to the new location. Therefore, if you were trying to somehow modify your Documentum or your Oracle install in the new location, this method limits your ability to do that.
• It moves all databases and docbases within your Documentum and your database install. For example, if you had multiple docbases sharing a single Oracle database, this method would require you to move all of those docbases.
• It requires some technical skill in restoring the backed up files to the new location. For example, in an NT environment, both Documentum and your database will write key information to the system registry. This information would need to exist in your new location as well.

Database extract and Docbase content move

This method is to extract the database data that is relevant to your docbase, and load it into the database in your target location. It also requires you to move the docbase content file to the new location. This has the advantage of allowing you to move only the specific docbase you want into a new installation. The limitations include that it is not recommended for moving into an environment where your database or your docbase are different versions than the original (although that may work in some instances). Also, not all databases are equal in their support of extracting and moving a piece of a database. In this example, we will show how to move a docbase in Oracle.

USING TABLESPACE_TRANSPORT TO MOVE AN ORACLE DOCBASE

This example takes you through the process of moving an Oracle based docbase. For simplicity, it assumes basically a default installation of Oracle and Documentum. It assumes Oracle Enterprise Edition, and that your docbase is installed into its own Oracle tablespace. The example walks through the process of a Documentum 4.2.1 install, using Oracle 8.1.6 on a Windows NT platform. However the process will be similar for other environments, and for additional information, the process is well documented in the Oracle 8i Backup and Recovery Guide.

Example Moving an Oracle Docbase

Preparing your database:

This process requires the use of Oracles import and export utilities. To enable these, your must run the catexp.sql or catalog.sql scripts. This can be done from a Dos command line by running:
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>sqlplus internal/oracle @catexp.sql

Once your database is prepared, perform the following steps:

Step 1: Stop your docbase.

Step 2: Set docbase’s tablespace to read-only.

To determine the name of the tablespaces your docbase uses, issue the following select:


SELECT tablespace_name, file_name
FROM sys.dba_data_files
WHERE tablespace_name like '%yourdocbasename%';

The result should look like DM_YOURDOCBASENAME_DOCBASE and DM_YOURDOCBASENAME_INDEX. You can then set the tablespaces to read only by issues the following SqlPlus statement:

alter tablespace TABLESPACENAME READ ONLY

Step 3: Export the tablespace information for your docbase

The purpose of this, is to package up the information on your tablespaces so that they can be moved to a new database. You can first run a double check to ensure that your tablespaces are tansportable. In a standard documentum install, they should be, however, a check can be performed by, while logged in as internal, run the following command from SqlPlus:

execute dbms_tts.transport_set_check('yourtablespacename1,yourtablespacename2', TRUE)

Then perform a select:

select * from transport_set_violations;

If this select returns no rows, then your tablespaces are valid for export. If rows exist, then you either need to fix the dependency or use one of the other methods to move your docbase.

The following command will actually perform the export. In this example, the docbase information is stored in two tablespaces: dm_docbasename_docbase and dm_docbasename_index. You can run the following command from a DOS command line where Oracle is installed:

EXP TRANSPORT_TABLESPACE=y TABLESPACES=dm_docbasename_docbase,dm_docbasename_idnex TRIGGERS=y CONSTRAINTS=y GRANTS=y FILE=yourdocbase.dmp

Logon as system/manager, and then watch as the export is performed. It should end with “Export terminated successfully without warnings.”

Step 4: Copy the tablespace data files to a safe location

These files will be located in a directory somewhere within your Oracle install. You can get the exact file names from the query:

SELECT file_name
FROM sys.dba_data_files
WHERE tablespace_name like '%yourdocbasename%';

Step 5: Copy the Documentum data files to a safe location

These files will be located on the Documentum server in a directory that looks like:

DCTM_Serverdatayourdocbasename

Copy the directory and its subdirectories to a safe location. This contains the actual content files for your docbase.

Step 6: Create docbase in target environment

This docbase will serve as the shell that you will move your docbase into. The docbase you create should have the same name and docbase Id as your original docbase.

Step 7: Move your original tablespace into your new database

To do this, perform the following steps:

1. Stop the new docbase you created in the previous step.
2. Drop the tablespace for the docbase. This can be done running the following commands from SqlPlus:
   DROP TABLESPACE DM_yourdocbasename_docbase including contents;
DROP TABLESPACE DM_yourdocbasename_index including contents;
   And then delete the .DBF files for your docbase’s tablespace from your Oracle data directory.
3. Copy the datafiles you saved from your original docbase into the data directory of your new Oracle install.
4. Load the original datafiles into your new database. This is done using Oracle’s import utility. You should be able to do this by running something like the following command from a Dos command prompt:

   imp transport_tablespace=y datafiles='originaldatafilename1','originaldatafilename2'

   My command looked like:

   imp transport_tablespace=y
datafiles='e:oracleoradataunkindDM_TESTDOCBASE062901_080326_DB1.DBF',
'e:oracleoradataunkindDM_TESTDOCBASE062901_080326_IND1.DBF'

   Logon as system/manager and when prompted, identify the extract file you created during the tablespace export of your original docbase. In my case, this was xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>e:testdocbase.dmp.
   A common error that may occur at this point is:

   IMP-00003 Oracle error 6550 encountered
ORA-06550 Line 1 Column 7:
PLS-00201 identifier 'DBMS_PLUGTS.NEWTABLESPACE' must be declared.
ORA-06550 Line 1 Column 7:

   In this case you must create a public synonym dbms_plugts for dbms_plugts.

5. Reset the tablespaces you just imported to read/write. This should be done using SqlPlus commands similar to the following:
   

   Introduction
   

   There are four basic options when it comes to moving a docbase:

   • Documentum dump and load
   • Third party move applications
   • Complete file system move
   • Database extract and Docbase content move

   Each method has its advantages, disadvantages and constraints. Here is a general listing of things you should consider when planning your docbase move.

   Dump and Load
   

   This is the most standard and highly recommended way to perform a docbase move. It is Documentum’s built in functionality for extracting all of a docbase’s meta-data and content files to a single file system file (a dump file). This file can then be loaded into the docbase of choice. The process itself is well documented in the Documentum eContent Server Administrator’s Guide – Dumping and Loading a Docbase.

   Occasionally, you will not be able to dump and load a docbase. Sometimes this is due to a known documented constraint in the dump and load process (such as a 2 gig limit). In other instances, the dump and load process just simply fails. Documentum support can often help you through these situations, as well as performing some database maintenance tasks such as running dm_clean. If that fails, or for other reasons, you may want to look at some of the other options for moving a docbase.

   The advantages of dump and load are that it is a simple and highly effective way of moving a docbase. It turns your entire docbase into a single file that can be easily moved or archived. Some of the disadvantages are that it has some known limitations, and on occasion fails to complete the dump or the load process. It also can be slower than some of the other methods because it writes the docbase to a proprietary formats, and then reads from that when it loads back into the docbase.

   Third Party Migration Utilities
   

   There are some existing and it is possible to create your own utilities for moving a docbase. At Blue Fish, we have created a utility like this called DIXI – Documentum Import eXport Interface. The advantages and disadvantages of these tools will obviously vary depending on what you select. However, there are some common constraints that can’t be worked around:

   • They will modify your documents r_modifier and r_modified_date attributes. They may also change the document owner. This is because they usually make a connection to your new docbase as dmadmin and import the files using that connection. Also, Documentum does not provide them with a means to go back and manually set these system attributes, therefore, they are automatically set when the utility performs the import into the new docbase.
   • Additional cost. Needless to say, these tools are not included in your basic Documentum installation, and therefore include additional licensing or service costs.

   File System Backup and Restore
   

   This method, is simply a file system backup and restore of your database and Documentum files. This is a quick and effective method if you have system administrators who are capable of perform the file transfer. However, it has a couple limitations:

   • It copies your install as is to the new location. Therefore, if you were trying to somehow modify your Documentum or your Oracle install in the new location, this method limits your ability to do that.
   • It moves all databases and docbases within your Documentum and your database install. For example, if you had multiple docbases sharing a single Oracle database, this method would require you to move all of those docbases.
   • It requires some technical skill in restoring the backed up files to the new location. For example, in an NT environment, both Documentum and your database will write key information to the system registry. This information would need to exist in your new location as well.

   Database extract and Docbase content move
   

   This method is to extract the database data that is relevant to your docbase, and load it into the database in your target location. It also requires you to move the docbase content file to the new location. This has the advantage of allowing you to move only the specific docbase you want into a new installation. The limitations include that it is not recommended for moving into an environment where your database or your docbase are different versions than the original (although that may work in some instances). Also, not all databases are equal in their support of extracting and moving a piece of a database. In this example, we will show how to move a docbase in Oracle.

   USING TABLESPACE_TRANSPORT TO MOVE AN ORACLE DOCBASE

   This example takes you through the process of moving an Oracle based docbase. For simplicity, it assumes basically a default installation of Oracle and Documentum. It assumes Oracle Enterprise Edition, and that your docbase is installed into its own Oracle tablespace. The example walks through the process of a Documentum 4.2.1 install, using Oracle 8.1.6 on a Windows NT platform. However the process will be similar for other environments, and for additional information, the process is well documented in the Oracle 8i Backup and Recovery Guide.

   Example Moving an Oracle Docbase

   Preparing your database:

   This process requires the use of Oracles import and export utilities. To enable these, your must run the catexp.sql or catalog.sql scripts. This can be done from a Dos command line by running:
   xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>sqlplus internal/oracle @catexp.sql

   Once your database is prepared, perform the following steps:

   Step 1: Stop your docbase.

   Step 2: Set docbase’s tablespace to read-only.

   To determine the name of the tablespaces your docbase uses, issue the following select:

   
SELECT tablespace_name, file_name
FROM sys.dba_data_files
WHERE tablespace_name like '%yourdocbasename%';

   The result should look like DM_YOURDOCBASENAME_DOCBASE and DM_YOURDOCBASENAME_INDEX. You can then set the tablespaces to read only by issues the following SqlPlus statement:

   alter tablespace TABLESPACENAME READ ONLY

   Step 3: Export the tablespace information for your docbase

   The purpose of this, is to package up the information on your tablespaces so that they can be moved to a new database. You can first run a double check to ensure that your tablespaces are tansportable. In a standard documentum install, they should be, however, a check can be performed by, while logged in as internal, run the following command from SqlPlus:

   execute dbms_tts.transport_set_check('yourtablespacename1,yourtablespacename2', TRUE)

   Then perform a select:

   select * from transport_set_violations;

   If this select returns no rows, then your tablespaces are valid for export. If rows exist, then you either need to fix the dependency or use one of the other methods to move your docbase.

   The following command will actually perform the export. In this example, the docbase information is stored in two tablespaces: dm_docbasename_docbase and dm_docbasename_index. You can run the following command from a DOS command line where Oracle is installed:

   EXP TRANSPORT_TABLESPACE=y TABLESPACES=dm_docbasename_docbase,dm_docbasename_idnex TRIGGERS=y CONSTRAINTS=y GRANTS=y FILE=yourdocbase.dmp

   Logon as system/manager, and then watch as the export is performed. It should end with “Export terminated successfully without warnings.”

   Step 4: Copy the tablespace data files to a safe location

   These files will be located in a directory somewhere within your Oracle install. You can get the exact file names from the query:

   SELECT file_name
FROM sys.dba_data_files
WHERE tablespace_name like '%yourdocbasename%';

   Step 5: Copy the Documentum data files to a safe location

   These files will be located on the Documentum server in a directory that looks like:

   DCTM_Serverdatayourdocbasename

   Copy the directory and its subdirectories to a safe location. This contains the actual content files for your docbase.

   Step 6: Create docbase in target environment

   This docbase will serve as the shell that you will move your docbase into. The docbase you create should have the same name and docbase Id as your original docbase.

   Step 7: Move your original tablespace into your new database

   To do this, perform the following steps:

   1. Stop the new docbase you created in the previous step.
   2. Drop the tablespace for the docbase. This can be done running the following commands from SqlPlus:
      DROP TABLESPACE DM_yourdocbasename_docbase including contents;
DROP TABLESPACE DM_yourdocbasename_index including contents;
      And then delete the .DBF files for your docbase’s tablespace from your Oracle data directory.
   3. Copy the datafiles you saved from your original docbase into the data directory of your new Oracle install.
   4. Load the original datafiles into your new database. This is done using Oracle’s import utility. You should be able to do this by running something like the following command from a Dos command prompt:

      imp transport_tablespace=y datafiles='originaldatafilename1','originaldatafilename2'

      My command looked like:

      imp transport_tablespace=y
datafiles='e:oracleoradataunkindDM_TESTDOCBASE062901_080326_DB1.DBF',
'e:oracleoradataunkindDM_TESTDOCBASE062901_080326_IND1.DBF'

      Logon as system/manager and when prompted, identify the extract file you created during the tablespace export of your original docbase. In my case, this was xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>e:testdocbase.dmp.
      A common error that may occur at this point is:

      IMP-00003 Oracle error 6550 encountered
ORA-06550 Line 1 Column 7:
PLS-00201 identifier 'DBMS_PLUGTS.NEWTABLESPACE' must be declared.
ORA-06550 Line 1 Column 7:

      In this case you must create a public synonym dbms_plugts for dbms_plugts.

   5. Reset the tablespaces you just imported to read/write. This should be done using SqlPlus commands similar to the following:

      Alter tablespace dm_yourdocbasename_docbase read write
      Alter tablespace dm_yourdocbasename_index read write

   Step 8: Move your original content files into the Documentum data directory

   This is done by simply replacing the current DCTM_ServerDatayourdocbasename with the files you saved from your original docbase.

   Step 9: Restart the new docbase.

   Introduction
   

   There are four basic options when it comes to moving a docbase:

   • Documentum dump and load
   • Third party move applications
   • Complete file system move
   • Database extract and Docbase content move

   Each method has its advantages, disadvantages and constraints. Here is a general listing of things you should consider when planning your docbase move.

   Dump and Load
   

   This is the most standard and highly recommended way to perform a docbase move. It is Documentum’s built in functionality for extracting all of a docbase’s meta-data and content files to a single file system file (a dump file). This file can then be loaded into the docbase of choice. The process itself is well documented in the Documentum eContent Server Administrator’s Guide – Dumping and Loading a Docbase.

   Occasionally, you will not be able to dump and load a docbase. Sometimes this is due to a known documented constraint in the dump and load process (such as a 2 gig limit). In other instances, the dump and load process just simply fails. Documentum support can often help you through these situations, as well as performing some database maintenance tasks such as running dm_clean. If that fails, or for other reasons, you may want to look at some of the other options for moving a docbase.

   The advantages of dump and load are that it is a simple and highly effective way of moving a docbase. It turns your entire docbase into a single file that can be easily moved or archived. Some of the disadvantages are that it has some known limitations, and on occasion fails to complete the dump or the load process. It also can be slower than some of the other methods because it writes the docbase to a proprietary formats, and then reads from that when it loads back into the docbase.

   Third Party Migration Utilities
   

   There are some existing and it is possible to create your own utilities for moving a docbase. At Blue Fish, we have created a utility like this called DIXI – Documentum Import eXport Interface. The advantages and disadvantages of these tools will obviously vary depending on what you select. However, there are some common constraints that can’t be worked around:

   • They will modify your documents r_modifier and r_modified_date attributes. They may also change the document owner. This is because they usually make a connection to your new docbase as dmadmin and import the files using that connection. Also, Documentum does not provide them with a means to go back and manually set these system attributes, therefore, they are automatically set when the utility performs the import into the new docbase.
   • Additional cost. Needless to say, these tools are not included in your basic Documentum installation, and therefore include additional licensing or service costs.

   File System Backup and Restore
   

   This method, is simply a file system backup and restore of your database and Documentum files. This is a quick and effective method if you have system administrators who are capable of perform the file transfer. However, it has a couple limitations:

   • It copies your install as is to the new location. Therefore, if you were trying to somehow modify your Documentum or your Oracle install in the new location, this method limits your ability to do that.
   • It moves all databases and docbases within your Documentum and your database install. For example, if you had multiple docbases sharing a single Oracle database, this method would require you to move all of those docbases.
   • It requires some technical skill in restoring the backed up files to the new location. For example, in an NT environment, both Documentum and your database will write key information to the system registry. This information would need to exist in your new location as well.

   Database extract and Docbase content move
   

   This method is to extract the database data that is relevant to your docbase, and load it into the database in your target location. It also requires you to move the docbase content file to the new location. This has the advantage of allowing you to move only the specific docbase you want into a new installation. The limitations include that it is not recommended for moving into an environment where your database or your docbase are different versions than the original (although that may work in some instances). Also, not all databases are equal in their support of extracting and moving a piece of a database. In this example, we will show how to move a docbase in Oracle.

   USING TABLESPACE_TRANSPORT TO MOVE AN ORACLE DOCBASE

   This example takes you through the process of moving an Oracle based docbase. For simplicity, it assumes basically a default installation of Oracle and Documentum. It assumes Oracle Enterprise Edition, and that your docbase is installed into its own Oracle tablespace. The example walks through the process of a Documentum 4.2.1 install, using Oracle 8.1.6 on a Windows NT platform. However the process will be similar for other environments, and for additional information, the process is well documented in the Oracle 8i Backup and Recovery Guide.

   Example Moving an Oracle Docbase

   Preparing your database:

   This process requires the use of Oracles import and export utilities. To enable these, your must run the catexp.sql or catalog.sql scripts. This can be done from a Dos command line by running:
   xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>sqlplus internal/oracle @catexp.sql

   Once your database is prepared, perform the following steps:

   Step 1: Stop your docbase.

   Step 2: Set docbase’s tablespace to read-only.

   To determine the name of the tablespaces your docbase uses, issue the following select:

   
SELECT tablespace_name, file_name
FROM sys.dba_data_files
WHERE tablespace_name like '%yourdocbasename%';

   The result should look like DM_YOURDOCBASENAME_DOCBASE and DM_YOURDOCBASENAME_INDEX. You can then set the tablespaces to read only by issues the following SqlPlus statement:

   alter tablespace TABLESPACENAME READ ONLY

   Step 3: Export the tablespace information for your docbase

   The purpose of this, is to package up the information on your tablespaces so that they can be moved to a new database. You can first run a double check to ensure that your tablespaces are tansportable. In a standard documentum install, they should be, however, a check can be performed by, while logged in as internal, run the following command from SqlPlus:

   execute dbms_tts.transport_set_check('yourtablespacename1,yourtablespacename2', TRUE)

   Then perform a select:

   select * from transport_set_violations;

   If this select returns no rows, then your tablespaces are valid for export. If rows exist, then you either need to fix the dependency or use one of the other methods to move your docbase.

   The following command will actually perform the export. In this example, the docbase information is stored in two tablespaces: dm_docbasename_docbase and dm_docbasename_index. You can run the following command from a DOS command line where Oracle is installed:

   EXP TRANSPORT_TABLESPACE=y TABLESPACES=dm_docbasename_docbase,dm_docbasename_idnex TRIGGERS=y CONSTRAINTS=y GRANTS=y FILE=yourdocbase.dmp

   Logon as system/manager, and then watch as the export is performed. It should end with “Export terminated successfully without warnings.”

   Step 4: Copy the tablespace data files to a safe location

   These files will be located in a directory somewhere within your Oracle install. You can get the exact file names from the query:

   SELECT file_name
FROM sys.dba_data_files
WHERE tablespace_name like '%yourdocbasename%';

   Step 5: Copy the Documentum data files to a safe location

   These files will be located on the Documentum server in a directory that looks like:

   DCTM_Serverdatayourdocbasename

   Copy the directory and its subdirectories to a safe location. This contains the actual content files for your docbase.

   Step 6: Create docbase in target environment

   This docbase will serve as the shell that you will move your docbase into. The docbase you create should have the same name and docbase Id as your original docbase.

   Step 7: Move your original tablespace into your new database

   To do this, perform the following steps:

   1. Stop the new docbase you created in the previous step.
   2. Drop the tablespace for the docbase. This can be done running the following commands from SqlPlus:
      DROP TABLESPACE DM_yourdocbasename_docbase including contents;
DROP TABLESPACE DM_yourdocbasename_index including contents;
      And then delete the .DBF files for your docbase’s tablespace from your Oracle data directory.
   3. Copy the datafiles you saved from your original docbase into the data directory of your new Oracle install.
   4. Load the original datafiles into your new database. This is done using Oracle’s import utility. You should be able to do this by running something like the following command from a Dos command prompt:

      imp transport_tablespace=y datafiles='originaldatafilename1','originaldatafilename2'

      My command looked like:

      imp transport_tablespace=y
datafiles='e:oracleoradataunkindDM_TESTDOCBASE062901_080326_DB1.DBF',
'e:oracleoradataunkindDM_TESTDOCBASE062901_080326_IND1.DBF'

      Logon as system/manager and when prompted, identify the extract file you created during the tablespace export of your original docbase. In my case, this was xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>e:testdocbase.dmp.
      A common error that may occur at this point is:

      IMP-00003 Oracle error 6550 encountered
ORA-06550 Line 1 Column 7:
PLS-00201 identifier 'DBMS_PLUGTS.NEWTABLESPACE' must be declared.
ORA-06550 Line 1 Column 7:

      In this case you must create a public synonym dbms_plugts for dbms_plugts.

   5. Reset the tablespaces you just imported to read/write. This should be done using SqlPlus commands similar to the following:

      Alter tablespace dm_yourdocbasename_docbase read write
      Alter tablespace dm_yourdocbasename_index read write

   Step 8: Move your original content files into the Documentum data directory

   This is done by simply replacing the current DCTM_ServerDatayourdocbasename with the files you saved from your original docbase.

   Step 9: Restart the new docbase.

   Alter tablespace dm_yourdocbasename_docbase read write
Alter tablespace dm_yourdocbasename_index read write

Step 8: Move your original content files into the Documentum data directory

This is done by simply replacing the current DCTM_ServerDatayourdocbasename with the files you saved from your original docbase.

Step 9: Restart the new docbase.