Kofax DM API User Manual

DM API Reference G uide

Hummingbird Enterprise

™

2004

Hummingbird Enterprise™ 2004, DM, and RM are trademarks of Hummingbird Ltd. and/or its subsidiaries. All other copyrights, trademarks, and trade names are the property of their respective owners.

Your enclosed license agreement with Hummingbird Ltd. or one of its affiliates specifies the permitted and prohibit ed uses of the pr oduct. A n y unau thorized d uplicatio n or use o f the pr od uct in whole or part is strictly forbidden. No part of this document may be copied, reproduced, translated, or transmitted in any form or by any means without the prior written consent of Hummingbird Ltd.

RESTRICTED RIGHTS LEGEND. Unpublished rights reserved under the copyright laws of the United States and any other appropriate countries. The SOFTWARE is provided with restricted rights. Use, duplications, or disclosure by the U.S. Government is subject to restriction as set forth in subparagraph (c) of The Rights in Technical Data and Computer Software clause at DFARS 252.2277013, and subparagraph (c)(1) of the Commercial Computer Software-Restricted Rights clause at 48 CFR 52.227-19, as applicable, similar clauses in the FAR and NASA FAR Supplement, any successor or similar regulation.

The information contained in this document is subject to change without notice. If this document is provided in both printed and electronic form, the electronic form will govern in the event of any inconsistency. Information in this document is subject to change without notice and does not represent a commitme nt on th e part of Hummingbird Ltd. Not all copyrights pertain to all products.

DISCLAIMER. Hummingbird Ltd. software and documentation have been tested and reviewed. Nevertheless, Hummingbird Ltd. makes no warranty or representation, either express or implied, with respect to the software and documentation included. In no event will Hummingbird Ltd. be liable for direct, indirect, special, incidental, or consequential damages resulting from any defect in the software or documentation included with these products. In particular, Hummingbird Ltd. shall have no liability for any programs or data used with these products, including the cost of recovering such programs or data.

Corporate Headquarters 1 Sparks Avenue, Toronto, Ontario M2H 2W1 Canada U.S./Canada Toll-free: 1 877 FLY HUMM (359 4866) Tel: 1 416 496 2200, Fax: 1 416 496 2207, Website: www.hummingbird.com

Preface

AddLogin 128 AddLoginLicensed 132 AddOrderByProperty 135 AddProperty 137 AddReturnMetaProperty 138 AddReturnProperty 140 AddSearchCriteria 142 AddSearchLib 145 AddTrustee 147 AddUserFilterCriteria 149 BeginGetBlock 150 BeginIter 151 BytesRead 153 BytesWritten 154 ClearOrderByProperties 155 ClearUserFilterCriteria 156 Clone 157 ColumnCount 158 Create 159 Delete 160 DeleteProperty 161

v

DeleteTrustee 163 EndGetBlock 164 ErrDescription 165 ErrNumber 166 Execute 167 Fetch 169 FetchTrustees 170 GetAliasList 174 GetAt 175 GetColumnCount 176 GetColumnName 177 GetColumnValue 178 GetCurrentPropertyName 179 GetCurrentPropertyValue 180 GetCurrentTrusteeFlags 181 GetCurrentTrusteeName 182 GetCurrentTrusteeRights 183

vi

GetDBVendor 184 GetDomainList 185 GetDOCSUserName 187 GetDST 188 GetFailedLoginList 189 GetGroupList 191 GetGroupMembers 193 GetLoginLibrary 195 GetMetaPropertyValue 196 GetMetaRowsFound 198 GetNextKey 200 GetPrimaryGroup 203 GetProperties 204 GetProperty 205

GetPropertyIndex 206 GetPropertyValue 209 GetPropertyValueByIndex 211 GetReturnProperties 213 GetReturnProperty 215 GetRowCount 216 GetRowsAffected 217 GetRowsFound 218 GetSearchCriteria 220 GetSize 221 GetSQLErrorCode 223 GetTrustee 225 GetTrusteeIndex 227 GetTrusteeRights 229 GetTrustees 230 GetUserFullName 231 GetUserGroups 233 GetUserList 235 GetValue 237 GrantRight 238 HasRight 240 IsEmpty 242 IsMemberOf 243 NewEnum 245 Next 246 NextMetaRow 247 NextProperty 248 NextRow 249 NextTrustee 251 OnEndPage 252 OnStartPage 253

vii

Read 254 ReleaseResults 255 Reset 256 RevokeRight 257 Seek 259 SetChunkFactor 260 SetComplete 262 SetDST 263 SetLibrary 265 SetLookupId 266 SetMaxRows 268 SetMetaRow 270 SetObjectType 272 SetOptions 274 SetProperties 276 SetProperty 277 SetReturnProperties 279

viii

SetRow 280 SetSearchCriteria 282 SetSearchObject 284 SetTargetProperty 286 SetTrustee 288 SetTrustees 290 SetTrusteeRights 292 Skip 293 UnitName 294 UnitType 295 Update 297 UpdateTrustees 298 UserName 299 Write 300

Chapter 5 DM API Tokens

%ADD_ATTACHMENT 302 %ATTACHMENT_ID 303 %CHECKIN_DATE 304 %CHECKOUT_COMMENT 305 %CONTENT 306 %CONTENTS_AFTER_ITEM 308 %CONTENTS_COPY_CONTENTS 310 %CONTENTS_DIRECTIVE 312 %CONTENTS_ITEM 314 %CONTENTS_MOVE_AFTER 316 %CONTENTS_MOVE_DOWN 318 %CONTENTS_MOVE_TO_TOP 320 %CONTENTS_MOVE_UP 322 %CONTENTS_REORDER_CONTENTS 324 %CONTENTS_SRC_PARENT 326 %CONTENTS_SRC_PARENT_LIBRARY 327 %CONTENTS_SRC_PARENT_VERSION 328 %CONTENTS_DST_PARENT 329 %CONTENTS_DST_PARENT_LIBRARY 330 %CONTENTS_DST_PARENT_VERSION 331 %CONTENTS_PARENT 332 %CONTENTS_PARENT_VERSION 333 %CONTENTS_WHERE_USED 334 %COPYDOC 336 %COPYDOC_LIBRARY 337 %COPYDOC_VERSION 338 %DATA 339 %DELETE_ALL 341 %DELETE_EXPUNGE 342 %DELETE_OPTION 343

ix

%DELETE_PHYSICAL_FILES 345 %DOCS_LIBRARY_NAME 346 %DOCUMENT_NUMBER 348 %EFFECTIVE_RIGHTS 350 %ELAPSED_TIME 352 %ENCAPSULATION_TYPE 354 %FILTER_DISABLED_ROWS 356 %FOLDERITEM_LIBRARY_NAME 357 %FORM_APPLICATION 359 %FORM_DEFAULT_PRIMARY 361 %FORM_LIST_TYPE 363 %FORM_NAME 365 %FORM_PROFILE_DEFAULTS 367 %FORM_TITLE 369 %FT_CHARACTER_SET 371 %FT_CONFIDENCE 373 %FT_FORMAT 375 %FT_MARKER_LIST 377 %FT_SCORE 379 %FT_SMART_DOCUMENT 381 %FT_TIMESTAMP 383 %FT_VCC_LIST 385 %FT_VCC_RULES 387 %GET_ALL_RELATED 389 %GET_LOCAL_RELATED 391 %GET_RELATED_ITEMS 393 %GET_REMOTE_RELATED 395 %HAS_SUBFOLDERS 397 %HITLIST 399 %ISTREAM_STATSTG_CBSIZE_LOWPART 401 %LOCK 402

x

%LOCK_FOR_CHECKOUT 403 %LOOKUP_ID 404 %MAKE_READ_ONLY 406 %MAXDAYS 408 %NUM_COMPONENTS 409 %OBJECT_IDENTIFIER 410 %OBJECT_TYPE_ID 412 %ORDER_BY 413 %PCD_DELETEVERSION 414 %PCD_NEW_VERSION 415 %PCD_NEWSUBVERSION 416 %PCD_PARM_HTML_RENDERING 417 %PCD_PARM_LIB_SETTINGS 419 %PCD_UPDATE_VERSION 420 %PR_ACCESS_CONTROL 421 %PR_CONTENT_COPY 423 %PR_CONTENT_DELETE 425 %PR_CONTENT_EDIT 427 %PR_CONTENT_RETRIEVE 429 %PR_CONTENT_VIEW 431 %PR_EDIT 433 %PR_VIEW 435 %PRIMARY_KEY 437 %PROFILE 438 %PROPERTYNAME 440 %PROPERTYTYPE 442 %PUBLISH_VERSION 444 %QS_DELETE 446 %QS_EDIT 448 %QS_VIEW 450 %RECENTACTIVITYDATE 452

xi

%RECENTACTIVITYTIME 454 %RELATED_REMOTE_LIBS 455 %REMOVE_READ_ONLY 456 %RENDITION_TYPE 459 %RIGHT8 461 %RIGHT9 463 %SCORE_GRAPHIC 465 %SCORE_PERCENT 467 %SEARCH 469 %SECURITY 471 %STATUS 472 %TARGET_LIBRARY 474 %TITLE 475 %TRUSTEE_ID 477 %TRUSTEE_RIGHTS 479 %TRUSTEE_TYPE 481 %TRUSTEES_ADD 483

xii

%TRUSTEES_REMOVE 485 %TRUSTEES_SET 487 %TRUSTEES_UPDATE 489 %UNLOCK 491 %UNPUBLISH_VERSION 492 %USER_ID 494 %VERIFY_ONLY 495 %VERSION_AUTHOR 497 %VERSION_COMMENT 498 %VERSION_DIRECTIVE 500 %VERSION_ID 502 %VERSION_LABEL 504 %VERSION_TO_INDEX 505 %VERSION_TYPIST 506

%VISIBLE 507

xiii

xiv

About This Guide

This guide describes the application programming interface (API) that is available as part of DM. It identifies each of the objects comprising the API and discusses the methods and properties that each object supports.

Who Should Read This Guide

Users who extend DM functionality by creating their own custom enhancements will use the DM API Reference Guide to show them how their extensions can operate seamlessly with the base product. This will also be the case for software developers who create their own software products for specialized applications that address unique user needs that are not addressed by DM.

Preface

How This Guide Is Organized

This book has four chapters.

• Chapter 1: The DM Architecture—This chapt er describes how the API and other components of DM work together.

• Chapter 2: An Overview of the DM API—This chapter describes the overall structure of DM.

• Chapter 3: DM API Objects —This chapter describes the objects in the API and lists the methods and properties that each supports.

• Chapter 4: DM API Methods and Properties —This chapter describes each of the methods and properties that are supported by DM API objects.

• Chapter 5: DM API Tokens —This chapter describes each of the tokens that are supported by DM API methods.

xv

Documentation Conventions

This book uses the following fonts and styles to indicate different types of information.

Convention Meaning

Italic

Monospaced font Indicates a file, directory, drive or command

Bold

> Separates items on more than one

Cross-reference Click on these links to be taken to related

