ADO 2.5ADO 2.5

Kamaljit Bath, Program ManagerKamaljit Bath, Program Manager Data Access Group Data Access Group

AgendaAgenda

ADO - OverviewADO - Overview Semi-structured DataSemi-structured Data ADO 2.5 - Programming ModelADO 2.5 - Programming Model URL binding for ADO ObjectsURL binding for ADO Objects Record ObjectRecord Object Relationship between Record and RecordsetRelationship between Record and Recordset Stream ObjectStream Object SummarySummary

ADO OverviewADO Overview A single, powerful consumer interface for A single, powerful consumer interface for

data exposed by OLE DB providersdata exposed by OLE DB providers Designed for use in Web-based and Designed for use in Web-based and

Client/Server applicationsClient/Server applications Supports all languages (Visual BasicSupports all languages (Visual Basic®®, ,

Visual C++Visual C++®®, Visual J++, Visual J++™™, Visual Basic , Visual Basic Scripting Edition)Scripting Edition)

High PerformanceHigh Performance Simple Object ModelSimple Object Model

Semi-structured data Semi-structured data

Data that is:Data that is: More structured than a BLOBMore structured than a BLOB Less structured than a Recordset or a relational Less structured than a Recordset or a relational

database tabledatabase table

Examples:Examples: A file systemA file system Email dataEmail data An arbitrary XML streamAn arbitrary XML stream Web pagesWeb pages Etc.Etc.

Semi-structured data: Semi-structured data: CharacteristicsCharacteristics

Data tends to be organized hierarchically, Data tends to be organized hierarchically, like a treelike a tree Hierarchies have arbitrary depthHierarchies have arbitrary depth

Each node in the tree has a set of propertiesEach node in the tree has a set of properties Each node may have a unique set of propertiesEach node may have a unique set of properties

Leaf-nodes associated with a special “Value” Leaf-nodes associated with a special “Value” propertyproperty

Non-leaf nodes are collections of other Non-leaf nodes are collections of other nodesnodes

Semi-structured data: Semi-structured data: RequirementsRequirements

Node OperationsNode Operations Get/Set properties, Add/Delete propertiesGet/Set properties, Add/Delete properties

Scoped OperationsScoped Operations Move, Copy, Delete operations apply to all contained Move, Copy, Delete operations apply to all contained

nodesnodes

QueryingQuerying A list of nodes that satisfy a predicate on propertiesA list of nodes that satisfy a predicate on properties

LightweightLightweight Operations such as reading email properties, etc. are Operations such as reading email properties, etc. are

done many timesdone many times

ADO 2.5 - Design GoalsADO 2.5 - Design Goals

Keep it simple!Keep it simple!

Allow ADO objects to be addressed by URL Allow ADO objects to be addressed by URL stringsstrings

Extend ADO to work with tree-structured & Extend ADO to work with tree-structured & hierarchical datasourceshierarchical datasources

Provide the ability to do scoped operationsProvide the ability to do scoped operations

Extend ADO so that it may be used to read Extend ADO so that it may be used to read and manipulate binary streamsand manipulate binary streams

Modeling semi-structured Modeling semi-structured data with ADO 2.5data with ADO 2.5 Collections are modeled as recordsetsCollections are modeled as recordsets

Common properties are modeled as fields of Common properties are modeled as fields of the recordsetthe recordset

Folders, DirectoriesFolders, Directories

Nodes are modeled as a record objectNodes are modeled as a record object Properties are modeled as fields of the record Properties are modeled as fields of the record

objectobject Files, Email folder objectsFiles, Email folder objects

Contents of nodes are manipulated by the Contents of nodes are manipulated by the Stream objectStream object

ADO 2.1 - Object ModelADO 2.1 - Object Model

ConnectionConnection

CommandCommand

RecordsetRecordset

ErrorsErrors

FieldsFields

ParametersParameters

ADO 2.5 - Object ModelADO 2.5 - Object Model

ConnectionConnection

CommandCommand

RecordsetRecordset

ErrorsErrors

FieldsFields

ParametersParameters

RecordRecord StreamStream

URL Naming for ADO objectsURL Naming for ADO objects URLs can be used to directly identify individual URLs can be used to directly identify individual

