ADO 2.5 Kamaljit Bath, Program Manager Data Access Group

Agenda  ADO - Overview  Semi-structured Data  ADO Programming Model  URL binding for ADO Objects  Record Object  Relationship between Record and Recordset  Stream Object  Summary

ADO Overview  A single, powerful consumer interface for data exposed by OLE DB providers  Designed for use in Web-based and Client/Server applications  Supports all languages (Visual Basic ®, Visual C++ ®, Visual J++ ™, Visual Basic Scripting Edition)  High Performance  Simple Object Model

Semi-structured data  Data that is:  More structured than a BLOB  Less structured than a Recordset or a relational database table  Examples:  A file system  data  An arbitrary XML stream  Web pages  Etc.

Semi-structured data: Characteristics  Data tends to be organized hierarchically, like a tree  Hierarchies have arbitrary depth  Each node in the tree has a set of properties  Each node may have a unique set of properties  Leaf-nodes associated with a special “Value” property  Non-leaf nodes are collections of other nodes

Semi-structured data: Requirements  Node Operations  Get/Set properties, Add/Delete properties  Scoped Operations  Move, Copy, Delete operations apply to all contained nodes  Querying  A list of nodes that satisfy a predicate on properties  Lightweight  Operations such as reading properties, etc. are done many times

ADO Design Goals  Keep it simple!  Allow ADO objects to be addressed by URL strings  Extend ADO to work with tree-structured & hierarchical datasources  Provide the ability to do scoped operations  Extend ADO so that it may be used to read and manipulate binary streams

Modeling semi-structured data with ADO 2.5  Collections are modeled as recordsets  Common properties are modeled as fields of the recordset  Folders, Directories  Nodes are modeled as a record object  Properties are modeled as fields of the record object  Files, folder objects  Contents of nodes are manipulated by the Stream object

ADO Object Model Connection Command Recordset Errors Fields Parameters

ADO Object Model Connection Command Recordset Errors Fields Parameters RecordStream

URL Naming for ADO objects  URLs can be used to directly identify individual objects in a datasource  nodes in a hierarchical namespace (files and folders)  table in a relational database, unique rows in a table  Record object represents a unique object  file, folder, table, row  Recordset object represents the contents of a collection object  rows of a table, files in a folder

URL binding to ADO objects  ADO 2.5 allows URL naming for  Connection, Recordset, Record, and Stream objects  For a Recordset, URL must point to a collection type node  For stream, URL must point to a node that has a default stream defined  Hides RootBinder/ProviderBinder objects from the developer  New record objects can also be created directly

URL naming - sample code Sub RsOpen() Dim cn As New ADODB.Connection Dim rs As New ADODB.Recordset Dim rs1 as New ADODB.Recordset cn.Open " rs1.Open “mysubfolder”, cn rs.Open " _ adOpenForwardOnly, _ adLockReadOnly, _ adCmdURLBind End Sub

Record Object (1 of 2)  New automation object implemented in ADO 2.5  Models an entity that has a collection of properties and (possibly) nested entities  , Files, web pages, structured documents, folders, XML node, Databases, Tables, etc.  can also represent a row of a recordset  /File contents appear as a stream property

Record Object (2 of 2)  Expresses the notion of containment & scoping  Folders contain other folders  Folder operations such as move, copy, etc. apply within the folder’s scope  Properties are modeled as a collection of Fields  Containment is modeled as Sub-Records  Child records can be viewed in a tabular form as a recordset  Properties and methods are implemented to operate on the record object

Opening 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 a Connection object  connection object is either implicitly created or explicitly specified

Record Properties

Record Methods (1 of 2) Open ([Source as variant], [ActiveConnection as variant], [Mode as ModeEnum = adoModeUnknown], [CreateOptions as RecordCreateOptionsEnum = -1], [OpenOptions as RecordOpenOptionsEnum = -1], [uid as string], [pwd as string])

Record Methods (2 of 2) CopyRecord ({SourceURL as string], DestURL as string, [destuid as string], [destpwd as string], [CopyRecordOptions as CopyRecordOptionsEnum], [AsyncFlag as Boolean]) as String GetChildren() as ADODB.Recordset