Professional Services

Hummingbird’s Professional Services’ consultants and educators successfully design, create, and implement powerful integrated solutions based on Hummingbird technology. They are dedicated to forging sustainable, long-term relationships with our clients and partners by delivering superior consulting, training, and education solutions.

Professional Services' engagements include all aspects of the system implementation life cycle, specifically:

• project management

• planning and process analysis

• requirements definition

• software installation and prototyping

• custom code development

• code reviews and walkthroughs

• integration with non-Hummingbird technology

•benchmarking

• data conversion and migration

• documentation knowledge transfer Our consultants are available to help you build or enhanc e application

components, high-level APIs, user interfaces and system administration utilities for Windows clients, Web clients, and serverside applications using various development environments.

If you are implementing enterprise portals, document and knowledge management, data integration and reporting, or ETL, Hummingbird Professional Services can help guide you to success. To find out more about Professional Services visit our Web site at http://

www.hummingbird.com/solutions/services or send an e-mail to getinfo@hummingbird.com.

xvii

Where to Go for Information

On the Web Our Web site at www.hummingbird.com/support/dkm/ carries the

most up-to-date information about Hummingbird’s document and knowledge management products. This information is presented in individual technical bulletins and in Knowledge Base Solutions, each dealing with a specific topic that is not covered in our manuals or that updates information in the manuals. Before installing or upgrading DM, we suggest you browse through the bulletins or search the Knowledge Base for items that may be pertinent to your installation. For WebSupport, you will be asked to enter your user name and password for authentication. If you have not registered for a WebSupport account, you can do so at www.hummingbird.com/

support/dkm/registration.html.

On the DM Suite

CD

In addition to software, the DM Suite CD houses important documentation and ancillary files to assist you install and use DM.

Release Notes

The DM Release Notes for the current version reside in the

…\Documentation\Readme

contain information that came to light after the documentation was printed. Hyperlinks to known bugs and workarounds ar e also listed in the Release Notes.

folder on the CD. The release notes

Installing Acrobat Reader

The DM product line’s online manuals, which are published in PDF format, are provided on the DM Suite CD . To r ead these manuals, you will need a copy of Ad obe Acr obat Reade r installed on your machine . A setup program for Acrobat Reader 5.0 is provided on the DM CD. If you do not already have a copy, follow the instructions below.

1 Insert the DM Suite CD into your computer’s CD-ROM drive. 2 The DM product line installation menu will be displayed. Click

Documentation.

xviii CHAPTER 3

3 Click Install Acrobat Reader. The Acrobat Reader version 5.0

install program will launch.

4 Follow the on-screen instructions and install the program. When

complete, exit the DM Product Line Installation menu.

To access the entire DM do cumentation set:

1 Insert the DM Suite CD into your computer’s CD-ROM drive. 2 The DM Product Line Installation menu will be displayed. Click

Documentation.

3 Select Browse Documentation. Double-click the Online

Manuals

4 Double-click HummingbirdDMBooks.html. Your Internet

browser will launch and a menu listing the DM documentation set will appear.

5 To open a document, click the document name.

directory.

Technical Support and Training

North America

Technical Support

Asia/Pacific

Technical Support

Europe Technical

Support

124 Marriott Drive Tallahassee, FL 32301 USA Telephone: Fax: 850 942 8085 E-Mail: supportTLH@hummingbird.com

Level 12 80 Mount Street North Sydney, NSW 2060, Australia Telephone: 61 2 9923 2011 Fax: 61 2 9922 3097 E-Mail: supportsyd@hummingbird.com

20 rue Thérèse 75001 Paris, France Telephone: 33 1 55 35 96 80 Fax: 33 1 42 61 31 87 E-Mail: support.eu.kmdm@hummingbird.com

800 486 0095 from 8:00 A.M. to 8:00 P.M. ET

xix

Training Hummingbird’s Education Services offers courses at authorized

training centers worldwide. For more information or to register for classes, contact Hummingbird Education Services:

Telephone: 613 238 1761 E-Mail: education@hummingbird.com Internet Address: www.hummingbird.com/education

xx CHAPTER 3

Chapter

1

The DM Architecture

In This Chapter

This chapter provides an overview of the DM functionality, ill ustrating how the major components of DM are designed to work with one another. C ode samples illustrate how custom applications can perform many basic operations, such as allowing user access and performing searches.

THE DM ARCHITECTURE 1

The DM Multi-Tier Architecture

DM is an application that runs on Window s NT/2000/XT P ro systems. As shown in the illustration below, the DM API provides a basic set of operations that interface with the DM Server. Client applications— whether the DM Webtop, any of the DM Extensions, or custom software you might develop—extend the DM API by providing a user interface and any other functionality appropriate to the new application.

DM Functionality

The diagram below illustrates how multiple clients can connect to a single DM Server and how a DM Server can connect to multiple DM repositories. A DM repository is comprised of the Document File Store, the SQL database, and the full-text indexer.

2 CHAPTER 1

DM Functionality

The DM Server is a transaction server, similar to Microsoft SQL Server .

The DM Server manages database connections via a connection pool. A client application connects to the DM Server via DCOM (Distributed Component Object Model) interfaces that are typically free threaded. The DM executable file (DOCSFusion.EXE) loads COM objects configured in the registry. Once connected, users can connect to any repositories to which they have access rights.

DM is stateless, so the client does not remain connected to the DM Server. A client application submits a transaction using a document security token (DST), and DM then determines the validity of the DST. If the DST is valid, the DM Server processes the transaction and returns the results to the client software. No state information is kept by the DM Server about the client.

Note: DM enforces document security rights. Users cannot access objects (for example, documents or folders) to which they do not have rig hts.

In DM, library maintenance tasks such as archiving and full-text indexing occur in the background, and the re is no nati ve user inte rface (UI). (T o simplify these diagrams, DM Index er Servers are not shown.) Developers must create user interfaces to connect to the DM Server.

THE DM ARCHITECTURE 3

Document Security

Tokens

Transactions With DM, multiple libraries can be configured for each server to

A document security token (DST) is initially constructed by DM when a user logs on via a client application to the server and is required for DM transactions. The DST can be used across multiple DM Servers—when the user logs on to other DM Servers to access other Document libraries, the server information is appended to the DST—or the client application can use multiple DSTs.

manage, and transactions can occur on these specified libraries. The libraries available to a DM Server are configured via the DM Server Manager program and the PCDOCS.INI file. The client application must handle multiple library access and take into account issues s uch as that of incompatible forms.

Caution: You have direct access to the SQL database, allowing yo to implement many operations directly by use of the computer langu age you use for your application. For example, specialized terms you implement can be managed by accessing the TERMINOLOGY table in the SQL database.

It is recommended that you do not use this capa bility. Using the appropriate DM API objects and methods will insure that the correct security controls are enforced and that other internal database relationship s are main tained.

DM Object Model

DM provides the following document management services:

• Search for documents stored in DM file stores.

• Create, delete, and update document profiles.

• Modify security on profiles and folders.

• Upload files to and download files from DM file stores.

DM Objects DM objects are low-level and general objects that presuppose a

knowledge of how the DM environment operates (for example, how security rights are enforced). It is also important for DM API users to have a thorough understanding of both client and server software, as well as how they interact.

Types of DM Objects

The DM Object Model consists of Distributed Component Object Model (DCOM) objects that are exposed via DM. Operations on DM objects map to operations on tables and typically require several properties to be set to define the objects. The object properties after instantiation may differ depending on how the object was created.

When building a DM client application, you will use the PCDClient type library (pcdclient.dll) and development tools such as C++, Visual Basic, Java, or Active Server Pages.

Note: Examples in this document show sample code w ritten in Visual Basic. Similarly, this document refers to API items using Visual Basic nomenclature in preference to terminology more common to C++, Java, or other progra mming language environments. For example, the term “o bject” is generally used in preference to “class” or “interface.” Also, “method” is used in place of “function,” and “property” is used in place of “attribute.”

DM Forms DM forms include those used as profile forms, query-by-example and

other search forms, results lists, and lookups. These forms are fully customizable using DM Designer. Using DM Designer, you can also create your own forms.

With DM, forms are an abstraction layer for the SQL database that allows your applications to access the library database. DM supports Search, Query, Lookup, and Profile forms. DM uses a form definition to mediate client requests for data and r ead/write access to the database. The form definition maps the name of a field in the form to a SQL column in the database. Most client appli cation calls are done using the name of the field as shown on the form, rather than the name of the column in the SQL database. DM uses the SQL_INFO call, which is embedded in the form definition that resides in the SQL database. Each form must specify a primary table in the database as part of its form definition.

Types of DM Objects

The DM API defines several types of objects:

• Support (read only), which facilitates the log on process.

THE DM ARCHITECTURE 5

Types of DM Objects

• Query (read only), which is used for search, Quick Retrieve, and lookups.

• PCDDocObject (read/write), which implements the DM objects and modifies tables in the library database.

• Child objects of PCDDocObject (read/write), which get or set trustees, and perform file uploads and downloads.

Defining a DM

Object

DM Support

Objects

In general, to define a DM object, you need to do the following:

1 Create the object in one of the following ways:

—Early bind:

Dim search as PCDSearch

—Late bind:

Dim search as Object Set search = _

CreateObject("PCDClient.PCDSearch")

2 Set the DST using the SetDST method. 3 Specify a library for the object. 4 Specify the object type (the name of a form). 5 Set properties to identify the specific object. 6 Perform a method.

The DM support objects provide a number of functions for the DM Server:

6 CHAPTER 1

• Provide information required for the DM Server log on process.

• Log on to the DM Server.

• Return a document security token (DST) for later transactions.

• Provide additional general objects that do not require a DST.

The following are DM support objects:

The Logon Process

• PCDError

• PCDGetLoginLibs

• PCDLogin

• PCDNetAliasList

DM Query Objects Query objects are used to search the library database. The query is

constructed in memory, e xecut ed, and the results returned to the client application. The following are DM query objects:

• PCDLookup

• PCDRecentDoc

• PCDSearch

Document Objects Document objects are document management system (DMS) objects

that represent database entities that can be modified. These entities include profiles, projects, and Quick Searches. The object identifier is:

PCDDocObject

Child Objects of

PCDDocObject

The following are child objects of PCDDocObject objects:

• PCDGetDoc

Objects

• PCDGetStream

• PCDPutDoc

• PCDPutStream

• PCDPropertyList

• PCDTrusteeList

The Logon Process

The following subsections describe the client logon process for DM.

THE DM ARCHITECTURE 7

The Logon Process

Getting a List of

Available Libraries

The following example displays a list of libraries managed by the DM Server that the user can log on to.

. . . Private Declare Function GetUserName Lib _ "advapi32.dll" Alias "GetUserNameA" _ (ByVal lpbuffer As String, nSize As Long) _ As Long Public OK As Boolean Private Sub Form_Load() Dim sBuffer As String Dim lSize As Long Dim libname As String

Dim i As Long Dim lim As Long Dim opOK As Boolean

Dim Libs As New PCDGetLoginLibs