objects in a datasourceobjects in a datasource nodes in a hierarchical namespace (files and nodes in a hierarchical namespace (files and

folders)folders) table in a relational database, unique rows in a table in a relational database, unique rows in a

tabletable

Record object represents a unique objectRecord object represents a unique object file, folder, table, rowfile, folder, table, row

Recordset object represents the contents of a Recordset object represents the contents of a collection objectcollection object rows of a table, files in a folderrows of a table, files in a folder

URL binding to ADO objectsURL binding to ADO objects

ADO 2.5 allows URL naming forADO 2.5 allows URL naming for Connection, Recordset, Record, and Stream objectsConnection, Recordset, Record, and Stream objects

For a Recordset, URL must point to a collection type nodeFor a Recordset, URL must point to a collection type node For stream, URL must point to a node that has a default For stream, URL must point to a node that has a default

stream definedstream defined

Hides RootBinder/ProviderBinder objects from Hides RootBinder/ProviderBinder objects from the developerthe developer

New record objects can also be created directlyNew record objects can also be created directly

URL naming - sample codeURL naming - sample codeSub RsOpen()Sub RsOpen()

Dim cn As New ADODB.ConnectionDim cn As New ADODB.Connection

Dim rs As New ADODB.RecordsetDim rs As New ADODB.Recordset

Dim rs1 as New ADODB.RecordsetDim rs1 as New ADODB.Recordset

cn.Open "http://server01/myfolder”cn.Open "http://server01/myfolder”

rs1.Open “mysubfolder”, cnrs1.Open “mysubfolder”, cn

rs.Open "http://server01/myfolder", , _ rs.Open "http://server01/myfolder", , _

adOpenForwardOnly, _adOpenForwardOnly, _

adLockReadOnly, _adLockReadOnly, _

adCmdURLBindadCmdURLBind

End SubEnd Sub

Sub RsOpen()Sub RsOpen()

Dim cn As New ADODB.ConnectionDim cn As New ADODB.Connection

Dim rs As New ADODB.RecordsetDim rs As New ADODB.Recordset

Dim rs1 as New ADODB.RecordsetDim rs1 as New ADODB.Recordset

cn.Open "http://server01/myfolder”cn.Open "http://server01/myfolder”

rs1.Open “mysubfolder”, cnrs1.Open “mysubfolder”, cn

rs.Open "http://server01/myfolder", , _ rs.Open "http://server01/myfolder", , _

adOpenForwardOnly, _adOpenForwardOnly, _

adLockReadOnly, _adLockReadOnly, _

adCmdURLBindadCmdURLBind

End SubEnd Sub

Record Object (1 of 2)Record Object (1 of 2)

New automation object implemented in New automation object implemented in ADO 2.5ADO 2.5

Models an entity that has a collection of Models an entity that has a collection of properties and (possibly) nested entitiesproperties and (possibly) nested entities Email, Files, web pages, structured documents, Email, Files, web pages, structured documents,

folders, XML node, Databases, Tables, etc.folders, XML node, Databases, Tables, etc. can also represent a row of a recordsetcan also represent a row of a recordset Email/File contents appear as a stream Email/File contents appear as a stream

propertyproperty

Record Object (2 of 2)Record Object (2 of 2)

Expresses the notion of containment & scopingExpresses the notion of containment & scoping Folders Folders containcontain other foldersother folders Folder operations such as move, copy, etc. apply Folder operations such as move, copy, etc. apply

within the folder’s within the folder’s scopescope Properties are modeled as a collection of FieldsProperties are modeled as a collection of Fields Containment is modeled as Sub-RecordsContainment is modeled as Sub-Records

Child records can be viewed in a tabular form as a Child records can be viewed in a tabular form as a recordsetrecordset

Properties and methods are implemented to operate Properties and methods are implemented to operate on the record objecton the record object

Opening a Record ObjectOpening a Record Object

Many ways to open a record object Open directly using a URL string that uniquely

identifies it From an ADO recordset by specifying an

individual record From a field’s value property

Record object always exists in the context of Record object always exists in the context of a Connection objecta Connection object connection object is either implicitly created or connection object is either implicitly created or

