EMC Documentum Dump and Load Technical Details and Troubleshooting

Transcription

1 EMC Documentum Dump and Load Technical Details and Troubleshooting A Detailed Review Abstract This white paper is intended to help users understand the EMC Documentum dump and load utility and troubleshoot problems encountered when using it. August 2007

2 Copyright 2007 EMC Corporation. All rights reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com All other trademarks used herein are the property of their respective owners. Part Number H2926 A Detailed Review 2

3 Table of Contents Executive summary...4 Introduction...4 Audience... 4 Key features...4 Dump...4 Which objects are dumped?... 5 Prerequisites to run dump... 5 Sample script to dump the whole repository... 5 Dumping a partial repository... 6 Tracing the dump... 6 Preload...7 Load...7 Before you perform the load... 7 Sample script to load... 7 Frequently asked questions...8 Conclusion...9 A Detailed Review 3

4 Executive summary The EMC Documentum dump and load utility let you copy a full or partial repository, including content from one machine to another. As with any migration across platforms or different databases, the utility helps keep the Documentum data integrity intact. Most businesses need to test their upgrades on a copy repository prior to their actual production in-place upgrades. When trying to move a repository to a different database, dump and load is the best option. Introduction This white paper is intended to help users understand the Documentum dump and load process and troubleshoot problems encountered when using dump and load. It provides information about dump and load, tips and tricks, and best practices. For complete technical information on dump and load, please refer to the EMC Documentum Content Server Version 5.3 SP 3 Release Notes and the EMC Documentum Administrator Version 5.3 SP 1 User Guide. Dump and load is not recommended or made for use as an alternate to a backup and restore utility. Audience This white paper is intended for repository administrators and developers who intend to copy or move full or partial repositories. It also gives them a baseline overview of how dump and load works, and will help them choose a custom predicate for their custom dump s requirement. This white paper is not intended to assist developers who are writing custom scripts. In addition, this paper is not intended to help administrators with troubleshooting their database issues prior to or after a dump and load. Readers should consult their database administrators for any database issue prior to or during the dump and load process. Key features Dump and load utilities provide users the ability to copy or move their repository from one machine to another machine or onto the same machine. You can copy a partial repository, that is, a folder, a cabinet, document of a particular type and so on. You can also do the following with dump and load utilities: Copy a repository Move a repository from one location to another Archive a repository Duplicate or move a partial repository Work on cross-platforms Work on cross-databases Enable dump with/without content Dump A dump occurs by creating a dump record object and issuing a Save API on this dump record. The dump creates a dump file that is in binary format. The dump file size depends on how the dump script looks like. By default, the dump file contains only metadata so the dump contains only the reference to the content file, but if you add to include the content parameter in the dump script then the dump file size will be bigger since it includes the content and metadata. A Detailed Review 4

5 Note: Only a Superuser can perform the dump. Which objects are dumped? Extra objects are dumped along with the objects that you are trying to dump. Let s say you are dumping a dm_document. Then the following objects will also be dumped: The object itself (type dm_document) The associated content object (dmr_content) The user who owns the document (dm_user) The group to which that user belongs (dm_group), excluding other users All folders or cabinets that the document is linked in to (dm_folder, dm_cabinet) The filestore in which the content is located (dm_filestore) The format of the document (dm_format) Referential objects such as dmr_containment, if it is a virtual document component Prerequisites to run dump The following prerequisites are recommended: Run the Consistency Checker job and remove all inconsistencies reported. Run the dmclean job. Check in all the checked-out documents. Clean unwanted document versions or renditions. Clean old log files by the dm_logpurge job. Ensure that there is enough disk space to accommodate the dump file. Sample script to dump the whole repository Use the following sample script to dump the whole repository: create,c,dm_dump_record set,c,l,file_name c:\temp\dumpfile.dmp set,c,l,dump_operation full_docbase_dump set,c,l,include_content T save,c,l getmessage,c You can run all these API commands one by one or run them as a script with the following command on the command prompt: D:\> iapi source_db -Uusername -Ppassword < script_filename Make sure that there are no blank spaces at the end of each line. The dump file is a binary file and can have any extension such as.dmp,.txt, or others. If the Include_content parameter is set to True then content will be added to the dump file; otherwise the dump file will contain only metadata. Usually the approximate dump file size is the size of the database data plus the content. Setting include_content to False results in a A Detailed Review 5

6 smaller dump file size and a slightly faster dump. If the source and target repositories are on the same machine then use include_content to F. Run a count on dm_sysobject, dm_document, dmr_content, dm_user, and dm_group before you perform the dump. Dumping a partial repository Use the following rules when dumping a partial repository: If you include a supertype, then objects of this supertype and its subtypes will be dumped. Type definitions are also dumped. If a subtype doesn t have any objects, then a subtype definition is not dumped unless you specify that type in the dump script. Custom types with no supertypes need an entry in the dump script. ACLs not associated with objects will not be dumped unless they have an entry in the dump script. The following shows how to describe the custom type in the dump script: append,c,l,type your_type_name append,c,l,predicate 1=1 1=1 means all objects of your custom type. To dump a smaller set you can use the WHERE clause in the predicate attribute. The predicate has a maximum character size limit of 255. However, when you dump an object, the server includes any objects referenced by the dumped object. This process is recursive, so the resulting dump file can contain many more objects than the object specified in the type, predicate, and predicate2 repeating attributes of the dump record. For example, for dumping objects under a single cabinet, you can use the following predicate: append,c,l,type dm_sysobject append,c,l,predicate folder('/<name of the cabinet>',descend) Tracing the dump You can do a different kind of tracing on the dump and load process by doing the following: API > trace,session,severity_level,logfile The following severity levels can be used: 8, Dump and load object information 10, Timing information; commits after every loaded object 11, Load operation information You can also do a SQL trace to troubleshoot dump and load processes. This trace goes to the session log of the user who is running dump or load. A SQL trace logs almost every single statement issued to the database. The log file grows much faster and bigger than any other tracing. To enable SQL trace use the following line as the first line of your dump or load script: A Detailed Review 6