'Initialize public variables. OK = False dst = "" user = "" library = "" group = "" 'Get the user we are currently logged on as. sBuffer = Space$(255) lSize = Len(sBuffer) Call GetUserName(sBuffer, lSize) If lSize > 0 Then txtUserName.Text = Left$(sBuffer, lSize) Else txtUserName.Text = vbNullString End If

'Get the list of available libraries 'and fill in combo box. Libs.Execute lim = Libs.GetSize() - 1 opOK = Libs.ErrNumber = 0 LibCombo.Text = ""

For i = 0 To lim

8 CHAPTER 1

The Logon Process

If (opOK) Then libname = Libs.GetAt(i) opOK = opOK And Libs.ErrNumber = 0 If i = 0 Then LibCombo.Text = libname LibCombo.AddItem libname End If Next 'List of Network logon types. NetworkType.AddItem "Network Bindery" NetworkType.AddItem "Network NDS" NetworkType.AddItem "Microsoft Network" NetworkType.Text = ""

End Sub

Private Sub cmdCancel_Click() OK = False Me.Hide End Sub

Providing Library

Access

The next subroutine creates the PCDLogin object. It appends a network alias to a document security token (DST). The following algorithm is used:

1 Create the PCDLogin object. 2 Call the AddLogin method, which provides the logon mode,

logon location, user name, and password.

3 Call the Execute method. 4 Call the GetDST method.

Note: If there is no network alias, the user name a nd Attaché password are used. Also, a second logon may be needed when file access occurs, such as when the user logs on to the DM Server or when a valid user acco unt on a particular DM Server is required. A second logon may also be required if a network alias to a DM Server is not set in Library maintenance.

The following example illustrates how you can provide Library logon support for your users:

Private Sub cmdOK_Click() Dim login As New PCDLogin Dim fl As Object Dim i As Long

THE DM ARCHITECTURE 9

The Logon Process

Dim lim As Long Dim LoginType As Integer Dim emsg As String

If (NetworkType = "Network Bindery") Then LoginType = 1 ElseIf (NetworkType = "Network NDS") Then LoginType = 2 ElseIf (NetworkType = "Microsoft Network") Then LoginType = 8 Else LoginType = 0 End If

If (Domain.Text <> "" And LoginType <> 0) Then 'The Network and Domain are specified, so 'log on to the network. login.AddLogin LoginType, Domain.Text, _ txtUserName.Text, txtPassword.Text Else 'Just log on as a Library user. login.AddLogin 0, library, _ txtUserName.Text, txtPassword.Text End If OK = (login.ErrNumber = 0)

If (OK) Then login.Execute OK = (login.ErrNumber = 0) End If

If OK Then 'Set the public variables others will 'need and then hide. library = login.GetLoginLibrary() user = login.GetDOCSUserName() group = login.GetPrimaryGroup() dst = login.GetDST Me.Hide Else 'Unable to log on. emsg = "Error logging on: " & _ login.ErrNumber & String(1, 13) & _ String(1, 10) & login.ErrDescription MsgBox emsg, , "Logon" txtPassword.SetFocus

10 CHAPTER 1

DM Search Transactions

txtPassword.SelStart = 0 txtPassword.SelLength = Len(txtPassword.Text) End If

'Dump any available information for 'debugging purposes. Set fl = _ CreateObject("PCDClient.PCDNetAliasList") Set fl = login.GetFailedLoginList

lim = fl.GetSize() - 1 For i = 0 To lim Debug.Print "FAILED List: "; _ fl.UnitName(i) & ";" & fl.UnitType(i) _ & ";" & fl.UserName(i) Next

Set fl = Nothing Set fl = login.GetAliasList

lim = fl.GetSize() - 1

For i = 0 To lim Debug.Print "Alias List: "; _ fl.UnitName(i) & ";" & fl.UnitType(i) _ & ";" & fl.UserName(i) Next

Set fl = Nothing Debug.Print "User: "; login.GetDOCSUserName() _ & " Primary Group: " & _ login.GetPrimaryGroup() & " LoginLib: " _ & login.GetLoginLibrary()

End Sub

DM Search Transactions

A typical search session involves the following:

1 A user enters search criteria in a user interface from which search

data is extracted. Most commonly, the user interface is a form.

2 A search request is sent from the client.

THE DM ARCHITECTURE 11

DM Search Transactions

3 The DM Server does the following:

— Captures search criteria, and immediately returns a “no

results” message to the client.

— Performs the search on requested databases and full-text

repositories. — Collects the results set and sorts it as user specified. — Caches the results of the search and returns them to the client

when requested.

The cached results can be deleted by the client using the R eleaseResults method. Also, results may time out based on administration settings.

The following sections describe various ways to execute search transactions in a DM environment.

General Steps to

Performing a

Search

The following are the general steps in performing a search in the DM environment:

1 Create the search object. 2 Set the DST. 3 Add a search library (or multiple libraries). 4 Set the search object to the name of the search form. 5 Add return properties. Properties refer to the field names in the

form. You need to specify the fields to return in the results set. Alternately, you can set an entire collection of properties using

SetReturnProperties.

6 Add search criteria, specifying a field name in the form and its

value.

7 Add a property by which the return properties are to be ordered. 8 Set the maximum number of rows to return in the results set. 9 Optionally, set a chunk factor, which is the number of rows to

return from the server results set into the local cache in one

12 CHAPTER 1

DM Search Transactions

operation. The default is 10. You do not need to repeat the execution of the search to get the next chunk. DM automatically does that for you.

10 Execute the search. For the search results returned, you can:

• Obtain the number of rows found.

• Get all the returned properties.

• Iterate through the rows.

• Get values for properties returned by the search.

• Release the results set to free server memory.

Retrieving

Recently Edited

Documents

The following example shows how to retrieve a list of documents that the user has recently edited.

. . . Private Sub cmdCancel_Click() Unload Me End Sub

Private Sub Form_Load() Dim rec As New PCDRecentDoc Dim i As Long Dim lim As Long Dim row As String

Screen.MousePointer = vbHourglass

rec.SetDST DST rec.AddSearchLib library 'This example uses the CYD_DEFPROF search form. rec.SetSearchObject "CYD_DEFPROF" rec.AddSearchCriteria "TYPIST_ID", Chr(3 4) _ & user & Chr(34)

rec.AddReturnProperty "DOCNUM" rec.AddReturnProperty "SYSTEM_ID" rec.AddReturnProperty "APP_ID"

THE DM ARCHITECTURE 13

DM Search Transactions

rec.AddReturnProperty "LASTEDITDATE" rec.AddReturnProperty "DOCNAME" rec.AddReturnProperty "TYPIST_ID" rec.AddReturnProperty "STATUS"

rec.AddOrderByProperty "LAST_EDIT_DATE", 0 rec.Execute

If (rec.ErrNumber <> 0) Then MsgBox "RecentEdit Failure on Execute: " & _ rec.ErrNumber & " " & _ rec.ErrDescription, , "Recent Edit" Else lim = rec.GetRowsFound If lim > 50 Then lim = 50

row = "DOCNAME" & Chr(9) & _ "DOCNUM" & Chr(9) & "SYSTEM_ID" _ & Chr(9) & "APP_ID" & Chr(9) _ & "LAST_EDIT_DATE" & Chr(9) _ & "TYPIST_ID" & Chr(9) & "STATUS"

reGrid.Cols = 8 reGrid.AddItem row i = 1 While i <= lim rec.NextRow If (rec.ErrNumber <> 0) Then MsgBox "RecentEdit Failure on " _ & "NextRow: " & rec.ErrNumber _ & " " & rec.ErrDescription, , _ "Recent Edit" Else row = rec.GetPropertyValue("DOCNAME") _ & Chr(9) row = row & _ rec.GetPropertyValue( _ "DOCNUM") & Chr(9) row = row & _ rec.GetPropertyValue("SYSTEM_ID") _ & Chr(9) row = row & _ rec.GetPropertyValue("APP_ID") _ & Chr(9) row = row & _ rec.GetPropertyValue("LASTEDITDATE") _ & Chr(9)

14 CHAPTER 1

DM Search Transactions

row = row & _ rec.GetPropertyValue("TYP IST _ID") _ & Chr(9) row = row & _ rec.GetPropertyValue("STATUS") reGrid.AddItem row End If i = i + 1 Wend rec.ReleaseResults End If Screen.MousePointer = vbDefault End Sub

Private Sub Form_Resize() Dim i As Long Dim cw As Long reGrid.Width = Width - 100 cw = reGrid.Width / reGrid.Cols For i = 0 To reGrid.Cols - 1 reGrid.ColWidth(i) = cw Next End Sub

Private Sub reGrid_Click() If reGrid.row <= 0 Then MsgBox "Select valid row" Exit Sub End If

reGrid.row = reGrid.RowSel reGrid.Col = 1 txtSelDocNumber = reGrid.Text docnumber = reGrid.Text

End Sub

Private Sub reGrid_DblClick() Dim c Dim dn As Variant c = reGrid.Col reGrid.Col = 1 dn = reGrid.Text

If IsNumeric(dn) Then 'Extract routine in frmVersions form_load

THE DM ARCHITECTURE 15

DM Search Transactions

'Versions (dn) End If End Sub

Performing a

Simple Search

The following example demonstrates how to do a simple search.

. . . Private Sub cmdCancel_Click() Me.Hide End Sub

Private Sub cmdDoLookup_Click()

cboDocType.Clear Call LookupDocType(cboDocType) End Sub

Private Sub cmdSearch_Click() Dim rec As New PCDSearch Dim i As Long Dim count As Long Dim row As String

Screen.MousePointer = vbHourglass

rec.SetDST DST rec.AddSearchLib library 'This example uses the CYD_DEFPROF form. rec.SetSearchObject "CYD_DEFPROF" If txtAuthor <> "" Then rec.AddSearchCriteria "AUTHOR_ID", _ Chr(34) & txtAuthor & Chr(34) End If If txtApp <> "" Then rec.AddSearchCriteria "APP_ID", Chr(34) _ & txtApp & Chr(34) End If If cboDocType <> "" Then rec.AddSearchCriteria "TYPE_ID", Chr(34) _ & cboDocType & Chr(34) End If

rec.AddReturnProperty "DOCNUM" rec.AddReturnProperty "APP_ID"

16 CHAPTER 1

DM Search Transactions

rec.AddReturnProperty "SYSTEM_ID" rec.AddReturnProperty "TYPE_ID" rec.AddReturnProperty "LASTEDITDATE" rec.AddReturnProperty "DOCNAME" rec.AddReturnProperty "AUTHOR_ID" rec.AddReturnProperty "STATUS" 'NOTE: This search should return data sorted 'by last edit then by document number. rec.AddOrderByProperty "LAST_EDIT_DAT E", 0 rec.AddOrderByProperty "DOCNUM", 1

rec.Execute

