From 672758d211010ebab25e0cdc3c390834eaa006d8 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 15 Jan 2013 10:13:25 +0200 Subject: Document SQL Server ROWVERSION support --- NEWS | 4 +++ doc/manual.xhtml | 76 ++++++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 64 insertions(+), 16 deletions(-) diff --git a/NEWS b/NEWS index b07df8b..f436fba 100644 --- a/NEWS +++ b/NEWS @@ -33,6 +33,10 @@ Version 2.2.0 released when commit()/rollback() is called rather than when the transaction instance goes out of scope. + * Support for SQL Server ROWVERSION-based optimistic concurrency. For more + information, refer to Section 18.1.1, "ROWVERSION Support" in the ODB + manual. + Version 2.1.0 * The ODB compiler is now capable of automatically discovering accessor and diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 32a339e..4ffd6ab 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -690,7 +690,13 @@ for consistency. 18Microsoft SQL Server Database - + + + @@ -702,7 +708,7 @@ for consistency. - +
18.1SQL Server Type Mapping
18.1SQL Server Type Mapping + + +
18.1.1ROWVERSION Support
+
18.2SQL Server Database Class
18.3SQL Server Connection and Connection Factory
18.4SQL Server Exceptions
18.5.3Unique Constraint Violations
18.5.4Multi-threaded Windows Applications
18.5.5Affected Row Count and DDL Statements
18.5.6Long Data and Automatically Assigned Object Ids
18.5.6Long Data and Auto Object Ids, ROWVERSION
18.5.7Long Data and By-Value Accessors/Modifiers
@@ -17874,6 +17880,35 @@ t.commit (); For more information, refer to Section 12.7, "Database Type Mapping Pragmas".

+

18.1.1 ROWVERSION Support

+ +

ROWVERSION is a special SQL Server data type that is + automatically incremented by the database server whenever a row + is inserted or updated. As such, it is normally used to implement + optimistic concurrency and ODB provides support for using + ROWVERSION instead of the more portable approach + for optimistic concurrency (Chapter 11, "Optimistic + Concurrency").

+ +

ROWVERSION is a 64-bit value which is mapped by ODB + to unsigned long long. As a result, to use + ROWVERSION for optimistic concurrency we need to + make sure that the version column is of the unsigned long + long type. We also need to explicitly specify that it + should be mapped to the ROWVERSION data type. For + example:

+ + 
+#pragma db object optimistic
+class person
+{
+  ...
+
+  #pragma db version type("ROWVERSION")
+  unsigned long long version_;
+};
+
+

18.2 SQL Server Database Class

The SQL Server database class encapsulates the ODBC @@ -18515,23 +18550,32 @@ namespace odb "Executing Native SQL Statements") function will always return zero for such statements.

-

18.5.6 Long Data and Automatically Assigned Object Ids

+

18.5.6 Long Data and Auto Object Ids, ROWVERSION

SQL Server 2005 has a bug that causes it to fail on an INSERT - statement with the OUTPUT clause (used to return - automatically assigned object ids) if one of the inserted columns + or UPDATE statement with the OUTPUT clause + (used to return automatically assigned object ids as well as + ROWVERSION values) if one of the inserted columns is long data. The symptom of this bug in ODB is an exception thrown - by the database::persist() function when used on an - object that contains long data and has an automatically assigned - object id. The error message reads "This operation conflicts with - another pending operation on this transaction. The operation failed."

- -

ODB includes a workaround for this bug which uses a less efficient - method to obtain automatically assigned object ids for objects that - contain long data. To enable this workaround you need to specify - that the generated code will be used with SQL Server 2005 or later - by passing the --mssql-server-version 9.0 ODB - compiler option.

+ by the database::persist() or database::update() + function when used on an object that contains long data and has an + automatically assigned object id or uses ROWVERSION-based + optimistic concurrency (Section 18.1.1, + "ROWVERSION Support"). The error message reads "This + operation conflicts with another pending operation on this transaction. + The operation failed."

+ +

For automatically assigned object ids ODB includes a workaround for + this bug which uses a less efficient method to obtain id values for + objects that contain long data. To enable this workaround you need + to specify that the generated code will be used with SQL Server 2005 + or later by passing the --mssql-server-version 9.0 + ODB compiler option.

+ +

For ROWVERSION-based optimistic concurrency no workaround + is currently provided. The ODB compiler will issue an error for + objects that use ROWVERSION for optimistic concurrency + and containing long data.

18.5.7 Long Data and By-Value Accessors/Modifiers

-- cgit v1.1