Working with the Record Object ‘opens an existing record object or creates a new one Sub OpenFolderIfExists() Dim rec As New ADODB.Record Dim rs as ADODB.Recordset rec.Open " _ adOpenIfExists|adCreateCollection adOpenIfExists|adCreateCollection Debug.Print "Record is Collection : " & Str(rec.RecordType) rec.MoveRecord “TestSubFolder”, “yourfolder” Set rs = rec.GetChildren End Sub

Fields of a Record object  A field represents a property associated with a record object  Title, size, modified time of a file, folder, message  Fields are implemented as a collection on the record object  Methods and properties are same as that on recordset’s field object  New fields can be added to the collection of an already open record object

The Recordset Object  When a record is a collection (such as a folder), it has other records contained in it  A view of contained records is available as a recordset  tabular view as opposed to the tree view  Use GetChildren method on the Record object  opens the default contents recordset - pre-defined schema for document source providers  Execute a command against a folder  Ability to search on properties  Use Record and Recordset for navigation  URL is one of the fields on the contents recordset & can be used to open the contained records

Recordsets with Variable # of Columns  Many data sources generate recordsets where each row has a different set of columns  Case in point: Contents of a mail folder  An folder has different properties from the Contacts folder  Case in point: An XML stream  Each element may have a different set of attributes  Case in point: The Contents recordset  Each file in a folder has different set of properties

Supporting Variable Column Recordsets  The fields collection on the recordset contains the set of “common” fields  From address, subject, receive date, etc. for  File name, size, last modified, etc. for files  Each record has a set of fields unique to that row  This is a superset of the common columns that exist for the recordset  To view the variable fields, obtain a record object from the recordset and then use its fields collection

Relationship between the Record & Recordset Objects  Record’s field collection  Superset of the fields collection on the associated source recordset, if any  It is possible to add/delete fields from an already open record object  only for fields that are unique to that record  Record behaves in the same update mode as its source recordset  if no source recordset, then in immediate update mode

Working with the Recordset Object 'open Recordset Sub OpenRecordset() Dim rs As New ADODB.Recordset Dim rec As New ADODB.Record Dim cn As New ADODB.Connection stSrc = " rs.Open stSrc,, _ adOpenForwardOnly, _ adLockReadOnly, _ adCmdURLBindrs.MoveNext rec.Open rs End Sub

Working with the Fields collection Sub RSFields() Dim rs As New Recordset Dim rec as new Record stURL = " rs.Open stURL,,,, adCmdURLBind while rs.eof <> True rec.Open rs For i = 0 To rec.Fields.Count - 1 Debug.Print rec.fields(I).name, “=“, _ rec.fields(I).value rec.fields(I).value Next I rs.MoveNextWend End Sub

Stream Object  A new ADO 2.5 object  An automation object used to manipulate the contents of a binary/textual stream  Implemented on top of IStream interface  Record objects usually have a default stream associated with them  content of an message, default document for a web folder  BLOB/Text fields in a database may also be viewed as a stream object

Stream Properties

Stream Methods (1 of 3) Open ([Source as variant], [Mode as ModeEnum = adoModeUnknown], [Options as StreamOpenOptionsEnum = adOpenFromURL], [uid as string], [pwd as string])

Stream Methods (2 of 3) ReadText ([NumChar as long = adReadAll]) as String WriteText (StrChars as string, [Options as StreamWriteOptionsEnum = adWriteChar])

Stream Methods (3 of 3) CopyTo(destStream as stream, [NumChars as integer = -1]) LoadFromFile (strFileName as string) SaveToFile(FileName as string, [SaveOptions as SaveOptionsEnum = adSaveCreateNotExist])

Working with the Stream object Sub StmOperations() Dim Stm as New ADODB.Stream stURL = " Stm.Open stURL Debug.Print Stm.Size Debug.Print Stm.Type Debug.Print Stm.ReadText Stm.SaveToFile “c:\my documents\copyofmydoc.doc” End Sub

ADO Summary  Extends core ADO to work with semi- strucutred data exposed by new datasources  Enables web-publishing and document management through scripting languages  Shipping in MDAC 2.5 with Windows 2000  Will be available in Beta3