If (rec.ErrNumber <> 0) Then MsgBox "Search Failure on Execute: " & _ rec.ErrNumber & " " & rec.ErrDescription, _ , "Search" Else count = rec.GetRowsFound txtCount = Str(count) If count > 50 Then count = 50 row = "DOCNAME" & Chr(9) & "DOCNUM" _ & Chr(9) & "SYSTEM_ID" & Chr(9) & _ "APP_ID" & Chr(9) & "TYPE_ID" & Chr(9) _ & _ "LAST_EDIT_DATE" & Chr(9) _ & "AUTHOR_ID" & Chr(9) & "STATUS"

reGrid.Clear reGrid.Cols = 8 reGrid.rows = 0 reGrid.AddItem row

i = 1 While i <= count rec.NextRow If (rec.ErrNumber <> 0) Then MsgBox "Search Failure on NextRow: " _ & rec.ErrNumber & " " & _ rec.ErrDescription, , "Search" Else row = rec.GetPropertyValue("DOCNAME") _ & Chr(9) row = row & _ rec.GetPropertyValue("DOCNUM") _ & Chr(9) row = row & _

THE DM ARCHITECTURE 17

DM Search Transactions

rec.GetPropertyValue("SYST EM_ID") _ & Chr(9) row = row & _ rec.GetPropertyValue("APP_ ID") _ & Chr(9) row = row & _ rec.GetPropertyValue("TYPE_ID") _ & Chr(9) row = row & _ rec.GetPropertyValue("LAST EDITDATE") _ & Chr(9) row = row & _ rec.GetPropertyValue("AUTH OR_ID") _ & Chr(9) row = row & _ rec.GetPropertyValue("STATUS") reGrid.AddItem row End If i = i + 1 Wend rec.ReleaseResults End If

Screen.MousePointer = vbDefault

End Sub

Private Sub cmdShowLookup_Click() frmLookup.Show vbModal End Sub

Private Sub Form_Resize() Dim i As Long Dim cw As Long reGrid.Cols = 8 cw = reGrid.Width / reGrid.Cols For i = 0 To reGrid.Cols - 1 reGrid.ColWidth(i) = cw Next End Sub

Private Sub reGrid_Click() If reGrid.row <= 0 Then MsgBox "Select valid row" Exit Sub End If

18 CHAPTER 1

Document Objects

reGrid.row = reGrid.RowSel reGrid.Col = 1 txtSelDocNumber = reGrid.Text docnumber = reGrid.Text

End Sub

Document Objects

The steps for working with the PCDDocObject object and other DM API objects are as follows:

1 Set the DST. 2 Set the object type property to the name of the form. 3 Set the library as a property of the object. 4 Set the object properties, each of which requires a name/value

pair.

Fetching a DM

Document Object

5 Once all the relevant properties have been set, create the object.

There are also methods for fetching information on the properties of an object as well as deletion and update methods.

The following example fetches a DM document object.

. . . Attribute VB_Name = "frmFetchDoc" Attribute VB_GlobalNameSpace = False Attribute VB_Creatable = False Attribute VB_PredeclaredId = True Attribute VB_Exposed = False Option Explicit Dim ret As Boolean Dim i As Long Dim FileName As String Dim FetchFlag As Boolean

Private Sub cmdCheckIn_Click()

THE DM ARCHITECTURE 19

Document Objects

Dim doc As New PCDDocObject

If docnumber = "" Or versionid = "" Then MsgBox "Check In requires that you set " _ & "the document number and " _ & "the version ID." Exit Sub End If

doc.SetDST DST doc.SetObjectType "cyd_defprof" doc.SetProperty "%TARGET_LIBRARY", library doc.SetProperty "%OBJECT_IDENTIFIER", docnum ber doc.SetProperty "%VERSION_ID", versionid doc.SetProperty "%STATUS", "%UNLOCK" doc.Update

'Check for error. Dim lngENum As Long lngENum = doc.ErrNumber If lngENum <> 0 Then Dim strEDesc As String, strENum As String strEDesc = doc.ErrDescription strENum = CStr( lngENum ) MsgBox "Error " & strENum & ": " & strEDesc 'Handle the error... End If

Set doc = Nothing Set doc = New PCDDocObject doc.SetDST DST doc.SetObjectType "cyd_defprof" doc.SetProperty "%TARGET_LIBRARY", library doc.SetProperty "%OBJECT_IDENTIFIER", docnum ber doc.Fetch

'Check for error. Dim lngENum As Long lngENum = doc.ErrNumber If lngENum <> 0 Then Dim strEDesc As String, strENum As String strEDesc = doc.ErrDescription strENum = CStr( lngENum ) MsgBox "Error " & strENum & ": " & strEDesc 'Handle the error... End If

20 CHAPTER 1

Document Objects

txtStatus = doc.GetReturnProperty("STATUS") Set doc = Nothing

If txtStatus = 0 Then cmdCheckOut.Enabled = True cmdCheckIn.Enabled = False

Else cmdCheckOut.Enabled = False cmdCheckIn.Enabled = True End If

MsgBox "Status field in profile updated " _ & "to 0 (checked in)." End Sub . . . Private Sub FetchButton_Click() Dim rec As New PCDGetDoc Dim i As Long Dim lim As Long Dim opOK As Boolean Dim row As String

Dim gd As Object Dim indata As Variant Dim bdata() As Byte

If docnumber = "" Or versionid = "" Then MsgBox "Must specify the document number " _ & "and the version ID." Exit Sub End If

FetchFlag = False FileName = "" rec.SetDST DST rec.AddSearchCriteria "%TARGET_LIBRARY", _ library rec.AddSearchCriteria "%DOCUMENT_NUMBER", _ docnumber rec.AddSearchCriteria "%VERSION_ID", versionid

rec.Execute

THE DM ARCHITECTURE 21

Document Objects

If (rec.ErrNumber <> 0) Then MsgBox "Fetch Doc Failure on Execute: " & _ rec.ErrNumber & " " & rec.ErrDescription, _ , "Fetch Doc" Else lim = rec.GetRowsFound i = 1 While i <= lim rec.NextRow If (rec.ErrNumber <> 0) Then i = lim + 1 MsgBox "Fetch Doc Failure on Execute: " _ & rec.ErrNumber & " " & _ rec.ErrDescription, , "Fetch Doc" End If If (i = 1) Then

Set gd = rec.GetPropertyValue("%CONTENT")

On Error GoTo saveFailed FileName = "c:\temp\" & _ Trim(docnumber) & "_" & _ Trim(versionid) & ".doc" Open FileName For Binary Access Write _ As #1 bdata() = "" bdata() = gd.Read(1024) While (gd.BytesRead > 0) Put #1, , bdata() bdata() = "" bdata() = gd.Read(1024) Wend

Close #1 GoTo saveDone

saveFailed: MsgBox "Fetch Doc Failure File Open: " _ & "Fetch Doc" savecancelled: On Error Resume Next saveDone: End If i = i + 1 Wend

22 CHAPTER 1

Document Objects

End If FetchFlag = True MsgBox "Exported document content to " _ & "designated file: " & FileName

End Sub . . .

Getting and

Updating Trustee

Information

The following example updates the trustees for a profiled document object.

. . . Attribute VB_Name = "frmTrustees" Attribute VB_GlobalNameSpace = False Attribute VB_Creatable = False Attribute VB_PredeclaredId = True Attribute VB_Exposed = False Option Explicit

Dim bRet As Boolean Dim Status As String Dim DocName As String Dim DefaultRights As Long Dim EffectiveRights As Long Dim AccessControl As Boolean Dim i As Integer Dim UserOrGroup As String Dim PDoc As Object Dim TrusteeList As PCDTrusteeList

Private Function _ GetTrusteesforProfile(docnumber As String) _ As Boolean

Dim docsfound As Long

On Error GoTo ErrorHandler GetTrusteesforProfile = False

If Val(docnumber) <= 0 Then Exit Function

Dim pclient As PCDSearch

THE DM ARCHITECTURE 23

Document Objects

Set pclient = _ CreateObject("PCDClient.PCDSearch")

pclient.SetDST DST pclient.AddSearchLib library 'This example uses the "def_qbe" form. pclient.SetSearchObject "def_qbe"

'Set the properties to be returned. These 'are the properties to be displayed in the 'search results page. pclient.AddReturnProperty("DOCNAME") pclient.AddReturnProperty("DOCNUM") pclient.AddReturnProperty("AUTHOR_ID") pclient.AddReturnProperty("STATUS") pclient.AddReturnProperty("VERSION") pclient.AddReturnProperty("SECURITY") pclient.AddReturnProperty("VERSION_ID") pclient.AddOrderByProperty "VERSION_ID", True pclient.AddSearchCriteria "DOCNUM", docnumber

pclient.Execute

'Check for error. Dim lngENum As Long lngENum = pclient.ErrNumber If lngENum <> 0 Then Dim strEDesc As String, strENum As String strEDesc = pclient.ErrDescription strENum = CStr( lngENum ) MsgBox "Error " & strENum & ": " & strEDesc 'Handle the error... End If

docsfound = pclient.GetRowsFound txtDocsFound = Str(docsfound) If docsfound = 0 Then Set pclient = Nothing Exit Function End If

pclient.NextRow

DefaultRights = _ pclient.GetPropertyValue("SECURITY") DocName = pclient.GetPropertyValue("DOCNAME")

24 CHAPTER 1

Document Objects

txtDefaultRights = Str(DefaultRights) pclient.ReleaseResults

Set PDoc = _ CreateObject("PCDClient.PCDDocObject") PDoc.SetDST DST PDoc.SetProperty "%TARGET_LIBRARY", library PDoc.SetObjectType("DEF_PROF") PDoc.SetProperty "%OBJECT_IDENTIFIER", _ docnumber

PDoc.Fetch

'Check for error. Dim lngENum As Long lngENum = PDoc.ErrNumber If lngENum <> 0 Then Dim strEDesc As String, strENum As String strEDesc = PDoc.ErrDescription strENum = CStr( lngENum ) MsgBox "Error " & strENum & ": " & strEDesc 'Handle the error... End If

EffectiveRights = _ PDoc.GetPropertyValue("%EFFECTIVE_RIGHTS") AccessControl = _ PDoc.HasRight("%PR_ACCESS_CONTROL", _ EffectiveRights) txtEffectiveRights = Str(EffectiveRights) txtAccessControl = Str(AccessControl)

'Only display trustees if security is set. If DefaultRights Then Call DisplayTrustees(PDoc, _ TreeTrustees, AccessControl) If AccessControl Then cmdAddTrustee.Enabled = True cmdRemoveTrustee.Enabled = True End If Else MsgBox "No security set for this profile." End If

Set PDoc = Nothing Set pclient = Nothing

THE DM ARCHITECTURE 25

Document Objects

GetTrusteesforProfile = True Exit Function

End If

ErrorHandler: MsgBox "Unhandled Error: " & _ Str(Err.Number) & " was generated by " _ & Err.Source & Chr(13) & Err.Description

End Function . . . Private Sub cmdAddTrustee_Click()

