dfcoverview

Using DFC in Documentum Applications

Version 4.2

December 2000

DOC3-USINGDFC-1200

DOC3-USINGDFC-1200

Copyright © 1999, 2000Documentum, Inc.6801 Koll Center ParkwayPleasanton, CA 94566All Rights Reserved.

Documentum®, Documentum 4i™, Docbase™, Documentum eContent Server™, Documentum Server®, Documentum Desktop Client™, Documentum Intranet Client™, Documentum WebPublisher™, Documentum ftpIntegrator™, Documentum RightSite®, Documentum Administrator™, Documentum Developer Studio™, Documentum Web Development Kit™, Documentum WebCache™, Documentum ContentCaster™, AutoRender Pro™, Documentum iTeam™, Documentum Reporting Gateway™, Documentum Content Personalization Services™, Documentum Site Delivery Services™, Documentum Content Authentication Services™, Documentum DocControl Manager™, Documentum Corrective Action Manager™, DocInput™, Documentum DocViewer™, Virtual Document Manager™, Docbasic®, Documentum DocPage Server®, Documentum WorkSpace®, Documentum SmartSpace®, and Documentum ViewSpace® 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 Overview of Documentum Foundation Classes (DFC)Introduction to DFC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

DFC Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Documentum Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Subtypes and Supertypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

DFC Interface Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8Overview of DFC Interface Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . 1-12

Typed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12Session and Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12Getting and Setting Attribute Values . . . . . . . . . . . . . . . . . . . . . 1-12Additional Methods for Operating on Repeating Attributes . . . . . . . . 1-15Attribute Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15

Persistent Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16Methods Relating to the Basic Properties of Persistent Objects . . . . . . . 1-16Basic Operations on an Object . . . . . . . . . . . . . . . . . . . . . . . . . 1-17Audit Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18Convenience Methods for Creating Object Relations . . . . . . . . . . . . 1-18Validation Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19Pass-Through Methods to the DMCL API . . . . . . . . . . . . . . . . . . 1-19

Persistent Objects Without Associated Content . . . . . . . . . . . . . . . . . . 1-20IDfACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20IDfFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20IDfUser and IDfGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21IDfType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21

Basic Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21Parent Type Information . . . . . . . . . . . . . . . . . . . . . . . . . 1-21Type Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22

Sysobjects—Persistent Objects With Content. . . . . . . . . . . . . . . . . . . . 1-24Basic Operations on Sysobjects . . . . . . . . . . . . . . . . . . . . . . . . . 1-24Types That Derive From IDfSysObject . . . . . . . . . . . . . . . . . . . . 1-25

IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26Provide Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26Create Objects and Obtain Object References . . . . . . . . . . . . . . . . . . . 1-27Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28Transaction Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28Docbase Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28Multithreading Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29

Using DFC in Documentum Applications iii

Inbox and Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-30Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-30Session State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-31Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-31

IDfClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-31Creating Sessions and Obtaining References to Existing Sessions . . . . . .1-31

Maps and Config Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-32Service Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-33

Common Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-34Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-34

Flow of Query Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-34IDfQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-35IDfCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-36

2 Using DFCUsing DFC From Application Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Syntax Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3Creating DFC Client Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4COM Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

Creating a DFC Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Shared Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Adopted Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

Using DFC Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Using the DFC Online Reference Documentation. . . . . . . . . . . . . . . . . . . . . 2-6

3 Managing DFC SessionsConnecting and Disconnecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

connectToDocbase in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2disconnectFromDocbase in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2displaySessionInfo in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3connectToDocbase in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3disconnectFromDocbase in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . 3-4displaySessionInfo in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

iv Using DFC in Documentum Applications

Using a Docbase Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5displayDocbaseInfo in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5connectToDocbase(map, index) in Java . . . . . . . . . . . . . . . . . . . . . . . . 3-5Step through Docbases in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5displayDocbaseInfo in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6connectToDocbase(name) in Visual Basic. . . . . . . . . . . . . . . . . . . . . . . 3-6

4 Manipulating Docbase Objects with DFCCreating and Destroying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

createCabinet in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1createFolder in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2createDocument in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2destroyObject in Visual Basic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3createType in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3createDQLStatement in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . 4-4createCabinet in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5createFolder in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5createDocument in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5displayObjectInfo in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6destroyObject in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6createType in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6createDQLStatement in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

Checking Sysobjects In and Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7checkOutObject in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7cancelCheckout in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8checkInObject in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8removeLocalFile in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9editFile in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9checkOutObject in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9cancelCheckout in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10checkInObject in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10removeLocalFile in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11editFile in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

Working With Sysobject Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11displayVersionInfo in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . 4-11changeVersionInfo in Visual Basic. . . . . . . . . . . . . . . . . . . . . . . . . . 4-12displayVersionInfo in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13changeVersionInfo in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13

Using DFC in Documentum Applications v

5 Managing Docbase Queries with DFCBasic Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

exQuery in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1displayResults in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2exQuery in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2displayResults in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

6 Automating Business Rules with DFCChecking Objects Against Validation Rules . . . . . . . . . . . . . . . . . . . . . . . . 6-1

validate in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1Changing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

changeBasicPermissions in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . 6-2changeExtendedPermissions in Visual Basic . . . . . . . . . . . . . . . . . . . . 6-3changeBasicPermissions in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3changeExtendedPermissions in Java . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

Using Private ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5privateACLs in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5privateACLs in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6

ACL Utility Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7permissionToString in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7extendedPermissionToString in Visual Basic . . . . . . . . . . . . . . . . . . . . 6-7displayBasicPermissions in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . 6-7displayExtendedPermissions in Visual Basic . . . . . . . . . . . . . . . . . . . . 6-8permissionToString in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8extendedPermissionToString in Java . . . . . . . . . . . . . . . . . . . . . . . . . 6-9displayBasicPermissions in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9displayExtendedPermissions in Java . . . . . . . . . . . . . . . . . . . . . . . . . 6-9

7 DFC Methods by TaskCommunicating with the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

IDfClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2DMCL (No Associated DFC Methods) . . . . . . . . . . . . . . . . . . . . . . . . 7-3

Administering the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3IDfClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4DMCL (No Associated DFC Methods) . . . . . . . . . . . . . . . . . . . . . . . . 7-5

Handling Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5IDfPersistentObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6IDfAcl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9

vi Using DFC in Documentum Applications

Retrieving and Setting Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10IDfTypedObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10

Searching the Docbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12IDfQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12IDfCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13

Handling Content Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13DMCL (No Associated DFC Methods) . . . . . . . . . . . . . . . . . . . . . . . 7-15

Printing Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15DMCL (No Associated DFC Methods) . . . . . . . . . . . . . . . . . . . . . . . 7-15

Handling Virtual Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16DMCL (No Associated DFC Methods) . . . . . . . . . . . . . . . . . . . . . . . 7-17

Handling Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18IDfWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18

Handling Process Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-19IDfProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-19

Handling Activity Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-20IDfActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-20

Handling Work Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-21IDfWorkitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-21

Managing Inboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-22IDfSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-22IDfSysObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-23

8 DFC and DMCLRelationship to DMCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1Calling DMCL Directly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3DMCL to DFC Correspondence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

A Questions and AnswersFolder Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1Create a Microsoft Word Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-3Name Strings for IDfOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-3IDfSession.sendToDistributionList Arguments . . . . . . . . . . . . . . . . . . . . . .A-4

Index

Using DFC in Documentum Applications vii

viii Using DFC in Documentum Applications


P R E F A C E

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 lots of sample code that uses DFC to perform common Documentum operations.

All of the sample code is extracted and simplified from the sample classes that Documentum provides with DFC. The sample classes provide complete working examples that you can run, modify, and experiment with.

The simplified examples focus on specific DFC tasks and omit code from the sample classes that is not specific to DFC.

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).

Organization of the Manual

The table summarizes the topics that this manual covers. The classes mentioned in the table are the sample classes that Documentum provides with DFC.

This manual does not cover structured documents, workflows, or document lifecycles. You can find examples of how to work with structured documents in the DfExVDM sample class, workflows in the DfExWorkflow sample class, and document lifecycles in the DfExBusinessPolicy class.

ix

Conventions

This manual uses the following conventions:

Chapter/Appendix Contents

Chapter 1, Overview of Documentum Foundation Classes (DFC)

How DFC helps you connect to a Docbase and gives you an object oriented interface to the Documentum object hierarchy.

Chapter 2, Using DFC Making DFC work with your programming and execution environments.

Chapter 3, Managing DFC Sessions

Annotated examples, based on the classes DfExSession and DfExDocbaseMap, of how to work with DFC sessions and a Docbase map.

Chapter 4, Manipulating Docbase Objects with DFC

Annotated examples, based on the classes DfExCreate, DfExCheckinCheckout, DfExVersionPolicy, and DfExDestroy, of how to manipulate Docbase objects.

Chapter 5, Managing Docbase Queries with DFC

Annotated examples, based on the class DfExSimpleQuery, of how to create and execute Docbase queries.

Chapter 6, Automating Business Rules with DFC

Annotated examples, based on the classes DfExSimpleValidation and DfExACL, of how to use Documentum to enforce business rules.

Chapter 7, DFC Methods by Task

An index to the major DFC methods, organized by the tasks the methods accomplish.

Chapter 8, DFC and DMCL An explanation of DFC in terms of the methods that previous Documentum client products use to access server capabilities.

Appendix A, Questions and Answers

Questions that developers who are starting to work with DFC have asked.

x Using DFC in Documentum Applications

Using Links in PDF Files

If you are reading this document as a Portable Display 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 manuals contain clickable cross-references to other manuals.

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 different directories, the references do not work.

➤ To follow a link:

1. Move the pointer over a linked area.

The pointer changes to a pointing finger when positioned over a link. The finger pointer displays a W when moved over a Web link.

2. Click to follow the link.

Note: To follow Web links, your Weblink preferences must specify a Web browser. See Setting Weblink preferences in Adobe Acrobat Help for more information.

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 brackets)

Indicates an optional argument that can be repeated more than once.

Using DFC in Documentum Applications xi

Bug Lists and Documentation Online

Customers with a Software Support Agreement can read our product documentation and, after commercial release of a product, view lists of fixed bugs on Documentum’s Technical Support web pages. To access online support, first request access and obtain a user name and password.

Applying for Access

➤ To apply for access to online support:

1. In your Web browser, openhttp://www.documentum.com/

2. Click the Technical Support link.

3. Click the Request Access link.

4. Complete the form and send it.

Documentum responds to access requests within two business days.

Fixed Bugs List

A list of customer-reported bugs that have been fixed in a release is available two weeks after the release, at the Technical Support area of the documentum.com Web site. For information about obtaining access to online support, refer to “Applying for Access.” The lists of fixed bugs are in PDF format.

➤ To view the list of fixed bugs:

1. In your web browser, openhttp://www.documentum.com/


3. Log on to the Technical Support site.

4. In the Troubleshooting section, click View Bugs.

5. Click Fixed Bugs and Feature Requests Lists.

6. Click the name of the bug list.

xii Using DFC in Documentum Applications

http://www.documentum.com

http://www.documentum.com/

Product Documentation

Customers with a software support agreement can view PDF format product documentation at the documentum.com Web site. First request a user name and password (refer to “Applying for Access”).

➤ To view a document:

1. In your Web browser, open http://www.documentum.com/


3. Log on to the Technical Support site.

4. In the Resources section, click Documentation.

5. Click the name of the document.

Purchasing Bound Paper Manuals

Our product documentation is available for purchase as bound paper manuals. To place an order, call the Documentation Order Line at (925) 600-6666. You can pay with a purchase order, check, or credit card.

Using DFC in Documentum Applications xiii

http://www.documentum.com/

xiv Using DFC in Documentum Applications

1
Overview of Documentum Foundation Classes (DFC) 1
Desktop Client components use the foundation class library Documentum Foundation Classes (DFC) to access the capabilities of eContent Server. This chapter describes DFC and introduces basic DFC concepts. It contains the following major sections:

■ “Introduction to DFC” on page 1-1

■ “Overview of DFC Interface Capabilities” on page 1-12

■ “IDfSession” on page 1-26

■ “IDfClient” on page 1-31

■ “Common Package” on page 1-34

■ “Queries” on page 1-34

Introduction to DFC

Documentum applications depend heavily on the Documentum object model, which is the object-oriented structure by which eContent Server organizes the contents and control mechanisms of Docbases. The eContent Server Fundamentals manual describes this object model and provides an overview of how to interact with it through the Documentum client library (DMCL), an application programming interface (API). DMCL flattens the object model as a set of commands issued via text string arguments to the dmAPIGet, dmAPISet, and dmAPIExec commands.

DFC exposes the Documentum object model as an object-oriented client library. Client-side applications, such as Desktop Client or applications that you develop, and middle-tier libraries and applications, such as Web Development Kit (WDK), use DFC.

Using DFC in Documentum Applications 1–1

Overview of Documentum Foundation Classes (DFC)Introduction to DFC

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 shared library that you must load to use DFC with non-Microsoft Java virtual machines (JVMs).

■ 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.

DFC Programming

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 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 session 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.

1–2 Using DFC in Documentum Applications


➤ 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 3-2).

3. If you have a reference to the object, call the IDfSession checkout method to lock it. Otherwise call an IDfSession method (for example, newObject or getObjectByQualification) to create an object or to obtain a reference to an existing object.

If the object is an IDfSysObject, you can call

a. setContentType to set the object’s format.

b. setFile to set the its content.

c. setObjectName to set its name.

d. save to save the object in the Docbase.

4. If you checked out the object in Step 3, call checkin to release the lock.

5. Close the session if you are done with it.

The following fragment from a Java program that uses DFC contains three blocks of code. 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 block 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 (see “createDocument in Visual Basic” on page 4-2).

Most DFC methods throw DfException to report errors. 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.

Packages

DFC is organized into 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-1 describes the purpose of the classes and interfaces of DFC packages.

Table 1-1 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

common.documentum.fc.client.qb Constructs and runs queries and SmartLists.

com.documentum.com Facilitates accessing DFC from COM.



Both the com.documentum.operations package and the IDfSysObject interface in the com.documentum.fc.client package have methods for high-level client operations, such as checking in and checking out documents. The methods in the operations package perform additional work, such as writing to the registry. Use the interfaces in the operations package to interact with Desktop Client components. Use the operation methods in IDfSysObject only if your code does not interact with Desktop Client components.

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 2-6) 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, in Java you can call the save method of a sysobject, because IDfSysObject inherits save from IDfPersistentObject (see “Persistent Objects” on page 1-16 and “Sysobjects—Persistent Objects With Content” on page 1-24).

Visual Basic 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. For example, you must convert a sysobject to a persistent object before you can save it.

com.documentum.fc.common Supplies utility methods for other DFC classes.

com.documentum.fc.common.session

Supports Docbase sessions.

com.documentum.operations Provides high-level functionality, such as checking documents or virtual documents in and out.

com.documentum.registry Maintains Documentum information on the client’s system, using the Windows registry on Win32 platforms, and .ini files otherwise.

Table 1-1 Description of DFC Packages (continued)

Java Package Name Purpose



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_.

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-3. 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 1-1. DFC interfaces are in the top (white) parts of the boxes. The corresponding server objects are in the lower (gray) parts.

Figure 1-1 DFC Hierarchy Corresponds to Documentum Object Hierarchy

In Figure 1-2 on page 1-10, you can see how the interfaces that derive from the Documentum hierarchy fit into the total DFC interface hierarchy.

IDfTypedObjectNon-Persistent Type

IDfDocbaseMap IDfPersistentObject IDfCollectionDocbase Locator Persistent Object Non-Persistent

IDfACL IDfFormat IDfGroup IDfSysObject IDfType IDfUserdm_acl dm_format dm_group dm_sysobject dm_type dm_user

IDfDocument IDfFolderdm_document dm_folder

<None>dm_cabinet



Figure 1-2 DFC Interface Hierarchy

IDfPersistentObject

IDfSysObjectIDfDocument

IDfFolder

IDfACL

IDfUser

IDfFormat

IDfGroup

IDfType

IDfTypedObject

IDfDocbaseMap

IDfCollection

IDfRouter

IDfPackage

IDfWorkItem

IDfAssembly

IDfContainment

IDfActivity

IDfProcess

IDfWorkflow

IDfQueueItem

IDfAliasSet

IDfRelation

IDfRelationType



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.

IDfOperation

IDfCancelCheckoutOperation

IDfCheckinOperation

IDfCheckoutOperation

IDfCopyOperation

IDfDeleteOperation

IDfExportOperation

IDfImportOperation

IDfMoveOperation

IDfOperationNode

IDfCancelCheckoutNode

IDfCheckinNode

IDfCheckoutNode

IDfCopyNode

IDfDeleteNode

IDfExportNode

IDfImportNode

IDfMoveNode

IDfClientRegistryObject

IDfCheckedOutObject

IDfLocalObject

IDfViewedObject


Overview of Documentum Foundation Classes (DFC)Overview of DFC Interface Capabilities

Overview of DFC Interface Capabilities

The following sections move through the DFC interfaces that derive from the Documentum object type hierarchy, starting from the top.

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 2-6). 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)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)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)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)int getAttrDataType(String attrName)int findAttrIndex(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).

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.

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.

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.

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 that 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. People who 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, not just its name.

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 methods come in two flavors. 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 index is 0-based. The above get type attribute methods return the type of the attribute. This is one of the following values:

IDfType.DF_BOOLEANIDfType.DF_INTEGERIDfType.DF_STRINGIDfType.DF_IDIDfType.DF_TIMEIDfType.DF_DOUBLEIDfType.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()int findAttrIndex(String attrName)IDfAttr getAttr(int index)int getAttrCount()int getAttrDataType(String attrName)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, calldoctype.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 (DLC).

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. 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

“Checking Sysobjects In and Out” on page 4-7 contains examples of how to check objects out of and into a Docbase and how to cancel a checkout.

■ 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. “Working With Sysobject Versions” on page 4-11 contains examples of how to use DFC to work with versions.



■ 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.


Overview of Documentum Foundation Classes (DFC)IDfSession

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,

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 1-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()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. “DFC Programming” 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)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.



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:



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)


Overview of Documentum Foundation Classes (DFC)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:

IDfClient client = DfClient.getLocalClient();

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.

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 3-2 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.

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 3-5 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.


Overview of Documentum Foundation Classes (DFC)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.

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, query:

■ For Java-based DFC programs, call new DfQuery.


Overview of Documentum Foundation Classes (DFC)Queries

■ For Visual Basic and C++ programs, call the getQuery method of IDfClientX.

4. Create a DQL query as a text string, dq.

5. Call query.setDQL(dq) to set the DQL string into the query object.

6. Call query.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.

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.

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.


Overview of Documentum Foundation Classes (DFC)Queries

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 1-35, which does not call getTypedObject, with the code in “displayResults in Visual Basic” on page 5-2, which does call getTypedObject).


2
Using DFC 2
This chapter discusses operational issues that arise when you set up and use DFC in your programming environment.

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. Simply add the DFC class and interface files (for example, ...Documentum\DFCre40\lib\dfc.jar) to your CLASSPATH.