7 apply,c,null,sql_trace,level,i,1 To disable SQL trace, use the following line as the last line of your dump or load script: apply,c,null,sql_trace,level,i,0 Preload The filestore names of the associated content must match in the source and target repositories. To generate a list of filestores that needs to be created before you run the load, you need to run the preload utility. The syntax for the preload utility is as follows: C:\> preload repository [-Uusername] -Ppassword -dump_file filename [-script_file name] Load A load is performed after creating a dm_load_record on the target repository. After finishing the dump on the source repository, copy the dump file on to the target machine and run the load script via IAPI. Before you perform the load Ensure that there is enough space for the content. Create the necessary filestores as mentioned by preload results. Only the name has to match; the location can be different. If you FTP the dump file it should be FTP d as binary. The user performing the load should have read/write permission on this file. If the dump didn t include content, the repository owner should have access to the source filestore. Sample script to load Use the following sample script to load: create,c,dm_load_record set,c,l,file_name c:\dumpfile.dmp save,c,l getmessage,c Each API can be run individually or the whole script in one. The dump file location can be different from shown in the above script. The load can be restarted in the event of a crash. Fetch the r_object_id of the dm_load_record and issue a save API on it. The load will start from the point where it left off. The dm_load_record has an attribute called relocate. It is a Boolean and used if the user decided to preserve r_object_ids of the objects in the target repository. For this the target repository has to have the same docbase ID. We do not encourage users to use this option as each repository has its own sets of r_object_ids to start with. As an option we recommend to use the database export/import option as described in the EMC Documentum Content Server Installation Guide. A Detailed Review 7

8 Frequently asked questions Q. Is there any size limit on the dump file? A: There is no size limit on the dump file from Documentum unless the O/S has a limit on it. Q. Do I need to have the same repository ID, name, and owner for the target repository? A: No. The target repository can have a different ID, name, or owner unless there is a need to preserve r_object_ids. Q. What do I do if the codepage of the source and target docbase are different? A: Use the following lines as the first line of your dump script: set,c,sessionconfig,session_codepage codepage where codepage is the codepage in which you want to dump the repository. Q. What if I see duplicate objects after the load? A: If after the load there is a document with the same name, a brand new document with a different r_object_id was created. You can delete the duplicate. Q. Can I load a part of a dump file? A: No. You cannot load a partial dump file. Q. In DA I see a source repository name when I go to configuration. What do I do? A: When you click Administration > Configuration > Repository you will see the source docbase config object. It came as the result of a load. It is safe to delete these server and docbase config objects. Q. Is the load going to bring in my DocApps? A: DocApps are not dumped with a dump. You need to use Documentum Application Builder to archive DocApps from the source repository and load using the DocApp Installer in the target repository. Q. How do I make sure the dump and load was completed? A: You can query the r_end_time attribute of dm_dump_record or dm_load_record. If it has a valid date and time then your dump or load was successful. Q. Can I use dump and load between cross-platform repositories? A: Yes, if you change include_content to TRUE in the dump script. For example, the source can be Windows/SQL Server and the target can be UNIX/Oracle. Check with your database administrator and your cross-database compatibility. Q. How can I dump a single cabinet? A: Support Note 2114 has a sample script to dump a single cabinet. Q. What if I don t want a full-text event created for loaded objects? A: Objects of SysObjects or their subtype create an event as a result of SAVE. This add an entry in dmi_queue_item to the dm_fulltext_index_user to ensure that the object is added to the target repository s index. You can control this by the load parameter called generate_event. If you do not want the load operation to queue save events set the parameter to F for the operation: generate_event=f A Detailed Review 8

9 Q. How do I estimate the size of the dump file? A: If you are dumping the complete docbase then approximate what the size of the dump file will be (Size of the database + Size of the content). In case of a partial docbase dump you can calculate the size of the content by following DQL (that is, for a single cabinet): select sum(content_size) from dmr_content where ANY parent_id in (select r_object_id from dm_sysobject(all) where folder('/the_folder_path',descend)) Q. Do all the users get dumped if an object has world in its ACL? A: No, it will not dump all the users. When you dump an object you also dump its owner, r_creator_name, and its group (not all users in the group, just the owner). It also dumps users in the Global User Default ACL, and dumps the groups to which these users belong. To see which users have the select Global User Default ACL, use "select * from dm_user where acl_name = 'Global User Default ACL'". Then you can find the groups they belong to. Q. How do I undo the load? A: Get the r_object_id of the dm_load_record: IDQL> select r_object_id, r_end_time,r_start_tiem from dm_load_record If you have more than one record, check the start and end time to pick the right tone. Then run the following API: API>revert,c,r_object_id of the load record. Run the dm_dmclean job after. Q. How do I know the old and new r_object_ids after the load? A: Check the old_id and new_id attribute in the dmi_load_object_record. Conclusion This white paper has provided a step-by step process to do dump and load. Most of the technical details and architecture overview has been described. Contact EMC Support for any issues that may arise during the dump and load process. A Detailed Review 9