'Two ways to do this: '1) Set trustee on profile object and ' update trustees. Set PDoc = _ CreateObject("PCDClient.PCDDocObject") PDoc.SetDST DST PDoc.SetProperty "%TARGET_LIBRARY", library PDoc.SetObjectType("DEF_PROF") PDoc.SetProperty "%OBJECT_IDENTIFIER", docnumber PDoc.FetchTrustees 'Set flags to 1 for group and 2 for user, but '0 may work. PDoc.SetTrustee cboTrustees.Text, 2, _ Val(txtRights)

'Check for error. Dim lngENum As Long lngENum = PDoc.ErrNumber If lngENum <> 0 Then Dim strEDesc As String, strENum As String strEDesc = PDoc.ErrDescription strENum = CStr( lngENum ) MsgBox "Error " & strENum & ": " & strEDesc 'Handle the error... End If

PDoc.UpdateTrustees

'Check for error. Dim lngENum As Long

26 CHAPTER 1

Document Objects

lngENum = PDoc.ErrNumber If lngENum <> 0 Then Dim strEDesc As String, strENum As String strEDesc = PDoc.ErrDescription strENum = CStr( lngENum ) MsgBox "Error " & strENum & ": " & strEDesc 'Handle the error... End If

PDoc.Update

'Check for error. Dim lngENum As Long lngENum = PDoc.ErrNumber If lngENum <> 0 Then Dim strEDesc As String, strENum As String strEDesc = PDoc.ErrDescription strENum = CStr( lngENum ) MsgBox "Error " & strENum & ": " & strEDesc 'Handle the error... End If

Set PDoc = Nothing MsgBox "Trustee " & cboTrustees.Text & _ " has been added." Exit Sub

'2) Add trustee to the trustees collection ' and update trustees. PDoc.FetchTrustees TrusteeList.AddTrustee cboTrustees.Te xt, _ 2, Val(txtRights) PDoc.SetTrustees TrusteeList PDoc.UpdateTrustees

'Check for error. Dim lngENum As Long lngENum = PDoc.ErrNumber If lngENum <> 0 Then Dim strEDesc As String, strENum As String strEDesc = PDoc.ErrDescription strENum = CStr( lngENum ) MsgBox "Error " & strENum & ": " & strEDesc 'Handle the error... End If

THE DM ARCHITECTURE 27

Document Objects

PDoc.Update

'Check for error. Dim lngENum As Long lngENum = PDoc.ErrNumber If lngENum <> 0 Then Dim strEDesc As String, strENum As String strEDesc = PDoc.ErrDescription strENum = CStr( lngENum ) MsgBox "Error " & strENum & ": " & strEDesc 'Handle the error... End If

End Sub . . .

28 CHAPTER 1

Chapter

2

An Overview of the DM API

In This Chapter

This chapter describes the overall structure of the DM API, including an itemized list that shows the methods and properties that each object supports. It also presents information that applies across the entire API.

AN OVERVIEW OF THE DM API 29

The PCDClient Object

Your custom applications interact with the DM Server through a number of objects that are collectiv ely referred to as the use the the Distributed Component Object Model (DCOM).

PCDClient objects, you should have some understanding of

List of DM API Objects

The following is a list of the DM client objects that comprise the DM API.

PCDDocObject PCDEnumPropertyLists PCDError PCDGetDoc

PCDClient. T o

30 CHAPTER 2

PCDGetForm PCDGetLoginLibs PCDGetStream PCDLogin PCDLookup PCDNetAliasList PCDNetworkInfo PCDPropertyList PCDPropertyLists PCDPutDoc PCDPutStream PCDRecentDoc PCDSearch

Early and Late Binding

PCDSQL PCDTrusteeList

Early and Late Binding

You can create objects in the DM API using either early binding or late binding. Examples shown in this document will sometimes use early binding, and other times will use late binding. In custom applications you implement, you can usually use either , but there are a few instances where the text will indicate that one should be used in preference to the other.

Early Binding With early binding you create an object in a single step when you first

dimension it. This may be the most appropriate wa y to creat e an object if you are going to use it immediately.

Early binding uses the New keyword within the Dim statement when the object is first dimensioned. For example:

Dim pDoc As New PCDClient.PCDPutDoc

The New operator must be used on Visual Basic objects that have

Private or PublicNotCreatable instancing properties.

Late Binding With late binding you first dimension the it em you want to create, ofte n

dimensioning it as a generic object. Later, when you are r eady to use the object, you use the For example:

Dim pObj As Object ... Set pObj = CreateObject(“PCDClient.PCDLookup”)

If your application uses the Microsoft Transaction Server, you must create objects using late binding with the Transaction Server cannot see instances of externally created objects that you generate with the

Set statement to instantiate the object in memory.

CreateObject method. The

New operator.

AN OVERVIEW OF THE DM API 31

Methods and Properties Supported by DM API Objects

Each of the DM API objects supports two or more methods or properties that perform the various tasks related to that object. The methods and properties that each DM API object supports are listed below.

Many

PCDClient objects support methods and properties with the

same name. For example, all

ErrNumber and ErrDescription properties.

To avoid repeating the information by discussing methods and properties with the objects they support, methods and properties are discussed separately. Chapter 3 presents DM API objects. Chapter 4 discusses the rich array of methods and properties available in the DM API.

PCDASPFileUpload

Execute IsEmpty OnEndPage OnStartPage

PCDClient objects access the

PCDDocObject

Create Delete Fetch FetchTrustees GetProperties GetProperty GetReturnProperties GetReturnProperty GetTrustee GetTrustees GrantRight

Methods and Properties Supported by DM API Objects

HasRight RevokeRight SetDST SetObjectType SetProperties SetProperty SetTrustee SetTrustees Update UpdateTrustees

PCDEnumPropertyLists

Clone Next Reset Skip

PCDError

ErrDescription ErrNumber

PCDGetDoc

AddSearchCriteria Execute GetPropertyValue GetReturnProperties GetRowsFound GetSearchCriteria NextRow SetDST SetRow

AN OVERVIEW OF THE DM API 33

Methods and Properties Supported by DM API Objects

SetSearchCriteria SetSearchObject

PCDGetForm

AddSearchLib Execute GetPropertyValue SetDST SetObjectType

PCDGetLoginLibs

Execute GetAt GetSize

PCDGetStream

BytesRead

34 CHAPTER 2

GetPropertyValue Read Seek SetComplete

PCDLogin

AddLogin Execute GetAliasList GetDOCSUserName GetDST GetFailedLoginList GetLoginLibrary GetPrimaryGroup SetDST

Methods and Properties Supported by DM API Objects

PCDLookup

AddOrderByProperty AddSearchCriteria AddSearchLib AddUserFilterCriteria ClearOrderByProperties ClearUserFilterCriteria ColumnCount Execute GetMetaPropertyValue GetMetaRowsFound GetPropertyValueByIndex GetRowsFound GetSearchCriteria NextMetaRow NextRow ReleaseResults SetChunkFactor SetDST SetLookupId SetMaxRows SetMetaRow SetRow SetSearchCriteria SetSearchObject SetTargetProperty

PCDNetAliasList

GetSize UnitName

AN OVERVIEW OF THE DM API 35

Methods and Properties Supported by DM API Objects

UnitType UserName

PCDNetworkInfo

GetDomainList GetGroupList GetGroupMembers GetRowCount GetUserFullName GetUserGroups GetUserList GetValue IsMemberOf NextRow SetDST

36 CHAPTER 2

PCDPropertyList

AddProperty BeginIter DeleteProperty GetCurrentPropertyName GetCurrentPropertyValue GetPropertyIndex GetPropertyValue GetSize NextProperty

PCDPropertyLists

BeginIter Execute GetCurrentPropertyName

Methods and Properties Supported by DM API Objects

GetCurrentPropertyValue NewEnum NextProperty NextRow SetChunkFactor SetDST SetObjectType SetOptions SetProperties SetProperty

PCDPutDoc

AddSearchCriteria Execute GetPropertyValue GetReturnProperties GetRowsFound GetSearchCriteria NextRow SetDST SetRow SetSearchCriteria SetSearchObject

PCDPutStream

BytesWritten GetPropertyValue SetComplete Write

AN OVERVIEW OF THE DM API 37

Methods and Properties Supported by DM API Objects

PCDRecentDoc

AddOrderByProperty AddReturnMetaProperty AddReturnProperty AddSearchCriteria AddSearchLib BeginGetBlock ColumnCount EndGetBlock Execute GetMetaPropertyValue GetMetaRowsFound GetPropertyValue GetPropertyValueByIndex

38 CHAPTER 2

GetReturnProperties GetRowsFound GetSearchCriteria NextMetaRow NextRow ReleaseResults SetChunkFactor SetDST SetMaxRows SetMetaRow SetReturnProperties SetRow SetSearchCriteria SetSearchObject

Methods and Properties Supported by DM API Objects

PCDSearch

AddOrderByProperty AddReturnMetaProperty AddReturnProperty AddSearchCriteria AddSearchLib BeginGetBlock ColumnCount EndGetBlock Execute GetMetaPropertyValue GetMetaRowsFound GetPropertyValue GetPropertyValueByIndex GetRowsFound NextMetaRow NextRow ReleaseResults SetChunkFactor SetDST SetMaxRows SetMetaRow SetReturnProperties SetRow SetSearchCriteria SetSearchObject

PCDSQL

Execute GetColumnCount

AN OVERVIEW OF THE DM API 39

Methods and Properties Supported by DM API Objects

GetColumnName GetColumnValue GetDBVendor GetNextKey GetRowCount GetRowsAffected GetSQLErrorCode NextRow ReleaseResults SetDST SetLibrary SetRow

40 CHAPTER 2

PCDTrusteeList

AddTrustee BeginIter DeleteTrustee GetCurrentTrusteeFlags GetCurrentTrusteeName GetCurrentTrusteeRights GetSize GetTrusteeIndex GetTrusteeRights NextT rustee SetTrusteeRights

Tokens Supported by DM API Methods and Properties

Tokens are special identifiers that instruct the DM Server to perform specific actions. They are often used as a short-hand reference to an object that otherwise could only be described by a longer text string, such as a reference to a SQL table and column. For example, the %LOGIN_DATE token can substitute for as a reference for the PEOPLE.LAST_LOGIN_DATE column of the SQL database.

Token identifiers are easily r ecognized. W hen used in application code, each token must be enclosed within double quote marks and must always be written in UPPERCASE. Each token begins with a percent sign (%), a syntax requirement that identifies them as DM system variables rather than local variables defined by the API program.

When used in application code, DM tokens perform one of three functions:

• Tokens set values either in the SQL database or in other variables. For example, the %CHECK OUT_COMMENTS token can be used to identify a string that the program stores in the COMMENTS column of the CHECKOUT table.

• Tokens identify data items that API applications are to return when the application executes. For example, the %DATA token returns the data and metadata associated when an application program executes the PDCSQL operation.

• Tokens manipulate column values in SQL dat abase tables. For example, the %CONTENTS_MOVE_TO_TOP adjusts the items in a DM Folder so that the specified object is shown at the top of the presentation list and the other items in the folder are adjust ed to lower positions in the list if necessary.