Visual Basic

From Visual Basic, the dfc.tlb type library provides access to DFC through COM. Visual Basic hides the details.

Interface inheritance requires a workaround if you access DFC from Visual Basic, because the Microsoft Java virtual machine does not support COM interface inheritance.

For example, in Java you can use the save method that a SysObject inherits from a PersistentObject.

//JavaIDfSysObject sysobj = session.newObject("dm_document");sysobj.setObjectName("test");sysobj.save();


Using DFCUsing DFC From Application Programs

In Visual Basic, however, you must assign the IDfSysObject object to an IDfPersistentObject object before calling its save method:

'Visual BasicDim sysobj As IDfSysObjectDim pobj As IDfPersistentObjectSet sysobj = session.newObject("dm_document")sysobj.setObjectName ("test")set pobj = sysobjpobj.save

C++

From C++, use COM directly, or 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 Microsoft’s 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 Visual Basic 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 objectCDfSysObject sobj1 = session.getObject(id);CDfSysObject *pSysObj = null;

//Delete the old pointerif (pSysObj) delete pSysObj;

//Create new CDfSysObjectpSysObj = new CDfSysObject(sobj1);


Using DFCCreating DFC Client Objects

■ 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 2-1 shows the COM equivalents of DFC datatypes.

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.

Table 2-1 Equivalents for DFC Datatypes

Java (DFC datatype) Visual Basic (and Docbasic)

C++ with MFC wrapper classes

C++ directly to COM

boolean Boolean BOOL VARIANT_BOOL

int Long long int

String String CString BSTR

double Double double double

IDfinterfacename IDfinterfacenameor Object

CDfinterfacename IDfinterfacename


Using DFCCreating a DFC Session

2. Provide login information and establish a DFC session (refer to “Creating a DFC Session” on page 2-4).

Java Example

Use the DfClient.getLocalClient static method.IDfClient myclient = DfClient.getLocalClient();

This line of code creates an interface, myclient, to a local DFC client object. The interface provides access to the methods and data in the DFC client object. Call the object’s methods through the interface.

COM Example

IDfClientX creates DFC objects in COM development environments. You must instantiate an IDfClientX object before you can create DFC objects. Use the IDfClientX interface’s getLocalClient static method. The following example demonstrates how to create a DFC client object in Visual Basic.

Dim myclient As IDfClientDim myclientx As DfClientXSet myclientX = CreateObject(“Documentum.Dfc”)Set myclient = myclientX.getLocalClient

Creating a DFC Session

Provide login information and establish a DFC session with a Documentum server. The DFC client issues server commands and accesses data via the session. Table 2-2 describes the three types of DFC sessions.

Table 2-2 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


Using DFCUsing DFC Tracing

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.

Using DFC Tracing

DFC provides a tracing mechanism through static methods of the DfTrace class. The principal ones are:

setTraceLevel(int traceLevel)steTraceFileName(String fileName)

Visual Basic programs can access the same methods through the IDfClientX interface.

Trace levels are 0 to turn off tracing or an integer from 1 to 10. Higher levels provide more detailed tracing. If you don’t set a trace file, the information goes to the standard output.

Because static methods implement tracing, the facility is independent of specific objects or sessions.


Using DFCUsing the DFC Online Reference Documentation

Using the DFC Online Reference Documentation

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 IDfClient.


3
Managing DFC Sessions 3
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 on the distribution CD.

The chapter contains the following main sections:

■ “Connecting and Disconnecting” on page 3-1

■ “Using a Docbase Map” on page 3-5

Connecting and Disconnecting

As explained in “DFC Programming” 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 on the CD 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);


Managing DFC SessionsConnecting and Disconnecting

in the Java version andSet 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



} } catch(DfException dfe) { System.out.println("\n" + dfe.toString()); } 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()); } catch(DfException dfe) { System.out.println("\n" + dfe.toString());} }

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 FunctionErrorHandler: writeDiagnostic Err.Description, FalseEnd Function



disconnectFromDocbase in Visual Basic

Function disconnectFromDocbase(sess As IDfSession) As Boolean Dim retVal As Boolean On Error GoTo ErrorHandler 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 FunctionErrorHandler: writeDiagnostic Err.Description, FalseEnd Function

displaySessionInfo in Visual Basic

Sub displaySessionInfo(sess As IDfSession) On Error GoTo ErrorHandler 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 SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub


Managing DFC SessionsUsing 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) { System.out.println("\n" + dfe.toString());} }

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 } } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

Step through Docbases in Java

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


Managing DFC SessionsUsing a Docbase Map

