Microsoft SQLNCli team blog : OLE DB

SQL Server Native Client: Connection strings and OLE DB

david_vcp — Thu, 07 May 2009 02:25:00 GMT

(Anton Klimov, a developer on the SQL Server Native Client team, wrote the following article.)

Connection strings for an OLE DB provider is a concept that causes a lot of confusion. One problem is that OLE DB itself does not define connection string as a provider concept.

The documentation at Connection String Syntax (http://msdn.microsoft.com/en-us/library/ms722656(VS.85).aspx) says:

"A connection string is a string version of the initialization properties needed to connect to a data store and enables you to easily store connection information within your application or to pass it between applications. Without a connection string, you would be required to store or pass a complex array of structures to access data. When accessing OLE DB directly, using IDataInitialize (http://msdn.microsoft.com/en-us/library/ms714296%28VS.85%29.aspx), the connection string is passed as a parameter to create an OLE DB data source object."

“when accessing OLE DB directly” actually means that the application doesn’t directly instantiate a corresponding provider object, but rather goes through the “service component”, (otherwise known as “core services”, layer (oledb32.dll) by doing something like:

hr = CoCreateInstance(
   CLSID_MSDASC,   // CLSID of “service component”
   NULL,           // pUnkOuter
   CLSCTX_INPROC_SERVER,
   IID_IDataInitialize,
   (void**)&m_pIDataInitialize)
;

This way, you get additional services from oledb32 like session pooling, automatic transaction enlistment, cursor engine, and support for additional interfaces.

This also applies to ADO; so for an ADO programmer, a connection string is a similar concept but the way the provider looks at it is frequently misunderstood.

From the provider point of view there is no such thing as a connection string, instead the provider understands the initialization properties, which are hinted to in the above passage as “complex array of structures to access data”. See also OLE DB Initialization Properties: Quick Reference (http://msdn.microsoft.com/en-us/library/ms723996(VS.85).aspx).

What makes the situation especially confusing is that one of the properties is similar to a connection string. These are the so called “Extended Properties” (DBPROP_INIT_PROVIDERSTRING).

http://msdn.microsoft.com/en-us/library/ms723996(VS.85).aspx for it says:

"A string containing provider-specific, extended connection information. Use of this property implies that the consumer knows how this string will be interpreted and used by the provider. Consumers should use this property only for provider-specific connection information that cannot be explicitly described through the property mechanism."

However, in practice, lack of understanding leads consumers to use a combination of keywords both corresponding to the generic OLE DB properties and to provider specific keywords making sense only in the context of the provider string.

For example the site listing lots of examples of connection strings has the following for SQL Server Native Client 10.0 OLE DB Provider (http://www.connectionstrings.com/sql-server-2008):

Provider=SQLNCLI10; Server=myServerAddress; Database=myDataBase; Trusted_Connection=yes; MarsConn=yes;

Equivalent key-value pair: "MultipleActiveResultSets=true" equals "MARS_Connection=yes"

Here “Provider” keyword is used by oledb32 to find a CLSID of the provider to instantiate. “Server”, “Database”, “Trusted_Connection” and “MarsConn” are not the names of the OLE DB initialization properties (which would be “Data Source”, “Integrated Security”, and “Mars Connection”). Moreover, MarsConn=yes will have no effect, see explanation below.

MultipleActiveResultSets is a keyword for ADO.NET , and MARS_Connection is for ODBC.

oledb32 process a connection string as follows: it tries to find the keywords corresponding to the generic OLE DB initialization keywords (corresponding to DBPROPSET_DBINIT), and it also queries a provider by using IDBProperties::GetPropertyInfo (http://msdn.microsoft.com/en-us/library/ms718175(VS.85).aspx) to see which initialization properties provider supports (for SQL Server Native Client it is DBPROPSET_SQLSERVERDBINIT). For matched keywords, the corresponding properties will be set, everything else goes into “Extended Properties”.

Consider the following example in VBScript:

set connection = CreateObject("ADODB.Connection")

connection.ConnectionString = "provider=sqlncli10;data source=akl6; integrated security=sspi;initial catalog=tempdb"

connection.Open

WScript.Echo connection.ConnectionString

Here is the result of the execution:

Provider=SQLNCLI10.1;Integrated Security=sspi;Initial Catalog=tempdb;Data Source=akl6;Use Procedure for Prepare=1;Auto Translate=True;Packet Size=4096;Workstation ID=AKL5;Use Encryption for Data=False;Tag with column collation when possible=False;MARS Connection=False;DataTypeCompatibility=0;Trust Server Certificate=False

If we try the following connection string

"provider=sqlncli10;server=akl6;database=tempdb;Trusted_Connection=yes;MarsConn=yes"

we will get:

Provider=SQLNCLI10.1;Extended Properties="server=akl6;database=tempdb;Trusted_Connection=yes;MarsConn=yes";Use Procedure for Prepare=1;Auto

Translate=True;Packet Size=4096;Workstation ID=AKL5;Use Encryption for Data=False;Tag with column collation when possible=False;MARS Connect

ion=False;DataTypeCompatibility=0;Trust Server Certificate=False

As you can see all the keywords that we specified are bundled into “Extended Properties” since they are not recognized as property names. What is worse is that now we apparently have two keywords corresponding to MARS Connectivity and one is “yes”, whether the other is “False”.

Which one wins? It turns out that the generic value wins. So the setting “MarsConn=yes” as a part of OLE DB connection string has no effect. It would work only if the provider was initialized directly and provider specific property was not used, but “Extended Properties” was used.

If you have the following:

“Server=server1; Data Source=server2;”

The data Source will win.

Generic Initialization properties (DBPROPSET_DBINIT)

The following list shows property IDs and their associated description/keywords:

Property ID	Description / keyword
DBPROP_AUTH_INTEGRATED	Integrated Security
DBPROP_AUTH_PASSWORD	Password
DBPROP_AUTH_PERSIST_SENSITIVE_AUTHINFO	Persist Security Info
DBPROP_AUTH_USERID	User ID
DBPROP_INIT_ASYNCH	Asynchronous Processing
DBPROP_INIT_CATALOG	Initial Catalog
DBPROP_INIT_DATASOURCE	Data Source
DBPROP_INIT_HWND	Window Handle
DBPROP_INIT_LCID	Locale Identifier
DBPROP_INIT_PROPMT	Prompt
DBPROP_INIT_PROVIDERSTRING	Extended Properties
DBPROP_INIT_TIMEOUT	Connect Timeout
DBPROP_INIT_GENERALTIMEOUT	General Timeout

If default value is specified the property cannot be overridden with an “extended property” when used in an OLE DB connection string.

Provider Specific Properties (DBPROPSET_SQLSERVERDBINIT)

The following list shows the associated property IDs, default values (if any) and description/keywords for provider specific properties.

SSPROP_INIT_CURRENTLANGUAGE

(no default value)

Current Language

SSPROP_INIT_NETWORKADDRESS

(no default value)

Network Address

SSPROP_INIT_NETWORKLIBRARY

(no default value)

Network Library

SSPROP_INIT_USEPROCFORPREP

Use Procedure for Prepare

SSPROP_INIT_AUTOTRANSLATE

VARIANT_TRUE

Auto Translate

SSPROP_INIT_PACKETSIZE

4096

Packet Size

SSPROP_INIT_APPNAME

(no default value)

Application Name

SSPROP_INIT_WSID

(no default value)

Workstation ID

SSPROP_INIT_FILENAME

(no default value)

Initial File Name

SSPROP_INIT_ENCRYPT

VARIANT_FALSE

Use Encryption for Data

SSPROP_AUTH_REPL_SERVER_NAME

(no default value)

Replication server name connect option

SSPROP_INIT_TAGCOLUMNCOLLATION

VARIANT_FALSE

Tag with column collation when possible

SSPROP_INIT_MARSCONNECTION

VARIANT_FALSE

MARS Connection

SSPROP_INIT_FAILOVERPARTNER

(no default value)

Failover Partner

SSPROP_AUTH_OLD_PASSWORD

(no default value)

Old Password

SSPROP_INIT_DATATYPECOMPATIBILITY

DataTypeCompatibility

SSPROP_INIT_TRUST_SERVER_CERTIFICATE

VARIANT_FALSE

Trust Server Certificate

SSPROP_INIT_SERVERSPN

(no default value)

Server SPN

SSPROP_INIT_FAILOVERPARTNERSPN

(no default value)

Failover Partner SPN

Note that the corresponding properties are not going to be set, and as mentioned above, some of the settings might be ignored.

The following list shows keywords recognized in the provider string and its (approximate) corresponding property.

“Server"

DBPROP_INIT_DATASOURCE

“UID"

DBPROP_AUTH_USERID

“PWD"

DBPROP_AUTH_PASSWORD

“APP"

SSPROP_INIT_APPNAME

“WSID"

DBPROP_INIT_CATALOG

“Database"

DBPROP_INIT_CATALOG

“Language"

SSPROP_INIT_CURRENTLANGUAGE

“Network" or “Net” or “Network Library”

SSPROP_INIT_NETWORKLIBRARY

“Address" or “Addr”

SSPROP_INIT_NETWORKADDRESS

“Trusted_Connection"

DBPROP_AUTH_INTEGRATED

“UseProcForPrepare"

SSPROP_INIT_USEPROCFORPREP

“LCID"

Not used

“Prompt"

DBPROP_INIT_PROPMT

“PersistSensitive"

DBPROP_AUTH_PERSIST_SENSITIVE_AUTHINFO

“AutoTranslate" or “Auto Translate”

SSPROP_INIT_AUTOTRANSLATE

“Timeout"

DBPROP_INIT_TIMEOUT

“PacketSize"

SSPROP_INIT_PACKETSIZE

“HWND"

DBPROP_INIT_HWND

“AttachDBFileName"

SSPROP_INIT_FILENAME

“Encrypt"

SSPROP_INIT_ENCRYPT

“MarsConn"

SSPROP_INIT_MARSCONNECTION

“FailoverPartner"

SSPROP_INIT_FAILOVERPARTNER

“DataTypeCompatibility"

SSPROP_INIT_DATATYPECOMPATIBILITY

“TrustServerCertificate"

SSPROP_INIT_TRUST_SERVER_CERTIFICATE

“ServerSPN"

SSPROP_INIT_SERVERSPN

“FailoverPartnerSPN"

SSPROP_INIT_FAILOVERPARTNERSPN

Linked server configuration note:

In the "Linked Server Properties -- New Linked Server" dialog box“ (SQL Server Management Studio go to Server Objects -> Linked Servers -> New Linked Server), the Provider string” really corresponds to “Extended Properties”.

Some users try putting their generic OLE DB Connection string, which leads to the server discarding all or the part of the settings and it could end up connecting to the local machine instead of the machine that the user thinks is specified. For instance if “Failover Partner” is specified in that dialog and it contains a space, the setting will have no effect since in the provider string no space is expected.

Welcome to the Microsoft SQL Server Native Client Team Blog

chrlee — Thu, 28 Sep 2006 00:55:00 GMT

Welcome!

In this blog you will find posts about Microsoft SQL Server Native Client, or SQL Native Client for short. This is the component that provides ODBC and OLE DB support for Microsoft SQL Server from SQL Server 2005 onwards.

I'll get the ball rolling with a FAQ about native data access for SQL Server 2005 and by reposting some articles from the old and now suspended Data Access blog which are still quite topical.

Chris Lee
Program Manager, SQL Native Client

Native Data Access for SQL Server 2005 FAQ

chrlee — Thu, 28 Sep 2006 00:50:00 GMT

Native Data Access for SQL Server 2005 FAQ

In SQL Server 2005 Microsoft decided to change the way it supports ODBC and OLE DB with the introduction of Microsoft SQL Server Native Client (SQL Native Client), a new component of SQL Server 2005. This FAQ answers some basic questions about SQL Native Client and about ODBC and OLE DB in general.

What is SQL Native Client?

Microsoft SQL Server Native Client (SQL Native Client) is a single native dynamic link library (DLL) that contains the ODBC driver and OLE DB provider which together support applications using native-code APIs (ODBC, OLE DB and ADO) to access Microsoft SQL Server. SQL Native Client is a component of SQL Server 2005 and is serviced in SQL Server 2005 service packs. It is also available for download from MSDN (http://msdn.microsoft.com/data/ref/sqlnative/default.aspx). In SQL Native Client, everything (APIs, TDS routines and netlibs) is packaged into a single DLL.

Previously ODBC and OLE DB support for SQL Server was provided via Microsoft Data Access Components (MDAC - http://msdn.microsoft.com/data/ref/mdac/). MDAC is now fully integrated into Windows and is available only in Windows releases and service packs – there will be no more standalone MDAC downloads on MSDN. MDAC continues to provide core data access functionality such as the ODBC Driver Manager and OLE DB Core Services, but the ODBC and OLE DB support for SQL Server is frozen at the level of functionality provided by SQL Server 2000.

Note that SQL Native Client supports SQL Server releases from SQL Server 7.0 onwards, so its use is not restricted to SQL Server 2005. However, new features such as MARS (http://msdn2.microsoft.com/en-us/library/ms131686.aspx) are only available when connected to SQL Server 2005.

Where do I find out more about SQL Native Client?

You can find information about SQL Native Client in Books Online and also on MDSN (http://msdn.microsoft.com/data/learning/sqlnative/).

For anything you can’t find there you can use the SQL Server Data Access forum (http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=87&SiteID=1)

Must I upgrade clients to use SQL Native Client as soon as I upgrade my server?

Applications deployed before SQL Server 2005 was released can and should continue to use MDAC.

Applications must upgrade to take full advantage of the new features and data types introduced in SQL Server 2005 (http://msdn2.microsoft.com/en-us/library/ms131456.aspx ). When an application is upgraded, it should be thoroughly tested since there are some differences in behavior between MDAC and SQL Native Client (http://msdn2.microsoft.com/en-us/library/ms131035.aspx ). The vast majority of applications will not be affected by these changes, but this does not remove the responsibility to test before deployment.

Should I rewrite my native API applications to use ADO.Net and managed code?

In most cases the old adage “If it isn’t broken, don’t fix it” applies. The .Net platform has many compelling attributes and will be the right choice for new development in most cases, but this does not mean that it is the right choice in all cases. There are valid reasons for making other choices in some case: Visual Studio 2005 and C++/CLI (http://msdn.microsoft.com/msdnmag/issues/04/05/VisualC2005/)makes re-use of existing native data access code within a .Net deployment infrastructure a more viable option than ever before; there are some scenarios where native code and native APIs provide the best solution; Microsoft now has its own high quality JDBC driver for SQL Server 2005(http://msdn.microsoft.com/data/ref/jdbc/default.aspx); also, Native XML Web Services in SQL Server 2005 (http://msdn2.microsoft.com/en-us/library/ms191274.aspx ) provide an additional means of exposing database-dependent services in service oriented architectures.

Isn’t ODBC is on the way out? If you have to use a native API isn’t OLE DB better?

ODBC and OLE DB are supported equally in SQL Native Client. Neither is better, they service different requirements and communities. There is no need to convert from one to the other unless there are other compelling business reasons. While there was a time when Microsoft expected OLE DB to supersede ODBC that time has passed and we now recognize that each API has its place.

OLE DB is a good choice for COM applications and has broader functionality than ODBC in some areas. It is used extensively within SQL Server itself. However, it is quite complex and more difficult to program for basic operations than ODBC.

ODBC may have been out of the limelight in recent years, but Microsoft anticipates strong and continued interest in this API going forward. ODBC has a huge following across the entire software industry and will therefore remain an essential component of SQL Server to meet requirements for standards alignment and interoperability. When migrating applications from other databases to SQL Server, where companies choose to re-use existing code and applications rather than make a fresh start and re-develop from scratch, ODBC will be the natural choice in most cases.

There is little difference in performance between OLE DB and ODBC – application architecture is likely to have a bigger impact on performance than choice of API for well-written applications that follow best practice guidelines.

Isn't ODBC just a ‘wrapper’ API and inherently inefficient?

This may be true for some ODBC drivers, but not for SQL Native Client. ODBC in SQL Native Client and also in MDAC is a true native API for SQL Server.

What about DB-Library and Embedded SQL for C(ESQL/C)?

DB-Library and ESQL/C components are not included in SQL Server 2005 but connections from existing applications are supported. Microsoft has no plans for any new development work involving these APIs. Customers may continue to deploy existing applications, but development of new applications and extension of existing applications is not recommended. Continued support for DB-Library and ESQL/C is not guaranteed in future releases of SQL Server (http://msdn2.microsoft.com/en-us/library/ms143729.aspx ).

Microsoft is reviewing support for DB-Library and ESQL/C in future releases of SQL Server and welcomes your input as part of the review process.

Chris Lee
Program Manager, SQL Native Client

Introducing SQL Native Client

chrlee — Thu, 28 Sep 2006 00:45:00 GMT

Introducing SQL Native Client

[This was originally posted on the DataWorks blog which is now suspended]

By now you may have heard of a new data access technology called “SQL Native Client” that will ship with SQL Server 2005. But before we go much further in discussing it, let’s be clear about what we mean by “new”. It is new in that this data access library did not exist prior to SQL Server 2005, but rest assured that it is not some radical new design for accessing data!

In a nutshell, SQL Native Client is a stand alone data access Application Programming Interface (API) that is used for both OLE DB and ODBC. It combines the SQL OLE DB provider and the SQL ODBC driver into one native dynamic link library (DLL) while also providing new functionality above and beyond that supplied by the Microsoft Data Access Components (MDAC). SQL Native Client can be used to create new applications or enhance existing applications that need to take advantage of new SQL Server 2005 features such as Multiple Active Result Sets (MARS), User-Defined Types (UDT), and XML data type support.

So SQL Native Client combines OLE DB and ODBC in one library, and then enhances that library to take advantage of new features offered by SQL Server 2005. Hopefully that is straightforward enough. But we imagine that this leads to a few questions such as “why have you done this?” and “when would I want to use it?” We’ll try to address those questions next.

Why have you done this?

The reason we have developed SQL Native Client is to allow us to continue to innovate OLE DB and ODBC functionality without being restricted by the constraints imposed by MDAC. MDAC now ships as a component of the Windows operating system and as such there are a number of setup, redistribution, and deployment issues that have occurred as a result of this. How many of you have installed a Windows service pack only to see your MDAC based application break? Or perhaps you have developed an application based on the latest MDAC release only to discover that when you deploy it, the users in your organization do not have the latest MDAC release so your app won’t function correctly. By wrapping the OLE DB and ODBC technologies into a single library, we are able to avoid these issues by making a clean break from MDAC so that you can effectively deploy SQL Native Client as needed, without concern about if it will “play nicely” with other versions of MDAC.

When would I want to use it?

But when would you actually want to use SQL Native Client as opposed to MDAC, or even ADO.NET? The answer is – only if you are upgrading existing or developing new COM-based (or native) applications that will target the new features of SQL Server 2005. If you don’t need any of the new features of SQL Server 2005, then you don’t need to use SQL Native Client, your existing OLE DB and ODBC code will work just fine. Of course, if you have or are planning on moving to a managed code base for data access, then the ADO.NET data access classes of the .NET Framework is what you should use.

More Information?

We’ve barely scratched the surface here of how you can use SQL Native Client, but hopefully you now understand what it is, where it fits in with the various other data access technologies, and when and where you would want to use it. Over the next few months you will see more and more information posted about SQL Native Client, but please let us know what questions and concerns you have. We currently have a number of articles and whitepapers in development, and we’d love to have your feedback to help shape the direction that they take.

And by the way, be sure to check out the Data Access Technologies Roadmap on MSDN for the complete story and status for the majority of data access technologies here at Microsoft.

Acey J. Bunch

Lead Programmer Writer - DataWorks User Education.

Disclaimer: This posting is provided "AS IS" with no warranties, and confers

Getting started with SQL Native Client

chrlee — Thu, 28 Sep 2006 00:40:00 GMT

Getting started with SQL Native Client [Chris Lee]

[This was originally posted on the DataWorks blog which is now suspended]

As Acey Bunch explained in April, SQL Native Client meets the needs of developers wanting to take advantage of new features in SQL Server 2005 from ADO, ODBC and OLE DB applications. For those of you who haven’t looked at SQL Native Client yet we now need to start the education process of how to use it. The good news is that it’s very simple. We have implemented a very small number of new interfaces for OleDb, but most new features are implemented via connection or statement attributes, which you already know how to use.

I’ll start at a very basic level and talk about how to convert existing applications to use SQL Native Client. This comes in three stages: first getting existing code running; second, preparing to exploit new features; third, using new features. In this post I’ll deal with the first two of these. The third will be covered in my next post, using Multiple Active Result Sets (MARS) as an example. If you have SQL Server 2005 installed on your machine, SQL Native Client is already installed. If not, SQLNCLI.msi is included with the SQL Server 2005 distribution, but isn’t copied when SQL Server 2005 is installed, so just copy it from the distribution in the \Setup folder.

Stage 1:Getting existing code running
For ADO you change your connection string to use SQLNCLI as the provider, and add a keyword to enable SQL Server 2000 data type compatibility, so
“ …;Provider=SQLOLEDB;…”
becomes
“…;Provider=SQLNCLI;DataTypeCompatibility=80;…”
ADO is a generic data access API that is now part of the Windows Platform and is not part of SQL Native Client, so the ADO on your machine did not change when you installed SQL Native Client. Therefore, it doesn’t have any specific knowledge of SQL Server in general, much less the new datatypes introduced for SQL Server 2005. For this reason, when using ADO we have to tell SQL Native Client to map new SQL Server 2005 data types to data types that ADO does understand. I’ll explain this in a later article, for now accept that we need this, and that it doesn’t get in the way of using other new features of SQL Server 2005.

For ODBC you change the driver name from ‘SQL Server’ to ‘SQL Native Client’. If your application uses a DSN you need to create a new DSN and select ‘SQL Native Client’ as the driver. If you use DSN-less connections just update the connection string in your application.

For OLE DB you simply change the provider name from ‘SQLOLEDB’ to ‘SQLNCLI’, or use CLSID_SQLNCLI instead of CLSID_SQLOLEDB.

Stage 2: Preparing to use new features
For ADO: If you’re using ADO, you’re already good to go.

ODBC and OLE DB applications need to use sqlncli.h to gain access to new features. You also need to be using Visual Studio.Net. Sqlncli.h is a new common header file for both ODBC and OLE DB and is typically installed to C:\Program Files\Microsoft SQL Server\90\SDK\Include.

For ODBC sqlncli.h is a straight replacement for odbcss.h. If you’re using bcp API calls alongside ODBC calls then you need to link with sqlncli.lib instead of odbcbcp.lib.

For OLE DB you can add the #include for sqlncli.h after the #include for sqloledb.h if you need to use both old and new providers (sqlncli.h doesn’t contain the CLSIDs for SQLOLEDB), or you can replace the #include for sqloledb.h with the #include for sqlncli.h if you don’t need the old CLSIDs. If you need both headers, the #include for sqloledb.h must come first.

Since sqlncli contains symbols for both ODBC and OLE DB, there’s a chance you may get a name clash between one of your own symbols and a symbol defined for use by the ‘other’ API (the one you’re not going to be using). In this case you can add a #define to get rid of the symbols for the API you don’t need. If you’re using OLE DB you #define _SQLNCLI_OLEDB_ and if you’re using ODBC you #define _SQLNCLI_ODBC_.

Next steps …
You’re now prepared to start using the new features of SQL Server 2005 available with SQL Native Client. Consult SQL Native Client Programming in SQL Server Programming Refernce in Books Online for details of these features. The documentation for SQL Native Client has been updated quite a lot recently, so you need to use the latest build available to you. Most of the new features are very simple to program and are controlled by connection or statement properties. In my next post I’ll take a look at Multiple Active Result Sets (MARS).

Chris Lee
Program Manager, DataWorks

Using MARS with SQL Native Client

chrlee — Wed, 27 Sep 2006 23:08:00 GMT

Using MARS with SQL Native Client [Chris Lee]

[This was originally posted on the DataWorks blog which is now suspended]

As stated in my previous post, the majority of new features available through SQL Native Client are accessed by connection or statement properties. MARS is about the simplest new feature to use in SQL Server 2005, and possibly the one we’ve all been waiting for the longest, so it’s a good candidate for your first excursion into the new features available with SQL Native Client.

MARS lets an application perform multiple operations on a single connection even if there are default result sets open on the connection. Prior to MARS, ADO and SQLOLEDB applications would (under default conditions) use implicit multiple connections and ODBC applications would get ‘connection busy’ errors.

Pre-MARS behavior
Let’s look at MARS using ADO for simplicity (I’ll mention how to enable MARS with ODBC or OLE DB at the end of this post, but don’t skip there just yet as most of what follows is still going to be useful to you even if you’re not using ADO). Try executing the following code (which assumes you have a SQL Server instance called SQL2K5 with the AdventureWorks demo database available on your local machine). This is just ‘nonsense’ code that just opens a default result set and then opens another result set using the same query multiple times, to make a point. The extension of the point it makes to your own applications shouldn’t be hard to grasp.

    Dim i As Integer
    Dim cn As ADODB.Connection
    Dim qryCustomers1 As ADODB.Command
    Dim qryCustomers2 As ADODB.Command
    Dim rsCustomers1 As ADODB.Recordset
    Dim rsCustomers2 As ADODB.Recordset

    Set cn = New ADODB.Connection
    cn.Open ("Provider=sqlncli;Data Source=.\SQL2K5" & _
             ";Database=AdventureWorks;Integrated Security=SSPI;")
    Set qryCustomers1 = New ADODB.Command
    Set qryCustomers1.ActiveConnection = cn
    qryCustomers1.CommandText = "SELECT CustomerID" & _
                       " FROM Sales.Customer" & _
                       " WHERE CustomerID=1" & _
                       " ORDER BY CustomerID"
    Set qryCustomers2 = New ADODB.Command
    Set qryCustomers2.ActiveConnection = cn
    qryCustomers2.CommandText = qryCustomers1.CommandText

    Set rsCustomers1 = qryCustomers1.Execute
    For i = 1 To 3
        Set rsCustomers2 = qryCustomers2.Execute
        rsCustomers2.Close
    Next i
    rsCustomers1.Close
    cn.Close

If you take a default SQL Server Profiler trace you’ll see something like this:

The second result set is using a new connection each time it is opened. This clearly has some overhead (and it turns out that the additional connections aren’t pooled, so the overhead is for a full server connection network protocol exchange each time). This is the default behavior for SQLOLEDB and SQL Native Client (OLE DB) – a new implicit connection is spawned when the main connection is busy with a default result set. You can prevent multiple implicit connections being spawned by changing the connection lines to

cn.Open ("Provider=sqlncli;Data Source=.\SQL2K5;Database=AdventureWorks;Integrated Security=SSPI;")
cn.Properties("Multiple Connections") = False

The effect of this is as follows. This is similar to ODBC where multiple implicit connections aren’t used and the application gets a ‘connection busy’ error.

Behavior with MARS
Now we’re ready for MARS. In addition to providing a great deal more convenience to the programmer, MARS can reduce server overhead too. Change the connection string to: cn.Open ("Provider=sqlncli;Data Source=.\SQL2K5;MARS Connection=True;Database=AdventureWorks;Integrated Security=SSPI;")

And the code works again, but now the Profiler trace looks like this:

Is MARS all good news, or is there any downside? Well, mostly MARS is good news. The downsides are twofold. First, existing code optimized to run in the non-MARS world may show a slight performance dip when run un-modified with MARS. Default result sets make very efficient use of network resources and adding the MARS capability incurs some additional network overhead. The message here is “if it ain’t broke don’t fix it”, or – as with any feature – you need to design your code to make best use of MARS.

This brings us to the second caveat when using MARS – don’t try to get too smart. With MARS you can send multiple multi-statement batches to the server. The server will interleave execution of such batches, which means that if the batches change server state via SET or USE statements, for example, or use TSQL transaction management statements (BEGIN TRAN, COMMIT, ROLLBACK), both you and the server can get confused about what your actual intent is. The outcome may be an error, or it may be that the application doesn’t behave as you expected it to. It is because of these potential difficulties when MARS is ‘over used’, that we decided to turn it off by default rather than have it enabled by default, as it was for Beta 2.

Without MARS you can only execute one multi-statement batch at a time, which results in completely predictable performance. Stay with this model with MARS – but of course with the relaxation that you can execute multiple single statement queries and have their result sets pending at the point at which you execute your multi-statement batch – and you’ll stay out of trouble. This model is all that most people want and expect to do with MARS anyway.

It’s likely that the first thing you’ll want to try with MARS is convert server cursors to default result sets. Is this the right thing to do? If the result set is fairly small, or will be consumed in its entirety fairly quickly and you don’t require locking on rows in the result set and you haven’t optimized your code to use block fetches, then conversion to a default result set with MARS will be beneficial. If you’re not going to process all the rows in a result set, or the result set is very large and will not be read quickly, or you need locking or scrolling, then you should stay with a server cursor.

There are some other considerations you need to take into account. Firstly, you can’t begin a transaction when you have a default result set open. Secondly, if you commit or rollback a transaction any open default result sets become unavailable (attempts to use them result in errors). These restrictions are the same whether you use MARS or not, although the error messages are different in some cases. If you need ‘Preserve On Commit’ behavior, then you must use a server cursor.

Using MARS from ODBC and OLE DB
To use MARS with ODBC the connection string addition is “MARS_Connection=yes”, or you can a connection attribute as follows:
SQLSetConnectAttr(hdbc, SQL_COPT_SS_MARS_ENABLED,SQL_MARS_ENABLED_YES, SQL_IS_UINTEGER);
before calling SQLDriverConnect or SQLBrowseConnect. With OLE DB, the provider string addition for IDBInitialize::Initialize is “MarsConn=yes”, or “MARS Connection=true” if you use an initialization string with IDataInitialize::GetDataSource. You can also enable MARS programmatically as follows:

IDBInitialize *pIDBInitialize = NULL;
IDBProperties *pIDBProperties = NULL;
// Create the data source object.
hr = CoCreateInstance(CLSID_SQLNCLI, NULL, CLSCTX_INPROC_SERVER,IID_IDBInitialize, (void**)&pIDBInitialize);
hr = pIDBInitialize->QueryInterface(IID_IDBProperties, (void**)&pIDBProperties);

// Set the MARS property.
DBPROP rgPropMARS;
IDBProperties rgPropMARS.dwPropertyID = SSPROP_INIT_MARSCONNECTION;
rgPropMARS.dwOptions = DBPROPOPTIONS_REQUIRED;
rgPropMARS.dwStatus = DBPROPSTATUS_OK;
rgPropMARS.colid = DB_NULLID;
V_VT(&(rgPropMARS.vValue)) = VT_BOOL;
V_BOOL(&(rgPropMARS.vValue)) = VARIANT_TRUE;

// Create the structure containing the properties.
DBPROPSET PropSet;
PropSet.rgProperties = &rgPropMARS;
PropSet.cProperties = 1;
PropSet.guidPropertySet = DBPROPSET_SQLSERVERDBINIT;

// Get an IDBProperties pointer and set the initialization properties.
pIDBProperties->SetProperties(1, &PropSet);
pIDBProperties->Release();
// Initialize the data source object.
hr = pIDBInitialize->Initialize();

Conclusion
MARS is a great new feature that fosters a more natural programming style when working with SQL Server 2005, especially if you’ve ever worked with other databases. With ADO and OLE DB your applications will probably require fewer server connections. MARS will be problem free when used sensibly, but you still need to give some thought to the choice between default result sets and server cursors, although you have more flexibility than before.

Chris Lee
Program Manager, DataWorks