Chapter 5, “DM API Tokens” on page 301, lists the most commonly used DM tokens.

AN OVERVIEW OF THE DM API 41

Tokens Supported by DM API Methods and Properties

42 CHAPTER 2

Chapter

3

DM API Objects

In This Chapter

This chapter describes each of the DM objects, including their syntax, usage, and other related information.

DM API OBJECTS 43

PCDASPFileUpload

Use this object only from scripts running inside Active Server Pages (ASP). This object is used to read from the ASP Request object and write to the supplied PCDPutStream object.

Syntax

PCDASPFileUpload.

methodOrProperty

Usage

The PCDASPFileUpload object is a client-side interface (CSI) object used to extract form data (specifically, uploaded files) from the requested object when a form is submitted. When uploading a file, ENCTYPE is set to “multipart/form-data.” A server-side c omponent is required to parse the information c ontained within the file. This utility is used in conjunction with the PCDPutDoc object to write the data stream to the document server.

To demonstrate the process, open the DM Webtop file. Locate the following line of code (where

UPLOADDSP.ASP

[...] markers indicate

that the same line of code continues on the next line of the page):

<FORM NAME=”uploadForm” ACTION=”<%= url %>?[...] <%=Server.HTMLEncode(formArgs) %>” ENCTYPE=[...] multipart/form-data METHOD=post>

<INPUT type=”button” Value=”<%=getString(([...] isImportVersion)?”IMPORT_BUTTON1”:”UPLOAD_[...] HEADER”)%>” onclick=”submitF un ct ion () ”>

44 CHAPTER 3

Assuming that you are not using the DM Webtop Smart CheckIn/ CheckOut feature, when the form is submitted, your Internet browser knows that you are uploading a file and will prompt you with an Input File dialog box that contains a Browse button. Select the file to be uploaded. The file itself is embedded as part of the form via the POST method. In used to extract the file from the

UPLOADACT.ASP, the PCDASPFileUpload component is

REQUEST object.

PCDASPFileUpload

PCDASPFileUpload is a helper class/interface/object that supports the tying of t he (The

POST.) It handles all the parsing of headers from the body content and

streaming of the file that is to be uploaded into the DM PCDPutStream object.

The OnStartPage method initializes the COM interface pointers to all of the ASP objects, such as Session, Application, Request, Response, and Server. These are passed by the ASP engine from the interface pointer.

The Execute method reads from the ASP Request object that is obtained during OnStartPage. It uses the to the PCDPutStream object that the server supplies.

The IsEmpty method can be used to determine if the body of the content is empty, which would indicate that a zero-byte file was sent.

IsEmpty looks at the posted stream, parses out the header, and

determines if the document being sent is empty. If the c ontent is empty , the success return value is set to

PCD_ERR_ZERO_BYTE_UPLOAD. If the body content is not empty, the

success return value is set to

POST of an ASP Multipart/Fo rm file into a PCDPutStream.

GET method is not supported in PCDPutStream, so always use

ReadBinary method to write

TRUE, and the error state is set to

FALSE, and no error condition is set.

The OnEndPage method releases all the interface pointers acquired during the OnStartPage initialization and resets the error state.

Example

The following is an example of creating an instance of the PCDASPFileUpload.

. . . Dim pFile As Object . . . pFile = _ Server.CreateObject("PCDClient.PCDASPFileUpload” )

DM API OBJECTS 45

PCDASPFileUpload

Related Items

See the following methods:

See the following properties:

. . .

Execute IsEmpty OnEndPage OnStartPage

ErrDescription ErrNumber

46 CHAPTER 3

PCDDocObject

This object is one of the true workhorses of the DM API. Custom applications use it to manipulate Document objects. Document objects include such elements as Document Profiles, search forms, and versions.

Syntax

PCDDocObject.

methodOrProperty

Example

The following is an example of creating an instance of the PCDDocObject.

. . . pObject = _ Server.CreateObject("PCDClient.PCDDocObject") . . .

Related Items

See the following methods:

Create Delete Fetch FetchTrustees GetProperties GetProperty GetReturnProperties GetReturnProperty GetTrustee GetTrustees GrantRight HasRight RevokeRight

DM API OBJECTS 47

PCDDocObject

SetDST SetObjectType SetProperties SetProperty SetTrustee SetTrustees Update UpdateTrustees

See the following properties:

ErrDescription ErrNumber

48 CHAPTER 3

PCDEnumPropertyLists

This object allows you to iterate through collections of property lists. Most often used with documents and folders, PCDEnumP r opertyLists also allows you to iterate through the property lists associated with collections of versions, root objects, and other items. For example, if a folder is deleted, all of the documents and folders it contained must have their properties updated to indicate that they are no longer contained in the deleted folder.

PCDEnumPropertyLists supports COM-standard enumeration interface methods. Every COM-standard enumeration object supports Clone, Next, Reset, and Skip methods.

Syntax

PCDEnumPropertyLists.

Related Items

See the following methods:

Clone Next Reset Skip

See the following properties:

ErrDescription ErrNumber

methodOrProperty

DM API OBJECTS 49

PCDError

This object is a base object for all other PCDClient objects. It provides common properties that you access through the other objects to get error information.

Usage

You do not have to create an instance of this object. All other PCDClient methods access it directly.

Example

All PCDClient objects can access the PCDError objects properties without creating a PCDError object in their application. Most of the sample code in this guide contains examples of how the ErrNumber and ErrDescription properties are accessed.

The section titled Fetching a DM Document Object in Chapter 1 is one of the many examples that illustrate how you can use PCDError properties in your custom applications.

50 CHAPTER 3

Related Items

See the following properties:

ErrDescription ErrNumber

PCDGetDoc

This object is used to manage the retrieval of a set of physical files that comprise the components of one version of a document. You use this object just as you would the PCDSearch object. Use PCDGetDoc.AddSearchCriteria to specify the criteria that identify which document and version you want. Normally, this would mean specifying criteria like

"%VERSION_ID" "3"

one version of one document.

"%DOCUMENT_NUMBER" "79",

. The provided criteria must resolve to exactly

Syntax

PCDGetDoc.

methodOrProperty

Returns

PCDGetDoc returns data stored in the COMPONENTS table, including the document number, version ID, size of the file, and the name of the file.

Usage

The following steps show the general usage sequence for the PCDGetDoc object:

1 Specify the library where the document is stored. 2 Provide a DST. 3 Set search criteria that will precisely identify the item you wish to

retrieve.

4 Call PCDGetDoc.Execute method to retrieve the document. 5 Iterate through them using PCDGetDoc.NextRow or call

PCDGetDoc.SetRow to get to a specific item.

6 Call PCDGetDoc.GetPropertyValue to retrieve the file content by

referencing the "%CONTENT" token. This will return a pointer to a Dispatch interface (a use to read the physical file.

PCDGetStream object) that you can then

DM API OBJECTS 51

PCDGetDoc

7 After file retrieval is complete, release memory associated with

your PCDGetDoc object.

52 CHAPTER 3

PCDGetDoc

Example

The following example shows you can use PCDGetDoc to retrieve the name of a file that contains a document in your DM repository.

. . . Dim objGetDoc As New PCDGetDoc

objGetDoc.SetDST strDST objGetDoc.AddSearchCriteria _

"%TARGET_LIBRARY", strLib objGetDoc.AddSearchCriteria _ "%DOCUMENT_NUMBER", strDocNum objGetDoc.AddSearchCriteria _ "%VERSION_ID", strVersionID

objGetDoc.Execute If objGetDoc.ErrNumber <> 0 Then

'Error occurred. End If

Dim lngRowCount As Long Dim strFileName As String 'Dim bdata() As Byte 'Dim indata As Variant

lngRowCount = objGetDoc.GetRowsFound If objGetDoc.ErrNumber <> 0 Then 'Error occurred.

End If If lngRowCount <> 1 Then

'Possible Error. Only 1 file expected. Else objGetDoc.SetRow( 1 )

strFileName = objGetDoc.GetPropertyValue( _ PATH ) MsgBox “The name of the document is: “ & _ strFileName EndIf .

DM API OBJECTS 53

PCDGetDoc

. .

Related Items

See the following methods:

AddSearchCriteria Execute GetPropertyValue GetReturnProperties GetRowsFound GetSearchCriteria

See the following properties:

ErrDescription ErrNumber

NextRow SetDST SetRow SetSearchCriteria SetSearchObject

54 CHAPTER 3

PCDGetForm

Use this object to retrieve information contained in the FORMS table in the SQL database. It is presently used specifically for the JavaForms interface.

Syntax

PCDGetForm.

methodOrProperty

Example

The following example shows how to create an instance of this object.

. . . pLibs = Server.CreateObject("PCDClient. PCDGetForm") . . .

Related Items

See the following methods:

AddSearchLib Execute GetPropertyValue SetDST SetObjectType

See the following properties:

ErrDescription ErrNumber

DM API OBJECTS 55

PCDGetLoginLibs

Use this object to get a list of available logon libraries from the DM Server. This is a list of the libraries configured in DM Server Manager, and they are obtained from a PCDOCS.INI file in the system.

Syntax

PCDGetLoginLibs.

methodOrProperty

Usage

This object allows you to determine which libraries are available for use by a user. Users can log on to any libraries this object returns. You also use it to select the current working library.

Example

The following example assembles the libraries available to the current user and puts them into a ListBox.

. . . Dim objGetLibs As New PCDGetLoginLibs

Dim LNumOfLibs As Long Dim strLibName() As String Dim LCounter Dim lstLibList As New ListBox

'Set the DST. objGetLibs.SetDST strDST

' Get a list of libraries available to the use r. objGetLibs.Execute If (objGetLibs.ErrNumber <> 0) Then ' Error occurred. Process it as appropriate. End If

'Get the number of libraries. LNumOfLibs = objGetLibs.GetSize - 1

56 CHAPTER 3

PCDGetLoginLibs

Related Items

See the following properties:

ReDim strLibName(LNumOfLibs) For LCounter = 0 To LNumOfLibs strLibName(LCounter) = _ objGetLibs.GetAt(LCounter) lstLibList.AddItem strLibName Next

Set objGetLibs = Nothing . . .

Execute GetAt GetSize

ErrDescription ErrNumber

DM API OBJECTS 57

PCDGetStream

Use this object to pro vide the user with a way to read the contents of a physical file.

Syntax

PCDGetStream.

methodOrProperty

Usage

When calling this object, after each Read, you should check the

ErrNumber property. If ErrNumber returns zero (indicating that no

error occurred), you should check the BytesRead property to see how many bytes were actually returned by the Read.

Note: If you are using a language such as Visual Basic or Visual C++, you can use the optional second parameter for Read to get the number of b ytes read, instead of checking the BytesRead property.

Example

The following example shows how PCDGetStream can be used to determine the length of a document in your DM Repository.

. . . 'Assumptions for this example: ' - bstrDocNum already contains doc number. ' - bstrDST already contains security to ke n. ' - bstrLib already contains library name. ' - bstrVerNum already contains the document ' version number.

'Object to get Doc information Dim objDOC As New PCDDocObject 'Create our Stream object Dim objGetStream As New PCDGetStream 'Vars to hold byte counts. Dim blnLoopCtrl As Boolean Set blnLoopCtrl = False

Dim lngCurCount As Long, lngTotCount As Long

58 CHAPTER 3

PCDGetStream

lngCurCount = 0 lngTotCount = 0

'Set our library objDOC.SetProperty "%TARGET_LIBRARY", bstrLib

'Set the DST. objDOC.SetDST bstrDST

'Set the Form (here the Default Profile For m) . objDOC.SetObjectType "DEF_PROF"

'Get the document. objDOC.SetProperty "%OBJECT_IDENTIFIER", _ bstrDocNum objDOC.Fetch If objDOC.ErrNumber <> 0 Then ' Error occurred during Fetch. Process it. End If

'Create/Set-up object to get the document. Dim objGetDoc As New PCDGetDoc objGetDoc.SetDST bstrDST objGetDoc.AddSearchCriteria "%TARGET_LIBRARY", _ bstrLib objGetDoc.AddSearchCriteria "%DOCUMENT_NUMBER", _ bstrDocNum objGetDoc.AddSearchCriteria "%VERSION_ID", _ bstrVerNum objGetDoc.Execute If objGetDoc.ErrNumber <> 0 Then ' Error occurred: Process it. End If

Set objGetStream = _ objGetDoc.GetPropertyValue("%CONTENT") bytInArray() = objGetStream.Read(5120) lngCurCount = objGetStream.BytesRead

While ((objGetStream.ErrNumber <> 0) And _ lngCurCount > 0))