explicitly specifiedexplicitly specified

Record PropertiesRecord PropertiesActiveConnection Identifies the active connection object

associated with the current record

State Current state of the record object

Source URL string used to open the recordobject

Mode Access mode for the record object

ParentURL URL string identifying the parent nodeof the current record object

RecordType Type of the current record object –simple document, collection, structureddocument

Record Methods (1 of 2)Record Methods (1 of 2)

Open ([Source as variant], Open ([Source as variant],

[ActiveConnection as variant], [ActiveConnection as variant],

[Mode as ModeEnum = adoModeUnknown], [Mode as ModeEnum = adoModeUnknown],

[CreateOptions as [CreateOptions as RecordCreateOptionsEnum = -1], RecordCreateOptionsEnum = -1],

[OpenOptions as RecordOpenOptionsEnum [OpenOptions as RecordOpenOptionsEnum = -1], [uid as string], [pwd as = -1], [uid as string], [pwd as string])string])

Open ([Source as variant], Open ([Source as variant],

[ActiveConnection as variant], [ActiveConnection as variant],

[Mode as ModeEnum = adoModeUnknown], [Mode as ModeEnum = adoModeUnknown],

[CreateOptions as [CreateOptions as RecordCreateOptionsEnum = -1], RecordCreateOptionsEnum = -1],

[OpenOptions as RecordOpenOptionsEnum [OpenOptions as RecordOpenOptionsEnum = -1], [uid as string], [pwd as = -1], [uid as string], [pwd as string])string])

Open Opens an existing record object or createsa new one using URL, a connection string,or a recordset object

Close Closes an already open record object

Cancel Cancels an aynchronous operation on therecordset

Record Methods (2 of 2)Record Methods (2 of 2)

CopyRecord ({SourceURL as string], CopyRecord ({SourceURL as string], DestURL as string, [destuid as DestURL as string, [destuid as string], [destpwd as string], string], [destpwd as string], [CopyRecordOptions as [CopyRecordOptions as CopyRecordOptionsEnum], CopyRecordOptionsEnum], [AsyncFlag as Boolean]) as [AsyncFlag as Boolean]) as StringString

GetChildren() as ADODB.RecordsetGetChildren() as ADODB.Recordset

CopyRecord ({SourceURL as string], CopyRecord ({SourceURL as string], DestURL as string, [destuid as DestURL as string, [destuid as string], [destpwd as string], string], [destpwd as string], [CopyRecordOptions as [CopyRecordOptions as CopyRecordOptionsEnum], CopyRecordOptionsEnum], [AsyncFlag as Boolean]) as [AsyncFlag as Boolean]) as StringString

GetChildren() as ADODB.RecordsetGetChildren() as ADODB.Recordset

CopyRecord Copies a sub-record and its children to anew location

MoveRecord Moves a sub-record and its children to anew location

DeleteRecord Deletes a sub-record and its children

GetChildren Opens a recordset containing the childnodes of the current record object

Working with the Record Working with the Record ObjectObject

‘‘opens an existing record object or creates a new oneopens an existing record object or creates a new one

Sub OpenFolderIfExists()Sub OpenFolderIfExists()

Dim rec As New ADODB.RecordDim rec As New ADODB.Record

Dim rs as ADODB.RecordsetDim rs as ADODB.Recordset

rec.Open "rec.Open "http://server01/http://server01/myfoldermyfolder//TestFolderTestFolder", , , _", , , _

adOpenIfExists|adCreateCollectionadOpenIfExists|adCreateCollection

Debug.Print "Record is Collection : " & Str(rec.RecordType)Debug.Print "Record is Collection : " & Str(rec.RecordType)

rec.MoveRecord “TestSubFolder”, “yourfolder”rec.MoveRecord “TestSubFolder”, “yourfolder”

Set rs = rec.GetChildrenSet rs = rec.GetChildren

End SubEnd Sub

‘‘opens an existing record object or creates a new oneopens an existing record object or creates a new one

Sub OpenFolderIfExists()Sub OpenFolderIfExists()

Dim rec As New ADODB.RecordDim rec As New ADODB.Record

Dim rs as ADODB.RecordsetDim rs as ADODB.Recordset

