Using DFC 4213

Using DFC in
Documentum
Applications
June 2002
Copyright © 2002
Documentum, Inc.
6801 Koll Center Parkway
Pleasanton, CA 94566
All Rights Reserved.
Documentum® Documentum RightSite®, Documentum Server®, Docbasic®,
Documentum DocPage Server®, Now You Know®, Documentum WorkSpace®,
Documentum SmartSpace®, Documentum ViewSpace®, AutoRender Pro™,
Docbase™, DocInput™, Docobject™, DocPage Builder™, Documentum 4i™,
Documentum Administrator™, Documentum CADLink™, Documentum
Commerce Server Integrators™, Documentum Application Server
Integrators™, Documentum Content Authentication Services™, Documentum
Content Personalization Services™, Documentum ContentCaster™,
Documentum Corrective Action Manager™, Documentum Desktop Client™,
Documentum Developer Studio™, Documentum DocControl Manager™,
Documentum DocLoader™, Documentum DocViewer™, Documentum
Dynamic Content Assembler™, Documentum eConnector for CAD™,
Documentum eConnector™ for IBM WebSphere® (IBM and WebSphere are
trademarks of IBM) Documentum eConnector for SAP™ (SAP is a trademark
of SAP AG), Documentum eConnector™, Documentum eConnector™ for BEA
Weblogic® (BEA is a registered trademark of BEA Systems Inc.) Documentum
eConnector™ for JDBC, Documentum eConnector™ for ATG Dynamo® (ATG
and Dynamo are registered trademarks of Art Technology Group),
Documentum eConnector™ for Lotus Notes® (Lotus Notes is a registered
trademark of Lotus Development Corporation) Documentum eContent
Server™, Documentum Engagement Services™, Document Engagement
Server™, Documentum ftpIntegrator™, Documentum Intranet Client™,
Documentum iTeam™, Documentum Reporting Gateway™, Documentum Site
Delivery Services™, Documentum Web Development Kit™, Documentum
Web Gear™, Documentum WebCache™, Documentum WebPublisher™,
GMPharma™, GXPharma™, GDPharma™, GSPharma™, Momentum™,
Virtual Document Manager™ (VDM), and Documentum Selfrepair™ are
trademarks or registered trademarks of Documentum, Inc. in the United States
and throughout the world. All other company and product names are used for
identification purposes only and may be trademarks of their respective owners.
Preface
1 Getting Started With DFC
What is DFC? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Where is DFC? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Programming with DFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Using DFC From Application Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Visual Basic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Establishing the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Using Interface Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Syntax Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Creating DFC Client Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Visual Basic Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Using DFC Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Using the DFC Online Reference Documentation . . . . . . . . . . . . . . . . . . . . 1-11
2 Working With Documents

Introduction to Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Virtual Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Introduction to Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Types of Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Basic Steps for Manipulating Documents. . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Steps for Manipulating Documents . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Details of Manipulating Documents. . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Obtaining the Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Setting Parameters for the Operation . . . . . . . . . . . . . . . . . . . . . . 2-7
Adding Documents to the Operation . . . . . . . . . . . . . . . . . . . . . . 2-8
Executing the Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Processing the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Working With Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Operations for Manipulating Documents . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Importing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Special Considerations for Import Operations . . . . . . . . . . . . . . . . 2-11
Setting up the Operation . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
XML Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Processing the Imported Documents . . . . . . . . . . . . . . . . . . 2-12
Using DFC in Documentum Applications iii

Exporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13
Special Considerations for Export Operations . . . . . . . . . . . . . . . . .2-13
Checking Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Special Considerations for Checkout Operations . . . . . . . . . . . . . . .2-14
Checking In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15
Special Considerations for Checkin Operations . . . . . . . . . . . . . . . .2-15
Setting up the Operation . . . . . . . . . . . . . . . . . . . . . . . . . .2-16
Processing the Checked In Documents . . . . . . . . . . . . . . . . . .2-16
Cancelling Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17
Special Considerations for CancelCheckout Operations . . . . . . . . . . .2-17
Copying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-18
Special Considerations for Copy Operations. . . . . . . . . . . . . . . . . .2-18
Moving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-19
Special Considerations for Move Operations . . . . . . . . . . . . . . . . .2-19
Deleting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
Special Considerations for Delete Operations . . . . . . . . . . . . . . . . .2-20
Validating an XML Document Against a DTD or Schema . . . . . . . . . . . . .2-21
Special Considerations for Validation Operations. . . . . . . . . . . . . . .2-22
Performing an XSL Transformation of an XML Document . . . . . . . . . . . .2-23
Special Considerations for XMLTransform Operations. . . . . . . . . . . .2-25
Handling Document Manipulation Errors. . . . . . . . . . . . . . . . . . . . . . . . .2-26
The add Method Cannot Create a Node . . . . . . . . . . . . . . . . . . . . . . .2-26
The execute Method Encounters Errors . . . . . . . . . . . . . . . . . . . . . . .2-26
Examining Errors After Execution . . . . . . . . . . . . . . . . . . . . . . .2-26
Examining Errors in an Operation Monitor . . . . . . . . . . . . . . . . . .2-27
Operations and Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28
3 DFC Methods by Task

Communicating with the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
IDfClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
DMCL (No Associated DFC Methods) . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Administering the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
IDfClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
DMCL (No Associated DFC Methods) . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Handling Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
IDfPersistentObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
IDfAcl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
iv Using DFC in Documentum Applications

Retrieving and Setting Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
IDfTypedObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Searching the Docbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
IDfQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
IDfCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Handling Content Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
DMCL (No Associated DFC Methods) . . . . . . . . . . . . . . . . . . . . . . . 3-15
Printing Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Handling Virtual Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
IDfVirtualDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Handling Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
IDfWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19
Handling Workflow Process Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3-20
IDfProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20
Handling Workflow Activity Definitions. . . . . . . . . . . . . . . . . . . . . . . . . 3-21
IDfActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21
Handling Workflow Work Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
IDfWorkitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Managing Inboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
4 Managing DFC Sessions

About Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Shared Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Adopted Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Connecting and Disconnecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
connectToDocbase in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
disconnectFromDocbase in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
displaySessionInfo in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
connectToDocbase in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
disconnectFromDocbase in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . 4-5
displaySessionInfo in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Using DFC in Documentum Applications v

Using a Docbase Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
displayDocbaseInfo in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
connectToDocbase(map, index) in Java . . . . . . . . . . . . . . . . . . . . . . . 4-6
Step through Docbases in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
displayDocbaseInfo in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
connectToDocbase(name) in Visual Basic . . . . . . . . . . . . . . . . . . . . . . 4-7
5 Managing Docbase Queries with DFC

Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Flow of Query Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
IDfQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
IDfCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Basic Query Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
execQuery in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
displayResults in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
execQuery in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
displayResults in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
6 Automating Business Rules with DFC

Checking Objects Against Validation Rules . . . . . . . . . . . . . . . . . . . . . . . . 6-1
validate in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Changing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
changeBasicPermissions in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . 6-2
changeExtendedPermissions in Visual Basic . . . . . . . . . . . . . . . . . . . . 6-3
changeBasicPermissions in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
changeExtendedPermissions in Java . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
Using Private ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
privateACLs in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
privateACLs in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
ACL Utility Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
permissionToString in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
extendedPermissionToString in Visual Basic . . . . . . . . . . . . . . . . . . . . 6-7
displayBasicPermissions in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . 6-7
displayExtendedPermissions in Visual Basic . . . . . . . . . . . . . . . . . . . . 6-8
permissionToString in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
extendedPermissionToString in Java . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
displayBasicPermissions in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
displayExtendedPermissions in Java . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
vi Using DFC in Documentum Applications

7 Overview of the DFC Interface Hierarchy
Documentum Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Subtypes and Supertypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
DFC Interface Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Typed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Session and Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Getting and Setting Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Additional Methods for Operating on Repeating Attributes . . . . . . . . . . . 7-10
Attribute Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
Persistent Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Methods Relating to the Basic Properties of Persistent Objects. . . . . . . . . . 7-12
Basic Operations on an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13
Audit Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14
Convenience Methods for Creating Object Relations . . . . . . . . . . . . . . . 7-14
Validation Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14
Pass-Through Methods to the DMCL API . . . . . . . . . . . . . . . . . . . . . 7-15
Persistent Objects Without Associated Content . . . . . . . . . . . . . . . . . . . . . 7-16
IDfACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16
IDfFormat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16
IDfUser and IDfGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17
IDfType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17
Basic Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17
Parent Type Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17
Type Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18
SysObjects—Persistent Objects With Content . . . . . . . . . . . . . . . . . . . . . . 7-20
Basic Operations on SysObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-20
Types That Derive From IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . 7-21
IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-22
Provide Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-22
Create Objects and Obtain Object References . . . . . . . . . . . . . . . . . . . 7-23
Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-24
Transaction Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-24
Docbase Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-24
Multithreading Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-25
API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-25
Inbox and Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-26
Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-26
Session State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-27
Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-27
Using DFC in Documentum Applications vii

IDfClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-27
Creating Sessions and Obtaining References to Existing Sessions. . . . . . . . .7-28
Maps and Config Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-29
Service Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-29
Common Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-30
8 DFC and DMCL

Relationship to DMCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1
Calling DMCL Directly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
DMCL to DFC Correspondence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
Index
viii Using DFC in Documentum Applications

PREFACE
Purpose of the Manual

This manual shows how to use Documentum Foundation Classes (DFC) in
building or customizing Documentum applications. It provides an overview
of DFC and includes sample code that uses DFC to perform common
Documentum operations.
Intended Audience
This manual is intended for application developers. It assumes a knowledge
of object-oriented programming, Java, interfaces, and, in some places, the
Microsoft component object model (COM).
Sample Code
Some sample code in this manual is extracted and simplified from sample
classes that Documentum makes available to customers at
www.documentum.com/developer/samplecode.htm.
The sample classes provide complete working examples that you can run,
modify, and experiment with. They are not part of the product, and while we
have made every effort to ensure that they work properly, Documentum does
not support them.
The simplified examples focus on specific DFC tasks and omit code from the
sample classes that is not specific to DFC.
This manual does not cover workflows, or document lifecycles.
Using DFC in Documentum Applications ix

Organization of the Manual
The table summarizes the topics that this manual covers. The classes referred
to in the descriptions of chapter contents are the sample classes referred to in
“Sample Code” on page ix.
Chapter/Appendix Contents
Chapter 1, Getting Started What DFC is, where it resides, and how to start using
With DFC it.
Chapter 2, Working With How to perform basic operations like checkin and
Documents checkout. How to work with XML documents.
Chapter 3, DFC Methods by An index to the major DFC methods, organized by

Task the tasks the methods accomplish.
Chapter 4, Managing DFC Annotated examples, based on the classes

Sessions DfExSession and DfExDocbaseMap, of how to work
with DFC sessions and a Docbase map.
Chapter 5, Managing Docbase Annotated examples, based on the class

Queries with DFC DfExSimpleQuery, of how to create and execute
Docbase queries.
Chapter 6, Automating Annotated examples, based on the classes

Business Rules with DFC DfExSimpleValidation and DfExACL, of how to use
Documentum to enforce business rules.
Chapter 7, Overview of the How DFC gives you an object oriented interface to
DFC Interface Hierarchy the Documentum object hierarchy.
Chapter 8, DFC and DMCL An explanation of DFC in terms of the methods that
previous Documentum client products use to access
server capabilities.
x Using DFC in Documentum Applications

Conventions
This manual uses the following conventions:
Convention Description
➤ Represents a pop-up or pull-down menu.

Indicates the introduction to a procedure.
italics Represents a variable name for which you must provide a

value, or a defined term.
typewriter Represents code samples, user input, and computer output.
[] square brackets Indicates an optional argument.
{} braces (curly Indicates an optional argument that can be repeated more than
brackets) once.
Using Links in PDF Files

If you are reading this document as a Portable Document Format (PDF) file,
cross-references and page numbers in the index are clickable blue hypertext
links. Table of contents page numbers are also clickable links, but they appear
in black.
Some Documentum manuals contain clickable cross-references to other
manuals. Click the link to go to the referenced section.
Note: These references assume that the referenced file is in the current
directory and that it has the name that Documentum originally assigned it. If
you change file names or store documents in separate directories, the
references do not work.
Using DFC in Documentum Applications xi

Bug Lists and Documentation Online
Customers with a software support agreement can access the support area of
www.documentum.com to download product documentation and, after
commercial release of a product, view lists of fixed bugs.
To access the support area, follow the links to request a user name and
password. Documentum responds to access requests within two business
days. Once you have a user name and password, you can access the support
area without delay.
Fixed Bug Lists
Two weeks after the release, we post a list of customer-reported bugs that
have been fixed in that release to the support area of www.documentum.com.
Product Documentation
Concurrently with a release, we post product documentation to the support

area of www.documentum.com.
Purchasing Bound Paper Manuals

You can order any of our documentation in the form of bound manuals. We
print and stock widely used manuals, usually several months after we publish
the online version. We print other documentation to order.
To place an order or to ask about prices, call the documentation order line at
(925) 600-6666. You can pay with a purchase order, check, or credit card. We do
not sell bound manuals through www.documentum.com.
xii Using DFC in Documentum Applications

1
Getting Started With DFC 1
This chapter introduces DFC. It contains the following major sections:

■ “What is DFC?” on page 1-1
■ “Programming with DFC” on page 1-2
■ “Using DFC From Application Programs” on page 1-5
■ “Creating DFC Client Objects” on page 1-8
■ “Using DFC Tracing” on page 1-9
■ “Using DFC Tracing” on page 1-9
■ “Packages” on page 1-9
■ “Using the DFC Online Reference Documentation” on page 1-11
What is DFC?
DFC is a set of Java classes and interfaces. It provides an object oriented
application programming interface (API) for accessing Documentum
functionality. You can use DFC in any of the following ways:
■ Access Documentum functionality from within one of your company’s
enterprise applications.
For example, your corporate purchasing application can retrieve a contract
from your Documentum system.
■ Customize or extend Documentum products like Desktop Client or WDK.
For example, you can modify the Desktop Client functionality to
implement one of your company’s business rules.
■ Write a method or procedure for eContent Server to execute as part of a
workflow or document lifecycle.
Using DFC in Documentum Applications 1–1

Getting Started With DFC
Where is DFC?
For example, the procedure that runs when you promote an XML
document might apply a transform to it and start a workflow to subject the
transformed document to a predefined business process.
The Documentum eContent Server Fundamentals manual provides a conceptual
explanation of the capabilities of eContent Server and how they work. DFC
provides a framework for accessing those capabilities. Using this framework
makes your code much more likely to survive future architectural changes in
the Documentum system.
The core of DFC is a set of Java classes, but it includes other elements as well:
■ A collection of DLLs to provide the DFC functionality.
■ A type library for accessing DFC via COM from Visual Basic or Visual
C++.
■ A set of C++ wrapper classes that hide many details of the DFC/COM
interface when you access DFC through the Microsoft foundation classes
(MFC) framework.
Where is DFC?
DFC runs on a JVM, which can be on:
■ The machine that runs eContent Server
For example, to execute a method as part of a workflow or document
lifecycle.
■ A middle-tier system
For example, to support WDK on an application server.
■ An end user’s computer
For example, to support Desktop Client.
Programming with DFC

Before you begin to use DFC, it is important to understand the DFC
programming approach. Because of the complexities of accessing Docbases
efficiently and reliably from remote client machines, Documentum centralizes
1–2 Using DFC in Documentum Applications

this access in client-side software that establishes and maintains

communication sessions with eContent Server and Docbases. DFC
encapsulates this client-side software in the IDfClient interface, which serves
as the entry point for DFC code.
IDfClient handles basic connection details. It loads the necessary shared
libraries. You obtain the initial IDfClient interface by calling the static method
DfClient.getLocalClient. The IDfClient interface then serves as a factory for
IDfSession objects. If you are familiar with the standard Java database
connectivity package, JDBC, you can see an analogy between that
programming model and this one.
An object that implements IDfSession represents a connection with the
Documentum server and provides services related to that session. DFC
programmers create new Docbase objects or obtain references to existing
Docbase objects through the IDfSession interface.
With DFC you usually don’t create objects directly. Instead, you obtain objects
by calling the methods of other objects. Those methods create or obtain the
requested object. Methods that create new Docbase objects or fetch existing
ones return objects that implement IDfPersistentObject.
The following general procedure may help to clarify the DFC approach. Don’t
worry if you don’t completely understand the references to the interface
hierarchy. Subsequent sections deal with that subject.
➤ To process a Docbase object:

1. Obtain an IDfClient object by calling DfClient.getLocalClient.
2. Call the IDfClient method newSession or getSharedSession to create a session
with the Docbase (see “connectToDocbase in Java” on page 4-3).
3. If you do not have a reference to the object, call an IDfSession method (for
example, newObject or getObjectByQualification) to create an object or to
obtain a reference to an existing object.
4. Use routines of the operations package (see Chapter 2, Working With
Documents) to manipulate the object—check it out, check it in, and so forth.
5. Close the session if you are done with it.

The following fragment from a Java program that uses DFC contains three
parts. They implement the first three steps of the procedure.
Example IDfClient client = DfClient.getLocalClient();
IDfLoginInfo loginInfo = new DfLoginInfo();

loginInfo.setUser("Mary");
loginInfo.setPassword("ganDalF");
loginInfo.setDomain("");
session = client.newSession("MyDocbase", loginInfo);
IDfDocument document = null;

document = (IDfDocument) session.newObject("dm_document");
document.setObjectName("Report on Wizards");
document.setContentType("crtext");
document.setFile("C:\Temp\Wiz.txt");
document.save();
The first part creates the client object, which encapsulates the Documentum
client software.
The second block creates and populates an object to hold login information
and uses it to manufacture an IDfSession object, which encapsulates a session
for this application program with the specified Docbase.
The third block of code creates and populates an IDfDocument object and
saves it in the Docbase. Notice that the newObject method of the session object
manufactures the object.
The newObject method returns an IDfPersistentObject object. The program
explicitly casts it to an IDfDocument object, then uses the document object’s
save method, a method that IDfDocument inherits from IDfPersistentObject.
COM does not support interface inheritance, so the Visual Basic and C++
versions of the above code explicitly cast the document object to a persistent
object before saving it.
Most DFC methods report errors by throwing a DfException object. Java code
like that in the above example normally appears within a try/catch/finally
block, with an error handler in the catch block. Visual Basic code uses the On
Error Goto statement to handle exceptions.
Note: When writing code that calls DFC , it is a good idea to include a finally
block to ensure that you can release storage and close open sessions.

Using DFC From Application Programs

You can use COM or Java to access DFC. Your choices depend on your
programming language.
Java
From Java, use the Java interface. Add the DFC class and interface files (for
example, ...Documentum\DFCre40\lib\dfc.jar) to your CLASSPATH. In your
Java source code, import the classes you wish to use.
Visual Basic
Using DFC from Visual Basic requires a small setup procedure.

You must use a workaround to allow an object to use methods inherited from
a superclass of its base class.
Establishing the Environment
The DFC installer establishes the software environment to allow Visual Basic
to access DFC using COM. From a Visual Basic project, you need only
establish a reference to the DFC type library.
➤ To establish a reference to the DFC type library:

1. Choose Properties ➤ References
The References dialog box appears.
2. Check the checkbox for Documentum Foundation Classes Type Library.
Using Interface Inheritance
Interface inheritance requires a workaround if you access DFC from Visual

Basic, because the Microsoft Java virtual machine (JVM) does not support
COM interface inheritance.

Example For example, in Java you can use the save method that an object of type
IDfSysObject inherits from IDfPersistentObject.
//Java
IDfSysObject sysObj = session.newObject("dm_document");
sysObj.setObjectName("test");
sysObj.save();
In Visual Basic, however, you must assign the IDfSysObject object to an
IDfPersistentObject object before calling its save method:
'Visual Basic
Dim sysObj As IDfSysObject
Dim perObj As IDfPersistentObject
Set sysObj = session.newObject("dm_document")

sysObj.setObjectName ("test")
set perObj = sysObj

perObj.save
C++
From C++, use COM directly, or, if you use MFC, you can use classes, called
wrapper classes, that Documentum provides to hide some of the complexities of
the COM interface. To use these classes with MFC, include the following files
in your Visual C++ project: DfClientX.h, DfClientX.cpp, dfc.h, and dfc_i.c
If you don’t use MFC or if you wish to write your own wrapper classes,
include only dfc.h and dfc_i.c.
Note: Interface inheritance requires a workaround if you access DFC from
C++, because the Microsoft Java virtual machine does not support COM
interface inheritance. See the example in the previous section.
Follow these rules for objects and pointers:
■ Always assign a DFC object to a new pointer.
First delete the old pointer, then create a new CDfSysObject, as in the
following C++ example:
//Get a DFC object
CDfSysObject sobj1 = session.getObject(id);
CDfSysObject *pSysObj = null;
//Delete the old pointer

if (pSysObj) delete pSysObj;

//Create new CDfSysObject

pSysObj = new CDfSysObject(sobj1);
■ A procedure that returns a DFC object should return a pointer to the object,
as demonstrated in the following Visual C++ example:
CDfSysObject *myFunction();
{
CDfSysObject sobj1 = session.getObject(id);
CDfSysObject *retval = new CDfSysObject (sobj1);
return retval;
}
Syntax Differences
COM and Java give you access to the same DFC classes and interfaces, but
COM datatypes differ slightly from Java datatypes. Table 1-1 shows the COM
equivalents of DFC datatypes.
Table 1-1 Equivalents for DFC Datatypes
Java (DFC datatype) Visual Basic C++ with MFC C++ directly to COM
(and Docbasic) wrapper classes
boolean Boolean BOOL VARIANT_BOOL
int Long long int
String String CString BSTR
double Double double double
IDfinterfacename IDfinterfacename CDfinterfacename IDfinterfacename

or Object

Creating DFC Client Objects
Creating DFC Client Objects