DM API OBJECTS 59

PCDGetStream

lngTotCount = lngTotCount + lngCurCount bytInArray = objGetStream.Read(5120) lngCurCount = objGetStream.BytesRead Wend

If (objGetStream <> 0) Then 'Error: Unexpected end to read loop. Else If (lngTotCount > 0) Then MsgBox "Done. File is " & _ CStr(lngTotCount) & _ " Bytes in Length." Else 'Error: Read Failed. Process the error. End If End If

Set objDoc = Nothing Set objGetDoc = Nothing Set objGetStream = Nothing . . .

60 CHAPTER 3

Related Items

See the following methods:

GetPropertyValue Read Seek SetComplete

See the following properties:

BytesRead ErrDescription ErrNumber

PCDLogin

Use this object to create or append validated network aliases to a document security token (DST)

Syntax

PCDLogin.

methodOrProperty

Example

The section titled Providing Library Access in Chapter 1 illustrate s how you can use the PCDLogin object in your documents.

Related Items

See the following methods:

AddLogin Execute GetAliasList GetDOCSUserName GetDST

See the following properties:

ErrDescription ErrNumber

GetFailedLoginList GetLoginLibrary GetPrimaryGroup SetDST

DM API OBJECTS 61

PCDLookup

PCDLookup allows you to execute a lookup of data stor ed in validat ed SQL columns, such as PCDLookup to do this in your custom application by specifying:

• the data in the fields on the form, and

• the lookup ID. PCDLookup returns the same data that would be displayed in the list

box of the DM lookup, plus any other columns that would be needed to update related fields on the base form. For example, if you use the Matter lookup definition, the column for the Client_ID will also be returned.

AUTHOR or DOCUMENTTYPE. You can use

Syntax

62 CHAPTER 3

PCDLookup.

methodOrProperty

Usage

This object works differently than the PCDSearch object in that you don’ t specify return properties. The server determines what they should be by looking at the lookup definition and the base form.

All the columns in the list box on the lookup will be included as return properties, plus the contents of any “r elated data” columns that need to be updated on the form when the lookup’s target field changes.

Also, unlike PCDSearch, you have to specify a target property. This is the field you are trying to fill in using the lookup (for example, Author or Matter).

After you Execute the lookup, you get back data and metadata. The metadata tells you what columns are in the data. The metadata c olumns include the following return properties: %PropertyName, %Title, %Visible, and %Data.

PCDLookup

Example

The following example demons trates ho w you can use PCDLookup to create and process a Lookup search. It includes most of the methods that PCDLookup supports.

Sub Lookup( ) 'Create our object Dim objPCDLookup As New PCDLookup 'Create a property list Dim objPCDPropList As New PCDPropertyList 'Set up our propertylist so it can be used later.

objPCDPropList.AddProper t y "AUTHOR_ID", "J_SMITH"

'Set up the parameters for the lookup. 'Set the DST. objPCDLookup.SetDST strDST 'Set the Library.

objPCDLookup.AddSearchLib strLib 'Set the search object. This form must contain 'the lookup (such as client or matter). objPCDLookup.SetSearchObject( "DEF_Q BE 1" ) 'Set the Lookup name. objPCDLookup.SetLookupId "PEOPLE " 'Set the target property to look up. objPCDLookup.SetTargetProperty "AUTHOR_ID" 'Set the search criteria. objPCDLookup.SetSearchCriteria objPCDPropList 'Set the filter criteria. objPCDLookup.AddUserFilterCriteria "AUTHOR_ID", "J*"

'Determine fields to search. Dim strAns As String, intAns As Integer Dim strPrompt As String, strTitle As String strTitle = "Author or Author/Typist Search “ _ & “Selection" strPrompt = "Current search is only in “ _ & “Author field.” & vbCr & "Do you “ _ & “also wish to search for the person" & _

DM API OBJECTS 63

PCDLookup

vbCr & "you selected in the Typist field?" strAns = MsgBox(strPrompt, vbYesNo, strTitle) intAns = CInt(strAns) If intAns = 6 Then 'User answered "Yes." Broaden search.

objLookup.AddSearchCriteria “TYPIST_ID", J_SMITH 'Also, delete filter on author name so it 'does not exclude J_SMITH as typist. objLookup.ClearUserFilterCriteria Else If intAns = 7 'User answered "No." Search is OK as is. MsgBox "No change to search criteria." End If

'Set the sort order for results. strTitle = "SORT ORDER" strPrompt = "Select the number of “ _ & “the Sort Order: " _ & vbCr & " 1 - Author, ascending sort " _ & vbCr & " 2 - Author, descending sort " _ & vbCr & " Other - Unsorted results " strAns = InputBox(strPrompt, strTitle) If IsNumeric(strAns) Then intAns = CInt(strAns) Else intAns = 9 'Can be any integer. End If

Select Case intAns Case 1 'Sort by author, ascending order. 'The Boolean value that follows AUTHOR_ID ca n be 'anything except zero (or an expression that 'evaluates to zero).

objPCDLookup.AddOrderByProperty "AUTHOR_ID", 1 Case 2 'Sort by author, descending order. objPCDLookup.AddOrderByProperty "AUTHOR_ID", 0 Case Else

64 CHAPTER 3

PCDLookup

'Unsorted. This assures unsorted results, but 'it may not be required unless there were 'previous searches.

objPCDLookup.ClearOrderByProperties End Select

'Set the maximum number of records search returns. objPCDLookup.SetMaxRows 500 'Set the number of records to be returned at

'one time to user’s local cache. objPCDLookup.SetChunkFactor 10

'Execute the lookup objPCDLookup.Execute If objPCDLookup.ErrNumber <> 0 Then 'Error: process it. End If

'Get the information from the result set Dim intColCount As Integer Dim lngRowsFound As Long, lngMetaFound As Long

'Get the number of data rows found by the lookup. lngRowsFound = objPCDLookup.GetRowsFound MsgBox "The search returned " _

& CStr( lngRowsFound ) & " rows of data."

'Get the number of metadata rows lookup found. lngMetaFound = objPCDLookup.GetMetaRowsFound MsgBox "The search returned " _

& CStr( lngMetaFound ) & " rows of metadata."

'Get the number of columns in the result data set. intColCount = objLookup.ColumnCount MsgBox "The search result data set contains " _

& CStr( intColCount ) & " columns of data."

'Clear the result set list box (if needed).

DM API OBJECTS 65

PCDLookup

lstResultSet.Clear 'Set pointer position to row 0 in the result set. 'NextRow will then increment it to the first data 'row.

objPCDLookup.SetRow( 0 ) Do While objPCDLookup.NextRow If objPCDLookup.ErrNumber <> 0 Then

'Error reading data row. Process it. End If 'Set pointer position to row 0 in the metadata 'result set. NextMetaRow will then increme nt 'it to the first data row. objPCDLookup.SetMetaRow (0)

Do While objPCDLookup.NextMetaRow If objPCDLookup.ErrNumber <> O Then

'Error reading metadata row. Process it. End If

'Retrieve short name of the metadata property. lstResultSet.AddItem _ objPCDLookup.GetMetaPropertyValue( _ "PROPNAME") 'Shows whether column is Visible: 0=No lstResultSet.AddItem _

objPCDLookup.GetMetaPropertyValue( _ "VISIBLE") 'Long Name of the metadata property. lstResultSet.AddItem _ objPCDLookup.GetMetaPropertyValue("TITLE") 'The lookup data associated with 'this metadata property. lstResultSet.AddItem _ objPCDLookup.GetMetaPropertyValue("DATA") lstResultSet.Show MsgBox "ListBox displays metadata “ _ “for current row." lstResultSet.Hide lstResultSet.Clear

66 CHAPTER 3

PCDLookup

Loop Loop

'Cleanup... objPCDLookup.ReleaseResults Set objPCDLookup = Nothing Set objPCDPropList = Nothing

End Sub . . .

Related Items

See the following methods:

AddOrderByProperty AddSearchCriteria AddSearchLib AddUserFilterCriteria ClearOrderByProperties ClearUserFilterCriteria ColumnCount Execute GetMetaPropertyValue GetMetaRowsFound GetPropertyValueByIndex GetRowsFound GetSearchCriteria

See the following properties:

ErrDescription ErrNumber

NextMetaRow NextRow ReleaseResults SetChunkFactor SetDST SetLookupId SetMaxRows SetMetaRow SetRow SetSearchCriteria SetSearchObject SetTargetProperty

DM API OBJECTS 67

PCDNetAliasList

The PCDNetAliasList object stores a list of network aliases. A network alias consists of the following:

•a UnitType

•a UnitName

•a UserName and Password The UnitType is a DM library, or a NetWare 5.x, NetWare 6.x, or

Microsoft Network. Depending on the either a DM library name, the NetWare server name , the NetWare NDS tree name, or the Windows network domain name, respectively. Note that this object accepts and stores passw ords, but it does not allow them to be retrieved.

UnitName, the UnitType is

Syntax

68 CHAPTER 3

PCDNetAliasList.

methodOrProperty

Example

The section titled Providing Library Acc ess in Chapter 1 illustrates how you can use the PCDNetAliasList object in your custom applications.

Related Items

See the following methods:

GetSize UnitName UnitType UserName

See the following properties:

ErrDescription ErrNumber

PCDNetworkInfo

The PCDNetworkInfo object supports the integration of DM with your network-based security. The methods PCDNetworkInfo supports allow you to build tight network operating system integration into your DM document management system. These methods also allow you to browse network information about domains, groups, and users.