rec.Open "rec.Open "http://server01/http://server01/myfoldermyfolder//TestFolderTestFolder", , , _", , , _

adOpenIfExists|adCreateCollectionadOpenIfExists|adCreateCollection

Debug.Print "Record is Collection : " & Str(rec.RecordType)Debug.Print "Record is Collection : " & Str(rec.RecordType)

rec.MoveRecord “TestSubFolder”, “yourfolder”rec.MoveRecord “TestSubFolder”, “yourfolder”

Set rs = rec.GetChildrenSet rs = rec.GetChildren

End SubEnd Sub

Fields of a Record objectFields of a Record object

A field represents a property associated with a A field represents a property associated with a record objectrecord object Title, size, modified time of a file, folder, email messageTitle, size, modified time of a file, folder, email message

Fields are implemented as a collection on the Fields are implemented as a collection on the record objectrecord object

Methods and properties are same as that on Methods and properties are same as that on recordset’s field objectrecordset’s field object

New fields can be added to the collection of an New fields can be added to the collection of an already open record objectalready open record object

The Recordset ObjectThe Recordset Object When a record is a collection (such as a folder), it has When a record is a collection (such as a folder), it has

other records contained in itother records contained in it A view of contained records is available as a recordsetA view of contained records is available as a recordset

tabular view as opposed to the tree viewtabular view as opposed to the tree view

Use GetChildren method on the Record objectUse GetChildren method on the Record object opens the default contents recordset - pre-defined schema opens the default contents recordset - pre-defined schema

for document source providersfor document source providers

Execute a command against a folderExecute a command against a folder Ability to search on propertiesAbility to search on properties

Use Record and Recordset for navigationUse Record and Recordset for navigation URL is one of the fields on the contents recordset & can be URL is one of the fields on the contents recordset & can be

used to open the contained recordsused to open the contained records

Recordsets with Variable # of Recordsets with Variable # of ColumnsColumns

Many data sources generate recordsets where Many data sources generate recordsets where each row has a different set of columnseach row has a different set of columns

Case in point: Contents of a mail folderCase in point: Contents of a mail folder An email folder has different properties from the An email folder has different properties from the

Contacts folderContacts folder

Case in point: An XML streamCase in point: An XML stream Each element may have a different set of attributesEach element may have a different set of attributes

Case in point: The Contents recordsetCase in point: The Contents recordset Each file in a folder has different set of propertiesEach file in a folder has different set of properties

Supporting Variable Column Supporting Variable Column RecordsetsRecordsets

The fields collection on the recordset contains the The fields collection on the recordset contains the set of “common” fieldsset of “common” fields From address, subject, receive date, etc. for emailFrom address, subject, receive date, etc. for email File name, size, last modified, etc. for filesFile name, size, last modified, etc. for files

Each record has a set of fields unique to that rowEach record has a set of fields unique to that row This is a superset of the common columns that exist for This is a superset of the common columns that exist for

the recordsetthe recordset

To view the variable fields, obtain a record object To view the variable fields, obtain a record object from the recordset and then use its fields from the recordset and then use its fields collectioncollection

Relationship between the Relationship between the Record & Recordset ObjectsRecord & Recordset Objects

Record’s field collectionRecord’s field collection Superset of the fields collection on the Superset of the fields collection on the

associated source recordset, if anyassociated source recordset, if any

It is possible to add/delete fields from an It is possible to add/delete fields from an already open record objectalready open record object only for fields that are unique to that recordonly for fields that are unique to that record

Record behaves in the same update mode Record behaves in the same update mode as its source recordsetas its source recordset if no source recordset, then in immediate if no source recordset, then in immediate

update modeupdate mode

Working with the Recordset Working with the Recordset ObjectObject

'open Recordset'open Recordset

Sub OpenRecordset()Sub OpenRecordset()

Dim rs As New ADODB.RecordsetDim rs As New ADODB.Recordset

Dim rec As New ADODB.RecordDim rec As New ADODB.Record

Dim cn As New ADODB.ConnectionDim cn As New ADODB.Connection

stSrc = "stSrc = "http://server02/http://server02/myfoldermyfolder//testfoldertestfolder""