for (int i = 0; i < m.getDocbaseCount(); i++) { exDbMap.displayDocbaseInfo(m, i); // Display details exDbMap.connectToDocbase(m, i); } } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

displayDocbaseInfo in Visual Basic

Sub displayDocbaseInfo(m As IDfDocbaseMap, idx As Integer) On Error GoTo ErrorHandler 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 SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

connectToDocbase(name) in Visual Basic

Sub connectToDocbase(docbaseName As String) On Error GoTo ErrorHandler 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 SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub


4
Manipulating Docbase Objects with DFC 4
This chapter describes the way to manipulate Docbase objects. The examples in it are based on the classes DfExCreate, DfExCheckinCheckout, DfExDestroy, and DfExVersionPolicy, which are available in Java and Visual Basic versions on the distribution CD.


■ “Creating and Destroying” on page 4-1

■ “Checking Sysobjects In and Out” on page 4-7

■ “Working With Sysobject Versions” on page 4-11

Creating and Destroying

createCabinet in Visual Basic

Sub createCabinet(sess As IDfSession, cabinetName As String) Dim sysObj As IDfSysObject Dim pObj As IDfPersistentObject On Error GoTo ErrorHandler

Set sysObj = sess.newObject("dm_cabinet") 'Create cabinet object sysObj.setObjectName cabinetName 'Set some attributes sysObj.setSubject "Sample cabinet" Set pObj = sysObj '"Cast" to persistent obj pObj.save 'Save displayObjectInfo sysObj 'Display details

Set sysObj = Nothing 'Release memory Exit SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub


Manipulating Docbase Objects with DFCCreating and Destroying

createFolder in Visual Basic

Sub createFolder(sess As IDfSession, folderName As String, linkName As String)

Dim sysObj As IDfSysObject Dim pObj As IDfPersistentObject On Error GoTo ErrorHandler

Set sysObj = sess.newObject("dm_folder") 'Create folder object sysObj.setObjectName folderName 'Set attributes sysObj.setSubject "Sample folder" sysObj.link linkName 'Set parent folder Set pObj = sysObj '"Cast" to persistent object pObj.save 'Save displayObjectInfo sysObj 'Display details

Set sysObj = Nothing 'Release memory Exit SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

createDocument in Visual Basic

Sub createDocument(sess As IDfSession, docName As String, contentFile As String, linkName As String) Dim sysObj As IDfSysObject Dim pObj As IDfPersistentObject On Error GoTo ErrorHandler Set sysObj = sess.newObject("dm_document") 'Create doc obj sysObj.setObjectName docName 'Set attributes sysObj.setSubject "Sample document" sysObj.setContentType "crtext" sysObj.setTitle "DFC Example Doc" sysObj.setFile contentFile sysObj.link linkName Set pObj = sysObj '"Cast" to persistent object pObj.save 'Save displayObjectInfo sysObj 'Display details

Set sysObj = Nothing 'Release memory Exit SubErrorHandler: writeDiagnostic Err.Description, FalseEnd SubdisplayObjectInfo in Visual BasicSub displayObjectInfo(sysObj As IDfSysObject)

Dim pObj As IDfPersistentObject On Error GoTo ErrorHandler Set pObj = sysObj 'Make it persistent to get ID writeDiagnostic "Id: " + pObj.getObjectId.getId, False writeDiagnostic "Name: " + sysObj.getObjectName, False writeDiagnostic "Owner: " + sysObj.getOwnerName, False writeDiagnostic "Created: " + sysObj.getCreationDate.toString, False



writeDiagnostic "Subject: " + sysObj.getSubject, False writeDiagnostic "Content type: " + sysObj.getContentType, False Exit SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

destroyObject in Visual Basic

Sub destroyObject(sess As IDfSession, objId As String, version As String)

Dim clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject Dim pObj As IDfPersistentObject On Error GoTo ErrorHandler

Set sysObjId = clientx.getId(objId) 'Convert string to sysObjId Set sysObj = sess.getObject(sysObjId) 'Get the object

Dim verString As String 'Display version labels verString = "" For i = 0 To (sysObj.getVersionLabelCount - 1) If i = 0 Then verString = verString + sysObj.getVersionLabel(i) Else verString = verString + ", " + sysObj.getVersionLabel(i) End If Next i writeDiagnostic verString, False

If version = "DESTROYCURRENT" Then 'If call specifies current Set pObj = sysObj ' Make it persistent, pObj.destroy ' then destroy it Else 'Otherwise sysObj.destroyAllVersions ' Destroy all versions End If

If Not pObj.isDeleted Then 'If object still exists 'ERROR ACTION ' Take error action End If

Set sysObj = Nothing 'Release memory Set IDfId = Nothing Exit SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

createType in Visual Basic

Sub createType( sess As IDfSession, 'Session typeName As String, 'Name for the new type supertypeName As String, 'Supertype of the new type lstAttrs As ListBox) 'Uninherited attributes ' (assume user entered these)



Dim dqlStatement As String Dim exQuery As DfExSimpleQuery On Error GoTo ErrorHandler

dqlStatement = createDQLStatement(typeName, supertypeName, lstAttrs) Set exQuery = New DfExSimpleQuery 'Use DfExSimpleQuery class exQuery.execQuery sess, dqlStatement

Set exQuery = Nothing 'Release memory Exit SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

createDQLStatement in Visual Basic

'Return a CREATE TYPE statement in the form:' create type typeName (attr_name datatype, ...) with supertype superNameFunction createDQLStatement( typeName As String, 'Name of new type superName As String, 'Supertype lstAttrs As ListBox 'List of ) As String ' (attr_name datatype) Dim dqlStatement As String Dim attrDefs As String On Error GoTo ErrorHandler

createDQLStatement = "" If lstAttrs.ListCount > 0 Then 'Build comma-separated For i = 0 To (lstAttrs.ListCount - 1) ' string of attributes If Not attrDefs = "" Then attrDefs = attrDefs + "," + lstAttrs.List(i) Else attrDefs = lstAttrs.List(i) End If Next i End If

dqlStatement = "CREATE TYPE " + typeName 'Construct statement If Not attrDefs = "" Then dqlStatement = dqlStatement + " (" + attrDefs + ")" End If dqlStatement = dqlStatement + " WITH SUPERTYPE " + superName createDQLStatement = dqlStatement Exit FunctionErrorHandler: writeDiagnostic Err.Description, FalseEnd Function



createCabinet in Java

void createCabinet(IDfSession sess) throws IOException { try { IDfSysObject sysObj = //Create cabinet obj (IDfSysObject)sess.newObject("dm_cabinet");

sysObj.setObjectName("SampleCabinet"); //Set attributes sysObj.setSubject("Sample Cabinet"); sysObj.save(); //Save cabinet displayObjectInfo(sysObj); //Display details } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

createFolder in Java

void createFolder(IDfSession sess) throws IOException { try { IDfSysObject sysObj = //Create folder obj (IDfSysObject)sess.newObject("dm_folder"); sysObj.setObjectName("SampleFolder"); //Set attributes sysObj.setSubject("DFC example folder"); sysObj.link("SampleParent"); //Assume it exists sysObj.save(); //Save displayObjectInfo(sysObj); //Display details } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

createDocument in Java

void createDocument(IDfSession sess) throws IOException { try { IDfSysObject sysObj = //Create document obj (IDfSysObject)sess.newObject("dm_document"); sysObj.setObjectName("SampleDoc"); //Set attributes sysObj.setSubject("Sample document"); sysObj.setContentType("crtext"); sysObj.setTitle("Sample Document"); sysObj.setFile("C:\test.txt"); //Assume content file sysObj.link("SampleCabinet"); // and cabinet exist sysObj.save(); //Save displayObjectInfo(sysObj); //Display details } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }



displayObjectInfo in Java

void displayObjectInfo(IDfSysObject Obj) { try { System.out.println("\tID : " + Obj.getObjectId().getId()); System.out.println("\tName : " + Obj.getObjectName()); System.out.println("\tOwner : " + Obj.getOwnerName()); System.out.println("\tCreated : " + Obj.getCreationDate()); System.out.println("\tSubject : " + Obj.getSubject()); System.out.println("\tContent : " + Obj.getContentType()); } catch (Exception e) { System.out.println("\n" + e.toString());} }

destroyObject in Java

void destroyObject(IDfSession sess, String objId, String version)throws IOException {

try { IDfId sysObjId = new DfId(objId); //objId --> IDfId obj IDfSysObject sysObj = //Get the object (IDfSysObject)sess.getObject(sysObjId);

//Display version labels for (int i = 0; i < sysObj.getVersionLabelCount(); i++) { System.out.println(sysObj.getVersionLabel(i)); } if (version == "A") { //If call specifies "A" sysObj.destroyAllVersions(); // Destroy all versions } else if (version == "C") { //If "C" sysObj.destroy(); // Destroy current } //Otherwise, do nothing } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

createType in Java

void createType( IDfSession sess, //Session String typeName, //Name of the new type String superName, //Supertype String attrDefs //Attribute definitions ) {

try { String dqlStatement = createDQLStatement(); DfExSimpleQuery exQuery = new DfExSimpleQuery(); exQuery.execQuery(sess, dqlStatement); } catch (Exception e) { System.out.println("\n" + e.toString());} }


Manipulating Docbase Objects with DFCChecking Sysobjects In and Out

createDQLStatement in Java

//Return a create type statement in the form:// CREATE TYPE typeName (attr_name datatype, ...) with supertype superNameString createDQLStatement( String typeName, //Name of the new type String superName, //Supertype String attrDefs //Attribute definitions ) throws IOException {

//Construct the DQL statement String dqlStatement = "CREATE TYPE " + typeName; if (attrDefs != null) { dqlStatement = dqlStatement + " (" + attrDefs + ")"; } dqlStatement = dqlStatement + " WITH SUPERTYPE " + superName; return dqlStatement;}

Checking Sysobjects In and Out

checkOutObject in Visual Basic

Function checkOutObject(sess As IDfSession, objId As String) As Boolean

Dim clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject On Error GoTo ErrorHandler checkOutObject = True Set sysObjId = clientx.getId(objId) 'Create IDfId object Set sysObj = sess.GetObject(sysObjId) 'Create IDfSysObject If sysObj.isCheckedOut Then 'If object is checked out 'ERROR ACTION ' Take error action Else 'If not checked out sysObj.checkout ' Lock the object sysObj.getFile sysObj.getObjectName ' Copy to curr working dir End If Set sysObjId = Nothing 'Release memory Set sysObj = Nothing Exit FunctionErrorHandler: writeDiagnostic Err.Description, False checkOutObject = FalseEnd Function



cancelCheckout in Visual Basic

Function cancelCheckout (sess As IDfSession, objId As String)

Dim clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject On Error GoTo ErrorHandler Set sysObjId = clientx.getId(objId) 'Create IDfId object Set sysObj = sess.GetObject(sysObjId) 'Create IDfSysObject If sysObj.isCheckedOut Then 'If object is checked out sysObj.cancelCheckout ' Cancel checkout removeLocalFile sysObj ' Remove local file cancelCheckout = True Else 'If not checked out 'ERROR ACTION ' Take error action End If Set sysObjId = Nothing 'Release memory Set sysObj = Nothing Exit Function ErrorHandler: writeDiagnostic Err.Description, FalseEnd Function

checkInObject in Visual Basic

Function checkInObject(sess As IDfSession, objId As String)

Dim clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject Dim newSysObjId As IDfId On Error GoTo ErrorHandler

Set sysObjId = clientx.getId(objId) 'Create IDfId object Set sysObj = sess.GetObject(sysObjId) 'Create IDfSysObject

If sysObj.isCheckedOut Then 'If object is checked out writeDiagnostic "Version: CURRENT, " + ' Display version label sysObj.getVersionPolicy.getNextMinorLabel, False sysObj.setFile sysObj.getObjectName ' Get the file Set newSysObjId = sysObj.checkin(False, "") ' Check in as default version writeDiagnostic "Checked in: " + ' Display ID newSysObjId.getId, False removeLocalFile sysObj ' Remove local file checkInObject = True Else 'If not checked out 'ERROR ACTION ' Take error action End If

Set sysObjId = Nothing 'Release memory Set sysObj = Nothing



Set newSysObjId = Nothing Exit FunctionErrorHandler: writeDiagnostic Err.Description, FalseEnd Function

removeLocalFile in Visual Basic

Sub removeLocalFile(sysObj As IDfSysObject) Dim clientx As New DfClientX Dim f As IDfFile On Error GoTo ErrorHandler

Set f = clientx.getFile(sysObj.getObjectName()) 'Create file object f.deleteFile 'Delete the file

Set f = Nothing 'Release memory Exit Sub

ErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

editFile in Visual Basic

Function editFile(sess As IDfSession, objId As String) Dim clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject On Error GoTo ErrorHandler Set sysObjId = clientx.getId(objId) 'Create IDfId object Set sysObj = sess.GetObject(sysObjId) 'Create IDfSysObject Shell "NOTEPAD.EXE " + 'Call editing program sysObj.getObjectName, vbNormalFocus editFile = True Set sysObjId = Nothing 'Release memory Set sysObj = Nothing Exit Function ErrorHandler: writeDiagnostic Err.Description, FalseEnd Function

checkOutObject in Java

boolean checkOutObject(IDfSession sess, String objId) { boolean retVal = false; try { IDfId sysObjId = new DfId(objId); //Create IDfId object IDfSysObject sysObj = //Create IDfSysObject (IDfSysObject)sess.getObject(sysObjId);



if (sysObj.isCheckedOut()) { //If object checked out //ERROR ACTION // Take error action } else { //If not checked out sysObj.checkout(); // Lock it sysObj.getFile(sysObj.getObjectName()); // Get local copy retVal = true; } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } return retVal;}

cancelCheckout in Java

void cancelCheckout(IDfSession sess, String objId)throws IOException { try { IDfId sysObjId = new DfId(objId); //Create IDfId object IDfSysObject sysObj = //Create IDfSysObject (IDfSysObject)sess.getObject(sysObjId);

if (sysObj.isCheckedOut()) { //If object checked out sysObj.cancelCheckout(); // Cancel checkout removeLocalFile(sysObj); // Delete local copy } else { //If not checked out //ERROR ACTION // Handle error } } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

checkInObject in Java

void checkInObject(IDfSession sess, String objId) throws IOException { try { IDfId sysObjId = new DfId(objId); //Create IDfId object IDfSysObject sysObj = //Create IDfSysObject (IDfSysObject)sess.getObject(sysObjId);

if (sysObj.isCheckedOut()) { //If checked out System.out.println("\nObject version: " + // Show label "CURRENT, " + sysObj.getVersionPolicy().getNextMinorLabel()); sysObj.setFile(sysObj.getObjectName()); // Get local copy IDfId newSysObjId = sysObj.checkin(false, ""); // Check in as // default version removeLocalFile(sysObj); // Delete local file } else { //If not checked out //ERROR ACTION // Handle error } } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }


Manipulating Docbase Objects with DFCWorking With Sysobject Versions

removeLocalFile in Java

void removeLocalFile(IDfSysObject sysObj) throws IOException { try { IDfFile f = new DfFile(sysObj.getObjectName()); //Create file object f.deleteFile(); //Delete file } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

editFile in Java

void editFile(IDfSession sess, String objId)throws IOException { try { IDfId sysObjId = new DfId(objId); //Create IDfId object IDfSysObject sysObj = //Create IDfSysObject (IDfSysObject)sess.getObject(sysObjId);

//Spawn child process for the editor to run in String editor = /*Obtain name of editor executable*/; Runtime.getRuntime().exec(editor + " " + sysObj.getObjectName()); } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

Working With Sysobject Versions

displayVersionInfo in Visual Basic

'Display version details about an objectSub displayVersionInfo(sess As IDfSession, objId As String) Dim clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject Dim pObj As IDfPersistentObject Dim verPolObj As IDfVersionPolicy On Error GoTo ErrorHandler Set sysObjId = clientx.getId(objId) Set sysObj = sess.GetObject(sysObjId) Set pObj = sysObj Set verPolObj = sysObj.getVersionPolicy 'Display version label details about the sysobject writeDiagnostic "Object: " + pObj.getObjectId.getId, False writeDiagnostic "Curr vers: " + verPolObj.getSameLabel, False writeDiagnostic "Nxt minor: " + verPolObj.getNextMinorLabel, False writeDiagnostic "Nxt major: " + verPolObj.getNextMajorLabel, False



if verPolObj.getDefaultCheckinVersion() = DFCLib.IDfVersionPolicy_DF_NEXT_MAJOR Then writeDiagnostic "Default label: DF_NEXT_MAJOR", False ElseIf verPolObj.getDefaultCheckinVersion = DFCLib.IDfVersionPolicy_DF_NEXT_MINOR Then writeDiagnostic "Default label: DF_NEXT_MINOR", False ElseIf verPolObj.getDefaultCheckinVersion = DFCLib.IDfVersionPolicy_DF_SAME_VERSION Then writeDiagnostic "Default label: DF_SAME_VERSION", False ElseIf verPolObj.getDefaultCheckinVersion = DFCLib.IDfVersionPolicy_DF_BRANCH_VERSION Then writeDiagnostic "Default label: DF_BRANCH_VERSION", False End If writeDiagnostic "Label: " + verPolObj.getBranchLabel, False writeDiagnostic "Summ: " + verPolObj.getVersionSummary("; "), False writeDiagnostic "Comnt: " + verPolObj.getLogComment, False

'Free memory Set sysObjId = Nothing Set sysObj = Nothing Set verPolObj = Nothing Exit SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

changeVersionInfo in Visual Basic

'Change the version of an object.Sub changeVersionInfo( sess As IDfSession, 'Docbase connection objId As String, 'Object to change symbolicLabel As String) 'Label to assign

Dim clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject Dim newId As IDfId On Error GoTo ErrorHandler

Set sysObjId = clientx.getId(objId) 'Create IDfId object Set sysObj = sess.GetObject(sysObjId) 'Create sysobject

If Not sysObj.isCheckedOut Then 'Check it out sysObj.checkout ' if necessary End If

if sysObj.isCheckedOutBy(sess.getLoginUserName) 'If user has the lock Then sysObj.mark symbolicLabel ' Assign the label Set newId = sysObj.checkin(False, "") ' Chk in minor version displayVersionInfo sess, newId.getId ' Display the new info

Else 'Otherwise 'ERROR ACTION ' Take error action End If

' Free memory. Set sysObjId = Nothing Set sysObj = Nothing



Set newId = Nothing Exit SubErrorHandler: writeDiagnostic "\n" + Err.Description, FalseEnd Sub

displayVersionInfo in Java

//Display version info for an objectvoid displayVersionInfo(IDfSession sess, String objId){ try { //Get ID, then corresponding sysobject, then version policy object IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId); IDfVersionPolicy verPolObj = sysObj.getVersionPolicy();

//Display version label details about the sysobject System.out.println("Version : " + verPolObj.getSameLabel()); System.out.println("Nxt minor: " + verPolObj.getNextMinorLabel()); System.out.println("Nxt major: " + verPolObj.getNextMajorLabel()); if (verPolObj.getDefaultCheckinVersion() == verPolObj.DF_NEXT_MAJOR) { System.out.println("Default label : DF_NEXT_MAJOR");

} else if (verPolObj.getDefaultCheckinVersion() == verPolObj.DF_NEXT_MINOR) { System.out.println("Default label : DF_NEXT_MINOR");

} else if (verPolObj.getDefaultCheckinVersion() == verPolObj.DF_SAME_VERSION) { System.out.println("Default label : DF_SAME_VERSION");

} else if (verPolObj.getDefaultCheckinVersion() == verPolObj.DF_BRANCH_VERSION) { System.out.println("Default label : DF_BRANCH_VERSION"); } System.out.println("Br label : " + verPolObj.getBranchLabel()); System.out.println("Vers summ: " + verPolObj.getVersionSummary(";")); System.out.println("Log cmt : " + verPolObj.getLogComment()); } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

changeVersionInfo in Java

//Change the version of an object.void changeVersionInfo(IDfSession sess, String objId) throws IOException { //Obtain the object ID, then the corresponding sysobject try { IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId);

if (!sysObj.isCheckedOut()) { //Check out if sysObj.checkout(); // necessary }



if (sysObj.isCheckedOutBy(sess.getLoginUserName())) { //If user owns lock //String symbolicLabel = OBTAIN LABEL FROM USER; // get label sysObj.mark(symbolicLabel); // assign it IDfId newId = sysObj.checkin (false, ""); // check in displayVersionInfo(sess, newId.getId()); } else { //Otherwise //ERROR ACTION // error action } } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }


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 the distribution CD.

You can find out more about queries by examining the DfExFullTextQuery class on the distribution CD. This manual does not contain examples from that class.

Basic Queries

exQuery in Visual Basic

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

Dim clientx As New DfClientX Dim col As IDfCollection Dim q As IDfQuery On Error GoTo ErrorHandler

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: writeDiagnostic Err.Description, False


Managing Docbase Queries with DFCBasic Queries

End Function

displayResults in Visual Basic

'Step through a collectionSub displayResults(col As IDfCollection)

Dim resItems As Integer Dim attr As IDfAttr Dim tObj As IDfTypedObject Dim msg As String On Error GoTo ErrorHandler

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 writeDiagnostic msg + tObj.getId(attr.getName()).getId, False ElseIf attr.getDataType = DFCLib.DF_INTEGER Then writeDiagnostic msg + CStr(tObj.getInt(attr.getName())), False ElseIf attr.getDataType = DFCLib.DF_STRING Then writeDiagnostic msg + tObj.getString(attr.getName()), False ElseIf attr.getDataType = DFCLib.DF_TIME Then writeDiagnostic msg + tObj.getTime(attr.getName()).toString(), False Else 'Unknown type 'ERROR ACTION ' Handle error End If Next i Wend

col.Close Exit SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

exQuery 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 } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } return col;}

displayResults in Java

//Step through a collection and display resultsvoid 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 } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }




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 on the distribution CD.

The classes DfExBusinessPolicy and DfExWorkflow show other ways to automate business rules. This manual does not contain examples from those classes.


■ “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 validationvoid 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); IDfValidator validator = perObj.getValidator(); IDfType type = perObj.getType();


Automating Business Rules with DFCChanging Permissions

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); } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }

Changing Permissions

changeBasicPermissions in Visual Basic

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

Dim clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject Dim pObj As IDfPersistentObject

On Error GoTo ErrorHandler

'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 SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

changeExtendedPermissions in Visual Basic

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

Dim clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject Dim pObj As IDfPersistentObject On Error GoTo ErrorHandler 'Use ID string to obtain the ID, then the object Set sysObjId = clientx.getId(objId) Set sysObj = sess.GetObject(sysObjId)

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


changeBasicPermissions in Java

//Change and display object permissionsvoid changeBasicPermissions( IDfSession sess, //Session 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 displayBasicPermissions(sysObj); //Display the object's permissions

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

sysObj.save(); //Save the object displayBasicPermissions(sysObj); //Display the object's permissions

} catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

changeExtendedPermissions in Java

//Change and display extended object permissionsvoid changeExtendedPermissions( IDfSession sess, //Session String objId, //ID of obj for which to change permissions String anotherUser) //A user to whom to assign permissionsthrows IOException { try { //Use ID string to obtain the ID, then the object IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId);

displayExtendedPermissions(sysObj); //Display the ext permissions

//Grant the user WRITE and CHANGE_STATE permissions sysObj.grant(anotherUser, 6, "CHANGE_STATE"); sysObj.save(); //Save the object displayExtendedPermissions(sysObj); //Display the ext permissions

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

sysObj.save(); //Save the object displayBasicPermissions(sysObj); //Display the ext permissions



Automating Business Rules with DFCUsing Private ACLs

Using Private ACLs

privateACLs in Visual Basic

'Create a private ACL and apply it to an objectSub privateACLs( sess As IDfSession, 'Session 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 clientx As New DfClientX Dim sysObjId As IDfId Dim sysObj As IDfSysObject Dim pObj As IDfPersistentObject Dim oldACL As IDfACL Dim newACL As IDfACL On Error GoTo ErrorHandler

'Use ID string to obtain the ID, then the object Set sysObjId = clientx.getId(objId) Set sysObj = sess.GetObject(sysObjId)

'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 SubErrorHandler:


Automating Business Rules with DFCUsing Private ACLs

writeDiagnostic Err.Description, FalseEnd Sub

privateACLs in Java

//Create a private ACL and apply it to an objectvoid privateACLs( IDfSession sess, //Session 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 { //Use ID string to obtain the ID, then the object IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId);

//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);



Automating Business Rules with DFCACL Utility Methods

ACL Utility Methods

permissionToString in Visual Basic

'Convert permission code to nameFunction 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 FunctionErrorHandler: writeDiagnostic Err.Description, FalseEnd Function

extendedPermissionToString in Visual Basic

'Convert extended permission code to nameFunction extendedPermissionToString(permission As String) As String On Error GoTo ErrorHandler 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 FunctionErrorHandler: writeDiagnostic Err.Description, FalseEnd Function

displayBasicPermissions in Visual Basic

'Display object permissionsSub displayBasicPermissions(sysObj As IDfSysObject)


writeDiagnostic " ACL Name: " + sysObj.getACLName, False 'ACL name



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


displayExtendedPermissions in Visual Basic

'Display the object's extended permissionsSub displayExtendedPermissions(sysObj As IDfSysObject) On Error GoTo ErrorHandler 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 SubErrorHandler: writeDiagnostic Err.Description, FalseEnd Sub

permissionToString in Java

//Convert permission code to nameString 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;}



extendedPermissionToString in Java

//Convert extended permission code to nameString 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 permissionsvoid 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))); } } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }

displayExtendedPermissions in Java

//Display the object's extended permissionsvoid 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 } } catch (DfException dfe) { System.out.println("\n" + dfe.toString());} }




7
DFC Methods by Task 7
This chapter provides an index to the major DFC methods, organized by the tasks the methods accomplish. The methods appear under the following categories:

■ “Communicating with the Server” on page 7-2

■ “Administering the System” on page 7-3

■ “Handling Objects” on page 7-5

■ “Retrieving and Setting Attributes” on page 7-10

■ “Searching the Docbase” on page 7-12

■ “Handling Content Objects” on page 7-13

■ “Printing Documents” on page 7-15

■ “Handling Virtual Documents” on page 7-16

■ “Handling Workflows” on page 7-18

■ “Handling Process Definitions” on page 7-19

■ “Handling Activity Definitions” on page 7-20

■ “Handling Work Items” on page 7-21

■ “Managing Inboxes” on page 7-22

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.


DFC Methods by TaskCommunicating 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

Cancel the transaction opened by the last beginTrans call, and discard all of its changes.

void abortTrans()

Open a transaction.void beginTrans()

Save changes made since the last beginTrans call, and close the transaction.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)

Specify the maximum number of rows an RDBMS call can return.void setBatchHint(int batchSize)


DFC Methods by TaskAdministering the System

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]")

Administering the System

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()

Return information about the servers known to the DocBroker.IDfTypedObject getServerMap(String docbaseName)IDfTypedObject getServerMapEx(

String docbaseName,String protocol,String hostName,String portNumber)


DFC Methods by TaskAdministering the System

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,int priority,boolean sendMail,IDfTime dueDate)


DFC Methods by TaskHandling Objects


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)

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)

Remove an intention lock from the object.void cancelCheckout()cancelCheckoutEx(

boolean sendMail,String compoundValue,String specialValue)

Create and save a new version of the checked-out object and remove the lock from 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 remove the lock from 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()

Retrieve the object from the Docbase 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)

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(String accessorName,String extendedPermission)

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()



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(

String accessorName,int accessorPermit,String extendedPermission)

Remove the access control entries or an extended permission for a user or group.

void revoke(String accessorName,String extendedPermission)


DFC Methods by TaskRetrieving and Setting Attributes

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, Id, int, String, IDfTime, IDfValue

For example, the notation appendType refers to the methods:appendBoolean, appendDouble, appendId, appendIntappendString, appendTime, appendValue

The declaration of the value parameter for each of these methods is:boolean value, double value, Id value, int valueString value, IDfTime value, IDfValue value

Add a new value to a repeating attribute.void appendType(

String attrName,type value)


DFC Methods by TaskRetrieving and Setting Attributes

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)

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)

Return True if the specified attribute is repeating, false if it is single-valued. boolean isAttrRepeating(String attrName)


DFC Methods by TaskSearching the Docbase

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)

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)


DFC Methods by TaskHandling Content Objects

IDfId getIdByQualification(String qualification)

Return the collection that resulted from the most recently executed query. IDfCollection getLastCollection()

IDfCollection

Close the collection.void close()

Move to the next item in the collection.boolean next()

To access the current item of the collection, use methods IDfCollection inherits from IDfTypedObject (see “Retrieving and Setting Attributes” on page 7-10).

Handling Content Objects

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)

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)


DFC Methods by TaskHandling Content Objects

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)

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)


DFC Methods by TaskPrinting Documents

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()


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")


DFC Methods by TaskHandling Virtual Documents

Handling Virtual Documents

The following methods manipulate the components of virtual documents.

IDfSysObject

Add a new component to the end of the object’s list of components.IDfId appendPart(

IDfId componentId,String versionLabel,boolean useNodeVerLabel,boolean followAssembly,int copyChild)

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 in the object’s list of components.

IDfId insertPart(IDfId componentID,String versionLabel,IDfId beforeContainmentId,double orderNo,boolean orderNoFlag,boolean useNodeVerLabel,boolean followAssembly,int copyChild)


DFC Methods by TaskHandling Virtual Documents

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,String versionLabel,double orderNo,boolean userNodeVerLabel,boolean followAssembly,int copyChild)


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]")


