Kofax DM API User Manual

DM API Reference G uide

Hummingbird Enterprise

™

2004

DM API Reference Guide
Version: 5.1.0.5
Copyright © 1998-2004 Hummingbird Ltd. All rights reserved.
Electronic Publication Date: April 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.227­7013, 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: [phone], Fax: [phone], Website: www.hummingbird.com

Preface

Contents

About This Guide xv
Who Should Read This Guide xv
How This Guide Is Organized xv
Documentation Conventions xvi
Related Documentation xvi
Professional Services xvii
Where to Go for Information xviii

On the Web xviii
On the DM Suite CD xviii

Technical Support and Training xix

North America Technical Support xix
Asia/Pacific Technical Support xix
Europe Technical Support xix
Training xx

Chapter 1 The DM Architecture

The DM Multi-Tier Architecture 2
DM Functionality 2

Document Security Tokens 4
Transactions 4

DM Object Model 4

DM Objects 4
DM Forms 5

Types of DM Objects 5

Defining a DM Object 6
DM Support Objects 6
DM Query Objects 7
Document Objects 7

iii

Child Objects of PCDDocObject Objects 7

The Logon Process 7

Getting a List of Available Libraries 8
Providing Library Access 9

DM Search Transactions 11

General Steps to Performing a Search 12
Retrieving Recently Edited Documents 13
Performing a Simple Search 16

Document Objects 19

Fetching a DM Document Object 19
Getting and Updating Trustee Information 23

Chapter 2 An Overview of the DM API

The PCDClient Object 30
List of DM API Objects 30

Early and Late Binding 31

Early Binding 31
Late Binding 31

Methods and Properties Supported by DM API Objects 32
Tokens Supported by DM API Methods and Properties 41

Chapter 3 DM API Objects

PCDASPFileUpload 44
PCDDocObject 47
PCDEnumPropertyLists 49
PCDError 50
PCDGetDoc 51
PCDGetForm 55
PCDGetLoginLibs 56
PCDGetStream 58
PCDLogin 61
PCDLookup 62
PCDNetAliasList 68

iv

PCDNetworkInfo 69
PCDPropertyList 83
PCDPropertyLists 96
PCDPutDoc 97
PCDPutStream 102
PCDRecentDoc 103
PCDSearch 105
PCDSQL 107
PCDTrusteeList 125

Chapter 4 DM API Methods and Properties

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

Related Documentation

In addition to this manual, you may find the following documents
helpful.

Indicates a new term or variable in a
command line. For example, replace

filename with the name of a file.

name, program code, or other text that
appears on the computer screen. For
example, the default library for DM is usually

c:\Program Files\ Hummingbird\D M
Server

In instruction steps, indicates information you
must type. In text, indicates emphasis.

cascading menu or successive choices of
icons or program groups.

information in the document.

.

xvi CHAPTER 3

• DM/RM Data Dictionary - Describes the tables and columns that
comprise the DM/RM SQL database.

• DM Designer Guide - Provides detailed instructions on how you
can use the Designer component of DM to create and maintain
forms used by your DM installation. I t also describes how y ou can
use Designer to customize the tables and columns that comprise
the SQL database that DM uses to manage your Hummingbird
environment.

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 server­side 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
[e-mail].

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: [phone]
E-Mail: [e-mail]

Level 12
80 Mount Street
North Sydney, NSW 2060, Australia
Telephone: [phone]
Fax: [phone]
E-Mail: [e-mail]

20 rue Thérèse
75001 Paris, France
Telephone: [phone]
Fax: [phone]
E-Mail: [e-mail]

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: [phone]
E-Mail: [e-mail]
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

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