rs.Open stSrc, , _rs.Open stSrc, , _

adOpenForwardOnly, _adOpenForwardOnly, _

adLockReadOnly, _adLockReadOnly, _

adCmdURLBindadCmdURLBind

rs.MoveNextrs.MoveNext

rec.Open rs rec.Open rs

End SubEnd Sub

'open Recordset'open Recordset

Sub OpenRecordset()Sub OpenRecordset()

Dim rs As New ADODB.RecordsetDim rs As New ADODB.Recordset

Dim rec As New ADODB.RecordDim rec As New ADODB.Record

Dim cn As New ADODB.ConnectionDim cn As New ADODB.Connection

stSrc = "stSrc = "http://server02/http://server02/myfoldermyfolder//testfoldertestfolder""

rs.Open stSrc, , _rs.Open stSrc, , _

adOpenForwardOnly, _adOpenForwardOnly, _

adLockReadOnly, _adLockReadOnly, _

adCmdURLBindadCmdURLBind

rs.MoveNextrs.MoveNext

rec.Open rs rec.Open rs

End SubEnd Sub

Working with the Fields Working with the Fields collectioncollection

Sub RSFields()Sub RSFields()

Dim rs As New RecordsetDim rs As New Recordset

Dim rec as new RecordDim rec as new Record

stURL = "stURL = "http://server01/http://server01/myfoldermyfolder""

rs.Open stURL, , , , adCmdURLBindrs.Open stURL, , , , adCmdURLBind

while rs.eof <> Truewhile rs.eof <> True

rec.Open rsrec.Open rs

For i = 0 To rec.Fields.Count - 1For i = 0 To rec.Fields.Count - 1

Debug.Print rec.fields(I).name, “=“, _Debug.Print rec.fields(I).name, “=“, _

rec.fields(I).valuerec.fields(I).value

Next INext I

rs.MoveNextrs.MoveNext

WendWend

End SubEnd Sub

Sub RSFields()Sub RSFields()

Dim rs As New RecordsetDim rs As New Recordset

Dim rec as new RecordDim rec as new Record

stURL = "stURL = "http://server01/http://server01/myfoldermyfolder""

rs.Open stURL, , , , adCmdURLBindrs.Open stURL, , , , adCmdURLBind

while rs.eof <> Truewhile rs.eof <> True

rec.Open rsrec.Open rs

For i = 0 To rec.Fields.Count - 1For i = 0 To rec.Fields.Count - 1

Debug.Print rec.fields(I).name, “=“, _Debug.Print rec.fields(I).name, “=“, _

rec.fields(I).valuerec.fields(I).value

Next INext I

rs.MoveNextrs.MoveNext

WendWend

End SubEnd Sub

Stream ObjectStream Object A new ADO 2.5 objectA new ADO 2.5 object An automation object used to manipulate the contents of An automation object used to manipulate the contents of

a binary/textual streama binary/textual stream Implemented on top of IStream interfaceImplemented on top of IStream interface Record objects usually have a default stream associated Record objects usually have a default stream associated

with themwith them content of an email message, default document for a web content of an email message, default document for a web

folderfolder

BLOB/Text fields in a database may also be viewed as a BLOB/Text fields in a database may also be viewed as a stream objectstream object

Stream PropertiesStream Properties

Size Total size of the stream in number ofbytes

EOS Identifies if cursor is currentlypositioned at end of stream

Position Offset is bytes of current position frombeginning of stream

Type Identifies the type of data in the stream

Lineseparator Identifies the line separator character intextual streams

State Identifies the current state of the streamobject

Stream Methods (1 of 3)Stream Methods (1 of 3)

Open ([Source as variant], [Mode as Open ([Source as variant], [Mode as ModeEnum = adoModeUnknown], [Options as ModeEnum = adoModeUnknown], [Options as StreamOpenOptionsEnum = adOpenFromURL], StreamOpenOptionsEnum = adOpenFromURL], [uid as string], [pwd as string])[uid as string], [pwd as string])