DFC Methods by TaskHandling Workflows

Handling Workflows

The following methods manage running 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)


DFC Methods by TaskHandling Process Definitions

Restart the halted workflow or specified failed activity.void restart(int activitySeqNo)

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

Resume the halted workflow.void resumeAll()

Handling 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)


DFC Methods by TaskHandling Activity Definitions

Remove the specified link from the process definition.void removeLink(String linkName)

Move the installed process definition back to the validated state.void uninstall()

Validate the process definition.void validate()

Handling 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()


DFC Methods by TaskHandling Work Items

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)

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 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)


DFC Methods by TaskManaging Inboxes

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)

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)




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 DMCLRelationship to DMCL

Figure 8-1 DFC Builds Business Logic Above DMCL

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:

IDfClient client = DfClient.getLocalClient();IDfLoginInfo loginInfo = new DfLoginInfo();loginInfo.setUser("user");loginInfo.setPassword("password");IDfSession session = client.newSession("docbase",loginInfo );

Server API

Data Validation

Workflow Runtime

Version Policy

DMCL

DFC

Operations

DocApp

Object-Oriented Access to Server API

VDM


DFC and DMCLCalling 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 IDfClientXcx = CreateObject(“Documentum.Dfc“)

Calling DMCL Directly

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


DFC and DMCLDMCL 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.

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.