➤ Perform the following steps before calling DFC methods:
1. Create a DFC client object as an interface to DFC.
The DFC client object must reside in the same process as the Documentum
client library, DMCL. DFC client objects are also called local DFC clients. Java
and COM use different interfaces to create the DFC client object, as shown in
the examples.
2. Provide login information and establish a DFC session (see “Connecting and
Disconnecting” on page 4-2).
Java Example
Use the DfClient.getLocalClient method.

IDfClient myclient = DfClient.getLocalClient();
This line of code creates a DFC client object. The object’s methods provide
access to the services of the local DFC client.
Visual Basic Example
IDfClientX creates DFC objects in COM development environments. You must

obtain an IDfClientX object before you can create DFC objects. Use the
IDfClientX interface’s getLocalClient method. The following example
demonstrates how to create a DFC client object in Visual Basic.
Dim myclient As IDfClient
Dim myclientx As DfClientX
Set myclientX = CreateObject(“Documentum.Dfc”)
Set myclient = myclientX.getLocalClient

Using DFC Tracing
Using DFC Tracing

DFC provides a tracing mechanism through static methods of the DfTrace
class. The principal ones are:
setTraceLevel (int traceLevel)
setTraceFileName (String fileName)
traceMsgCond (int triggerLevel, String msg)
The fact that these methods are static allows you to set up tracing before
establishing sessions or creating objects.
Visual Basic programs must access these methods through the IDfClientX
interface.
Trace levels range are integers in the range 0–10. The level controls the amount
of information DFC places into the trace file. The level 0 means no tracing, and
each increment asks DFC to provide more information. Each level includes all
of the information of the smaller numbered levels.
If you don’t set a trace file, the information goes to the standard output.
Packages
DFC comprises a number of packages, that is, sets of related classes and
interfaces.
■ The names of DFC Java classes begin with Df (for example, DfWorkflow).
■ Names of interfaces begin with IDf (for example, IDfWorkflow).
Interfaces expose DFC’s public methods and constants. Each interface

contains a set of related methods.
Table 1-2 describes the purpose of the classes and interfaces of DFC packages.

Packages
Table 1-2 Description of DFC Packages
Java Package Name Purpose
com.documentum.fc.client Provides basic functionality:

■ Establishing DFC sessions
■ Retrieving and validating data
■ Managing workflows
■ Manipulating virtual documents
■ Working with document versions
com.documentum.operations Provides high-level functionality, such as

checking documents or virtual documents in
and out. Provides XML support.
common.documentum.fc.client.qb Constructs and runs queries and SmartLists.
com.documentum.xml.xql Facilitates constructing Docbase queries that

return results in an XML format.
com.documentum.fc.common Supplies utility methods for other DFC classes.
com.documentum.registry Maintains Documentum information on the

client’s system, using the Windows registry on
Win32 platforms, and .ini files otherwise.
com.documentum.com Provides factory methods for constructing DFC

objects. Facilitates access to DFC through COM.
Note: The com.documentum.operations package and the IDfSysObject

interface in the com.documentum.fc.client package have some methods for
the same basic tasks (for example, checkin, checkout). The IDfSysObject
methods are mostly for internal use and for supporting legacy applications.
The methods in the operations package perform the corresponding tasks at a
higher level—keeping track of client-side files and implementing eContent
Server XML functionality.
Note: The name of the com.documentum.com interface might lead you to
believe that it is only for accessing DFC through COM. In fact, you should use
its factory methods (all of its getxxx methods, except for those dealing with
the DFC version or trace levels) from Java code as well. Never use the
corresponding new xxx, even if you know the name of the implementing
class.

Using the DFC Online Reference Documentation
The DFC interfaces form a hierarchy; some derive methods and constants
from others. Use the Tree link from the home page of the DFC online reference
(see “Using the DFC Online Reference Documentation” on page 1-11) to
examine the interface hierarchy. Click any interface to go to its definition.
Each interface inherits the methods and constants of the interfaces above it in
the hierarchy. For example, IDfPersistentObject has a save method.
IDfSysObject is a subclass of IDfPersistentObject, so it inherits the save
method (see “Persistent Objects” on page 7-12 and “SysObjects—Persistent
Objects With Content” on page 7-20).
In Java, you can call the save method of an object of type IDfSysobject.
COM does not support interface inheritance. Visual Basic or C++ programs
access DFC via COM and see DFC as a type library. The library is flat, that is, it
contains all of the interfaces but none of the inheritance information. In Visual
Basic, you must assign an object of type IDfSysObject to an object of type
IDfPersistent object before you can save it.

This section explains how to use the DFC online reference documentation to
find greater detail about DFC structure and syntax.
Documentum uses the Javadoc facility to produce a DFC reference. This
reference is available online in HTML form, both by itself and as part of the
Developer Studio online help.
From the home page of the reference, you can choose a variety of views. The
Help link provides a description of how the reference is organized.
The DFC library is large, and programmers sometimes have difficultly
determining where to find or look for functionality. If this happens, consider
using the following decision sequence.

➤ To find the interface that provides a specified operation:

1. If you wish to operate on an object in the Docbase, determine the most general
interface that should support the operation, and look there.
For example, you can save any persistent object, so look for a save method
in IDfPersistentObject.
If the functionality involves content, security, versioning, or checkout/
checkin, look at IDfSysObject or interfaces derived from it.
2. If you wish to create an object, obtain a reference to an object, or perform a
general operation,
a. If the operation depends on having a session, look in IDfSession.
b. Otherwise, look in IDfClientX.

2
Working With Documents 2
This chapter describes the way to use DFC to perform the most common
operations on documents. It contains the following main sections:
■ “Introduction to Documents” on page 2-1
■ “Introduction to Operations” on page 2-4
■ “Types of Operations” on page 2-5
■ “Basic Steps for Manipulating Documents” on page 2-5
■ “Operations for Manipulating Documents” on page 2-10
■ “Handling Document Manipulation Errors” on page 2-26
■ “Operations and Transactions” on page 2-28
Introduction to Documents
The Documentum eContent Server Fundamentals manual explains the
Documentum facilities for managing documents. This section provides a
concise summary of what you need to know to understand the remainder of
this chapter.
Documentum maintains a repository of objects that it classifies according to a
type hierarchy. For this discussion, SysObjects are at the top of the hierarchy
(see “SysObjects—Persistent Objects With Content” on page 7-20). A document
is a specific kind of SysObject. Its primary purpose is to help you manage
content.
Virtual Documents
A virtual document is a container document that includes one or more objects

called components structured as an ordered hierarchy. A component is another
virtual document or any SysObject subtype except folders, cabinets, or subtypes of

Working With Documents
folders and cabinets. A virtual document can have any number of components,
nested to any level. Documentum imposes no limit on the depth of nesting in
a virtual document.
Documentum uses two sets of terminology for virtual documents. In the first
set, a virtual document that contains a component is called the component’s
parent, and the component is called the virtual document’s child. Children, or
children of children to any depth, are called descendants.
Note: Descendants are sometimes called descendents in internal variables,
Javadoc comments, and registry keys.
The second set of terminology derives from graph theory. The virtual
document and all of its descendants are called nodes. The directed relationship
between a parent node and a child node is called an edge.
In both sets of terminology, the original virtual document is sometimes called
the root.
Documentum maintains more than one version of a document. A version tree is
an original document and all of its versions. Every version of the document
has a unique object ID, but every version has the same chronicle ID—the object
ID of the original document.
You can associate a particular version of a component with the virtual
document (this is called early binding) or you can associate the component’s
entire version tree with the virtual document. The latter allows you to select
which version to include at the time you assemble the document (this is called
late binding). Documentum provides an extremely flexible set of rules for
controlling the way it assembles documents.
An assembly is a snapshot of a virtual document. It consists of the set of
specific component versions that resulted from assembling the virtual
document according to a set of binding rules. To preserve it, you must attach it
to an existing SysObject—usually the virtual document. A SysObject can have
at most one attached assembly.
Documentum represents the components of virtual documents by containment
objects and the components of assemblies by assembly objects. An assembly
object refers to the SysObject to which the assembly is attached, and to the
virtual document from which the assembly came.
If an object appears more than once as a node in a virtual document or
assembly, each node has a separate associated containment or assembly
object. No object can appear as a descendant of itself in a virtual document.

You can version a virtual document and manage its versions just as you do a
simple document. Deleting a virtual document version also removes any
containment objects or assembly objects associated with that version.
When you copy a virtual document, the server can make a copy of each
component or it can create an internal reference or pointer to the source
component. It maintains information in the containment object about which of
these possibilities to choose. One option is to require the copy operation to
specify the choice.
Whether it copies a component or creates a reference, Documentum creates a
new containment object corresponding to that component.
Note: DFC allows you to process the root of a virtual document as an ordinary
document. For example, suppose that doc is an object of type IDfDocument
and also happens to be the root of a virtual document. If you tell DFC to check
doc out, it does not check out any of the descendants. If you wish to check out
the descendants, you must first execute an instruction like
IDfVirtualDocument vDoc =
doc.asVirtualDocument(CURRENT, “false”)
If you tell DFC to check vDoc out, it processes doc and all of its descendants.
XML Documents
When you import an XML document, DFC creates a virtual document. It

imports other documents that the XML document refers to as entity references
or links, and makes them components of the virtual document. It uses
attributes of the containment object associated with a component to remember
whether it came from an entity or a link and to maintain other necessary
information. Assembly objects have the same XML-related attributes.
Documentum’s XML support has many more features. It also requires you to
provide a controlling XML application. Information about those subjects
appears in Documentum eContent Server Fundamentals and in Managing XML
Content in Documentum.

Introduction to Operations
Introduction to Operations
To manipulate documents in Documentum, you must understand operations.
Operations are like the document carriers you use to put small pieces of paper
through the feeder of a copying machine. Operations provide interfaces and a
processing environment to ensure that Documentum can handle a variety of
documents and collections of documents in a standard way. You obtain an
operation of the appropriate kind, place one or more documents into it, and
“run it through the machine,” that is, execute the operation.
The operations apply to objects of type IDfSysObject, not just the subtype
IDfDocument, but all of the examples in this chapter pertain only to
documents.
For example, to check out a document, take the following steps:
1. Obtain a checkout operation.
2. Add the document to the operation.
3. Execute the operation.
DFC carries out the behind-the-scenes tasks associated with checking out a
document. For a virtual document, for example, DFC adds all of its
components to the operation and ensures that links between them are still
valid when it stores the documents into the checkout directory on the file
system. It corrects filename conflicts, and it keeps a local record of which
documents it checked out. This is only a partial description of what DFC does
when you check out a document. Because of the number and complexity of
the underlying tasks, DFC wraps seemingly elementary document-
manipulation tasks in constructs called operations.
An object that implements the IDfClientX interface has methods for creating
operations. For this reason, we call it a factory for operations. Once you have
the factory object (say cX) and a sysobject representing the document (say
doc), the code for the checkout looks like this:
// Obtain a checkout operation
IDfCheckoutOperation checkout =
(IDfCheckoutOperation) cX.getOperation("Checkout");
// Add the document to the checkout operation

checkout.add(doc); //This might fail and return a null
// Check the document out

checkout.execute(); //This might produce errors without
//throwing an exception

Types of Operations
In real code, you would check to see if the add method returns a null or the
execute method returns errors.
Types of Operations
There are operation types for many of the tasks you might wish to perform on
documents or, where appropriate, files or folders.
The names of the DFC interfaces associated with operations follow a naming
convention based on a root character string for each operation. In the
following list of tasks, the root string for naming the associated interfaces
appears in parentheses after the task.
■ Import into a Docbase (Import)
■ Export from a Docbase (Export)
■ Check into a Docbase (Checkin)
■ Check out of a Docbase (Checkout)
■ Cancel checkout (CancelCheckout)
■ Delete (Delete)
■ Copy from one Docbase location to another (Copy)
■ Move from one Docbase location to another (Move)
■ Validate an XML document against a DTD or Schema (Validation)
■ Transform an XML document using XSLT (XMLTransform)
Note: When you use the root string, you must reproduce the capitalization
exactly. Java is case sensitive, as is the factory method that creates operations.
Basic Steps for Manipulating Documents

This section describes the basic steps common to using the facilities of the
operations package to manipulate documents. It sets forth the basic steps,
then discusses the steps in greater detail.

Steps for Manipulating Documents
➤ To perform a document-manipulation task:

1. Use the getOperation method of an object of type IDfClientX to obtain an
operation of the type appropriate to the document-manipulation task.
For example, if you wish to check documents into a Docbase, start by calling
clientX.getOperation (“Checkin”). Note that the calling argument is the root
string for the operation and that getOperation interprets the string in a case-
sensitive way.
2. Set parameters to control the way the operation performs the task.
Each operation type has setXxx methods for setting its parameters.
The operation behaves in predefined (default) ways if you do not set optional
parameters. Some parameters (the session for an import, for example) are
mandatory.
3. Add documents to the operation:
a. Use its inherited add method to place a document, file, or folder into the
operation.
See the note about inherited methods on page page 2-7. The add method
returns the newly created node (or a null if it fails).
b. Set parameters to change the way the operation handles this item and its
descendants.
Each type of operation node has methods for setting parameters that are
important for that type of operation. These are generally the same as the
methods for the corresponding type of operation. If you do not set
parameters, the operation handles this item according to the settings you
give it in Step 2.
c. Repeat Step a and Step b for all items you wish to place into the operation.
4. Invoke the operation’s inherited execute method to perform the task.
See the note about inherited methods on page page 2-7.
Note that this step may add and process additional nodes. For example, if part
of the execution entails scanning an XML document for links, DFC may add
the linked documents to the operation.
5. Process the results

a. Handle errors.
If it detects errors, the execute method returns the boolean value false. You
can use the operation’s inherited getErrors method to obtain a list of
failures (see the note about inherited methods on page page 2-7). For
details of how to process errors, see “Processing the Results” on page 2-9.
b. Perform tasks specific to the operation.
For example, after an import operation, you may wish to take note of all of
the new objects that the operation created in the repository. You might
wish to display or modify their properties.
Details of Manipulating Documents
This section discusses some issues and background for the steps of the general
procedure in the previous section, “Steps for Manipulating Documents” on
page 6.
Note: Each operation has a type (for example, IDfCheckinOperation) that
inherits most of its methods (in particular, its add and execute methods) from
IDfOperation. To use an operation from Visual Basic, you must assign the
operation to an object of type IDfOperation before using inherited methods.
See “Using Interface Inheritance” on page 1-5 for more details.
Obtaining the Operation
The getOperation method of an IDfClientX object manufactures an object of

the type you specify in the calling argument. Because the calling argument is a
character string, the method cannot know before it is called which type of
operation it will manufacture, so it returns the operation as an object of type
IDfOperation. You must then cast that object to the appropriate type.
Setting Parameters for the Operation
Different operations accept different parameters to control the way they carry
out their tasks. Some parameters are optional, some mandatory.
In some cases you can also use the getProperties method of IDfOperation to
obtain an IDfProperties object associated with the operation. The DFC
Javadocs explain how to use this object to fine tune operation behavior.

Note: You must use the setSession method of IDfImportOperation or

IDfXMLTransformOperation to set a Docbase session before adding nodes to
either of these types of operation. No other operation type has a setSession
method.
Adding Documents to the Operation
An operation contains a structure of nodes and descendants. When you obtain

the operation, it has no nodes (DFC does not regard the operation itself as a
node). When you use the operation’s add method to add documents to the
operation, it creates new root nodes. The add method returns the node as an
IDfOperationNode object. You must cast it to the appropriate operation node
type (see “Working With Nodes” on page 2-9).
Note: If the add method cannot create a node for the specified document, it
returns a null argument. Be sure to test for this case.
DFC may add additional nodes to the operation. For example, if you add a
Docbase folder, DFC adds nodes for the documents linked to that folder, as
children of the folder’s node in the operation.
Each node can have zero or more child nodes. If you add a virtual document,
the add method creates as many descendant nodes as necessary to create an
image of the virtual document’s structure within the operation.
You can add objects from more than one Docbase to an operation.
You can use a variety of methods to obtain and step through all nodes of the
operation (see “Working With Nodes” on page 2-9). You may wish to set
parameters on individual nodes differently from the way you set them on the
operation.
Executing the Operation
The operations package processes the objects in an operation as a group,

possibly invoking many DFC calls for each object. Operations encapsulate
Documentum client conventions for registering, naming, and managing local
content files.
DFC executes the operation in a predefined set of steps, applying each step to
all of the documents in the operation before proceeding to the next step. It
processes each document in an operation only once, even if the document
appears at more than one node.

Once DFC has executed a step of the operation on all of the documents in the
operation, it cannot execute that step again. If you wish to perform the same
task again, you must construct a new operation to do so.
Normally, you use the operation’s execute method and let DFC proceed
through the execution steps. DFC provides a limited ability for you to execute
an operation in steps, so that you can perform special processing between
steps. Documentum does not recommend this approach, because the number
and identity of steps in an operation may change with future versions of DFC.
If you have a programming hurdle that you cannot get over any other way,
work with Documentum Technical Support or Consulting to design a
solution.
Processing the Results
If DFC encounters an error while processing one node in an operation, it

continues to process the other nodes. For example, if one object in a checkout
operation is locked, the operation checks out the others. Only fatal conditions
cause an operation to throw an exception. DFC catches other exceptions
internally and converts them into IDfOperationError objects. The getErrors
method returns an IDfList object containing those errors, or a null if there are
no errors. The calling program can examine the errors, and decide whether to
undo the operation, or to accept the results for those objects that did not
generate errors.
Once you have checked the errors you may wish to examine and further
process the results of the operation. “Details of Manipulating Documents” on
page 2-7 shows some of the ways you can process the results. The next section,
“Working With Nodes,” shows how to access the objects and results
associated with the nodes of the operation.
Working With Nodes
Note: Each operation node type (for example, IDfCheckinOperationNode)

inherits most of its methods from IDfOperationNode. To use an operation
node from Visual Basic, you must assign the node to an object of type
IDfOperationNode before using inherited methods. See “Using Interface
Inheritance” on page 1-5 for more details.

Operations for Manipulating Documents
The getChildren method of an IDfOperationNode object returns the first level

of nodes under the given node. You can use this method recursively to step
through all of the descendant nodes. Alternatively, you can use the
operation’s getNodes method to obtain a list of all of its descendant nodes.
These methods return nodes as objects of type IDfOperationNode, not as the
specific node type (for example, IDfCheckinOperationNode).
The getId method of an IDfOperationNode object returns a unique identifier
for the node, not the object ID of the corresponding document. IDfOperationNode
does not have a method for obtaining the object ID of the corresponding
object. Each operation node type (for example, IDfCheckinOperationNode)
has its own getObjectID method. You must cast the IDfOperationNode object
to a node of the specific type before obtaining the object ID.

This section provides sample code and discusses specific details of the
following kinds of document manipulation operations:
■ “Importing” on page 2-11
■ “Exporting” on page 2-13
■ “Checking Out” on page 2-14
■ “Checking In” on page 2-15
■ “Cancelling Checkout” on page 2-17
■ “Copying” on page 2-18
■ “Moving” on page 2-19
■ “Deleting” on page 2-20
■ “Validating an XML Document Against a DTD or Schema” on page 2-21
■ “Performing an XSL Transformation of an XML Document” on page 2-23
The examples use the term file to refer to files on the file system and the terms
document and folder to refer to Docbase documents and folders, as represented
by DFC objects of type IDfDocument and IDfFolder.

Importing
The execute method of an IDfImportOperation object imports files into the

repository. It creates objects as required, transfers the content to the repository,
and removes local files if appropriate. If any of the nodes of the operation refer
to existing objects (for example, through XML or OLE links), it imports those
into the repository too.
Example Import an XML document.
//Assume that the following objects already exist:
IDfClientX cX; // a factory for operations
IDfSession sess; // the Docbase session to use
IDfID foldId; // ID of the destination folder
IDfFile myFile; // the file to import
// Get an import operation from the factory

IDfImportOperation op = (IDfImportOperation) cX.getOperation("Import");
// Set the Docbase session and destination folder