Open ([Source as variant], [Mode as Open ([Source as variant], [Mode as ModeEnum = adoModeUnknown], [Options as ModeEnum = adoModeUnknown], [Options as StreamOpenOptionsEnum = adOpenFromURL], StreamOpenOptionsEnum = adOpenFromURL], [uid as string], [pwd as string])[uid as string], [pwd as string])

Open Opens an exisiting stream object from aURL or a record object

Close Closes an already open stream object

Cancel Cancels an aynchronous operation on the astream object

Stream Methods (2 of 3)Stream Methods (2 of 3)

ReadText ([NumChar as long = adReadAll]) as ReadText ([NumChar as long = adReadAll]) as StringString

WriteText (StrChars as string, [Options as WriteText (StrChars as string, [Options as StreamWriteOptionsEnum = adWriteChar])StreamWriteOptionsEnum = adWriteChar])

ReadText ([NumChar as long = adReadAll]) as ReadText ([NumChar as long = adReadAll]) as StringString

WriteText (StrChars as string, [Options as WriteText (StrChars as string, [Options as StreamWriteOptionsEnum = adWriteChar])StreamWriteOptionsEnum = adWriteChar])

ReadReadText

Reads specified number of bytes orcharacters from a stream

WriteWriteText

Writes the specified text or binary streaminto the stream object starting from thecurrent position

SkipLine For textual streams, skips an entire line ofcharacters

SetEOS Sets the “end of Stream” character.Truncates all the remaining data.

Flush Flushes the contents of a stream to theunderlying object that it is bound to(implementor of Istream)

Stream Methods (3 of 3)Stream Methods (3 of 3)

CopyTo(destStream as stream, [NumChars as CopyTo(destStream as stream, [NumChars as integer = -1]) integer = -1])

LoadFromFile (strFileName as string)LoadFromFile (strFileName as string)

SaveToFile(FileName as string, [SaveOptions as SaveOptionsEnum = adSaveCreateNotExist])

CopyTo(destStream as stream, [NumChars as CopyTo(destStream as stream, [NumChars as integer = -1]) integer = -1])

LoadFromFile (strFileName as string)LoadFromFile (strFileName as string)

SaveToFile(FileName as string, [SaveOptions as SaveOptionsEnum = adSaveCreateNotExist])

CopyTo Copies a specified number of bytes orcharacters from a stream to another streamobject

LoadfromFile Loads the contents of a file by reading indata from an existing file

SaveToFile Saves the contents of a stream into aspecified file

Working with the Stream Working with the Stream objectobject

Sub StmOperations()Sub StmOperations()

Dim Stm as New ADODB.StreamDim Stm as New ADODB.Stream

stURL = "stURL = "http://server01/http://server01/myfoldermyfolder//mydocmydoc.doc.doc""

Stm.Open stURLStm.Open stURL

Debug.Print Stm.SizeDebug.Print Stm.Size

Debug.Print Stm.TypeDebug.Print Stm.Type

Debug.Print Stm.ReadTextDebug.Print Stm.ReadText

Stm.SaveToFile “c:\my documents\copyofmydoc.doc”Stm.SaveToFile “c:\my documents\copyofmydoc.doc”

End SubEnd Sub

Sub StmOperations()Sub StmOperations()

Dim Stm as New ADODB.StreamDim Stm as New ADODB.Stream

stURL = "stURL = "http://server01/http://server01/myfoldermyfolder//mydocmydoc.doc.doc""

Stm.Open stURLStm.Open stURL

Debug.Print Stm.SizeDebug.Print Stm.Size

Debug.Print Stm.TypeDebug.Print Stm.Type

Debug.Print Stm.ReadTextDebug.Print Stm.ReadText

Stm.SaveToFile “c:\my documents\copyofmydoc.doc”Stm.SaveToFile “c:\my documents\copyofmydoc.doc”

End SubEnd Sub

ADO 2.5 - SummaryADO 2.5 - Summary

Extends core ADO to work with semi-Extends core ADO to work with semi-strucutred data exposed by new datasourcesstrucutred data exposed by new datasources

Enables web-publishing and document Enables web-publishing and document management through scripting languagesmanagement through scripting languages

Shipping in MDAC 2.5 with Windows 2000Shipping in MDAC 2.5 with Windows 2000 Will be available in Beta3Will be available in Beta3