DMCL to DFC Correspondence

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-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.

Table 8-2 DFC methods corresponding to DMCL API commands

DMCL DFC

Abort IDfSession :: abortTrans

Acquire IDfRouter :: acquire



Addnote IDfSysObject :: addNote

Addrendition IDfSysObject :: addRenditionIDfSysObject :: addRenditionEx

Anyevents IDfSession :: hasEvents

Append IDfTypedObject :: appendBooleanIDfTypedObject :: appendDoubleIDfTypedObject :: appendIdIDfTypedObject :: appendIntIDfTypedObject :: appendStringIDfTypedObject :: appendTimeIDfTypedObject :: 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 :: CheckinIDfSysObject :: CheckinEx

Checkinapp IDfSysObject :: checkinApp

Checkout IDfSysObject :: CheckoutIDfSysObject :: CheckoutEx

Table 8-2 DFC methods corresponding to DMCL API commands (continued)

DMCL DFC



Close IDfCollection :: close

Commit IDfSession :: commitTrans

Connect IDfClient :: newSessionIDfClient :: getSharedSession

Count IDfTypedObject :: getAttrCount

Create IDfSession :: newObjectIDfSession :: 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 :: fetchIDfSession :: getObjectIDfSession :: getObjectWithType

Flush IDfSession :: flush

Flushcache IDfSession :: flushCache

Force IDfRouter :: force

Forward IDfRouter :: forward

Freeze IDfSysObject :: freeze


DMCL DFC



Get IDfTypedObject :: getBooleanIDfTypedObject :: getDoubleIDfTypedObject :: getIdIDfTypedObject :: getIntIDfTypedObject :: getStringIDfTypedObject :: getTimeIDfTypedObject :: getValueIDfTypedObject :: getAllRepeatingStringsIDfTypedObject :: getRepeatingBooleanIDfTypedObject :: getRepeatingDoubleIDfTypedObject :: getRepeatingIdIDfTypedObject :: getRepeatingIntIDfTypedObject :: getRepeatingStringIDfTypedObject :: getRepeatingTimeIDfTypedObject :: getRepeatingValue

Getcontent IDfSysObject :: getContentIDfSysObject :: getContentEx

Getdocbasemap IDfClient :: getDocbaseMapIDfClient :: getDocbaseMapEx