op.setSession(sess);
op.setDestinationFolderId(foldId);
// Add the file and cast the node to the appropriate type
IDfImportNode node = (IDfImportNode) op.add(myFile);
if (node == null) { // See “Handling Document Manipulation Errors” on page 2-26 }
// Set the XML application
// See “Setting Parameters for the Operation” on page 2-7 for information
// about properties
node.getProperties().putString("XMLApplication", "CellPhoneCatalog");
// Execute the operation

if (!op.execute()) { //See “Handling Document Manipulation Errors” on page 2-26 }
Special Considerations for Import Operations
Follow the steps in “Steps for Manipulating Documents” on page 2-6.
Setting up the Operation
Use the object’s setSession method to specify a Docbase session and the
object’s setDestinationFolder method to specify the Docbase cabinet or folder
into which the operation should import documents.
You must set the session before adding files to the operation.
You must set the destination folder, either on the operation or on each node.

You can add an IDfFile object or specify a file system path. You can also
specify whether to keep the file on the file system (the default choice) or delete
it after the operation is successful.
If you add a file system directory to the operation, DFC imports all files and
(recursively) directories in that directory.
You can also control version labels, object names, object types and formats of
the imported objects.
XML Processing
The line in the example under the comment “Set the XML application” tells
DFC not to determine the controlling XML application automatically but
instead to use the application called CellPhoneCatalog.
You can import XML files without doing XML processing. If node is an
IDfImportNode object, you can turn off XML processing on the node and all
its descendants by calling
node.setFormat(dm_document);
This also turns off content detection, so the operation will not recognize
embedded OLE objects.
Turning off these kinds of processing can shorten the time it takes DFC to
perform the operation.
Processing the Imported Documents
Executing an import operation results in the creation of new objects in the

repository. If impOp is the IDfImportOperation object, you can obtain a
complete list of the new objects by calling
IDfList list = impOp.getNewObjects;
The list contains the object IDs of the newly created SysObjects.
In addition, the IDfImportNode objects associated with the operation are still
available after you execute the operation (see “Working With Nodes” on page
2-9). You can use their methods to find out many other facts about the new
SysObjects associated with those nodes. For example, you can find out object
IDs, object names, version labels, file paths, and formats.

Exporting
The execute method of an IDfExportOperation object creates copies of

documents on the local file system. If the operation’s add method receives a
virtual document as an argument, it also adds all of the document’s
descendants (determined by applying the applicable binding rules), creating a
separate node for each.
Example Export a document to the default checkout directory. Do not create registry
information about the resulting file.
IDfID docId; // ID of the document
// Get an export operation from the factory

IDfExportOperation operation =
(IDfExportOperation) cX.getOperation("Export");
// Add the document and cast the node to the appropriate type
IDfExportNode node = (IDfExportNode) operation.add(docID);
Special Considerations for Export Operations

By default, an export operation creates files on the local system and makes no
provision for Documentum to manage them. You can tell DFC to create
registry entries for the files by invoking the setRecordInRegistry method of an
object of type either IDfExportOperation or IDfExportNode, using the
parameters described in the Javadocs.
If any node corresponds to a checked out document, DFC copies the latest
Docbase version to the local file system. DFC does not treat this as an error.
You can find out where on the file system the export operation creates files.
Use the getDefault DestinationDirectory and getDestinationDirectory
methods of IDfExportOperation objects and the getFilePath method of
IDfExportNode objects to do this.

Checking Out
The execute method of an IDfCheckoutOperation object checks out the

Docbase documents in the operation. Checking out a document is like
exporting one, but the checkout operation:
■ Locks the document
■ Always creates registry entries to enable Documentum to manage the files
it creates on the file system
If the operation’s add method receives a virtual document as an argument, it
also adds all of the document’s descendants (determined by applying the
applicable binding rules), creating a separate node for each.
Example Check out a virtual document to the default checkout directory.
IDfDocument doc; // the root of the virtual document
// Create the virtual document object (see note on page 2-3)

IDfVirtualDocument vDoc = doc.asVirtualDocument("CURRENT", false);
// Get an export operation from the factory

IDfCheckoutOperation checkout =
(IDfCheckoutOperation) cX.getOperation("Checkout");
// Add the virtual document and cast the node to the appropriate type
IDfCheckoutNode node = (IDfCheckoutNode) operation.add(vDoc);

Special Considerations for Checkout Operations

If any node corresponds to a checked out document, there is no need to check
it out again. DFC does not treat this as an error.
DFC applies XML processing to XML documents. If necessary it modifies the
resulting files to ensure that it has enough information to check the
documents in properly.
You can use many of the same methods for setting up checkout operations
and processing results that you use for export operations.

Checking In
The execute method of an IDfCheckinOperation object checks documents into

the repository. It creates new objects as required, transfers the content to the
repository, and removes local files if appropriate. It checks in existing objects
that any of the nodes refer to (for example, through XML links).
Example Check in a document as the next minor version, setting the version labels to
DRAFT and WIP, and taking the content from C:/myfile.doc.
IDfDocument doc; // the document
// Get a checkin operation from the factory
IDfCheckinOperation op =
(IDfCheckinOperation) cX.getOperation("Checkin");
IDfCheckinNode node = (IDfCheckinNode) op.add(doc);
// Set the version and labels
op.setCheckinVersion(IDfCheckinOperation.NEXT_MINOR);
op.setVersionLabels("DRAFT,WIP");
// Override the default filepath

node.setFilePath("C:\\myfile.doc"); //See note on this page.

After executing this code, you can obtain the ID of the document you just
checked in:
IDfId newId = node.getNewObjectId();
Note: to refer to the Windows files (for example, C:\myfile.doc), represent each
backslash by a double backslash (for example, the syntax C:\\myfile.doc). This
works in all Java environments.
Special Considerations for Checkin Operations

Setting up the Operation
To check in a document, you pass an object of type IDfSysObject, not the file on
the local file system, to the operation’s add method. DFC keeps track of which
local files correspond to which objects. If you specify a document that is not
checked out, DFC does not check it in. DFC does not treat this as an error.
You can specify checkin version, symbolic label, or alternate content file, and
you can direct DFC to preserve the local file.
If between checkout and checkin you remove a link between documents, DFC
adds the orphaned document to the checkin operation as a root node, but the
relationship between the documents no longer exists in the repository.
Processing the Checked In Documents
Executing a checkin operation normally results in the creation of new objects

in the repository. If ciOp is the IDfCheckinOperation object, you can obtain a
complete list of the new objects by calling
IDfList list = ciOp.getNewObjects;
The list contains the object IDs of the newly created SysObjects.
In addition, the IDfCheckinNode objects associated with the operation are still
available after you execute the operation (see “Working With Nodes” on page
2-9). You can use their methods to find out many other facts about the new
SysObjects associated with those nodes.

Cancelling Checkout
The execute method of an IDfCancelCheckoutOperation object cancels the

checkout of documents by releasing locks, deleting local files if appropriate,
and removing registry entries.
Example Cancel checkout of a virtual document and preserve the local files.

// Get a cancel checkout operation from the factory

IDfCancelCheckoutOperation op =
(IDfCancelCheckoutOperation) cX.getOperation("CancelCheckout");
IDfCancelCheckoutNode node = (IDfCancelCheckoutNode) op.add(vDoc);
// Tell DFC not to remove the local file

op.setKeepLocalFile(true);

Special Considerations for CancelCheckout Operations

If a document in the cancel checkout operation is not checked out, DFC does
not process it. DFC does not treat this as an error.

Copying
The execute method of an IDfCopyOperation object copies the current versions

of documents or folders from one repository location to another.
If the add method receives a folder (unless you override this default
behavior), it adds all documents and folders linked to that folder. This
continues recursively until the entire hierarchy of documents and subfolders
under the original folder is part of the operation. The execute method
replicates this hierarchy at the target location.
Example Copy a folder.
IDfFolder srcFold; // the source folder
IDfID destId; // ID of the destination folder
// Obtain a copy operation from the factory

IDfCopyOperation op = (IDfCopyOperation) cX.getOperation("Copy");
// Tell DFC to copy the folder and all of its descendants
// (Unnecessary, because this is the default behavior)
op.setDeepFolders(true);
// Add the folder and cast the node to the appropriate type
IDfCopyNode node = (IDfCopyNode) op.add(srcFold);
// Set the destinationfolder

op.setDestinationFolderId(destId);

Special Considerations for Copy Operations

You must set the destination folder, either on the operation or on each node.
You can use the setDeepFolders method of the operation object (node objects
do not have this method) to override the default behavior of recursively
adding folder contents to the operation.

Moving
The execute method of an IDfMoveOperation object moves the current versions

of documents or folders from one repository location to another by unlinking
them from the source location and linking them to the destination. Versions
other than the current version remain linked to the original location.
If the add method receives a folder (unless you override this default
behavior), it adds all documents and folders linked to that folder. This
continues recursively until the entire hierarchy of documents and subfolders
under the original folder is part of the operation. The execute method links
this hierarchy to the target location.
Example Move a virtual document.
IDfID scrId; // ID of the source folder
// Obtain a move operation from the factory

IDfMoveOperation op = (IDfMoveOperation) cX.getOperation("Move");
// Set the source and destination folders

op.setSourceFolderId(srcId);
op.setDestinationFolderId(destId);

IDfMoveNode node = (IDfMoveNode) op.add(vDoc);

Special Considerations for Move Operations
Follow the steps in “Steps for Manipulating Documents” on page 2-6. Options
for moving are essentially the same as for copying.
If the operation entails moving a checked out document, DFC leaves the
document unmodified and reports an error.

Deleting
The execute method of an IDfDeleteOperation object removes documents and

folders from the repository.
Example Delete a document.
IDfDocument doc; // the document
// Obtain a delete operation from the factory

IDfDeleteOperation op = (IDfDeleteOperation) cX.getOperation("Delete");
IDfDeleteNode node = (IDfDeleteNode) op.add(doc);
Example Delete all versions of all documents in a folder. Assume that fold is an object
of type IDfFolder and cX, an IDfClientX object, is a factory for operations.
IDfFolder fold; // the folder
// Obtain a delete operation from the factory

IDfDeleteOperation op = (IDfDeleteOperation) cX.getOperation("Delete");
// Tell DFC to delete all versions of the objects
// Note: You must set this before you add documents or folders
op.setVersionDeletionPolicy(IDfDeleteOperation.ALL_VERSIONS);
// Add the folder and cast the node to the appropriate type
IDfDeleteNode node = (IDfDeleteNode) op.add(fold);

Special Considerations for Delete Operations

If the operation entails deleting a checked out document, DFC leaves the
document unmodified and reports an error.

Validating an XML Document Against a DTD or Schema
DFC uses a modified version of the Xerces XML parser, which it includes in
dfc.jar. See the DFC release notes for details about the specific version and the
Documentum modifications.
The execute method of an IDfValidateOperation object runs the parser in
validation mode to determine whether or not documents are well formed and
conform to the DTD or schema. If you do not specify it explicitly, DFC
determines the XML application automatically and looks in the application’s
folder in the repository for the DTD or schema.
If any argument or the DTD or schema is in the repository, the execute method
copies the content to the file system and performs the validation there.
If the parser detects errors, the operation’s execute method returns a value of
false, and you can use the operation’s getErrors method to obtain the error
information that the parser returns.
Example Validate an XML document, using C:\Temp for a working directory.
IDfDocument doc; // the root of the XML document
// Obtain a validation operation from the factory

IDfValidationOperation op =
(IDfValidationOperation) cX.getOperation("Validation");

// Give DFC a working directory

op.setDestinationDirectory("C:\\Temp"); //See note on page 2-15
IDfValidationNode node = (IDfValidationNode) op.add(vDoc);
Example Validate the XML file C:\ContactInfo.xml, using the DTD associated with the
XML application called TelephoneBook.
// Obtain a validation operation from the factory

IDfValidationOperation op =
(IDfValidationOperation) cX.getOperation("Validation");

// Add the file and cast the node to the appropriate type
IDfOperationNode node =
op.add("C:\\ContactInfo.xml"); //See note on page 2-15
// Set the XML application (see “Setting Parameters for the Operation” on page 2-7)
node.getProperties().putString("XMLApplication", "TelephoneBook");

Special Considerations for Validation Operations

You can use the operation’s setDestinationDirectory method to specify the file
system directory to which the operation exports XML files and DTDs or
schemas to pass to the parser.
In order to specify the XML application you must use the node object’s
getProperties method, as in the second example (see “Setting Parameters for
the Operation” on page 2-7).

Performing an XSL Transformation of an XML Document
DFC uses a version of the Xalan XSL transformation (XSLT) engine, which it
includes in dfc.jar. See the DFC release notes for details about the specific
version and the Documentum modifications.
The execute method of an IDfXMLTransformOperation object uses the XSLT
engine and the specified XSL stylesheet to transform an XML file or
document. It places the output into a new document or attaches it to the
original document as a rendition. It can also output an object of type IDfFile,
or either of the Java types Writer or OutputStream.
Example Transform the file C:\PhoneInfo.xml into an HTML file
C:\PhoneDisplay.htm.
IDfSession sess; // the session to use
IDfDocument style; // the XSL stylesheet in the repository
// Obtain an XML transform operation from the factory

IDfXMLTransformOperation op =
(IDfXMLTransformOperation) cX.getOperation("XMLTransform");
// Add the file to transform (see note on page 2-15)

IDfXMLTransformNode node =
(IDfXMLTransformNode) op.add("C:\\PhoneInfo.xml");
// Specify the stylesheet

op.setTransformation(style);
// Specify the session

// Specify the output file and format (see note on page 2-15)
FileOutputStream outputStream = new
FileOutputStream("C:\\PhoneDisplay.htm");
op.setDestination(outputStream);
op.getProperties().putString("FileFormat", "html");

Example Transform the file C:\ContactInfo.xml into a new HTML document in the
repository, using the stylesheet C:\PublishContact.xsl.

// Obtain an XSLT transformation operation from the factory

IDfXMLTransformOperation tOp =
// Add the file to transform (see note on page 2-15)

IDfXMLTransformNode tNode =
(IDfXMLTransformNode) tOp.add("C:\\ContactInfo.xml");
if (tNode == null) { //See “Handling Document Manipulation Errors” on page 2-26 }
// Specify the stylesheet and session for the transformation

// (see note on page 2-15)
tOp.setTransformation("C:\\PublishContact.xsl");
tOp.setSession(sess);
// Obtain an import operation

IDfImportOperation iOp = cX.getOperation("Import");
// Set the session and destination folder for importing the HTML doc
iOp.setSession(sess);
iOp.setDestinationFolderId(destId);
// Link the operations by specifying the import operation as the

// destination for the transformation operation
tOp.setDestination(iOp);
// Specify the output format
// (Note: on the transform node, not the import node)
tNode.getProperties().putString("FileFormat", "html");
// Execute the transform operation

if (!tOp.execute()){ //See “Handling Document Manipulation Errors” on page 2-26 }
Example Transform an XML document into an HTML rendition of the document.

IDfSession sess; // the session to use
IDfDocument doc; // the root of the XML document
IDfDocument style; // the XSL stylesheet in the repository
// Obtain an XML transform operation from the factory

IDfXMLTransformOperation op =
// Add the XML file to the operation
IDfXMLTransformNode node = (IDfXMLTransformNode) op.add(vDoc);
if (node == null) { //See “Handling Document Manipulation Errors” on page 2-26 }
// Specify the stylesheet and session

op.setTransformation(style);
// Tell DFC to add the output to the document as a rendition

// (see “Setting Parameters for the Operation” on page 2-7)
op.getProperties().putInt("TransformationOption", 0);
// Set up the format for the output

node.getProperties().putString("FileFormat", "html");


if (!op.execute()){ //See “Handling Document Manipulation Errors” on page 2-26 }
Special Considerations for XMLTransform Operations

You must use the operation’s setSession method to specify a Docbase session.
This operation requires a session, even if all of the files it operates on are on
the file system.
The add method of an IDfXMLTransformOperation object accepts Java types
as well as Documentum types. It allows you to specify the file to transform as
an object of any of the following types:
■ IDfDocument, IDfVirtualDocument, or IDfVirtualDocumentNode
■ IDfFile
■ String (for example “C:\\PhoneInfo.xml”)
■ InputStream
■ Reader
■ URL

Handling Document Manipulation Errors

The examples in this chapter illustrate the ways that DFC reports errors that
arise in the course of populating or executing operations.
The add Method Cannot Create a Node
The add method of any operation returns a null node if it cannot successfully
add the document, file or folder that you pass it as an argument. Test for a null
to detect and handle this failure. DFC does not report the reason for returning
a null.
The execute Method Encounters Errors
The execute method of an operation throws DfException only in the case of a

fatal error. Otherwise it creates a list of errors, which you can examine when
the execute method returns or, if you use an operation monitor, as they occur.
Examining Errors After Execution
After you execute an operation, you can use its getErrors method to retrieve
an IDfList object containing the errors. You must cast each to
IDfOperationError to read its error message.
Example Print errors returned by an operation.
//Assume that the following object already exists:
IDfOperation op; // the operation
if (!op.execute()) {
IDfList errors = op.getErrors();
int errorCount = errors.getCount();
if (errorCount > 0) {
for (int i = 0; i < errorCount; i++) {
IDfOperationError error = (IDfOperationError) errors.get(i);
String errorMsg = error.getMessage();
System.out.println(errorMsg);
} } }

After detecting that the operation’s execute method has returned errors, you
can use the operation’s abort method to undo as much of the operation as it
can. You cannot undo XML validation or transform operations, nor can you
restore deleted objects.
Examining Errors in an Operation Monitor
You can monitor the operation for progress and errors. Create a class that
implements the IDfOperationMonitor interface and install it by calling
IDfOperation.setOperationMonitor(). The operation periodically notifies the
operation monitor of its progress or of errors that it encounters.
Example Execute an operation, monitoring progress and checking for errors.
//Assume that the following object already exists:
IDfOperation op; // the operation
Observer // a class that implements IDfOperationMonitor
//Tell DFC about your operation monitor

op.setOperationMonitor(new Observer());
op.execute();
During execution, DFC calls the methods of your Observer instance to report
progress or errors. You can display this information to an end user. In each
case DFC expects a response that tells it whether or not to continue. You can
make this decision in the program or ask an end user to decide.
Your Observer class must implement the following methods:
■ progressReport
DFC supplies the percentage of completion of the operation and of its
current step. DFC expects a response that tells it whether to continue or to
abort the operation.
■ reportError
DFC passes an object of type IDfOperationError representing the error it
has encountered. It expects a response that tells it whether to continue or to
abort the operation.
■ getYesNoAnswer
This is the same as reportError, except that DFC gives you more choices.
DFC passes an object of type IDfOperationError representing the error it
has encountered. It expects a response of yes, no, or abort.
The Javadocs explain these methods and arguments in greater detail.

Operations and Transactions
Operations and Transactions

Operations do not use transactions, because operations
■ Support distributed operations involving multiple docbases.
■ May potentially process vast numbers of objects.
■ Manage non-database resources such as the system registry and the local
file system.
You can undo most operations by calling an operation’s abort method. The
abort method is specific to each operation, but generally undoes Docbase
actions and cleans up registry entries and local content files. Some operations
(for example, delete) cannot be undone.
If you know an operation only contains objects from a single docbase, and the
number of objects being processed is small enough to ensure sufficient
database resources, you can wrap the operation execution in a transaction.

3
DFC Methods by Task 3
This chapter provides an index to the major DFC methods, organized by the
tasks the methods accomplish. The methods appear under the following
categories of Documentum-related activities:
■ “Communicating with the Server” on page 3-2
■ “Administering the System” on page 3-3
■ “Handling Objects” on page 3-5
■ “Retrieving and Setting Attributes” on page 3-10
■ “Searching the Docbase” on page 3-12
■ “Handling Content Objects” on page 3-13
■ “Printing Documents” on page 3-15
■ “Handling Virtual Documents” on page 3-16
■ “Handling Workflows” on page 3-18
■ “Handling Workflow Process Definitions” on page 3-20
■ “Handling Workflow Activity Definitions” on page 3-21
■ “Handling Workflow Work Items” on page 3-22
■ “Managing Inboxes” on page 3-23
Under each category, the methods are grouped by interface.

Some tasks have no associated DFC methods. The apiSet, apiGet, and apiExec
methods of the IDfSession interface enable you to use the Documentum client
library (DMCL) API to perform those tasks. Such tasks appear under the
DMCL headings at the ends of their categories.
The division of Documentum-related tasks into categories that appears in this
chapter parallels the breakdown that appears in Documentum eContent Server
API Reference.
For concepts and terminology not previously introduced in this manual, refer
to Documentum eContent Server Fundamentals.

DFC Methods by Task
Communicating with the Server
Communicating with the Server

The following methods communicate with the server to disconnect, retrieve
messages, or manage explicit transactions.
IDfClient
Establish a session with a Docbase.

IDfSession newSession(
String docbaseName, IDfLoginInfo loginInfo)
IDfSession getSharedSession(String docbaseName, IDfLoginInfo
loginInfo, String key)
IDfSession
End the transaction opened by the last beginTrans call, and discard (roll back,
undo) all of its changes.
void abortTrans()
Start a transaction.
void beginTrans()
Save changes made since the last beginTrans call (commit the change log to
the Docbase), and end the transaction (stop transaction logging).
void commitTrans()
Disconnect the session.

void disconnect()
Obtain a ticket that an application can substitute for the current user’s
password as an argument to the Connect method.
String getLoginTicket()
Return all error and informational messages at or above the specified severity
level for a session.
String getMessage(int severityLevel)

DFC Methods by Task
Administering the System
Specify the maximum number of rows an RDBMS call can return (for
performance tuning).
void setBatchHint(int batchSize)
Shut down the server connected to the session.

void shutdown(boolean immediate, boolean deleteEntry)
Turn on tracing for the server for the session.

void traceDMCL(int level, String traceFile)
DMCL (No Associated DFC Methods)
Shut down a session.

apiExec("kill,session,session_to_kill"[,immediacy_level]
[,message]")

The following methods carry out system administration tasks.
IDfClient
Return information about all Docbases known to the DocBroker.

IDfDocbaseMap getDocbaseMap()
IDfDocbaseMap getDocbaseMapEx(
String protocol,
String hostName,
String portNumber)
Return information about known DocBrokers.

IDfTypedObject getDocbrokerMap()
Note: Not getDocBrokerMap.
Return information about the servers known to the DocBroker.

IDfTypedObject getServerMap(String docbaseName)

DFC Methods by Task
IDfTypedObject getServerMapEx(
String docbaseName,
String protocol,
String hostName,
String portNumber)
IDfSession
Send a DM_ARCHIVE event to the Docbase operator.

IDfId archive(
String predicate,
String operatorName,
int priority,
boolean sendMail,
IDfTime dueDate)
Change the user’s password.

void changePassword(
String oldPasswd,
String newPasswd)
Remove query caches, release memory for the server, or remove data
dictionary information.
void flush(
String flushType,
String cacheKey)
Remove objects in server and client caches.

void flushCache(boolean discardChanged)
Remove files copied to the local common area during a session.

void purgeLocalFiles()
Reinitialize the root process server.

void reInit(String serverConfigName)
Reinitialize the session’s server process.

void reStart(
String serverConfigName,
boolean restartClient)
Queue a restore from archives request to the Docbase operator.

IDfId restore(
String predicate,
String dumpFile,
String operatorName,

DFC Methods by Task
Handling Objects
int priority,
boolean sendMail,
IDfTime dueDate)
Enable auditing of the specified event.

apiSet("audit,session,object_id","event_name")
Return a list of subconnections and the Docbases to which they are connected.
apiGet("dumpconnection[,session]")
Return the subconnection identifier for an existing connection or establish a

new subconnection.
apiGet("getconnection,session,scoping_value[,connect_flag]")
Indicate whether an object type is in the DMCL type cache.

apiGet("iscached,session,typecache,cache_key")
Return the subconnections and the Docbases associated with them for a
specified session.
apiGet("listconnection,session")
Stop auditing an event.

apiSet("unaudit,session,object_id","event_name")
Handling Objects
The following methods manipulate objects.
IDfSession
Create a new persistent object of the specified type, optionally specifying the
fully qualified name of the DFC-derived subclass of IDfPersistentObject.
IDfPersistentObject newObject(String typeName)
IDfPersistentObject newObjectWithType(
String typeName,
String className)

DFC Methods by Task
Handling Objects
Resolve an alias, returning its value.

String resolveAlias(
IDfId sysObject,
String scopeAlias)
IDfPersistentObject
Remove the object from the Docbase.

void destroy()
Retrieve but don’t lock the object.

boolean fetch(String internalType)
Fetch the object from the Docbase again (discard unsaved changes).
void revert()
Save the object, overwriting the copy currently in the Docbase.

void save()
IDfSysObject
Attach a dm_note (annotation) to the object.

void addNote(
IDfId annotationId,
boolean keepPermanent)
Associate a business policy with the object.

void attachPolicy(
IDfId policyId,
String state,
String scope)
Simultaneously check the object out and create a new version branch.
IDfId branch(String versionLabel)
Unlock the object.

void cancelCheckout()
cancelCheckoutEx(
boolean sendMail,
String compoundValue,
String specialValue)

DFC Methods by Task
Handling Objects
Create and save a new version of the checked-out object, and unlock the
previous version.
IDfId checkin(
boolean fRetainLock,
String versionLabels)
IDfId checkinEx(
boolean fRetainLock,
String versionLabels,
String oldCompoundArchValue,
String oldSpecialAppValue,
String newCompoundArchValue,
String newSpecialAppValue)
Create and save a new version of the checked-out object and unlock the
previous version. This method is intended for use internally and by user-
written applications. It differs from checkin by providing arguments that set
the a_special_app and a_compound_architecture attributes.
checkinApp()
Obtain a copy of the object from the repository, and lock it.
void checkout()
IDfId checkoutEx(
String versionLabel,
String compoundArchValue,
String specialAppValue)
Demote the object to an allowable normal state of its lifecycle.

void demote(
String state,
boolean toBase)
Mark the object and, optionally, its associated assembly, as unchangeable.

void freeze(boolean freezeComponents)
Obtain the ID of the remote object pointed to by the object. This only applies if
the object is a local mirror object.
IDfId getRemoteId()
Create an access control entry in the object.

void grant(
String accessorName,
int accessorPermit,
String extendedPermission)
Associate the object with the specified folder or cabinet.

void link(String folderSpec)

DFC Methods by Task
Handling Objects
Assign the specified symbolic labels to the object.

void mark(String versionLabels)
Promote the object to the specified state of its lifecycle, optionally overriding
entry criteria. Optionally, test the entry criteria without promoting the object.
void promote(
String state,
boolean override,
boolean fTestOnly)
Remove all old versions of the object, optionally keeping labeled versions.
void prune(boolean keepSLabel)
Refresh attribute values from the remote object pointed to by the object. This
applies only if the object is a local mirror object.
void refreshReference()
Detach the specified annotation from the object.

void removeNote(IDfId annotationId)
Resolve an alias, returning its value.

String resolveAlias(String scopeAlias)
Move the object from a suspended state to a normal state in its lifecycle.
void resume(
String state,
boolean toBase,
boolean override,
boolean fTestOnly)
Discard unsaved permission changes.

void revertACL()
Remove all access control entries from this object for the specified user or
group.
void revoke(
Create a copy of the object, optionally sharing content.

IDfId saveAsNew(boolean shareContent)
Save the object, overwriting the copy in the Docbase. Keep the lock, and don’t
change the version.
void saveLock()

DFC Methods by Task
Handling Objects
Move the object from the specified lifecycle state to the associated exception
state.
void suspend(
String state,
boolean override,
boolean fTestOnly)
Unfreeze the object and, optionally, unfreeze its associated assembly.

void unfreeze(boolean thawComponents)
Unlink the object from the specified folder or cabinet.

void unlink(String folderSpec)
Remove one or more symbolic labels from an object.

void unmark(String versionLabels)
Specify which ACL to use for the object (folder, user, type, or none).
void useACL(String aclType)
IDfAcl
Create an access control entry in the object.

void grant(
int accessorPermit,
Remove the access control entries or an extended permission for a user or

group.
void revoke(

DFC Methods by Task
Retrieving and Setting Attributes

The following methods manipulate object attributes
IDfSession
Return a description of the attributes of an object type or registered table.

String describe(
String type,
String objType)
Return the data dictionary description of the specified type or attribute.

IDfTypedObject getTypeDescription(
String typeName,
String attribute,
IDfId businessPolicyId,
String state)
IDfTypedObject
Some of the methods of IDfTypedObject that deal with attributes have

different versions for each of the allowed attribute types. In this section the
notation MethodType represents a collection of methods, one for each of the
following values of Type:
Boolean, Double, Id, Int, String, Time, Value
The associated argument or return type declarations, type, are:

boolean, double, IDfId, int, String, IDfTime, IDfValue
For example, the notation appendType refers to the methods:

appendBoolean, appendDouble, appendId, appendInt
appendString, appendTime, appendValue
The declaration of the value parameter for each of these methods is:
boolean value, double value, Id value, int value
String value, IDfTime value, IDfValue value
Add a new value to a repeating attribute.

void appendType(
String attrName,
type value)

DFC Methods by Task
Return the names and values of the object’s attributes.

String dump()
Return the position of an attribute in the object’s indexed set of attributes.

int findAttrIndex(String attrName)
Return the index of the first occurrence of the specified value in the specified
repeating attribute.
int findType(
String attrName,
type value)
Return all the values of the specified repeating attribute, concatenated into a
single string.
String getAllRepeatingStrings(
String attrName,
String separator)
Return the number of attributes the object has.

int getAttrCount()
Return the specified attribute’s datatype, encoded as an integer.

int getAttrDataType(String attrName)
See the IDfType Javadocs for the associated named constants.
Return the value of the specified attribute.

type getType(String attrName)
Return the value at the specified index in the specified repeating attribute.
type getRepeatingType(
String attrName,
int valueIndex)
Return the number of values the specified attribute has (always 1 for a single-
valued attribute).
int getValueCount(String attrName)
Insert a value into a the specified repeating attribute.

void insertType(
String attrName,
int valueIndex,
type value)

DFC Methods by Task
Searching the Docbase
Return True if the specified attribute is repeating, false if it is single-valued.

boolean isAttrRepeating(String attrName)
Remove the value at the specified index from the specified repeating attribute.
void remove(
String attrName,
int valueIndex)
Remove all values from the specified repeating attribute.

void removeAll(String attrName)
Set the value of the specified attribute.

void setType(
String attrName,
type value)
void setRepeatingType(
String attrName,
int valueIndex,
type value)
Remove all values with index greater than or equal to the specified index from
the specified repeating attribute.
void truncate(
String attrName,
int valueIndex)
Searching the Docbase

The following methods execute, process, and close DQL queries.
IDfQuery
Execute a DQL query, and return the results as a collection.

void setDQL(String dqlStatement)
IDfCollection execute(
IDfSession session,
int queryType)

DFC Methods by Task
Handling Content Objects
IDfSession
Return the object (or its ID) that satisfies the search condition, which is the
portion of a SELECT statement that begins with the keyword FROM.
IDfPersistentObject getObjectByQualification
(String qualification)
IDfId getIdByQualification(String qualification)
Return the collection that resulted from the most recently executed query.
IDfCollection getLastCollection()
IDfCollection
An IDfCollection object is like an SQL cursor (see “IDfCollection” on page

5-3). It represents an ordered set of objects of type IDfTypedObject. It has a
current item. Applying a method of IDfTypedObject to the collection applies
that method to the current item (see “Retrieving and Setting Attributes” on
page 3-10).
Close the collection.

void close()
Make the next item in the collection the current item.

boolean next()

The following methods manipulate content objects.
IDfSysObject
Add a rendition to the document, using the specified format and the contents
of the specified file.
void addRendition(
String fileName,
String formatName)

DFC Methods by Task
void addRenditionEx(
String fileName,
String formatName,
int pageNumber,
String storageName,
boolean atomic)
Append information in working memory as the last content file for the
document (used in applications to append content to multipaged documents).
void appendContent(ByteArrayOutputStream content)
Append a content file to the document’s list of files.

void appendFile(String fileName)
Bind a content object belonging to another document to this document at the

specified page number. The content then belongs to both documents.
void bindFile(
int pageNumber,
IDfId srcId,
int srcPageNumber)
Fetch the object’s contents into a byte array stream.

ByteArrayInputStream getContent()
ByteArrayInputStream getContentEx(
String format,
int pageNum)
Fetch the specified content file from the Docbase, and return the file path at
which the system places it.
String getFile(String fileName)
String getFileEx(
String fileName,
String formatName,
int pageNumber,
boolean getResource)
Insert content from a byte array stream into the document at the specified
page. (Used by applications to insert data into multipaged documents.)
void insertContent(
ByteArrayOutputStream content,
int pageNumber)
Insert content from a file into the document.

void insertFile(
String fileName,
int pageNumber)

DFC Methods by Task
Printing Documents
Remove content from the specified page of the object.

void removeContent(int pageNumber)
Remove the specified rendition from the document, optionally saving the
changes to the Docbase as part of the operation.
void removeRendition(String formatName)
void removeRenditionEx(
String formatName,
int pageNumber,
boolean atomic)
Set data in working memory as new content or use it to replace content. (Used
in applications to set the content of an object.)
boolean setContent(ByteArrayOutputStream content)
Identify a file to be new or replacement content for the object.

void setFile(String fileName)
void setFileEx(
String fileName,
String formatName,
int pageNumber,
String otherFile)
Set the next position (byte range) for reading a content collection.
apiExec("seek,session,collection,
position[,direction]")
Printing Documents
The following methods perform print operations.
IDfSysObject
Send a document to a printer.

print(String printer,
boolean printCover,
boolean saveObject,
int numCopies,

DFC Methods by Task
Handling Virtual Documents
int startingContentPage,
int endingContentPage)
Show the print queue for a printer.

apiGet("lpq,session[,printer]")
IDfClient::
apiExec
Remove a print job from a print queue.

apiExec("unprint,session
[,printer_name],job_id")

The following methods manipulate the components of virtual documents.
IDfSysObject
Create an object of type IDfVirtualDocument representing the object.

IDfVirtualDocument asVirtualDocument(
String lateBindingValue,
boolean followRootAssembly)
Add a new component as the last component the virtual document.

IDfId appendPart(
IDfId componentId,
boolean useNodeVerLabel,
boolean followAssembly,
int copyChild)
DFC recognizes a sequential ordering of the components of a virtual
document.

DFC Methods by Task
Create an assembly and associate it with the object.

IDfCollection assemble(
IDfId virtualDocId,
int interruptFreq,
String qualification,
String nodesortList)
Destroy the object’s assembly.

void disassemble()
Mark the object and all components of its assembly as unchangeable.

void freeze(boolean freezeComponents)
Insert the specified component at the specified position among the virtual
document’s components.
IDfId insertPart(
IDfId componentID,
IDfId beforeContainmentId,
double orderNo,
boolean orderNoFlag,
boolean useNodeVerLabel,
int copyChild)
Remove the specified component from the object.

void removePart(
IDfId containmentId,
double orderNo,
boolean orderNoFlag)
Force the server to treat the object as a virtual document, even though it may
have no components.
void setIsVirtualDocument(boolean treatAsVirtual )
Unfreeze the object and, optionally, its assembly.

void unfreeze(boolean thawComponents)
Modify the specified component of the object.

void updatePart(
IDfId containmentId,
double orderNo,
boolean userNodeVerLabel,
int copyChild)

DFC Methods by Task
Handling Workflows
IDfVirtualDocument
The IDfVirtualDocument interface provides methods for manipulating virtual

documents. Refer to the Javadocs for details.
Return paths to a component in one or more virtual documents. This method

provides faster performance than Vdmpathdql but less flexibility in choosing
the paths.
apiGet("vdmpath,session,component_id
[,root_id][,shortest_path]
{,version_list}")
IDfClient::
apiGet
Return paths to a component in one or more virtual documents. This method

provides more flexibility in choosing the paths but slower performance.
apiGet("vdmpathdql,session,
component_id[,root_id]
[,shortest_path][,type]
[,binding_condition][,nodesort_by]")
Handling Workflows
Most of the following methods manage running workflows.
IDfSession
Create and start a custom workflow.

IDfId sendToDistributionList(
IDfList toUsers,
IDfList toGroups,
String instructions,
IDfList objectIDs,
int priority,
boolean endNotification)

DFC Methods by Task
Handling Workflows
IDfWorkflow
Abort the workflow.

void abort()
Attach a package to the specified start activity of the workflow.

IDfId addPackage(
String startActivityName,
String inputPortName,
String packageName,
String packageType,
String noteText,
boolean notePersistent,
IDfList componentIds)
Start the workflow.

void execute()
Halt the specified activity of the workflow.

void halt(int activitySeqNo)
Halt the workflow.

void haltAll()
Notify the workflow about the specified event.

IDfId queue(
String supervisor,
int eventType,
int priority,
boolean sendMail,
IDfTime dueDate,
String message)
Remove a package from the specified start activity of the workflow..

void removePackage(
String startActivityName,
String portName,
String packageName)
Restart the halted workflow or specified failed activity.

void restart(int activitySeqNo)
Resume a halted activity of the workflow.

void resume(int activitySeqNo)

DFC Methods by Task
Handling Workflow Process Definitions
Resume the halted workflow.

void resumeAll()
Handling Workflow Process Definitions

The following methods help you create and manage workflow process
definitions.
IDfProcess
Add an activity to a process definition.

void addActivity(
String actName,
IDfId actId,
String actType,
int actPriority)
Create a link to connect the specified output port of the specified source
activity to the specified input port of the specified destination activity (all
ports and activities are already part of the process definition).
void addLink(
String linkName,
String linkSrcActivity,
String linkSrcPortName,
String linkDestActivity,
String linkDstPortName)
Install the validated process definition and, if necessary, its activities. Specify
whether to resume or to abort workflows that are based on this definition.
void install(
boolean installActivity,
boolean resume)
Remove the specified activity from the process definition.

void removeActivity(String actName)
Remove the specified link from the process definition.

void removeLink(String linkName)
Move the installed process definition back to the validated state.

void uninstall()

DFC Methods by Task
Handling Workflow Activity Definitions
Validate the process definition.

void validate()
Handling Workflow Activity Definitions

The following methods help you define and manage process activities.
IDfActivity
Add the specified package to the specified port of the activity definition.
void addPackageInfo(
String portName,
String packageName,
String packageType,
IDfId packageId,
String packageLabel,
String packageOperation)
Add the specified port to the activity definition.

void addPort(
String portName,
String portType)
Add the specified route case (a conditional selection of a set of destination

ports—like a line in a case statement) to the activity definition.
void addRouteCase(
String routeCaseIdentifier,
String condition,
IDfList outputPorts)
Install the validated activity definition.

void install()
Remove the specified package from the specified port of the activity
definition.
void removePackageInfo(
String portName,
String packageName)
Remove the specified port from the activity definition.

void removePort(String portName)

DFC Methods by Task
Handling Workflow Work Items
Remove the specified route case from the activity.

void removeRouteCase(String routeCaseIdentifier)
Uninstall the validated activity definition.

void uninstall()
Validate the package definitions associated with the activity definition.

void validate()
Handling Workflow Work Items

The following methods manage work items.
IDfWorkitem
Acquire the work item for the performer.

void acquire()
Attach the specified package to the work item.

IDfId addPackage(
String packageName,
String packageType,
IDfList componentIds)
Mark the work item as finished. If desired, return additional information.

void complete()
void completeEx(
int returnValue,
String execOSError,
IDfId execResultId)
Delegate the work item to the specified user.

void delegateTask(String user)
Suspend the work item.

void pause()
Remove the specified package from the work item.

void removePackage(String packageName)

DFC Methods by Task
Managing Inboxes
Designate a list of additional users or groups to receive the work item when
the performer finishes it.
void repeat(IDfList list)
Move the paused work item to the dormant state.

void resume()
Managing Inboxes
The following methods manage inboxes (user queues).
IDfSession
Remove the specified item from the user’s queue.

void dequeue(IDfId stampId)
Return the collection of unread items in the user’s queue.

IDfCollection getEvents()
Return True if there are unread items in the user’s queue.

boolean hasEvents()
IDfSysObject
Register the user to receive notification if the specified event happens to the
object.
void registerEvent(
String message,
String event,
int priority,
boolean sendMail)
Remove the specified event registration from the object.

void unRegisterEvent(String event)

DFC Methods by Task
Managing Inboxes

4
Managing DFC Sessions 4
This chapter describes the way to work with DFC sessions and a Docbase
map. The examples in it are based on the classes DfExSession and
DfExDocbaseMap, which are available in Java and Visual Basic versions from
The chapter contains the following main sections:
■ “About Sessions” on page 4-1
■ “Connecting and Disconnecting” on page 4-2
■ “Using a Docbase Map” on page 4-6
About Sessions
In order to use DFC, you must provide login information and establish a DFC
session with a Documentum server. The following section, “Connecting and
Disconnecting” on page 4-2, shows how to do this.
The DFC client (see “Creating DFC Client Objects” on page 1-8) issues server
commands and accesses data via the session. Table 4-1 describes the types of
DFC sessions.
Table 4-1 DFC Session Types
Type Description DFC Method
Shared Can be shared across components getSharedSession
Private Used by only one component newSession
Adopted DMCL session used as a DFC session adoptDMCLSession

Managing DFC Sessions
Connecting and Disconnecting
Shared Sessions
If you ask for a shared session, DFC returns an existing one or creates a new
one for you. Using shared sessions decreases the number of sessions you must
connect and disconnect yourself.
To establish a shared session, you must specify a session key. For security
reasons, there is no DFC method to retrieve this key, so you must save it if you
need to use it again. To use a specific shared session, you must know its key.
Adopted Sessions
To create an adopted session, DFC uses the ID of an existing DMCL session,

that is, a session established by a direct call to the connect method. When
migrating pre-DFC customizations, you may find adopted sessions
convenient. Otherwise, Documentum recommends establishing sessions
through DFC.
To prevent synchronization problems, DFC allows a DMCL session to be
adopted only once. Adopted sessions cannot be shared.
Note: You cannot disconnect an adopted session through DFC. After you
unadopt an adopted session with the DFC unadopt method, you must use the
disconnect server API to disconnect the underlying DMCL session.

As explained in “Programming with DFC” on page 1-2, the IDfClient interface
provides the programmer’s gateway into DFC. It handles basic connection
details and loads the necessary shared libraries.
You obtain the initial IDfClient interface by calling the static method
DfClient.getLocalClient. The IDfClient interface then serves as a factory for
IDfSession objects.
In order to create a session to a Docbase, you must provide login information.
The examples in DfExSession contain code to obtain this information from the
user. The examples in this chapter suppress the user interaction and error
checking. For example, the line
li.setUser(DfExUtils.gUsername);

in the Java version and the line

li.setUser DfExMainForm.txtUsername.Text
in the Visual Basic version both assume that the corresponding mechanism
returns a valid user name.
The code that establishes the session is
sess = client.newSession(docbase, li);
in the Java version and
Set sess = client.newSession
(DfExMainForm.cbxDocbase.Text, li)
in the Visual Basic version. In either case, the call can produce a DfException.
The Java code uses a try block followed by a catch statement to handle this
exception. The visual Basic code uses an On Error statement and an error
handling section to accomplish the same thing.
connectToDocbase in Java
//Connect to the Docbase.
IDfSession connectToDocbase() throws IOException {
IDfSession sess = null;
String docbase = null;
try {
//Get local client object that calls into DMCL40 to connect
//to Documentum servers - this is the entrance to DFC
IDfClient client = DfClient.getLocalClient();
//Set up login credentials.

IDfLoginInfo li = new DfLoginInfo();
//Assume user has entered user name, password,

//and Docbase via DfExUtils
li.setUser(DfExUtils.gUsername);
li.setPassword(DfExUtils.gPassword);
docbase = DfExUtils.gDocbase; //Connect to docbase

sess = client.newSession(docbase, li);
if(sess.isConnected()) {
System.out.println("\nConnected");
}
} catch(DfException dfe) {
System.out.println("\n" + dfe.toString());
}
return sess;
}

disconnectFromDocbase in Java
boolean disconnectFromDocbase(IDfSession sess) {
boolean retVal = false;
try {
if(sess.isConnected()) { //If session is connected
sess.disconnect(); // Disconnect
if(!sess.isConnected()) { // If disconnect succeeded
retVal = true; // Report success
} else { // If disconnect failed
//ERROR ACTION // Take error action
}
} else { //If session not connected
//ERROR ACTION // Take error action
}
}
return retVal;
}
displaySessionInfo in Java
//Display details about the active session.
void displaySessionInfo(IDfSession s) {
try {
System.out.println("\nDocbase : " + s.getDocbaseName());
System.out.println("Srvr Vers : " + s.getServerVersion());
System.out.println("DBMS : " + s.getDBMSName());
System.out.println("Owner : " + s.getDocbaseOwnerName());
System.out.println("Sess Id : " + s.getSessionId());
System.out.println("DMCL Sess Id: " + s.getDMCLSessionId());
System.out.println("Docbase Id : " + s.getDocbaseId());
System.out.println("Scope : " + s.getDocbaseScope());
System.out.println("User : " + s.getLoginUserName());
System.out.println("Login Ticket: " + s.getLoginTicket());
System.out.println("Security : " + s.getSecurityMode());
} }
connectToDocbase in Visual Basic

Function connectToDocbase(sess As IDfSession) As IDfSession
Dim clientx As New DfClientX
Dim client As IDfClient
Dim li As IDfLoginInfo
On Error GoTo ErrorHandler
Set connectToDocbase = Nothing

If sess Is Nothing Then
Set client = clientx.getLocalClient 'Get client object
Set li = clientx.getLoginInfo 'Get login info object
li.setUser DfExMainForm.txtUsername.Text 'Assume username,
li.setPassword DfExMainForm.txtPassword.Text 'password,domain,

li.setDomain DfExMainForm.txtDomain.Text 'and Docbase

'from DfExMainForm
'Establish the session
Set sess = client.newSession(DfExMainForm.cbxDocbase.Text, li)
End If
Set connectToDocbase = sess

Exit Function
ErrorHandler:
writeDiagnostic Err.Description, False
End Function
disconnectFromDocbase in Visual Basic

Function disconnectFromDocbase(sess As IDfSession) As Boolean
Dim retVal As Boolean
disconnectFromDocbase = retVal
If sess.isConnected Then 'If session is connected

sess.disconnect ' Disconnect
If Not sess.isConnected Then ' If disconnect succeeded
retVal = True ' Report success
Set sess = Nothing
Else ' If disconnect failed
'ERROR ACTION ' Take error action
End If
Else 'If session not connected
'ERROR ACTION ' Take error action
End If
disconnectFromDocbase = retVal
Exit Function
ErrorHandler:
End Function
displaySessionInfo in Visual Basic

Sub displaySessionInfo(sess As IDfSession)
writeDiagnostic "Docbase: " + sess.getDocbaseName(), False

writeDiagnostic "Server Version: " + sess.getServerVersion(), False
writeDiagnostic "DBMS: " + sess.getDBMSName(), False
writeDiagnostic "Owner: " + sess.getDocbaseOwnerName(), False
writeDiagnostic "Session: " + sess.getSessionId(), False
writeDiagnostic "DMCL Session: " + sess.getDMCLSessionId(), False
writeDiagnostic "Docbase Id: " + sess.getDocbaseId(), False
writeDiagnostic "Docbase Scope: " + sess.getDocbaseScope(), False
writeDiagnostic "Current User: " + sess.getLoginUserName(), False
writeDiagnostic "Login Ticket: " + sess.getLoginTicket(), False
writeDiagnostic "Security Mode: " + sess.getSecurityMode(), False
Exit Sub
ErrorHandler:
End Sub

Using a Docbase Map
Using a Docbase Map

The Documentum system uses intermediaries called docbrokers to help client
programs connect to Docbases. Each Docbase projects (that is, sends its
address and identifying information) to one or more docbrokers. A client
program connects to a docbroker, after which it can communicate with any
Docbase that projects to that docbroker.
displayDocbaseInfo in Java
void displayDocbaseInfo(IDfDocbaseMap m, int idx){
try {
System.out.println("Docbase: " + m.getDocbaseName(idx));
System.out.println("Descrip: " + m.getDocbaseDescription(idx));
System.out.println("Id : " + m.getDocbaseId(idx));
System.out.println("Server : " + m.getServerVersion(idx));
} catch (DfException dfe) {
} }
connectToDocbase(map, index) in Java

void connectToDocbase(IDfDocbaseMap m, int idx)
throws IOException {
try {
DfExSession exSess = new DfExSession(); //Create session object
DfExUtils.gDocbase = m.getDocbaseName(idx); //Connect
IDfSession sess = exSess.connectToDocbase();
if (sess != null) {
System.out.println("\nConnected: " + m.getDocbaseName(idx));
DfExUtils.getInput("\nRETURN to continue...");
exSess.disconnectFromDocbase(sess); //Disconnect
}
} }
Step through Docbases in Java

static void main (String argv[]) throws IOException {
DfExDocbaseMap exDbMap = new DfExDocbaseMap();
try {
// Get a DFC local client object
IDfDocbaseMap m = client.getDocbaseMap();
System.out.println("\nHost: " + m.getHostName() + "\n");

Using a Docbase Map
for (int i = 0; i < m.getDocbaseCount(); i++) {

exDbMap.displayDocbaseInfo(m, i); // Display details
exDbMap.connectToDocbase(m, i);
}
} }
displayDocbaseInfo in Visual Basic

Sub displayDocbaseInfo(m As IDfDocbaseMap, idx As Integer)
writeDiagnostic "Name : " + m.getDocbaseName(idx), False
writeDiagnostic "Descrip: " + m.getDocbaseDescription(idx), False
writeDiagnostic "Id : " + m.getDocbaseId(idx), False
writeDiagnostic "Server : " + m.getServerVersion(idx), False
Exit Sub
ErrorHandler:
End Sub
connectToDocbase(name) in Visual Basic

Sub connectToDocbase(docbaseName As String)
Dim sess As IDfSession
Dim exSess As New DfExSession 'Instantiate session obj
DfExMainForm.cbxDocbase.Text = docbaseName
Set sess = exSess.connectToDocbase(sess) 'Connect to Docbase
If Not sess Is Nothing Then
writeDiagnostic "Connected to: " +
docbaseName, False
exSess.displaySessionInfo sess 'Display session details
exSess.disconnectFromDocbase sess 'Disconnect
End If
Exit Sub
ErrorHandler:
End Sub

Using a Docbase Map

5
Managing Docbase Queries
with DFC 5
This chapter describes the way to use DFC to create and perform queries and
to process the results. The examples in it are based on the class
DfExSimpleQuery, which is available in Java and Visual Basic versions on
You can find out more about queries by examining the DfExFullTextQuery
class. This manual does not contain examples from that class.
Queries
DFC provides an easy-to-use mechanism for querying the Docbase and
processing the query results. You use a query object to submit the query, and
receive the results in a collection object.
Flow of Query Processing
The general flow of query processing is as follows.
➤ To query the Docbase and process the results:

1. Obtain an IDfClient interface by calling DfClient.getLocalClient.
2. Create a session, sess, by calling newSession or getSharedSession on the
IDfClient object.
3. Obtain an IDfQuery object, q:
■ For Java-based DFC programs, call new DfQuery.
■ For Visual Basic and C++ programs, call the getQuery method of
IDfClientX.

Managing Docbase Queries with DFC
Queries
4. Create a DQL query as a text string, dq.

5. Call q.setDQL(dq) to set the DQL string into the query object.
6. Call q.execute(sess, querytype) to execute the query.
The arguments of the execute method include a session reference, because the
query is not tied to the session, and a code for the type of query to execute.
The method returns an IDfCollection, col. The session remains locked until the
execute method returns.
7. Iterate through the IDfCollection by calling col.next() until it returns False.
Obtain values from an IDfCollection by calling the various get methods of
IDfTypedObject (the parent type of IDfCollection).
For example, if you know that attribute 0 of the object at the current row of the
collection is a string, the following code prints it:
IDfAttr attr = col.getAttr(0)
System.out.println(typedObj.getString(attr.getName()))
If you don’t know that the attribute is a string, you can find out what it is by
calling
attr.getDataType()
and changing the second line above according to what getDataType returns.
8. Close the IDfCollection and IDfSession objects.
IDfQuery has no close method, because a query object is not tied to a session.
Note: the number of sessions available to an application is limited. If you do
not close them, you make it more likely that you will exhaust the supply.
Be careful to close open collections and sessions even in the event of an
exception. The best place for a Java program to call close is in a finally block,
because Java executes a finally block whether there is an exception or not.
IDfQuery
An IDfQuery object holds a DQL query string and allows you to perform that
query in any session. You pass the session and the query to the execute
method, and it returns results as an IDfCollection object.

Basic Query Examples
IDfCollection
An IDfCollection object is like an SQL cursor. It contains references to the

objects that the query returns, in an ordered sequence of rows. The collection
points to one row of data at a time. You must call next before accessing the
first row (if the collection is empty, the first call to next returns False).
Note: An IDfCollection is a typed object. You access the current row’s data by
calling the IDfTypedObject methods getBoolean, getInt, getString, and so
forth, as if the collection were the same as its current row. You should not, and do
not need, to call the collection’s getTypedObject method unless you want to
save the current row for later use (compare the code in Step 7 on page 5-2,
which does not call getTypedObject, with the code in “displayResults in
Visual Basic” on page 5-4, which does call getTypedObject).
execQuery in Visual Basic

Function execQuery(
sess As IDfSession, 'Session
queryString As String) 'Query string
As IDfCollection 'Return a collection

Dim col As IDfCollection
Dim q As IDfQuery
Set execQuery = Nothing 'Initialize return value
Set q = clientx.getQuery 'Create query object

q.setDQL queryString 'Give it the query string
Set col = q.execute(sess, 'Execute the query and get

DFCLib.IDfQuery_DF_READ_QUERY) ' back a collection
Set execQuery = col 'Set the return value

Exit Function
ErrorHandler:
End Function

displayResults in Visual Basic

'Step through a collection
Sub displayResults(col As IDfCollection)
Dim resItems As Integer

Dim attr As IDfAttr
Dim tObj As IDfTypedObject
Dim msg As String
resItems = 0 'Count rows

While (col.Next()) 'Step thru rows
Set tObj = col.getTypedObject
resItems = resItems + 1
writeDiagnostic "\nRow: " + CStr(resItems), False 'Display row num
For i = 0 To (tObj.getAttrCount() - 1) 'For each attribute
Set attr = tObj.GetAttr(i)
msg = attr.getName() + ": " ' Display name
If attr.getDataType = DFCLib.DF_BOOLEAN Then ' Display value
writeDiagnostic msg + ' using method
CStr(tObj.getBoolean(attr.getName)), False ' for its type
ElseIf attr.getDataType = DFCLib.DF_DOUBLE Then
writeDiagnostic msg +
CStr(tObj.getDouble(attr.getName())), False
ElseIf attr.getDataType = DFCLib.DF_ID Then
tObj.getId(attr.getName()).getId, False
ElseIf attr.getDataType = DFCLib.DF_INTEGER Then
CStr(tObj.getInt(attr.getName())), False
ElseIf attr.getDataType = DFCLib.DF_STRING Then
tObj.getString(attr.getName()), False
ElseIf attr.getDataType = DFCLib.DF_TIME Then
tObj.getTime(attr.getName()).toString(), False
Else 'Unknown type
'ERROR ACTION ' Handle error
End If
Next i
Wend
col.Close
Exit Sub
ErrorHandler:
End Sub

execQuery in Java
IDfCollection execQuery(IDfSession sess, String queryString)
{
IDfCollection col = null; //For the result
try {
IDfQuery q = new DfQuery(); //Create query object
q.setDQL(queryString); //Give it the query
col = q.execute(sess, DfQuery.DF_READ_QUERY); //Execute synchronously
}
return col;
}
displayResults in Java
//Step through a collection and display results
void displayResults(IDfCollection col) throws IOException
{
try {
int resItems = 1; //Count rows
while (col.next()) {
System.out.println("\nResult row: " + resItems++); //Display row num
for (int i = 0; i < col.getAttrCount(); i++) { //For attribute
IDfAttr attr = col.getAttr(i);
System.out.print("\t" + attr.getName() + ": "); // Display name
if (attr.getDataType() == attr.DM_BOOLEAN) { // Display value
System.out.println( // using method
col.getBoolean(attr.getName())); // for its type
} else if (attr.getDataType() == attr.DM_DOUBLE) {
System.out.println(
col.getDouble(attr.getName()));
} else if (attr.getDataType() == attr.DM_ID) {
System.out.println(
col.getId(attr.getName()).toString());
} else if (attr.getDataType() == attr.DM_INTEGER) {
System.out.println(
col.getInt(attr.getName()));
} else if (attr.getDataType() == attr.DM_STRING) {
System.out.println(
col.getString(attr.getName()));
} else if (attr.getDataType() == attr.DM_TIME) {
System.out.println(
col.getTime(attr.getName()).toString());
} else { //Unknown type
//ERROR ACTION // Handle error
} } }
col.close(); //Close collection
} }


6
Automating Business Rules
with DFC 6
This chapter describes the way to work with Documentum features that help
you automate your business rules. The examples in it are based on the classes
DfExSimpleValidation andDfExACL, which are available in Java and Visual
Basic versions at www.documentum.com/developer/samplecode.htm.
Documentum provides other ways to automate business rules (for example
workflows and document lifecycles). The Documentum eContent Server
Fundamentals manual describes those facilities. This manual does not contain
examples of using DFC to work with workflows and document lifecycles.
This chapter contains the following main sections:
■ “Checking Objects Against Validation Rules” on page 6-1
■ “Changing Permissions” on page 6-2
■ “Using Private ACLs” on page 6-5
■ “ACL Utility Methods” on page 6-7
Checking Objects Against Validation Rules
validate in Java
// Perform validation
void validate(
IDfSession sess, //Session
String objIdStr, //ID of the object to validate
String attrName) //Attribute to validate (null or "" = perform both
// object level and attribute level validation)
throws DfValidationException, IOException
{
try {
IDfId objId = new DfId(objIdStr);
IDfPersistentObject perObj = sess.getObject(objId);

Automating Business Rules with DFC
Changing Permissions
IDfValidator validator = perObj.getValidator();

IDfType type = perObj.getType();
if (attrName == null || attrName.equals("")) {

validator.validateAll(null, false);
} else {
if (type.findTypeAttrIndex(attrName) < 0) {
//ERROR ACTION
return;
}
// validate the value of the specific attribute
validator.validateAttrRules(attrName, null, null);
}
} }
changeBasicPermissions in Visual Basic

'Change and display object permissions
Sub changeBasicPermissions(
objId As String, 'ID of obj for which to change permissions
anotherUser As String) 'A user to whom to assign permissions

Dim sysObjId As IDfId
Dim pObj As IDfPersistentObject
'Use ID string to obtain the ID, then the object

Set sysObjId = clientx.getId(objId)
Set sysObj = sess.GetObject(sysObjId)
displayBasicPermissions sysObj 'Display the object's permissions
sysObj.grant anotherUser, 6, "" 'Grant the user and dm_world

sysObj.grant "dm_world", 6, "" ' WRITE permission
Set pObj = sysObj 'Make the object persistent

pObj.save ' then save it
displayBasicPermissions sysObj 'Display the object's permission
sysObj.revoke anotherUser, "" 'Revoke the user's permissions

sysObj.grant "dm_world", 3, "" 'Grant dm_world READ permission

displayBasicPermissions sysObj 'Display the object's permission

Set sysObjId = Nothing 'Free memory

Set sysObj = Nothing
Exit Sub
ErrorHandler:
End Sub
changeExtendedPermissions in Visual Basic

'Change and display extended object permissions
Sub changeExtendedPermissions(
objId As String, 'ID of obj for which to change permissions
anotherUser As String) 'A user to whom to assign permissions


displayExtendedPermissions sysObj 'Display the ext permissions
sysObj.grant anotherUser, 6, "CHANGE_STATE" 'Grant WRITE and CHANGE_STATE

sysObj.revoke anotherUser, "CHANGE_STATE"

sysObj.revoke anotherUser, ""

Set sysObjId = Nothing 'Free memory

Set sysObj = Nothing
Exit Sub
ErrorHandler:
End Sub
changeBasicPermissions in Java
//Change and display object permissions
void changeBasicPermissions(

String objId, //ID of obj for which to change permissions

String anotherUser) //A user to whom to assign permissions
throws IOException {
try {
//Use ID string to obtain the ID, then the object
IDfId sysObjId = new DfId(objId);
IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId);
displayBasicPermissions(sysObj); //Display the object's permissions
//Grant the user and dm_world WRITE permission

sysObj.grant( anotherUser, 6, "");
sysObj.grant("dm_world", 6, "");
sysObj.save(); //Save the object

//Revoke the user's permissions and grant dm_world READ permission
sysObj.revoke(anotherUser, "");
sysObj.grant ("dm_world", 3, "");


} }
changeExtendedPermissions in Java
//Change and display extended object permissions
void changeExtendedPermissions(
String objId, //ID of obj for which to change permissions
String anotherUser) //A user to whom to assign permissions
throws IOException
{
try {
displayExtendedPermissions(sysObj); //Display the ext permissions
//Grant the user WRITE and CHANGE_STATE permissions

sysObj.grant(anotherUser, 6, "CHANGE_STATE");

displayExtendedPermissions(sysObj); //Display the ext permissions
sysObj.revoke(anotherUser, "CHANGE_STATE"); //Revoke user's CHANGE_STATE

sysObj.revoke(anotherUser, ""); //Revoke user's basic perms

displayBasicPermissions(sysObj); //Display the ext permissions

} }

Using Private ACLs
Using Private ACLs
privateACLs in Visual Basic

'Create a private ACL and apply it to an object
Sub privateACLs(
objId As String, 'Object with which to associate the ACL
permission As String, 'Permission to grant world and owner
extPermission As String, 'Ext permissions to grant world and owner
aclName As String) 'Name of ACL to create

Dim oldACL As IDfACL
Dim newACL As IDfACL

'Create a new ACL object and give it the specified name

Set pObj = sess.newObject("dm_acl")
pObj.apiSet "set", "object_name", aclName
'Grant the specifiedpermissions to owner and world
pObj.apiExec "grant", "dm_owner," + permission + "," + extPermission
pObj.apiExec "grant", "dm_world," + permission + "," + extPermission
pObj.save 'Save the new private ACL

Set oldACL = sysObj.getACL 'Save the object's current ACL
'Instantiate an instance of the new private ACL

Set newACL = sess.getACL(sess.getLoginUserName(), aclName)
sysObj.setACL newACL 'Apply new ACL to the sysobject

Set pObj = sysObj 'Use persistent obj interface to
pObj.save ' save it with its new ACL
displayBasicPermissions sysObj 'Display the new permissions

displayExtendedPermissions sysObj
sysObj.setACL oldACL 'Apply old ACL to the sysobject

pObj.save 'Save it (pObj & sysObj are the same)
displayBasicPermissions sysObj 'Display restored permissions

displayExtendedPermissions sysObj
Set sysObj = Nothing 'Free memory

Set sysObjId = Nothing
Set oldACL = Nothing
Set newACL = Nothing
Exit Sub
ErrorHandler:

Using Private ACLs

End Sub
privateACLs in Java
//Create a private ACL and apply it to an object
void privateACLs(
String objId //Object with which to associate the ACL
String permission, //Permission to grant to world and owner
String extPermission, //Ext permissions to grant world and owner
String aclName //Name of ACL to create
) throws IOException {
try {
//Create a new ACL object and give it the specified name

IDfPersistentObject pObj = (IDfPersistentObject)sess.newObject("dm_acl");
pObj.apiSet("set", "object_name", aclName);
//Grant the specified permissions to owner and world
pObj.apiExec("grant", "dm_owner," + permission + "," + extPermission);
pObj.apiExec("grant", "dm_world," + permission + "," + extPermission);
pObj.save(); //Save the new private ACL

IDfACL oldACL = sysObj.getACL(); //Save the object's current ACL
// Instantiate an instance of the new private ACL

IDfACL newACL = sess.getACL(sess.getLoginUserName(), aclName);
sysObj.setACL(newACL); //Apply new ACL to the sysobject

sysObj.save(); //Save sysobject with its new ACL
displayBasicPermissions(sysObj); //Display new permissions

displayExtendedPermissions(sysObj);
sysObj.setACL(oldACL); //Apply old ACL to the sysobject

sysObj.save(); //Save sysobj with restored ACL
displayBasicPermissions(sysObj); //Display restored permissions

displayExtendedPermissions(sysObj);

} }

ACL Utility Methods
ACL Utility Methods
permissionToString in Visual Basic

'Convert permission code to name
Function permissionToString(permission As String) As String
If permission = "1" Then permissionToString = "NONE"

ElseIf permission = "2" Then permissionToString = "BROWSE"
ElseIf permission = "3" Then permissionToString = "READ"
ElseIf permission = "4" Then permissionToString = "NOTE"
ElseIf permission = "5" Then permissionToString = "VERSION"
ElseIf permission = "6" Then permissionToString = "WRITE"
ElseIf permission = "7" Then permissionToString = "DELETE"
End If
Exit Function
ErrorHandler:
End Function
extendedPermissionToString in Visual Basic

'Convert extended permission code to name
Function extendedPermissionToString(permission As String) As String
If permission = "1" Then extendedPermissionToString = "CHANGE_STATE"

ElseIf permission = "2" Then extendedPermissionToString = "CHANGE_PERMIT"
ElseIf permission = "3" Then extendedPermissionToString = "CHANGE_OWNER"
ElseIf permission = "4" Then extendedPermissionToString = "EXECUTE_PROC"
ElseIf permission = "5" Then extendedPermissionToString = "CHANGE_LOCATION"
End If
Exit Function
ErrorHandler:
End Function
displayBasicPermissions in Visual Basic

'Display object permissions
Sub displayBasicPermissions(sysObj As IDfSysObject)
writeDiagnostic
" ACL Name: " +
sysObj.getACLName, False 'ACL name

ACL Utility Methods
For i = 0 To (sysObj.getAccessorCount - 1) 'For each accessor

writeDiagnostic
" Accessor: " + ' Name
sysObj.getAccessorName(i) +
" Permission: " + ' Permission
permissionToString(sysObj.getAccessorPermit(i)), False
Next i
Exit Sub
ErrorHandler:
End Sub
displayExtendedPermissions in Visual Basic

'Display the object's extended permissions
Sub displayExtendedPermissions(sysObj As IDfSysObject)
writeDiagnostic
" ACL Name: " + sysObj.getACLName, False 'ACL name
For i = 0 To (sysObj.getAccessorCount - 1) 'For each accessor

writeDiagnostic
" Accessor: " + sysObj.getAccessorName(i) + ' Name
" Extended Permissions: " +
sysObj.getAccessorXPermitNames(i), False ' Extended permissions
Next i
Exit Sub
ErrorHandler:
End Sub
permissionToString in Java
//Convert permission code to name
String permissionToString(String permission)
{
String retVal = null;
if (permission.equals("1")) retVal = "NONE";

else if (permission.equals("2")) retVal = "BROWSE";
else if (permission.equals("3")) retVal = "READ";
else if (permission.equals("4")) retVal = "NOTE";
else if (permission.equals("5")) retVal = "VERSION";
else if (permission.equals("6")) retVal = "WRITE";
else if (permission.equals("7")) retVal = "DELETE";
return retVal;
}

ACL Utility Methods
extendedPermissionToString in Java
//Convert extended permission code to name
String extendedPermissionToString(String permission)
{
String retVal = null;
if (permission.equals("1")) retVal = "CHANGE_STATE";

else if (permission.equals("2")) retVal = "CHANGE_PERMIT";
else if (permission.equals("3")) retVal = "CHANGE_OWNER";
else if (permission.equals("4")) retVal = "EXECUTE_PROC";
else if (permission.equals("5")) retVal = "CHANGE_LOCATION";
return retVal;
}
displayBasicPermissions in Java
//Display object permissions
void displayBasicPermissions(IDfSysObject sysObj)
{
try {
System.out.println(
"\tACL Name: " + //ACL name
sysObj.getACLName());
for (int i = 0; i < sysObj.getAccessorCount(); i++) { //For each accessor

System.out.println(
"\tAccessor: " + //Name
sysObj.getAccessorName(i) +
" Permission: " + //Permission
permissionToString(sysObj.getAccessorPermit(i)));
}
} }
displayExtendedPermissions in Java
//Display the object's extended permissions
void displayExtendedPermissions(IDfSysObject sysObj)
{
try {
System.out.println(
"\tACL Name: " + sysObj.getACLName()); //ACL name
for (int i = 0; i < sysObj.getAccessorCount(); i++) { //For each accessor

System.out.println(
"\tAccessor: " + sysObj.getAccessorName(i) + // Name
" Extended Permissions: " +
sysObj.getAccessorXPermitNames(i)); // Ext permissions
}
} }

ACL Utility Methods

7
Overview of the DFC
Interface Hierarchy 7
This chapter moves through the DFC interfaces that derive from the
Documentum object type hierarchy, starting from the top. It contains the
following major sections:
■ “Documentum Object Hierarchy” on page 7-1
■ “Typed Objects” on page 7-8
■ “Persistent Objects” on page 7-12
■ “Persistent Objects Without Associated Content” on page 7-16
■ “SysObjects—Persistent Objects With Content” on page 7-20
■ “IDfSession” on page 7-22
■ “IDfClient” on page 7-27
■ “Common Package” on page 7-30
Documentum Object Hierarchy

Everything you manipulate in Documentum is an object. Documents,
cabinets, folders, and even users are objects. Objects have associated
characteristics called attributes (or properties), and associated operations
called methods. Each object has a type, which is a template for objects of that
kind. All objects of a given type have the same sets of attributes and methods.
When the server creates an object, it uses the type description as a model. For
example, document objects belong to the dm_document type. When you
create a new document, the server uses the dm_document type description to
create the new document object. The names of all system-defined type names
begin with the prefix dm_.

Overview of the DFC Interface Hierarchy
Attributes are fields that are part of the object. The values in these fields
describe the object. For example, two of the attributes for a document object
are title and subject. When you create a document, you provide a title and
subject that are specific to that document. Attributes are either single-valued
or multi-valued (repeating). Some are read only and some can be read or
written.
Using DFC, you operate on objects through interfaces that represent the
object. Because the Documentum model and DFC are both object-oriented, a
large part of the DFC structure corresponds directly to the Documentum
object type structure. DFC provides interfaces corresponding to most system-
defined object types. The interface has separate set and get methods for each
of the type’s attributes, and it has methods that pertain to objects of that type.
You read or change the attribute values via the get and set methods, and you
operate on the object through the interface’s methods.
By the conventions of object-oriented programming, a method without
arguments performs the corresponding operation on its associated object. For
example, the statement
document.save();
appears in the example on page 1-4. It tells the document object to apply its
save method to itself, that is, to save the document in the Docbase. Methods
that operate on other objects take references to those objects as arguments.
Subtypes and Supertypes
Documentum object types exist in a hierarchy. A supertype is an object type

that is the basis for another object type, called a subtype. The subtype inherits
the attributes of the supertype. The subtype can also have additional
attributes of its own. Within the hierarchy, an object type can be a supertype, a
subtype, both, or neither.
For example, the dm_folder type is a subtype of dm_sysobject. It has all the
attributes defined for dm_sysobject plus two defined specifically for
dm_folder. A type can be both a supertype and a subtype. For example,
dm_folder is a subtype of dm_sysobject and a supertype of dm_cabinet.
Documentum lets you create your own object types. You can create a type
with no supertype, defining all of its attributes yourself, or you can create a
subtype of any of the following types:
■ dm_sysobject and its subtypes

■ dm_user and its subtypes

■ dm_relation
■ User-defined types
Persistence
Most objects the server manipulates are persistent, that is, they reside in the
Docbase and persist across sessions. A document you create and save in one
session is still there in another session on another day.
Some objects are not persistent, that is, they do not reside in the Docbase. The
server creates them as needed at runtime. For example, collection objects and
query result objects, which return the results of DQL statements, are not
persistent. When the server executes a DQL query it creates a collection object
to contain the results of the query. It creates a query result object for each row
that the underlying database returns for the underlying SELECT statement,
and it associates the query result objects with the collection object. When you
close a collection, the server destroys the collection object and the query result
objects.
DFC Interface Hierarchy
DFC exposes most of the Documentum object hierarchy as a set of interfaces.

An interface defines a contract between an implementation class and any
client that uses instances of that class. Interfaces do not specify
implementation. They simply define a set of methods with specific signatures
and specific semantics. A class provides the implementation, but as an
application programmer, you usually don’t need to know which class. If you
hold a reference to a class that implements a given interface, you know that
objects of that class have all of the functionality that the interface promises.
DFC includes a default implementation for each interface.
For example, to operate on a document object, obtain an IDfDocument
interface from DFC (this is an abbreviated way to say “obtain an object that
implements the IDfDocument interface”). That interface allows you to read or
set the object’s attributes, attach content to the object, check the object into or
out of a Docbase, and so forth. It doesn’t matter whether the implementation
class is DfDocument (DFC’s default implementation of the IDfDocument
interface) or another class that properly implements the functionality. By
separating the implementation from the definition, interfaces isolate client

code from changes in the underlying implementation. DFC’s use of interfaces

promotes customization, because it allows customers to substitute their own
implementations for DFC’s default implementations.
DFC does not provide an interface for every server object type. Sometimes
you must use the DFC interface that corresponds to a supertype of a given
object type. For example, to write code to operate on cabinets, you must use
IDfFolder (dm_folder is the parent, or supertype, of dm_cabinet).
Some DFC interfaces correspond to operations that are independent of server
object types. For example, the IDfLoginInfo interface, which allows you to
assemble and maintain access information, does not correspond to a server
object type.
Another example is IDfPersistentObject. The IDfPersistentObject interface
defines functionality common to all server objects that derive from
dm_persistentobject. The type dm_persistentobject is the base type of all
server objects that persist beyond the current session, but you cannot create a
dm_persistentobject in the server, nor can you run a query that selects objects
from the type dm_persistentobject. The server only allows the creation and
querying of objects of types that are subtypes of dm_persistentobject. In DFC,
on the other hand, IDfPersistentObject is a common type for arguments or
return values.
You can operate on a more derived type with a less-derived interface, but
some methods are available only on more derived interfaces. For example,
you cannot perform a save on the IDfTypedObject interface. To save, you must
hold a reference to an IDfPersistentObject interface or an interface that derives
from IDfPersistentObject. Similarly, to perform checkins and checkouts on an
object whose type derives from dm_sysobject, you need to refer to that object
with at least an IDfSysObject interface.
A small subset of the Documentum object hierarchy appears in Figure 7-1.
DFC interfaces are in the top (white) parts of the boxes. The corresponding
server objects are in the lower (gray) parts.

Figure 7-1 DFC Hierarchy Corresponds to Documentum Object Hierarchy
IDfTypedObject
Non-Persistent Type
IDfDocbaseMap IDfPersistentObject IDfCollection

Docbase Locator Persistent Object Non-Persistent
IDfACL IDfFormat IDfGroup IDfSysObject IDfType IDfUser

dm_acl dm_format dm_group dm_sysobject dm_type dm_user
IDfDocument IDfFolder
dm_document dm_folder
<None>
dm_cabinet
In Figure 7-2 on page 7-6, you can see how the interfaces that derive from the
Documentum hierarchy fit into the total DFC interface hierarchy.

Figure 7-2 DFC Interface Hierarchy
IDfTypedObject
IDfPersistentObject
IDfACL
IDfAliasSet
IDfAssembly
IDfContainment
IDfFormat
IDfGroup
IDfPackage
IDfQueueItem
IDfRelation
IDfRelationType
IDfActivity
IDfSysObject
IDfDocument
IDfType
IDfFolder
IDfUser
IDfProcess
IDfWorkItem
IDfRouter
IDfWorkflow
IDfCollection
IDfDocbaseMap

IDfOperation
IDfCancelCheckoutOperation
IDfCheckinOperation
IDfCheckoutOperation
IDfCopyOperation
IDfDeleteOperation
IDfExportOperation
IDfImportOperation
IDfMoveOperation
IDfOperationNode
IDfCancelCheckoutNode
IDfCheckinNode
IDfCheckoutNode
IDfCopyNode
IDfDeleteNode
IDfExportNode
IDfImportNode
IDfMoveNode
IDfClientRegistryObject
IDfCheckedOutObject
IDfLocalObject
IDfViewedObject
DFC interfaces that are not in the above diagrams are not part of the interface
hierarchy. They do not derive from other DFC interfaces, and vice versa.

Typed Objects
Typed Objects
The IDfTypedObject interface provides the basis for both persistent and non-
persistent types. Here are the main facts about typed objects:
■ They have attributes (properties) that you can retrieve and set.
■ In almost all cases, you obtain them directly or indirectly through a DFC
session; therefore they have a reference to the session that created them.
■ A unique object ID identifies them.
The ID of a persistent object uniquely identifies the object in the Docbase. The
ID of a non-persistent object, such as a collection or a Docbase map, identifies
the object only for the session that creates it.
The DFC online reference contains signatures of the methods of DFC
interfaces (see “Using the DFC Online Reference Documentation” on page
1-11). This section describes the general categories of methods of the
IdfTypedObject interface. IDfTypedObject is the base object for most DFC
objects.
Session and Identifier
Typed objects have IDs, and they hold references to the session that created
them. The IDfTypedObject methods getSession and getObjectId return this
information.
Getting and Setting Attribute Values
An attribute of a Documentum object can contain either a single value or

multiple values. An attribute that can have multiple values is called a
repeating-value attribute or just a repeating attribute.
Documentum defines the following types for attribute values: Boolean,
Integer, String, ID, Time, and Double.
The IDfTypedObject methods for setting and getting attribute values reflect
these types. For single-valued attributes, call one of the following methods:
boolean getBoolean(String attrName)
double getDouble(String attrName)
IDfId getId(String attrName)

Typed Objects
int getInt(String attrName)

String getString(String attrName)
IDfTime getTime(String attrName)
IDfValue getValue(String attrName)
The argument attrName refers to the attribute, such as object_name.
Regardless of the type of the attribute, you can call getString to retrieve the
value in the form of a string. If you call a get method that is inappropriate for
the type of the attribute, for example, getInt("object_name"), DFC attempts to
convert the value to that type.
To set the value of a single-valued attribute, call one of the following methods,
where attrName is the name of the attribute and value is the value you want
to assign to that attribute:
void setBoolean(String attrName, boolean value)
void setDouble(String attrName, double value)
void setId(String attrName, IDfId value)
void setInt(String attrName, int value)
void setString(String attrName, String value)
void setTime(String attrName, IDfTime value)
void setValue(String attrName, IDfValue value)
There are several sets of methods that relate to repeating attributes. The server
maintains an indexed array of values for a repeating attribute.
For example, the authors attribute may contain the following values with the
specified indexes:
[0] Sleepy
[1] Dopey
[2] Happy
[3] Sneezy
[4] Grumpy
[5] Doc
[6] Bashful
Methods that operate on repeating attributes often take an index, which
specifies which value the operation should affect. The descriptions that follow
refer to the authors listed above.
The set and get methods for repeating attributes are similar to the set and get
methods for single-valued attributes:
boolean getRepeatingBoolean(String attrName, int index)
double getRepeatingDouble(String attrName, int index)
IDfId getRepeatingId(String attrName, int index)
int getRepeatingInt(String attrName, int index)
String getRepeatingString(String attrName, int index)

Typed Objects
IDfTime getRepeatingTime(String attrName, int index)

IDfValue getRepeatingValue(String attrName, int index)
void setRepeatingBoolean(
String attrName, int index, boolean value)
void setRepeatingDouble(
String attrName, int index, double value)
void setRepeatingId(
String attrName, int index, IDfId value)
void setRepeatingInt(
String attrName, int index, int value)
void setRepeatingString(
String attrName, int index, String value)
void setRepeatingTime(
String attrName, int index, IDfTime value)
void setRepeatingValue(
String attrName, int index, IDfValue value)
You can use single-value attribute methods to set/get repeating attributes and
repeating-attribute methods to get/set single valued attributes. Single-valued
methods always operate on the repeating attribute value at index 0. To use a
repeating-attribute method for a single-valued attribute, the index argument
must be 0.
The call
getAllRepeatingStrings(String attrName, String separator)
returns all values of a repeating attribute as a single string with values
delimited by separator, or by a comma if separator is null.
For example, given the authors mentioned above,
getAllRepeatingStrings("authors", null)
returns the string
Sleepy,Dopey,Happy,Sneezy,Grumpy,Doc,Bashful
Additional Methods for Operating on Repeating Attributes
The following methods operate on repeating attributes. Type stands for

Boolean, Double, Id, . . ., and datatype represents boolean, double, IDfId, . . . .
void appendType (String attrName, datatype value)
void insertType (String attrName, int index, datatype value)
int findType (String attrName, datatype value)
int getValueCount (String attrName)
void remove (String attrName, int index)

Typed Objects
void removeAll (String attrName)

void truncate (String attrName, int index)
The appendType methods add values to the end of a repeating attribute’s list
of values. For example, to add an eighth dwarf, call
myobj.appendString ("authors", "Burpy")
The insertType methods are similar, but they add the value at the specified
index rather than at the end. To make Burpy the fourth dwarf, call
myobj.insertString ("authors", 3, "Burpy")
Generally, appending is more efficient, because insertions can force the server
to copy existing values to new index locations.
The find methods retrieve the first index at which a specified value appears.
For example, findString ("authors", "Happy") returns 2.
The remove method deletes the value at the specified index. The truncate
method deletes all values from the specified index onward. The removeAll
method deletes all values from the specified repeating attribute. The
getValueCount method returns the number of values the specified repeating
attribute has.
Attribute Information
IDfTypedObject has a number of methods that allow you to get information

about the object’s attributes:
String dump()
int getAttrCount()
boolean hasAttr(String attrName)
boolean isAttrRepeating(String attrName)
IDfAttr getAttr(int index)
Enumeration enumAttrs()
The dump method is for debugging. It returns the object’s attributes and
values in a formatted string.
The getAttrCount method returns the number of attributes that the object has.
The hasAttr method returns a boolean value indicating whether the object’s
type has the specified attribute.
The isAttrRepeating method returns a boolean value indicating whether the
specified attribute is repeating (True) or single (False).

Persistent Objects
The getAttrDataType method returns an integer representing the attribute’s

type (see the DFC online reference for IDfAttr for the possible return values).
The attributes of a Documentum object have a column order. The
findAttrIndex method returns the column index of the specified attribute.
The getAttr and enumAttrs methods provide more detailed information about
the specified attribute. The getAttr method returns an IDfAttr object for the
attribute at the specified index. An IDfAttr object allows you to get the
attribute’s name and type. IDfAttr also allows you to determine whether an
attribute is repeating. If an attribute is of type String, the maximum character
length of any value stored in that attribute may be obtained by calling
IDfAttr’s getLength method.
The enumAttrs method returns an enumeration of IDfAttr objects. This
enables you to iterate over all of the object’s attributes.
Persistent Objects
Persistent objects are at the second level of the DFC interface hierarchy. They
are typed objects that reside in the Docbase. The IDfPersistentObject interface
inherits from the IDfTypedObject interface, and hence, IDfPersistentObject
has all the methods of IDfTypedObject. In addition IDfPeristentObject has the
following sets of methods.
Methods Relating to the Basic Properties of Persistent Objects
Every object in the Docbase has an i_vstamp attribute, which contains the
number of committed transactions that have changed the object. This value is
used for versioning, as part of the locking mechanism, to ensure that one user
does not overwrite the changes made by another. The getVStamp method
returns this value.
You can replicate Documentum objects, that is, have them appear in more
than one Docbase. The isReplica method returns True if the object is a local
replica of an object in a remote Docbase.
Every object in the Docbase has an object type. DFC exposes the type through
the IDfType interface. To obtain an object’s type information, call the getType
method.

Persistent Objects
Basic Operations on an Object
IDfPersistentObject defines the following methods that affect or query the

state of an object in the current session or in the Docbase:
void save()
void destroy()
boolean isDeleted()
boolean isNew()
boolean isDirty()
void fetch()
void revert()
The save method directs the server to store the local copy of the object into the
Docbase. When you create a new Docbase object, others cannot see it until you
explicitly call its save method. Saving an existing object fails if your version of
the object is older than the object in the Docbase, that is, if the i_vstamp of
your version contains a lower number than the i_vstamp of the object in the
Docbase. This happens if another user saves changes to the object between the
time you obtain a copy and the time you try to save it. You can prevent this
from happening by checking out the object before changing it.
The destroy method directs the server to remove the object from the Docbase.
The isDeleted method tells you whether the object has been destroyed in the
current session. This method does not detect deletion by another user or even
in another session subsequent to the time that you obtained the local copy.
The isNew method returns False if the object has ever been successfully saved
in the Docbase.
The isDirty method returns True if you have made unsaved changes to the
local copy of the object.
The fetch method obtains the latest version of the object from the Docbase if
and only if the Docbase version has a newer i_vstamp. If the values are the
same, the local copy retains any changes you have made.
The revert method obtains the latest version of the object from the Docbase
unconditionally. The local copy loses any changes you have made to it.

Persistent Objects
Audit Trail
Auditing enables you to record information about system events and preserve
information in an audit trail, which you can then use to track events and
generate reports. You choose which events to monitor, and the audit system
logs pertinent data, including the time of the event. To support this process,
IDfPersistentObject has the signoff method, which creates an audit trail entry
of signoff information for an object.
Convenience Methods for Creating Object Relations
Documentum provides the dm_relation type to enable you to define

relationships between objects. The IDfPersistentObject interface has methods
that create a relationship between the persistent object and another persistent
object specified as an argument.
Other methods return information about the object’s relationships (see the
DFC online reference for more information):
IDfRelation addChildRelative(
String relationTypeName, IDfId childId, String childLabel,
boolean isPermanent, String description)
IDfRelation addParentRelative(
String relationTypeName, IDfId parentId, String childLabel,
boolean isPermanent, String description)
void removeChildRelative(
String relationTypeName, IDfId childId, String childLabel)
public void removeParentRelative(
String relationTypeName, IDfId parentId, String childLabel)
public IDfCollection getChildRelatives(
String relationTypeName)
public IDfCollection getParentRelatives(
String relationTypeName)
Validation Methods
DFC provides the IDfValidator interface, which makes it easy to validate

proposed new or changed attribute values against information in the data
dictionary. Normally, you need to do this when you interact with a user to
obtain the attribute values. A related interface, IDfValueAssistance, supports
providing contitional value assistance in the user interface.

Persistent Objects
The following method returns an IDfValidator object for the persistent object:
IDfValidator getValidator()
You can also obtain an IDfValidator interface for an IDfType object:
IDfValidator getValidator(IDfID policy, String state)
The IDfValidator interface provides a variety of utilities:
void validateAll(IDfProperties attrValues, boolean
modifiedAttrsOnly)
void validateAllAttrRules(IDfProperties attrValues, boolean
modifiedAttrsOnly)
void validateAllObjRules(IDfProperties attrValues)
void validateAttrRules(String attrName, IDfList values,
IDfProperties depAttrValues)
IDfValueAssistance getValueAssistance(String attrName,

IDfProperties depAttrValues)
boolean hasValueAssistance(String attrName)
IDfProperties getValueAssistanceDependencies(String attrName)
void setMaxErrorBeforeStop(int stopAfterNumOfErrors)

int getMaxErrorBeforeStop()
String getWidgetType(int environment, String attrName)

void setTimePattern(String timePattern)
String getTimePattern()
IDfPersistentObject getAssociatedObject()
String getObjectType()
IDfId getPolicyID()
String getStateName()
Pass-Through Methods to the DMCL API
IDfPersistentObject provides methods that invoke the DMCL dmAPIGet,

dmAPISet, and dmAPIExec methods. These IDfPersistentObject methods
automatically insert the session ID and the object ID in the appropriate places.
Use these methods only where necessary, that is, to access functionality that is
not available via DFC. Calling these methods bypasses built-in support for
validation:
String apiGet(String cmd, String args)
boolean apiSet(String cmd, String args, String value)
boolean apiExec(String cmd, String args)

Persistent Objects Without Associated Content

The level of the object hierarchy below IDfPersistentObject contains
IDfSysObject, which is the root type for all objects that have associated
content. Most user types extend IDfSysObject. Discussion of IDfSysObject
appears in a subsequent section
The other types at the level of the object hierarchy below IDfPersistentObject
relate to the administration and operation of the Docbase. The following
sections discuss these types.
IDfACL
IDfACL provides the functionality associated with the server type dm_acl. An
access control list (ACL), also called a permission set, is the usual server
mechanism for controlling who has access to an object. If the Docbase security
mode is set to acl, then every sysobject (that is, every object of type
dm_sysobject or of a type that derives from dm_sysobject) has an associated
ACL that specifies which users can operate on an object and what they can do.
The Documentum eContent Server Fundamentals manual discusses the two kinds
of permissions: basic and extended. Chapter 6, Automating Business Rules
with DFC contains an extended example of how to use DFC to work with
these permissions.
IDfFormat
IDfFormat provides the interface methods for obtaining the attribute

information from a dm_format object.
A format object contains information about a file format recognized by the
server. All content stored in the Docbase has an associated format such as
msw8 (Microsoft Word 97 document), pdf (Acrobat PDF document), or html
(an HTML file). All sysobjects that have associated content keep the content
type in the a_content_type attribute. This value corresponds to a dm_format
object.
Administrators can create new format objects for formats that the server does
not support automatically. Format objects provide the information necessary
to open a viewer or editor appropriate to the content type.

IDfUser and IDfGroup
The server documentation contains information about how to work with

users and groups. Refer to the DFC online reference for details of the IDfUser
and IDfGroup interfaces and their methods.
IDfType
IDfType provides methods for getting information about a type. IDfType

provides the following categories of information.
Basic Attributes
The getName method returns the type’s name—a string like dm_format or
dm_document.
The getDescription method returns the type’s user-friendly name from the
data dictionary. The user interface uses the user-friendly name. For example, a
search dialog box may display the name Format rather than dm_format.
Parent Type Information
Most types derive from other types. Firms that deploy Documentum usually
create several layers of new types to meet their specific needs. IDfType
provides the following methods to test whether the type derives from another
type:
String getSuperName()
IDfType getSuperType()
boolean isSubTypeOf(String typeName)
The getSuperName method returns the name of the type’s parent type, or null
if the type has no parent type. For example, if you hold an IDfType reference
to the dm_document type, getSuperName returns dm_sysobject.
The method getSuperType returns an IDfType reference to the supertype.
You can call isSubTypeOf to test whether a type is a subtype of another type.
For example, if you hold an IDfType reference to the dm_document type,
isSubTypeOf("dm_sysobject") returns True. By convention, a type is
not a subtype of itself, so isSubTypeOf("dm_document") returns False.

Type Information
Programs typically make use of IDfType objects to get information about the
attributes of that type. The type dm_type contains several repeating attributes
that describe the attributes of the type. The DFC methods for most of these
attributes come in two varieties. One takes an index into the array of repeating
attributes; the other takes a string specifying the attribute name. The indexed
methods are slightly more efficient.
The following IDfType methods return type information:
int getTypeAttrCount()
String getTypeAttrNameAt(int index)
int getTypeAttrDataTypeAt(int index)
int getTypeAttrDataType(String attrName)
boolean isTypeAttrRepeatingAt(int index)
boolean isTypeAttrRepeating(String attrName)
int getTypeAttrLengthAt(int index)
int getTypeAttrLength(String attrName)
int findTypeAttrIndex(String attrName)
String getTypeAttrDescriptionAt(int index)
String getTypeAttrDescription(String attrName)
The getTypeAttrCount method returns the number of attributes the type has.
The method getTypeAttrNameAt returns the attribute name at the specified
index. To find an attribute’s index, call findTypeAttrIndex. The indexes start at
zero. The above get type attribute methods return the type of the attribute.
This is one of the following values:
IDfType.DF_BOOLEAN
IDfType.DF_INTEGER
IDfType.DF_STRING
IDfType.DF_ID
IDfType.DF_TIME
IDfType.DF_DOUBLE
IDfType.DF_UNDEFINED
They return IDfType.DF_UNDEFINED only in unusual circumstances.
The isRepeating methods indicate whether the attribute is repeating.
For attributes whose type is DF_STRING, the getTypeAttrLengthAt and
getTypeAttrLengthAt methods return the maximum character length of any
string that can be stored in that attribute. For attributes of other types, these
methods return 0.

The get type attribute description methods return attribute descriptions from
the data dictionary. This information does not reside in the dm_type object.
Recall that IDfType derives from IDfPersistentObject, which, in turn, derives
from IDfTypedObject. IDfTypedObject has the following methods:
Enumeration enumAttrs()
IDfAttr getAttr(int index)
int getAttrCount()
boolean hasAttr(String attrName)
isAttrRepeating(String attrName)
Developers often find this confusing. Calling these methods on an IDfType
object returns information about the attributes of the type dm_type, not the
type that the IDfType object describes.
For example, suppose that the IDfType object named doctype describes the
type dm_document. The method doctype.getAttrCount returns 15, even
though dm_document has almost 70 attributes. The reason is that
getAttrCount returns the number of attributes that dm_type has, not the
number of attributes that dm_document has.
To get the number attributes for dm_document, call
doctype.getTypeAttrCount
Similarly, if you call doctype.getAttrDataType("object_name"), DFC throws an
exception, because dm_type does not have an attribute called "object_name".
To discover the type of the dm_document attribute object_name, call
getTypeAttrDataType("object_name").
All IDfType methods that return attribute information about the type that the
IDfType object describes have method names that begin with getTypeAttr. The
methods inherited from IDfTypedObject return information about dm_type.

SysObjects—Persistent Objects With Content

IDfSysObject provides the functionality associated with sysobjects, that is,
objects of the type dm_sysobject. Sysobjects can do the following:
■ Own content.
■ Be checked into and out of the Docbase.
■ Have an ACL to control access.
■ Reside in a folder.
■ Be versioned.
■ Be part of a virtual document.
■ Have an attached business policy (document lifecycle).
Types that need any of these capabilities derive from dm_sysobject. Since the
primary focus of Docbases is content, most objects in the Docbase are either
SysObjects or objects whose type derives from dm_sysobject.
Basic Operations on SysObjects
The IDfSysObject interface has a large number of methods. Some of these

methods perform the same basic functions as correspondingly named
methods in the operations package. In general, you should always use the
version from the operations package.
Refer to the DFC online reference for detailed information. The Documentum
eContent Server Fundamentals manual provides the conceptual background.
The following functional categories provide an overview of IDfSysObject:
■ Checkout/Checkin
These methods are mainly for internal use. See Chapter 2, Working With
Documents, for the correct way to perform these tasks.
■ Content-Related
The eContent Server Fundamentals manual discusses content, renditions,
and file formats.
■ Versioning
Documentum provides implicit versions, major and minor version
changes, version labels, and branching.Security

Documentum provides two kinds of permissions: basic and extended. A

user can have one basic permission level, and each basic permission level
includes the capabilities of all of the lower levels. Users can also have any
combination of the extended permissions. “Using Private ACLs” on page
6-5 and “ACL Utility Methods” on page 6-7 contain examples of how to
use DFC to work with basic and extended permissions.
■ Folder-Related
Documentum provides folder and cabinet objects to organize the contents
of a Docbase. All SysObjects and SysObject subtypes (except cabinets)
must reside in a cabinet or in a folder.
■ Virtual Document
A virtual document is a compound document whose components are
either simple documents or other virtual documents. The content that
users see is the content files associated with these components. A virtual
document can also have its own associated content file (or files). The
components of virtual documents can have a mixture of formats.
■ Business Policy
Business policies are also known as document lifecycles (DLCs). The
Documentum eContent Server Fundamentals manual explains how DLCs
work.
Types That Derive From IDfSysObject
An IDfDocument object contains information about a document. Documents

can be simple documents or virtual documents. In a simple document, the
content generally seen by a user is in one or more content files associated with
the document. IDfDocument is a logical interface for operating on
documents, but it does not add attributes or methods to those found in
IDfSysObject.
Documentum provides a folder and cabinet paradigm for organizing the
documents in a Docbase. Cabinet objects are top-level folders and cannot
reside in other folders or cabinets. A folder must reside in a cabinet or in
another folder. DFC does not provide an IDfCabinet interface, so use an
IDfFolder interface to operate on cabinet references.
The dm_cabinet type has an attribute is_private, which is not an attribute of
dm_folder. To retrieve this value, call the getBoolean method inherited from
IDfTypedObject. For example,

IDfSession
boolean bIsPrivate = myCabinet.getBoolean("is_private");

Folders and cabinets do not usually have associated content. They derive from
IDfSysObject because folders use the ACL security mechanism.
The preceding sections discuss all of the interfaces in Figure 7-1, except for
IDfDocbaseMap and IDfCollection. Discussion of those interfaces follows the
discussion of the IDfSession and IDfClient interfaces.
IDfSession
All interaction with a Docbase occurs in a session, that is, using an IDfSession
object. In broad terms, a session:
■ Uses the underlying DMCL library to maintain a connection to a Docbase.
■ Maintains the state of the interaction between an application and the
Docbase.
■ Caches information to increase performance.
A session keeps track of the objects you fetch and change. It provides
explicit and implicit transaction support. The underlying DMCL does most
of this, but DFC also caches some information and maintains some state.
■ Provides service methods for creating and fetching objects, performing
administrative tasks, and obtaining session information.
An IDfSession provides the following categories of functionality.
Provide Information
The following methods ask for information that the session has access to:
IDfClient getClient();
IDfLoginInfo getLoginInfo()
String getDBMSName()
String getDMCLSessionId()
String getDocbaseId()
String getDocbaseName()
String getDocbaseOwnerName()
String getLoginUserName()
String getSecurityMode()
String getServerVersion()

IDfSession
String getSessionId()
boolean isACLDocbase()
boolean isAdopted()
boolean isConnected()
boolean isRemote()
boolean isShared()
Note: be careful not to write getRDBMSName for getDBMSName. The
version without the “R”is correct.
Create Objects and Obtain Object References
Developers sometimes ask why they can’t create a new SysObject as follows:
obj = new DfSysObject;
The short answer is that all persistent objects reside in the Docbase, so you can
create or fetch them only through a session. “Programming with DFC” on
page 1-2 discusses this point in more detail.
The getObject methods return IDfPersistentObject interfaces, because
IDfPersistentObject is the most derived interface that is general to all of the
possible return types. For example, getObject could return an IDfType, an
IDfUser, an IDfDocument, or an IDfFolder (among other possibilities). The
only interfaces common to those types are IDfTypedObject and
IDfPersistentObject. IDfPersistentObject is the more derived. The effect of this
is that Java code must provide an explicit cast. For example
IDfFormat format =
(IDfFormat) mysession.getObjectByQualification
("dm_format where name = 'tex');
The following methods support creating objects and obtaining object
references:
int getDefaultACL()
IDfACL getACL(String aclDomain, String aclName)
IDfFolder getFolderByPath(String folderPath)
IDfFormat getFormat(String formatName)
IDfGroup getGroup(String groupName)
IDfId getIdByQualification(String qualification)
IDfPersistentObject getObject(IDfId objectId)
IDfPersistentObject getObjectByPath(String objectPath)
IDfPersistentObject getObjectByQualification(
String qualification)
IDfPersistentObject getObjectWithType(
IDfId objectId, String objType, String className)
DfPersistentObject newObject(String typeName)

IDfSession
DfPersistentObject newObjectWithType(
String typeName, String className)
DfType getType(String typeName)
DfTypedObject getTypeDescription(
String typeName, String attribute, IDfId businessPolicyId,
String state)
DfUser getUser(String userName)
DfUser getUserByOSName(
String userOSName, String userOSDomain)
Configuration Information
The eContent Server documentation discusses configuration objects (see the

sections dealing with apiconfig, sessionconfig, and serverconfig).
The IDfClient interface provides the following methods. They return typed
objects, because they return configuration information, not Docbase objects.
IDfTypedObject getClientConfig() throws DfException;
IDfTypedObject getConnectionConfig()
IDfTypedObject getDocbaseConfig()
IDfTypedObject getDocbrokerMap()
IDfTypedObject getServerConfig()
IDfTypedObject getServerMap(String DocbaseName)
IDfTypedObject getSessionConfig()
Transaction Support
The following are the basic methods for managing transactions:

void abortTrans()
void beginTrans()
void commitTrans()
Docbase Scope
Docbase scope tells the server which Docbase a method applies to. In many
cases this does not change; in other cases, the server can determine it by
examining a method argument that conveys the scope implicitly. For example,
if one of the method’s arguments is an object ID, the server can determine the
Docbase scope from the ID.

IDfSession
The following are the basic methods for managing Docbase scope when
necessary:
String getDocbaseScope()
String setDocbaseScope(String DocbaseName)
String setDocbaseScopeById(IDfId objectId)
Multithreading Support
If more than one thread can access a session, you must take care to lock and
unlock the session before using it.
The following IDfSession methods provide this capability:
boolean lock(int timeoutInMsec);
boolean unlock();
You can lock the session explicitly (calling a method of IDfSession) or
implicitly (calling a method of IDfPersistentObject, because persistent objects
hold a reference to a session).
Generally, you should lock and unlock blocks of code. If you lock and unlock a
session at too fine a granularity, performance suffers and you increase the
chance of making a mistake. If you lock too big a chunk of code, you cause
other threads to wait needlessly, also hurting performance.
DFC does not enforce the locking mechanism on sessions, so a multithreaded
application must be careful to lock and unlock the session. Failure to do so can
cause crashes. The need to protect a session against concurrent access applies
to both shared sessions and private sessions (sessions obtained through the
newSession call), but you must be especially careful if you share sessions
across components in a multithreaded environment. You don’t need to lock
and unlock a session if only one thread at a time can use it.
Tip: In Java you can use the finally statement to ensure that a thread releases
its lock when it dies.
Tip: Lock sessions during transactions to prevent synchronization problems.
API Calls
Occasionally, an application needs to interact directly with the session’s

underlying DMCL programs in ways for which DFC does not provide
interfaces. The following routines allow such interactions:

IDfSession
ByteArrayInputStream apiGetBytes(
String cmd, String args, String buf,
String buflen, int length)
IDfCollection apply(
String objId, String functionName, IDfList args,
IDfList dataType, IDfList values)
IDfCollection getLastCollection()
IDfList apiDesc(String api)
String apiGet(String cmd, String args)
String describe(String type, String objType)
String getMessage(int severityLevel)
boolean apiExec(String cmd, String args)
boolean apiSet(String cmd, String args, String value)
boolean apiSetBytes(
String cmd, String args, ByteArrayOutputStream content)
void traceDMCL(int level, String traceFile)
Inbox and Workflow
The Documentum eContent Server Fundamentals manual explains the way

workflow templates and workflows work.
The following methods pertain to inboxes and workflows:
IDfCollection getTasks(
String userName, int filter,
String additionalAttributes, String orderBy)
IDfId sendToDistributionList(
IDfList toUsers, IDfList toGroups,
String instructions, IDfList objectIDs,
int priority, boolean endNotification)
IDfWorkflowBuilder newWorkflowBuilder(IDfId processId)
String resolveAlias(IDfId sysObject, String scopeAlias)
void dequeue(IDfId stampId)
IDfCollection getEvents()
boolean hasEvents()
IDfCollection getRunnableProcesses(
String additionalAttributes)
Administration
The following methods support system administration:

IDfId archive(
String predicate, String operatorName, int priority,
boolean sendMail, IDfTime dueDate)

IDfClient
IDfId restore(
String predicate, String dumpFile, String operatorName,
int priority, boolean sendMail, IDfTime dueDate)
void changePassword(String oldPasswd, String newPasswd)
void reInit(String serverConfigName)
void reStart(String serverConfigName, boolean restartClient)
void shutdown(boolean immediate, boolean deleteEntry)
Session State
The following methods enable you to control certain aspects of the session:
void disconnect()
void flush(String flushType, String cacheKey)
void flushCache(boolean discardChanged)
void purgeLocalFiles()
void setBatchHint(int batchSize)
Miscellaneous
IDfRelationType getRelationType(String relationName)
IDfVersionTreeLabels getVersionTreeLabels(IDfId chronicleId)
String getLoginTicket()
IDfClient
Most DFC programs start by obtaining an object that implements the
IDfClient interface, through a call like the following:
The IDfClient object loads the DMCL shared library. Its main function is to
create and share sessions, but programs also use IDfClient to get information
about the available Docbases and to obtain certain DMCL configuration
information. IDfClient also enables client programs to cache information.

IDfClient
Creating Sessions and Obtaining References to Existing

Sessions
An IDfClient object enables an application to create new sessions, share

sessions across components, or obtain references to existing sessions. It has the
following session-related methods:
IDfSession newSession(
String DocbaseName, IDfLoginInfo loginInfo)
IDfSession getSharedSession(
String DocbaseName, IDfLoginInfo loginInfo, String key)
IDfSession adoptDMCLSession(String dmclSessionId)
void unadoptDMCLSession(String dmclSessionId)
Enumeration enumSharedSessions(String key)
IDfSession findSession(String dfcSessionId)
The methods for creating a new session (newSession and getSharedSession)
take an IDfLoginInfo object as an argument. An IDfLoginInfo object carries
the user name, the password, and, optionally, the domain name. The sample
code in“connectToDocbase in Java” on page 4-3 shows how to use
IDfLoginInfo.
Shared sessions enable the components of a DFC application to share a DFC
session. The getSharedSession method uses a key known to all components
that share the session. Internally, DFC checks whether it has already created a
session for the same Docbase, the same login information, and same key. If it
has, it returns that session. Otherwise, it creates a new session.
Sharing sessions saves resources on both the client and the server sides. The
getSharedSession method does not allow sharing sessions among users. It is
for sharing sessions across components accessed by the same user for the
same Docbase in the same application.
The method newSession always creates a new session. Applications should
call newSession if they do not intend to share sessions across components.
The method adoptDMCLSession is intended for integrating with legacy
applications that use DMCL. This method takes the identifier for a session
created by a DMCL connect call (s0, for example) and wraps the underlying
session as a DFC session so DFC code can use it. If you adopt a session, you
must call unadoptDMCLSession when you finished with the session. Do not
call the close method of IDfSession.
The DFC online reference contains detailed information about the
enumSharedSessions and findSession methods.

IDfClient
Maps and Config Information
Client applications often present the user with a list of available Docbases.
DFC returns this list through the IDfDocbaseMap interface, which is obtained
by calling the IDfClient getDocbaseMap method. The IDfDocbaseMap
interface provides methods for getting the number of Docbases in the list, the
name of the Docbase at a specified index, a description of the Docbase at the
specified index, and the version of the server at the specified index. IDfClient
also provides methods for obtaining a docbroker map (the list of docbrokers
that you can access) and a server map (the servers that you can access). It
returns these maps as IDfTypedObjects. Typical client applications do not
need these maps. The server documentation provides more information about
them under the headings Docbroker Locator and Server Locator. The
examples in “Using a Docbase Map” on page 4-6 show how to work with
Docbase maps.
IDfClient allows you to obtain information about your general client
configuration through the getClientConfig method. This client configuration
object maps to the API Config object discussed in the server documentation.
Through this object you can dynamically configure such things as your
Docbroker, the maximum number of simultaneous sessions allowed, and the
maximum number of open collections allowed. You should alter the default
values only after reading the server administration documentation.
Service Methods
The IDfClient object provides an IDfProperties object for caching and sharing
information within your application. An IDfProperties object is an object that
allows you to store name-value pairs. The method
getContext(String contextId)
returns the properties object for the specified ID or creates a new one if one
does not already exist. The method
removeContext(String contextId)
removes the specified properties object. Some applications share data within a
session by using this object. In this case, they typically use the session ID
returned by the IDfSession method getSessionId as the context ID. You should
not use the DMCL session ID (for example, s0) for this purpose. Applications
should be careful to remove the properties object associated with a session
when they no longer use that session.

Common Package
Common Package
The com.documentum.fc.common package contains interfaces that client
programs sometimes find useful.
DFC wraps IDs and Time values in IDfId and IDfTime objects. To get an ID as
a string you can call either getId or toString (they return the same thing).
IDfTime objects allow you to perform time format conversions. Both the IDfId
and IDfTime interfaces provide convenience methods.
The getValue method returns an IDfValue object, which contains not only the
attribute’s value, but also its type. IDfValue objects are convenient when you
need to store an attribute value as an object (such as inserting it into a Java
hashtable), but later need to determine its type as well as its value.
Avoid calling getValue if you can, because creating an additional object and
obtaining and storing the type information are needless overhead if you don’t
use those features.

8
DFC and DMCL 8
This chapter assumes that you are familiar with the methods that previous
Documentum client products use to access server capabilities. It explains DFC
by relating it to those methods. It contains the following main sections:
■ “Relationship to DMCL” on page 8-1
This section explains the relationship between DFC and the Documentum
client library (DMCL).
■ “Calling DMCL Directly” on page 8-3
This section describes a way to bypass DFC and to communicate with the
server via DMCL.
■ “DMCL to DFC Correspondence” on page 8-4
This section contains a table of DMCL methods and the corresponding
DFC methods.
Relationship to DMCL
The Documentum client library, DMCL, is a library of procedures and
functions that implement the server API. DFC implements the API and an
additional layer of related business logic, as shown in Figure 8-1. It does so
through a set of interfaces that client programs can use to access DFC from
Java or COM.

DFC and DMCL
Relationship to DMCL
Figure 8-1 DFC Builds Business Logic Above DMCL
DocApp
Data Workflow Version

VDM Operations
Validation Runtime Policy
DFC
Object-Oriented Access to Server API
DMCL Server API
Using DFC differs from using DMCL in the following ways:

■ DMCL communicates via strings of arguments and results. DFC creates
objects that implement specified interfaces.
■ DMCL reports errors via error messages. DFC uses the Java exception
mechanism.
Example The following calls show the ways to use DMCL to access the server.
■ Pass DMCL a method (connect) and its arguments.
char *session = dmAPIGet("connect,docbase,user,password")
■ Pass the method (create), the session ID (s0), and the argument.
char *object = dmAPIGet("create,s0,dm_document")
■ Pass the method (get), the session ID (s0), the object ID (09017...), and the
argument.
char *name = dmAPIGet("get,s0,09017...,object_name")
The following code illustrates DMCL error handling:
boolean fOK = dmAPIExec(“checkout,s0, 09017...“);
if (fOK == FALSE) {
char *err = dmAPIGet(“getmessage,s0“);
dmAPIExec(“reset,s0,09017...“);
}
DFC’s IDfSession interface hides the session ID and object ID, leading to the
following code corresponding to the first DMCL call:
IDfLoginInfo loginInfo = new DfLoginInfo();
loginInfo.setUser("user");
loginInfo.setPassword("password");
IDfSession session = client.newSession("docbase",loginInfo );

DFC and DMCL
Calling DMCL Directly
The second DMCL call corresponds to the following DFC code:

IDfDocument object =
(IDfDocument)session.newObject("dm_document");
The third DMCL call can take either of the following forms with DFC:
String name = object.getString("object_name");
String name = object.getObjectName();
In the first form, you know that the attribute is a string. In the second form,
you know that the object is of type dm_sysobject.
If any of the DFC calls fails, DFC throws DfException, and the getMessage
method of the exception object returns the same string that the DMCL
getmessage method returns. DFC also performs the reset automatically.
The following code fragments show how to handle the error: first in Java, then
in Visual Basic:
try //Java
{ object.checkout(); }
catch (DfException e)
{ // checkout failed
System.out.println(e.getMessage());
}
On Error GoTo errHandler #Visual Basic

object.checkout
GoTo finish
errHandler:
Dim e As IDfException
Set e = cx.parseException(Err.Description)
MsgBox e.getMessage
finish:
The Visual Basic fragment assumes you have set cx via code like the
following:
Dim cx as IDfClientX
cx = CreateObject(“Documentum.Dfc“)
Calling DMCL Directly

This section describes a way to bypass DFC and access the server via DMCL.

DFC and DMCL
DMCL to DFC Correspondence
DFC provides complete, object-oriented access to the server API. Sometimes,

such as when migrating legacy customizations, you may wish to call the
server API directly. Table 8-1 describes DFC methods in the IDfSession
interface that provide direct access to DMCL.
Note: When you call DMCL directly, you bypass the DFC validation services.
You must provide code to validate the data explicitly.
Table 8-1 DFC Methods Providing Access to DMCL
Method Description
apiGet Equivalent to calling dmAPIGet from DFC.
apiSet Equivalent to calling dmAPISet from DFC.
apiExec Equivalent to calling dmAPIExec from DFC.
Refer to the eContent Server reference documentation for more information

about how to use these methods.
DFC returns a DfException object when a DMCL error occurs. In Java, use a
try . . . catch code block to handle the error.

This section contains a table of DMCL methods and the corresponding DFC
methods.
Table 8-2 shows the DFC methods corresponding to DMCL API commands. If
you are familiar with DMCL commands, use the table to find the
corresponding DFC interface and method. The DFC column has format
Interface :: Method.
Table 8-2 DFC methods corresponding to DMCL API commands
DMCL DFC
Abort IDfSession :: abortTrans
Acquire IDfRouter :: acquire

DFC and DMCL
Table 8-2 DFC methods corresponding to DMCL API commands (continued)
DMCL DFC
Addnote IDfSysObject :: addNote
Addrendition IDfSysObject :: addRendition

IDfSysObject :: addRenditionEx
Anyevents IDfSession :: hasEvents
Append IDfTypedObject :: appendBoolean

IDfTypedObject :: appendDouble
IDfTypedObject :: appendId
IDfTypedObject :: appendInt
IDfTypedObject :: appendString
IDfTypedObject :: appendTime
IDfTypedObject :: appendValue
Appendcontent IDfSysObject :: appendContent
Appendfile IDfSysObject :: appendFile
Appendpart IDfSysObject :: appendPart
Appendtask IDfRouter :: appendTask
Apply IDfSession :: apply
Archive IDfSession :: archive
Assemble IDfSysObject :: assemble
Attach IDfSysObject :: attachPolicy
Begintran IDfSession :: beginTrans
Bindfile IDfSysObject :: bindFile
Branch IDfSysObject :: branch
Changepassword IDfSession :: changePassword
Checkin IDfSysObject :: Checkin

IDfSysObject :: CheckinEx
Checkinapp IDfSysObject :: checkinApp
Checkout IDfSysObject :: Checkout

IDfSysObject :: CheckoutEx

DFC and DMCL
DMCL DFC
Close IDfCollection :: close
Commit IDfSession :: commitTrans
Connect IDfClient :: newSession

IDfClient :: getSharedSession
Count IDfTypedObject :: getAttrCount
Create IDfSession :: newObject

IDfSession :: newObjectWithType
Datatype IDfTypedObject :: getAttrDataType
Demote IDfSysObject :: demote
Dequeue IDfSession :: dequeue
Describe IDfSession :: describe
Destroy IDfPersistentObject :: destroy
Disassemble IDfSysObject :: disassemble
Disconnect IDfSession :: disconnect
Dump IDfTypedObject :: dump
End IDfRouter :: end
Fetch IDfPersistentObject :: fetch

IDfSession :: getObject
IDfSession :: getObjectWithType
Flush IDfSession :: flush
Flushcache IDfSession :: flushCache
Force IDfRouter :: force
Forward IDfRouter :: forward
Freeze IDfSysObject :: freeze

DFC and DMCL
DMCL DFC
Get IDfTypedObject :: getBoolean

IDfTypedObject :: getDouble
IDfTypedObject :: getId
IDfTypedObject :: getInt
IDfTypedObject :: getString
IDfTypedObject :: getTime
IDfTypedObject :: getValue
IDfTypedObject :: getAllRepeatingStrings
IDfTypedObject :: getRepeatingBoolean
IDfTypedObject :: getRepeatingDouble
IDfTypedObject :: getRepeatingId
IDfTypedObject :: getRepeatingInt
IDfTypedObject :: getRepeatingString
IDfTypedObject :: getRepeatingTime
IDfTypedObject :: getRepeatingValue
Getcontent IDfSysObject :: getContent

IDfSysObject :: getContentEx
Getdocbasemap IDfClient :: getDocbaseMap

IDfClient :: getDocbaseMapEx
Getdocbrokermap IDfClient :: getDocbrokerMap

IDfClient :: getDocbrokerMapEx
Getevents IDfSession :: getEvents
Getfile IDfSysObject :: getFile

IDfSysObject :: getFileEx
Getlastcoll IDfSession :: getLastCollection
Getlogin IDfSession :: getLoginTicket
Getmessage this happens automatically when the error occurs

IDfSession :: getMessage
Getpath IDfSysObject :: getPath
Getservermap IDfClient :: getServerMap

IDfClient :: getServerMapEx
Grant IDfACL :: grant

IDfSysObject :: grant

DFC and DMCL
DMCL DFC
Halt IDfRouter :: halt
Id IDfSession :: getIdByQualification
Insert IDfTypedObject :: insertBoolean

IDfTypedObject :: insertDouble
IDfTypedObject :: insertId
IDfTypedObject :: insertInt
IDfTypedObject :: insertString
IDfTypedObject :: insertTime
IDfTypedObject :: insertValue
Insertcontent IDfSysObject :: insertContent
Insertfile IDfSysObject :: insertFile
Insertpart IDfSysObject :: insertPart
Inserttask IDfRouter :: insertTask
Link IDfSysObject :: link
Locate IDfTypedObject :: findBoolean

IDfTypedObject :: findDouble
IDfTypedObject :: findId
IDfTypedObject :: findInt
IDfTypedObject :: findString
IDfTypedObject :: findTime
IDfTypedObject :: findValue
Mark IDfSysObject :: mark
Next IDfCollection :: next
Offset IDfTypedObject :: findAttrIndex
Pause IDfRouter :: pause
Print IDfSysObject :: print
Promote IDfSysObject :: promote
Prune IDfSysObject :: prune
Purgelocal IDfSession :: purgeLocalFiles

DFC and DMCL
DMCL DFC
Query IDfQuery.execute
Queue IDfSysObject :: queue
Readquery IDfQuery.execute
Reassign IDfRouter :: reAssign
Register IDfSysObject :: register
Reinit IDfSession :: reInit
Remove IDfTypedObject :: remove

IDfTypedObject :: removeAll
Removecontent IDfSysObject :: removeContent
Removenote IDfSysObject :: removeNote
Removepart IDfSysObject :: removePart
Removerendition IDfSysObject :: removeRendition

IDfSysObject :: removeRenditionEx
Removetask IDfRouter :: removeTask
Repeating IDfTypedObject :: isAttrRepeating
Reset Happens automatically when the error occurs
Restart IDfSession :: reStart
Restore IDfSession :: restore
Resume IDfRouter :: resumeRouter

IDfSysObject :: resume
Retrieve IDfSession :: getObjectByQualification
Reverse IDfRouter :: reverse
Revert IDfPersistentObject :: revert

IDfSysObject :: revertACL
Revoke IDfACL :: revoke

IDfSysObject :: revoke

DFC and DMCL
DMCL DFC
Save IDfPersistentObject :: save

IDfSysObject :: saveLock
Saveasnew IDfSysObject :: saveAsNew
Scope IDfSession :: setDocbaseScope
Set IDfTypedObject :: setBoolean

IDfTypedObject :: setDouble
IDfTypedObject :: setId
IDfTypedObject :: setInt
IDfTypedObject :: setString
IDfTypedObject :: setTime
IDfTypedObject :: setValue
IDfTypedObject :: setRepeatingBoolean
IDfTypedObject :: setRepeatingDouble
IDfTypedObject :: setRepeatingId
IDfTypedObject :: setRepeatingInt
IDfTypedObject :: setRepeatingString
IDfTypedObject :: setRepeatingTime
IDfTypedObject :: setRepeatingValue
Setbatchhint IDfSession :: setBatchHint
Setcontent IDfSysObject :: setContent

IDfSysObject :: setContentEx
Setdoc IDfSysObject :: setIsVirtualDocument
Setfile IDfSysObject :: setFile

IDfSysObject :: setFileEx
Setpath IDfSysObject :: setPath
Shutdown IDfSession :: shutdown
Signoff IDfRouter :: signOff
Start IDfRouter :: start
Suspend IDfSysObject :: suspend
Trace IDfSession :: traceDMCL
Truncate IDfTypedObject :: truncate

DFC and DMCL
DMCL DFC
Type IDfSession :: getTypeDescription
Unfreeze IDfSysObject :: unfreeze
Unlink IDfSysObject :: unlink
Unlock IDfSysObject :: cancelCheckout

IDfSysObject :: cancelCheckoutEx
Unmark IDfSysObject :: unmark
Unregister IDfSysObject :: unRegister
Updatepart IDfSysObject :: updatePart
Useacl IDfSysObject :: useACL
Validate IDfRouter :: validateRouter
Values IDfTypedObject :: getValueCount

DFC and DMCL

INDEX
A common.documentum.fc.client.qb package
abortTrans method 7-24 1-10
ACLs 6-2 connections
private 6-5 methods related to 3-3
adoptDMCLSession method 7-28 connectToDocbase method 4-7
API calls 7-26 containment objects
API Config object 7-29 copy_child attribute 2-3
apiDesc method 7-26 content objects
apiExec method 6-5, 7-26 methods that work with 3-13
apiGet method 7-26 copy_child attribute 2-3
apiGetBytes method 7-26
apiSet method 6-5, 7-26 D
apiSetBytes method 7-26 dequeue method 7-26
apply method 7-26 describe method 7-26
archive method 7-26 DFC (Documentum Foundation Classes)
attributes COM interface 1-2
methods related to 3-10 elements 1-2
DFC (Documentum foundation classes)
B adopted sessions
beginTrans method 7-24 4-2
bug lists -xii comparison with DMCL 8-4
datatypes 1-7
DMCL process 1-8
C inheritance 1-5
changePassword method 7-27 migrating to 8-4
close method 5-2 naming convention 1-9
collections objects and pointers 1-6
stepping through 5-4 online reference 1-11
COM server API calls
inheritance 1-11 8-4
com.documentum.com package 1-10 shared sessions 4-2
com.documentum.fc.client package 1-10 DFC interface hierarchy 7-5
com.documentum.fc.common package 1- DfClient class 4-2, 4-3, 4-6, 7-27
10, 7-30 DfLoginInfo class 4-3
com.documentum.operations package 1-10 DfPersistentObject class 7-24
com.documentum.registry package 1-10 DfQuery class 5-1
commitTrans method 7-24 DfType class 7-24
DfTypedObject class 7-24
Using DFC in Documentum Applications Index–1

DfUser class 7-24 getAttrCount method 7-19
DfValidationException class 6-1 getAttrDataType method 7-19
disconnect method 7-27 getBoolean method 7-8, 7-22
disconnectFromDocbase method 4-6 getClient method 7-22
dm_cabinet type 7-21 getClientConfig method 7-24, 7-29
dm_folder type 7-21 getConnectionConfig method 7-24
DMCL commands 8-4 getContext method 7-29
DMCL shared library 7-27 getDataType method 5-2
Docbase scope 7-24 getDBMSName method 4-5, 7-22
Docbases getDefaultACL method 7-23
querying with methods 3-12 getDMCLSessionId method 4-5, 7-22
docbrokers 4-6, 7-29 getDocbaseConfig method 7-24
documentation -xii getDocbaseDescription method 4-7
documents getDocbaseId method 4-5, 7-22
methods for printing 3-15 getDocbaseMap method 4-6, 7-29
Documentum foundation classes. See DFC getDocbaseName method 4-6, 4-7, 7-22
DQL (Document Query Language) getDocbaseOwnerName method 4-5, 7-22
methods that work with 3-12 getDocbaseScope method 4-5, 7-25
DQL queries 5-2 getDocbrokerMap method 7-24
getDouble method 7-8
E getEvents method 7-26
getFolderByPath method 7-23
eContent Server
getFormat method 7-23
communicating with 3-2
getGroup method 7-23
methods for communicating with 3-2
getId method 7-8
enumAttrs method 7-19
getIdByQualification method 7-23
enumSharedSessions method 7-28
getInt method 7-9
execute method 5-3
getLastCollection method 7-26
External applications
getLocalClient method 4-2
XML support 2-3
getLoginInfo method 7-22
getLoginTicket method 4-5, 7-27
F getLoginUserName method 4-5, 7-22
findAttrIndex method 7-19 getMessage method 7-26
findSession method 7-28 getObject method 7-23
flush method 7-27 getObjectByPath method 7-23
flushCache method 7-27 getObjectByQualification method 7-23
getObjectWithType method 7-23
G getQuery method 5-1
getACL method 7-23 getRDBMSName is incorrect 7-23
getAllRepeatingStrings method 7-10 getRelationType method IDfRelationType
getAttr method 5-2, 7-19 interface 7-27
Index-2 Using DFC in Documentum Applications

getRepeatingBoolean method 7-9 IDfDocument interface 7-21
getRepeatingDouble method 7-9 IDfFolder interface 7-23
getRepeatingId method 7-9 IDfFormat interface 7-23
getRepeatingInt method 7-9 IDfGroup interface 7-23
getRepeatingString method 7-9 IDfId interface 7-8, 7-9, 7-10, 7-23, 7-26,
getRepeatingTime method 7-10 7-27
getRepeatingValue method 7-10 IDfList interface 7-26
getRunnableProcesses method 7-26 IDfLoginInfo interface 4-3, 4-4, 7-22, 7-28
getSecurityMode method 4-5, 7-22 IDfPersistentObject interface 7-4, 7-23
getServerConfig method 7-24 IDfProperties interface 7-29
getServerMap method 7-24 IDfSession interface 1-3, 7-22, 7-25, 7-28
getServerVersion method 4-5, 4-7, 7-22 IDfSysObject interface 1-10, 7-20
getSessionConfig method 7-24 IDfTypedObject interface 7-24
getSessionId method 4-5, 7-23 IDfValidator interface 6-2
getSharedSession method 7-28 IDfValue interface 7-30
getString method 5-2, 7-9 IDfVersionTreeLabels interface 7-27
getTasks method 7-26 IDfWorkflowBuilder interface 7-26
getTime method 7-9 inboxes
getType method 7-24 methods related to 3-23
getTypeDescription method 7-24 isACLDocbase method 7-23
getTypedObject method 5-3 isAdopted method 7-23
getUser method 7-24 isAttrRepeating method 7-19
getUserByOSName method 7-24 isConnected method 4-4, 7-23
getValue method 7-9, 7-30 isRemote method 7-23
when to avoid 7-30 isShared method 7-23
getVersionTreeLabels method 7-27
grant method 6-2, 6-3 M
methods
H server communication 3-2
hasAttr method 7-19
hierarchy, of DFC interfaces 7-5 N
newObjectWithType method 7-24
I newSession method 4-3, 7-28
IdfACL interface 7-23 newWorkflowBuilder method 7-26
IDfAttr interface 7-19
IDfClient interface 1-3, 4-2, 4-3, 4-6, 7-22, O
7-24, 7-27
objects
IDfClientX interface 5-1
methods for handling 3-5
IDfCollection interface 5-2, 5-3, 7-26
online documentation -xii
IDfDocbaseMap interface 4-6, 7-29
Using DFC in Documentum Applications Index-3

P setDouble method 7-9
setId method 7-9
passwords 7-28
setInt method 7-9
permissions 6-2, 6-3
setPassword method 4-3
persistent objects 7-3, 7-23
setRepeatingBoolean method 7-10
printing
setRepeatingDouble method 7-10
methods related to 3-15
setRepeatingId method 7-10
private ACLs 6-5
setRepeatingInt method 7-10
purgeLocalFiles method 7-27
setRepeatingString method 7-10
setRepeatingTime method 7-10
Q setRepeatingValue method 7-10
queries 5-3 setString method 7-9
displaying results 5-4 setTime method 7-9
flow of processing 5-1 setUser method 4-3
queues, user. See inboxes setValue method 7-9
shared sessions 7-28
R shutdown method 7-27
reInit method 7-27 subconnections
removeContext method 7-29 methods related to 3-3
repeating attributes 7-10 subtypes 7-2
resolveAlias method 7-26 supertypes 7-2, 7-4
restore method 7-27 support -xii
revoke method 6-3 sysobjects 7-20
rows 5-3 system administration
methods for 3-3
S
save method 6-5
T
sendToDistributionList method 7-26 technical support -xii
sessions 4-2, 7-22, 7-27, 7-28 traceDMCL method 7-26
keys 7-28 transactions 7-24
multithreading 7-25 type libraries 1-2
shared 7-28 typed objects 7-24
setACL method 6-5
setBatchHint method 7-27 U
setBoolean method 7-9 unlock method 7-25
setDocbaseScope method 7-25 user names 7-28
setDocbaseScopeById method 7-25
setDomain method 4-5

V W
validateAttrRules method 6-2 warnings
virtual documents COM interface inheritance fails
containment objects 1-5
copy_child attribute 2-3 workflow templates 7-26
copy behavior, defining 2-3 workflows 7-26
defined 2-2
methods related to 3-16 X
purpose 2-2
XML support 2-3
versioning 2-3
Using DFC in Documentum Applications Index-5


Using DFC 4213

Uploaded by

Copyright:

Available Formats

Using DFC 4213

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Using DFC 4213

Uploaded by

Copyright:

Available Formats

Using DFC in

2 Working With Documents

Using DFC in Documentum Applications iii

3 DFC Methods by Task

iv Using DFC in Documentum Applications

4 Managing DFC Sessions

Using DFC in Documentum Applications v

5 Managing Docbase Queries with DFC

6 Automating Business Rules with DFC

vi Using DFC in Documentum Applications

Using DFC in Documentum Applications vii

8 DFC and DMCL

viii Using DFC in Documentum Applications

Purpose of the Manual

Using DFC in Documentum Applications ix

Chapter 3, DFC Methods by An index to the major DFC methods, organized by

Chapter 4, Managing DFC Annotated examples, based on the classes

Chapter 5, Managing Docbase Annotated examples, based on the class

Chapter 6, Automating Annotated examples, based on the classes

x Using DFC in Documentum Applications

This manual uses the following conventions:

➤ Represents a pop-up or pull-down menu.

italics Represents a variable name for which you must provide a

typewriter Represents code samples, user input, and computer output.

[] square brackets Indicates an optional argument.

Using Links in PDF Files

Using DFC in Documentum Applications xi

Fixed Bug Lists

Concurrently with a release, we post product documentation to the support

Purchasing Bound Paper Manuals

xii Using DFC in Documentum Applications

This chapter introduces DFC. It contains the following major sections:

Using DFC in Documentum Applications 1–1

Programming with DFC

1–2 Using DFC in Documentum Applications

this access in client-side software that establishes and maintains

➤ To process a Docbase object:

Using DFC in Documentum Applications 1–3

IDfLoginInfo loginInfo = new DfLoginInfo();

IDfDocument document = null;

1–4 Using DFC in Documentum Applications

Using DFC From Application Programs

Using DFC from Visual Basic requires a small setup procedure.

Establishing the Environment

➤ To establish a reference to the DFC type library:

Using Interface Inheritance

Interface inheritance requires a workaround if you access DFC from Visual

Using DFC in Documentum Applications 1–5

Set sysObj = session.newObject("dm_document")

set perObj = sysObj

//Delete the old pointer

1–6 Using DFC in Documentum Applications

//Create new CDfSysObject

Table 1-1 Equivalents for DFC Datatypes

boolean Boolean BOOL VARIANT_BOOL

int Long long int

String String CString BSTR

double Double double double

IDfinterfacename IDfinterfacename CDfinterfacename IDfinterfacename