MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 8: Binder Objects and Direct Binding

Direct Binding

Through direct binding, a consumer can specify an OLE DB object in such a way that it can be obtained in a single method call, without the use of connection strings, accessors, or provider-specific mechanisms. This is done by associating OLE DB objects with resources named by URLs. Row, rowset, stream, data source, and session objects can all be obtained through direct binding.

The consumer calls IBindResource::Bind on the root binder object, passing as an argument the URL of the resource that is to be bound to the requested OLE DB object.

IBindResource::Bind has flags that encapsulate the most common properties to be set on the returned OLE DB object. The consumer can set additional properties by calling IDBBinderProperties methods.

When IBindResource::Bind is called for a URL, the following procedure occurs:

1. The root binder obtains the CLSID of the provider binder that is registered to the nearest matching URL prefix.
   
   
2. The root binder cocreates the provider binder object of the provider that is registered for that prefix, if it is not already instantiated.
   
   
3. The root binder delegates the bind request to the appropriate provider. Any properties that were set on the root binder are also passed to the provider binder object. These properties are passed when IBindResource::Bind is called because the root binder does not know which provider binder to use at any other time.
   
   
4. The provider binder object opens the resource named by the URL.
   
   
5. If the requested OLE DB object type is a data source or session object and this object does not currently exist, the provider instantiates the object. If the object type requested is a row, stream, or rowset object, the provider creates a new row, stream, or rowset object over the resource named by the URL.
   
   
6. The provider binder object returns the requested interface pointer on the OLE DB object to the caller. The OLE DB object remains bound as long as this interface pointer is held by the calling application.

A URL designates a resource in a hierarchical data store owned by an OLE DB provider. By virtue of this association, the URL that is requested in a direct binding call (to IBindResource::Bind or ICreateRow::CreateRow) defines a scope for the session object associated with the object that is obtained from the bind. The scope is that of the resource named by the URL. This scope is the same, no matter how the session object is obtained. The session object can be obtained in one of the following ways:

• The consumer calls IBindResource::Bind or ICreateRow::CreateRow to bind to a URL, requesting a rowset, row, or stream object. The consumer can then obtain the session object by calling IRowsetInfo::GetSpecification, IGetSession::GetSession, or IGetSourceRow::GetSourceRow.
  
  
• The consumer calls IBindResource::Bind to bind to a URL, requesting a session object in the bind call. Bind then returns the implicit session object.
  
  
• The consumer calls IBindResource::Bind to bind to a URL, requesting a data source object in the bind call. The consumer then calls IDBCreateSession::CreateSession on the returned data source object to obtain the implicit session object.

Note   It is provider-specific if binds requested outside the scope of the current session or row object succeed.

If the resource named by a URL does not exist, an application can create the resource itself, as well as the row or rowset object, through the ICreateRow interface. The newly created row or rowset object inherits the default columns of the object named by the parent URL. When a consumer instantiates a row or rowset directly in this way, the provider implicitly creates an OLE DB session object and then creates the desired object within the scope of that session. To obtain an interface pointer on this implicit session, the consumer can use the DBIMPLICITSESSION parameter of IBindResource::Bind (or ICreateRow::CreateRow) or can call IGetSession::GetSession on the row object (or IRowsetInfo::GetSpecification on the rowset object). This interface pointer can be used to commit or abort a transaction that the row or rowset is part of.

Note   For a given instance of a provider binder object, each time IBindResource::Bind is called, the provider creates a new row, rowset, or stream object in the context of the same implicit session.

When a new row or rowset object is created, the provider might need to generate the suffix of the new URL. The DBPROP_GENERATEURL data source object property indicates whether the provider generates URL suffixes or the consumer must supply the complete URL.

When binding to a URL, with either IBindResource or ICreateRow, the consumer must specify the type of object to be returned: data source, session, rowset, row, or stream. If the caller binds to a URL of a row or rowset but requests a data source or session object, no row or rowset is instantiated. Instead, the appropriate data source object or session is instantiated if it does not already exist. To obtain a row or rowset object, the caller must bind again and request a row or rowset object.