Getdocbrokermap IDfClient :: getDocbrokerMapIDfClient :: getDocbrokerMapEx

Getevents IDfSession :: getEvents

Getfile IDfSysObject :: getFileIDfSysObject :: getFileEx

Getlastcoll IDfSession :: getLastCollection

Getlogin IDfSession :: getLoginTicket

Getmessage this happens automatically when the error occursIDfSession :: getMessage

Getpath IDfSysObject :: getPath

Getservermap IDfClient :: getServerMapIDfClient :: getServerMapEx

Grant IDfACL :: grantIDfSysObject :: grant


DMCL DFC



Halt IDfRouter :: halt

Id IDfSession :: getIdByQualification

Insert IDfTypedObject :: insertBooleanIDfTypedObject :: insertDoubleIDfTypedObject :: insertIdIDfTypedObject :: insertIntIDfTypedObject :: insertStringIDfTypedObject :: insertTimeIDfTypedObject :: insertValue

Insertcontent IDfSysObject :: insertContent

Insertfile IDfSysObject :: insertFile

Insertpart IDfSysObject :: insertPart

Inserttask IDfRouter :: insertTask

Link IDfSysObject :: link

Locate IDfTypedObject :: findBooleanIDfTypedObject :: findDoubleIDfTypedObject :: findIdIDfTypedObject :: findIntIDfTypedObject :: findStringIDfTypedObject :: findTimeIDfTypedObject :: 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


DMCL DFC



Query IDfQuery.execute

Queue IDfSysObject :: queue

Readquery IDfQuery.execute

Reassign IDfRouter :: reAssign

Register IDfSysObject :: register

Reinit IDfSession :: reInit

Remove IDfTypedObject :: removeIDfTypedObject :: removeAll

Removecontent IDfSysObject :: removeContent

Removenote IDfSysObject :: removeNote

Removepart IDfSysObject :: removePart

Removerendition IDfSysObject :: removeRenditionIDfSysObject :: removeRenditionEx

Removetask IDfRouter :: removeTask

Repeating IDfTypedObject :: isAttrRepeating

Reset Happens automatically when the error occurs

Restart IDfSession :: reStart

Restore IDfSession :: restore

Resume IDfRouter :: resumeRouterIDfSysObject :: resume

Retrieve IDfSession :: getObjectByQualification

Reverse IDfRouter :: reverse

Revert IDfPersistentObject :: revertIDfSysObject :: revertACL

Revoke IDfACL :: revokeIDfSysObject :: revoke


DMCL DFC



Save IDfPersistentObject :: saveIDfSysObject :: saveLock

Saveasnew IDfSysObject :: saveAsNew

Scope IDfSession :: setDocbaseScope

Set IDfTypedObject :: setBooleanIDfTypedObject :: setDoubleIDfTypedObject :: setIdIDfTypedObject :: setIntIDfTypedObject :: setStringIDfTypedObject :: setTimeIDfTypedObject :: setValueIDfTypedObject :: setRepeatingBooleanIDfTypedObject :: setRepeatingDoubleIDfTypedObject :: setRepeatingIdIDfTypedObject :: setRepeatingIntIDfTypedObject :: setRepeatingStringIDfTypedObject :: setRepeatingTimeIDfTypedObject :: setRepeatingValue

Setbatchhint IDfSession :: setBatchHint

Setcontent IDfSysObject :: setContentIDfSysObject :: setContentEx

Setdoc IDfSysObject :: setIsVirtualDocument

Setfile IDfSysObject :: setFileIDfSysObject :: setFileEx

Setpath IDfSysObject :: setPath

Shutdown IDfSession :: shutdown

Signoff IDfRouter :: signOff

Start IDfRouter :: start

Suspend IDfSysObject :: suspend

Trace IDfSession :: traceDMCL

Truncate IDfTypedObject :: truncate


DMCL DFC



Type IDfSession :: getTypeDescription

Unfreeze IDfSysObject :: unfreeze

Unlink IDfSysObject :: unlink

Unlock IDfSysObject :: cancelCheckoutIDfSysObject :: cancelCheckoutEx

Unmark IDfSysObject :: unmark

Unregister IDfSysObject :: unRegister

Updatepart IDfSysObject :: updatePart

Useacl IDfSysObject :: useACL

Validate IDfRouter :: validateRouter

Values IDfTypedObject :: getValueCount


DMCL DFC




A
Questions and Answers A
This appendix contains a selection of questions that developers sometimes ask as they start to work with DFC. Many of the questions come from an internal mailing list at Documentum.

This appendix contains the following questions:

■ “Folder Path” on page A-1

■ “Create a Microsoft Word Document” on page A-3

■ “Name Strings for IDfOperation” on page A-3

■ “IDfSession.sendToDistributionList Arguments” on page A-4

Folder Path

How do I get the path on the local file system for the content file for a document, given its folder path in Documentum?

Answer 1

The first answer comes from service note 4810. It pertains to the case when the object is checked out. This example uses a hardcoded object_id. Normally, the ID comes from an earlier query or selection. The example also assumes a valid IDfClientX object and session (sess) object.

Private Sub cmdGetPath_Click() Dim id_obj As IDfId Dim po As IDfPersistentObject Dim regobj As IDfClientRegistryObject Dim reg As IDfClientRegistry Dim checked_out_obj As IDfCheckedOutObject ' object_id = "0909f883800003ac"

Using DFC in Documentum Applications A–1

Questions and AnswersFolder Path

If object_id = "" ThenMsgBox "Please select an object_id from _

the Results list" Exit Sub

ElseSet id_obj = clientx.getId(object_id)

' chk_id$ = id_obj.getId' MsgBox chk_id Set po = sess.GetObject(id_obj)

Set reg = clientx.getClientRegistry Set checked_out_obj = reg.getCheckedOutObjectById(id_obj)

' This failed originally... ' VB shows getFilePath as a method of an ' IDfCheckedOutObject object' filepath$ = checked_out_obj.getFilePath

' VB lets you access inherited methods from the children.' You need to call the method from the parent class' where it is defined.' IDfCheckedOutObject extends IDfClientRegistryObject' so getFilePath is called from IDfClientRegistryObject' ...so the right way to do it is.

Set regobj = checked_out_obj filepath$ = regobj.getFilePath End IfEnd Sub

Answer 2

If the document is checked out, you can get the path from the object ID using IDfClientRegistry.getCheckedOutObjectById(), which returns an IDfCheckedOutObject, which is a subclass of IDfClientRegistryObject. Use IDfClientRegistryObject.getFilePath() to get the path to the checked out file.

There are similar calls for “viewed” or “local files” documents.

A–2 Using DFC in Documentum Applications

Questions and AnswersCreate a Microsoft Word Document

Create a Microsoft Word Document

How do I create a word document by calling DFC directly from VB?

Answer

Look at “createDocument in Visual Basic” on page 4-2. Substitute msw8 for crtext in the example. The relevant portion of the code looks like this:

Set sysObj = sess.newObject("dm_document") 'Create doc obj sysObj.setObjectName docName 'Set attributes sysObj.setSubject "Sample document" sysObj.setContentType "msw8" sysObj.setTitle "DFC Example Doc" sysObj.setFile contentFile sysObj.link linkName Set pObj = sysObj '"Cast" to persistent object pObj.save 'Save

Don’t forget to create a persistent object version before saving. If you try to execute sysObj.save, Visual Basic crashes, because a sysobject inherits its save method from the persistent object type, but COM does not handle this inheritance. See the discussion following the example on page 1-3.

Name Strings for IDfOperation

For IDfOperation and its subclasses (for example, IDfCopyOperation), you create an instance by using the DfClientX method getOperation. The getOperation method takes one string that specifies which subclassed Operation type to create. For example

Set IDfCopyOperation = DfClientX.getOperation("Copy")

creates an IDfCopyOperation object.

What are the valid strings that can be passed as operation name to IDfClientX::getOperation to get an IDfOperation?


Questions and AnswersIDfSession.sendToDistributionList Arguments

Answer

The following are the valid strings that can be passed as operation name to IDfClientX::getOperation to get an IDfOperation:

IDfSession.sendToDistributionList Arguments

We need help with the IDfSession.sendToDistributionList method. Several arguments are identified as being of type IDfList, which is a container object, but what type does sendToDistributionList expect to be in the IDfList objects?

For instance we’re currently passing a DfList of IDfUser objects for the first argument, an empty DfList for the second argument (since we don’t want to route to groups, only named users), a string containing a message for the third argument, a DfList of DfID objects for the documents parameter, an integer, and a boolean.

The error message we get back is:[DM_DFC_E_TYPE_MISMATCH_GET]error: "Type mismatch. The type 'String' cannot be returned as type 'Object'."

Answer

Don’t insert IDfUser into the IDfList. Just insert the user name as a string. Don’t use the user’s OS name. Try with a user name in the Docbase.

Checkout Checkout operation

Checkin Checkin operation

Import Import operation

Export Export operation

CancelCheckout CancelCheckout operation

Copy Copy operation

Delete Delete operation

Move Move operation



It is fine if you don’t insert any IDfGroup to the IDfList.

The following VB program runs the sendToDistributionList method: Dim session82ID As StringDim session82 As IDfSession

Dim cx As DfClientXDim client As IDfClient

Private Sub Form_Load() makeSession

End Sub