Syntax

PCDNetworkInfo.MethodOrProperty

Usage

Use methods supported by PCDNetworkInfo to make inquiries of current network elements within your network environment. You can retrieve information about Domains, Groups, and U sers. Most of these methods load a result set with data. You retrieve data from these result sets by using a pair of methods in conjunction with one another:

NextRow and GetValue.

Example

The following example illustrates the use of PCDN etw orkInfo and the methods it supports.

DM API OBJECTS 69

PCDNetworkInfo

Public sDST As String

Private Sub cbDomain_Click() DomainForm.oNWInfo.SetDST (sDST) DomainForm.Show End Sub

Private Sub cbGroupInfo_Click() GroupForm.sDST = sDST GroupForm.oGroupInfo.SetDST (sDST) GroupForm.Show End Sub

Private Sub cbQuit_Click() Unload NetInfoBaseForm End Sub

Private Sub Form_Load() 'Local Variable declarations. Dim oLogin As New PCDLogin Dim nResult As Long Dim sTempBuf As String

'Login process. nResult = oLogin.AddLogin(0, "MyLibrary", "", "") nResult = oLogin.AddLogin(0, "MyDomain", _ "MyUserID", "MyPassword") nResult = oLogin.Execute() sDST = oLogin.GetDST()

'Get And display the DST. txtDST.Text = sDST

End Sub

70 CHAPTER 3

PCDNetworkInfo

Public oNWInfo As New PCDNetworkInfo

Private Sub cbCancel_Click() Unload DomainForm End Sub

Private Sub Form_Load()

Dim nResult As Long Dim nNumRows As Long

'Load the Domain List. ' %NI_NT indicates this is an NT based OS. ' %UNDEFINED returns all domains from the root.

nResult = oNWInfo.GetDomainList("%NI_NT", _ "%UNDEFINED")

nNumRows = 0

'If the Domain list has been retrieved, 'get the number of domains in the list. If nResult = 0 Then

DM API OBJECTS 71

PCDNetworkInfo

nNumRows = oNWInfo.GetRowCount() End If

If nNumRows = 0 Then MsgBox "You do not have access to Domain “ _ & “information at this time." Else 'Fill the listbox. For i = 1 To nNumRows

nResult = oNWInfo.NextRow() lstDomains.AddItem (oNWInfo.GetValue())

Next i

'Initialize this list to its first element. lstDomains.ListIndex = 0

'Fill up the UserList with Users in this list. nResult = oNWInfo.GetUserList("%NI_NT", _ lstDomains.Text)

nNumRows = 0

'Get number of rows that are returned. If nResult = 0 Then nNumRows = oNWInfo.GetRowCount() End If 'Display the list of users in the 'lsDomainUsers listbox. If nNumRows = 0 Then MsgBox "User information for this domain “ _ & “is not available to you." Else For i = 1 To nNumRows

nResult = oNWInfo.NextRow() lstDomainUserList.AddItem ( _ oNWInfo.GetValue()) Next i

72 CHAPTER 3

PCDNetworkInfo

'Pre-select the first item in the list. lstDomainUserList.ListIndex = 0

End If

End Sub

Private Sub lstDomains_Click()

Dim nResult As Long Dim nNumRows As Long

'Clear listbox for results of this call. lstDomainUserList.Clear

'Fill the UserList with Users within this list. nResult = oNWInfo.GetUserList("%NI_NT", _ lstDomains.Text)

nNumRows = 0

'Get the number of rows that are returned. If nResult = 0 Then

nNumRows = oNWInfo.GetRowCount() End If

'Display users in the lstDomainUsers listbox If nNumRows = 0 Then MsgBox "User information for this domain “ _ & “is not available to you." Else For i = 1 To nNumRows

nResult = oNWInfo.NextRow() lstDomainUserList.AddItem( _ oNWInfo.GetValue()) Next i

DM API OBJECTS 73

PCDNetworkInfo

'Pre-select the first item in the list. lstDomainUserList.ListIndex = 0

End If

End Sub

74 CHAPTER 3

Public sDomainName As String Public sGroupName As String Public sDST As String Public oGroupInfo As New PCDNetworkInfo

Private Sub cbCancel_Click() Unload GroupForm End Sub

Private Sub cbIsMember_Click()

Dim nResult As Long nResult = IsMemberForm.oIsMember.SetDST(sDST)

PCDNetworkInfo

IsMemberForm.sDomainName = "MyDomain" IsMemberForm.sGroupName = "MyGroup"

IsMemberForm.TxtUserID = "Jimmy Jone s" IsMemberForm.Show

End Sub

Private Sub cbGetMembers_Click()

Dim nResult As Long

'Before loading the next form use load 'load the next form's Group and Domain 'data members. GroupMembersForm.sGroupName = sGroupName GroupMembersForm.sDomainName = sDomainName

'Set the next form's object DST. nResult = GroupMembersForm.oMembers.SetDST(sDST)

GroupMembersForm.Show

End Sub

Private Sub Form_Load()

Dim nResult As Long Dim sName As String Dim nNumRows As Long

'Load up the Domain List. nResult = oGroupInfo.GetDomainList( _ "%NI_NT", "%UNDEFINED")

nNumRows = 0

'If the Domain list has been retrieved, 'get the number of domains in the list.

DM API OBJECTS 75

PCDNetworkInfo

If nResult = 0 Then nNumRows = oGroupInfo.GetRowCount() End If

If nNumRows = 0 Then MsgBox "You do not have access to “ _ & “Domain information at this time." Else 'Fill ListBox with Domain information. For i = 1 To nNumRows

nResult = oGroupInfo.NextRow() lstDomains.AddItem (oGroupInfo.GetValue())

Next i

'Initialize Domain list to first element. lstDomains.ListIndex = 0

'This Form data member holds currently 'selected Domain information. sDomainName = lstDomains.Text

nResult = oGroupInfo.GetGroupList( _ "%NI_NT", sDomainName)

If nResult = 0 Then nNumRows = oGroupInfo.GetRowCount() End If

'If no rows are returned then place that 'information in the ListBox. Otherwise, place 'the list of all groups in the ListBox. If nNumRows = 0 Then lstGroups.AddItem "NO GROUPS FOR THIS DOMAIN " Else For i = 1 To nNumRows nResult = oGroupInfo.NextRow()

lstDomains.AddItem (oGroupInfo.GetValue()) Next i

76 CHAPTER 3

PCDNetworkInfo

End If End If

cbGetMembers.Enabled = False

End Sub

Private Sub lstDomains_Click()

sDomainName = lstDomains.Text

lstGroups.Clear

'Fill the UserList with Users in this list. nResult = oGroupInfo.GetGroupList( _ "%NI_NT", sDomainName)

nNumRows = 0

'Get the rowcount. If nResult = 0 Then nNumRows = oGroupInfo.GetRowCount() End If

'Display user list in the lstGroups ListBox. If nNumRows = 0 Then MsgBox "User information for this domain “ _ “is not available to you." Else For i = 1 To nNumRows

nResult = oGroupInfo.NextRow() lstGroups.AddItem (oGroupInfo.GetValue())

Next i

'Pre-select the first item in the list. lstGroups.ListIndex = 0 sGroupName = lstGroups.Text cbGetMembers.Enabled = True End If

DM API OBJECTS 77

PCDNetworkInfo

End Sub

Private Sub lstGroups_Click() sGroupName = lstGroups.Text cbGetMembers.Enabled = True End Sub

78 CHAPTER 3

Public oMembers As New PCDNetworkInfo Public sDomainName As String Public nFirstTime As Long Public sGroupName As String

Private Sub cbCancel_Click() Unload GroupMembersForm End Sub

Private Sub Form_Load()

Dim nResult As Long

PCDNetworkInfo

Dim sMember As String Dim nNumRows As Long

'Retrieve the GroupMembers from the netwo rk nResult = oMembers.GetGroupMembers( _ "%NI_NT", sDomainName, sGroupName)

If nResult = 0 Then

'Get the Group members. nNumRows = oMembers.GetRowCount()

If nNumRows = 0 Then MsgBox "No access to Members for this group." Else

'Place all of the members of this group 'in the ListBox. For i = 1 To nNumRows nResult = oMembers.NextRow()

lstMembers.AddItem (oMembers.GetValue()) Next i

'Select the first member in the list. lstMembers.ListIndex = 0 End If

Else 'No members in this group. lstMembers.AddItem sDomainName + "No Members" End If

nFirstTime = 1

End Sub

Private Sub lstMembers_Click()

Dim nResult As Long

DM API OBJECTS 79

PCDNetworkInfo

Dim nNumRows As Long

'If program is now checking the top of Member 'list from the opening of the form... If nFirstTime > 0 Then

'...Clear the Users Groups ListBox. lstUsersGroups.Clear

'Retrieve the selected user’s full name. nResult = oMembers.GetUserFullName( _ "%NI_NT", sDomainName, lstMembers.Text) nResult = oMembers.NextRow()

txtFullName.Text = oMembers.GetValue()

'Retrieve all groups that include the 'selected user.

nResult = oMembers.GetUserGroups( _ "%NI_NT", sDomainName, lstMembers.Text) If nResult = 0 Then nNumRows = oMembers.GetRowCount()

If nNumRows > 0 Then

'Place all Groups that include this user 'into the UsersGroups ListBox. For i = 1 To nNumRows

nResult = oMembers.NextRow() lstUsersGroups.AddItem ( _ oMembers.GetValue()) Next i Else lstUsersGroups.AddItem lstMembers.Text _ & " is not a member of any groups." End If Else lstUsersGroups.AddItem "Unable to “ _

80 CHAPTER 3

Kofax DM API User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

About This Guide

Who Should Read This Guide

Preface

How This Guide Is Organized

Documentation Conventions

Related Documentation

Professional Services

Where to Go for Information

On the Web Our Web site at www.hummingbird.com/support/dkm/ carries the

Technical Support and Training

Training Hummingbird’s Education Services offers courses at authorized

The DM Architecture

The DM Multi-Tier Architecture

DM Functionality

Transactions With DM, multiple libraries can be configured for each server to

DM Object Model

DM Objects DM objects are low-level and general objects that presuppose a

Types of DM Objects

DM Forms DM forms include those used as profile forms, query-by-example and

The Logon Process

DM Query Objects Query objects are used to search the library database. The query is

Document Objects Document objects are document management system (DMS) objects

DM Search Transactions

Document Objects

An Overview of the DM API

The PCDClient Object

List of DM API Objects

Early and Late Binding

Early Binding With early binding you create an object in a single step when you first

Late Binding With late binding you first dimension the it em you want to create, ofte n

Methods and Properties Supported by DM API Objects

Tokens Supported by DM API Methods and Properties

DM API Objects

PCDASPFileUpload

PCDDocObject

PCDEnumPropertyLists

PCDError

PCDGetDoc

PCDGetForm

PCDGetLoginLibs

PCDGetStream

PCDLogin

PCDLookup

PCDNetAliasList

PCDNetworkInfo