Sub makeSession() Set cx = New DfClientX cx.setTraceFileName "D:\OpenDialogVBTestTrace.txt" cx.setTraceLevel 6 Set client = cx.getLocalClient Dim li As IDfLoginInfo Set li = cx.getLoginInfo li.setUser ("yourUserName") li.setPassword ("yourPassword") Set session82 = client.getSharedSession("yourDocbase",_

li, "my_key") session82ID = session82.getSessionId Dim ticket As String ticket = session82.getLoginTicket() Dim users As IDfList Set users = cx.getList users.appendString "tuser1" users.appendString "tuser2" 'users.appendString "Lazyworm" Dim groups As IDfList Set groups = cx.getList Dim obj As IDfList Set obj = cx.getList Dim objID As IDfId 'for docbs Set objID = cx.getId("Document Object ID")



obj.appendId objID session82.apiExec "trace", "8,d:\temp\dmcl.txt" session82.sendToDistributionList users, groups,_

"Testing", obj, 10, False 'session82.apiExec "trace", "0" End Sub



I N D E X

AabortTrans method 1-28ACLs 6-2

private 6-5adoptDMCLSession method 1-32API calls 1-30API Config object 1-33apiDesc method 1-30apiExec method 1-30, 6-5apiGet method 1-30apiGetBytes method 1-30apiSet method 1-30, 6-5apiSetBytes method 1-30apply method 1-30archive method 1-30attributes

methods related to 7-10

BbeginTrans method 1-28

Ccabinets 4-1, 4-5cancelCheckout method 4-8cancelling checkouts 4-8changePassword method 1-31checkin method 4-8checking in objects 4-8checking out objects 4-7checkout method 4-7close method 1-35collections

stepping through 5-2COM

inheritance 1-5, 4-1, 4-2com.documentum.com package 1-4com.documentum.fc.client package 1-4

com.documentum.fc.common package 1-5, 1-34

com.documentum.fc.common.session package 1-5

com.documentum.operations package 1-5com.documentum.registry package 1-5commitTrans method 1-28common.documentum.fc.client.qb package

1-4connections

methods related to 7-3connectToDocbase method 3-6content objects

methods that work with 7-13create type statement 4-4, 4-7creating

cabinets 4-1, 4-5documents 4-2, 4-5folders 4-2, 4-5types 4-7

DdeleteFile 4-9deleting

local files 4-9See also destroying

dequeue method 1-30describe method 1-30destroy method 4-6destroyAllVersions method 4-3, 4-6destroying

objects 4-3, 4-6DFC (Documentum Foundation Classes)

COM interface 1-2elements 1-2

DFC (Documentum foundation classes)adopted sessions 2-5comparison with DMCL 8-4

Index–1

datatypes 2-3DMCL process 2-3inheritance 2-1migrating to 8-4naming convention 1-4objects and pointers 2-2online reference 2-6server API calls

8-4shared sessions 2-5

DFC interface hierarchy 1-9DfClient class 1-31, 3-1, 3-2, 3-5DfClientX class 4-7, 4-8DfLoginInfo class 3-2DfPersistentObject class 1-28DfQuery class 1-34DfType class 1-28DfTypedObject class 1-28DfUser class 1-28DfValidationException class 6-1disconnect method 1-31disconnectFromDocbase method 3-5dm_cabinet type 1-26dm_folder type 1-26DMCL commands 8-4DMCL shared library 1-31Docbase scope 1-28Docbases

querying with methods 7-12docbrokers 1-33, 3-5documents 4-2

methods for printing 7-15Documentum foundation classes. See DFCDQL (Document Query Language)

methods that work with 7-12DQL queries 1-35DQL statements 4-4, 4-7

Index-2

EeContent Server

communicating with 7-2methods for communicating with 7-2

enumAttrs method 1-23enumSharedSessions method 1-32execute method 5-1

FfindAttrIndex method 1-23findSession method 1-32flush method 1-31flushCache method 1-31folders 4-2, 4-5

GgetACL method 1-27getAllRepeatingStrings method 1-14getAttr method 1-23, 1-35getAttrCount method 1-23getAttrDataType method 1-23getBoolean method 1-13, 1-26getClient method 1-26getClientConfig method 1-28, 1-33getConnectionConfig method 1-28getContext method 1-33getDataType method 1-35getDBMSName method 1-26, 3-4getDefaultACL method 1-27getDMCLSessionId method 1-26, 3-4getDocbaseConfig method 1-28getDocbaseDescription method 3-6getDocbaseId method 1-26, 3-4getDocbaseMap method 1-32, 3-5getDocbaseName method 1-26, 3-5, 3-6getDocbaseOwnerName method 1-26, 3-4getDocbaseScope method 1-29, 3-4getDocbrokerMap method 1-28getDouble method 1-13getEvents method 1-30


getFile method 4-9getFolderByPath method 1-27getFormat method 1-27getGroup method 1-27getId method 1-13, 4-8getIdByQualification method 1-27getInt method 1-13getLastCollection method 1-30getLocalClient method 3-1getLoginInfo method 1-26getLoginTicket method 1-31, 3-4getLoginUserName method 1-27, 3-4getMessage method 1-30getNextMinorLabel method 4-8GetObject method 4-8getObject method 1-27, 4-3getObjectByPath method 1-27getObjectByQualification method 1-27getObjectName method 4-7, 4-8getObjectWithType method 1-28getQuery method 1-35getRDBMSName is incorrect 1-27getRelationType method IDfRelationType

interface 1-31getRepeatingBoolean method 1-14getRepeatingDouble method 1-14getRepeatingId method 1-14getRepeatingInt method 1-14getRepeatingString method 1-14getRepeatingTime method 1-14getRepeatingValue method 1-14getRunnableProcesses method 1-30getSecurityMode method 1-27, 3-4getServerConfig method 1-28getServerMap method 1-28getServerVersion method 1-27, 3-4, 3-6getSessionConfig method 1-28getSessionId method 1-27, 3-4getSharedSession method 1-32getString method 1-13, 1-35getTasks method 1-30


getTime method 1-13getType method 1-28getTypeDescription method 1-28getTypedObject method 1-36getUser method 1-28getUserByOSName method 1-28getValue method 1-13, 1-34

when to avoid 1-34getVersionLabel method 4-6getVersionLabelCount method 4-3, 4-6getVersionPolicy method 4-8, 4-11getVersionTreeLabels method 1-31grant method 6-2, 6-3

HhasAttr method 1-23hierarchy, of DFC interfaces 1-9

IIdfACL interface 1-27IDfAttr interface 1-23IDfClient interface 1-2, 1-26, 1-28, 1-31, 3-

1, 3-2, 3-5IDfClientX interface 1-35IDfCollection interface 1-30, 1-35, 5-1IDfDocbaseMap interface 1-32, 3-5IDfDocument interface 1-25IDfFolder interface 1-27IDfFormat interface 1-27IDfGroup interface 1-27IDfId interface 1-13, 1-14, 1-27, 1-30, 1-31IDfList interface 1-30IDfLoginInfo interface 1-26, 1-32, 3-2, 3-3IDfPersistentObject interface 1-8, 1-27, 1-

28IDfProperties interface 1-33IDfSession interface 1-2, 1-26, 1-29, 1-32IDfSysObject interface 1-5, 1-24IDfTypedObject interface 1-28IDfValidator interface 6-1

Index-3

IDfValue interface 1-34IDfVersionTreeLabels interface 1-31IDfWorkflowBuilder interface 1-30inboxes

methods related to 7-22isACLDocbase method 1-27isAdopted method 1-27isAttrRepeating method 1-23isCheckedOut method 4-7, 4-8isConnected method 1-27, 3-2isDeleted method 4-3isRemote method 1-27isShared method 1-27

Llink method 4-2, 4-5

Mmethods

server communication 7-2

NnewObject method 4-1, 4-2, 4-5newObjectWithType method 1-28newSession method 1-32, 3-1, 3-2newWorkflowBuilder method 1-30

Oobjects

methods for handling 7-5

Ppasswords 1-32permissions 6-2, 6-3persistent objects 1-7, 1-27printing

methods related to 7-15private ACLs 6-5purgeLocalFiles method 1-31

Index-4

Qqueries 1-36, 5-1

displaying results 5-2flow of processing 1-34

queues, user. See inboxes

RreInit method 1-31removeContext method 1-33repeating attributes 1-15resolveAlias method 1-30restore method 1-31revoke method 6-3rows 1-36

Ssave method 4-5, 6-5saving

sysobject as persistent object 4-1, 4-2sendToDistributionList method 1-30sessions 1-26, 1-31, 1-32, 3-1

keys 1-32multithreading 1-29shared 1-32

setACL method 6-5setBatchHint method 1-31setBoolean method 1-13setContentType method 4-2, 4-5setDocbaseScope method 1-29setDocbaseScopeById method 1-29setDomain method 3-3setDouble method 1-13setFile method 4-2, 4-5, 4-8setId method 1-13setInt method 1-13setObjectName method 4-1, 4-2, 4-5setPassword method 3-2setRepeatingBoolean method 1-14setRepeatingDouble method 1-14setRepeatingId method 1-14


setRepeatingInt method 1-14setRepeatingString method 1-14setRepeatingTime method 1-14setRepeatingValue method 1-14setString method 1-13setSubject method 4-1, 4-2, 4-5setTime method 1-13setTitle method 4-2, 4-5setUser method 3-2setValue method 1-13shared sessions 1-32shutdown method 1-31subconnections

methods related to 7-3subtypes 1-7supertypes 1-7, 1-8sysobjects 1-24system administration

methods for 7-3

TtraceDMCL method 1-30transactions 1-28type libraries 1-2typed objects 1-28

Uunlock method 1-29user names 1-32

VvalidateAttrRules method 6-2versions 4-11virtual documents

methods related to 7-16

Wwarnings

COM interface inheritance fails 2-1


workflow templates 1-30workflows 1-30

Index-5

Index-6