譯者注：譯者部落格(http://blog.csdn.net/lin_strong)，轉載請保留這條。此為_mssql模組version2.1.4官方文件的翻譯，僅供學習交流使用，請勿用於商業用途。

模組級符號

_mssql.version

見 pymssql.version.

_mssql.VERSION

見 pymssql.VERSION.
這是版本 2.2.0. 中新加的特性。

_mssql.full_version

見 pymssql.full_version.

你可以修改其值以改變全域性行為的變數：

_mssql.login_timeout

用秒錶示的連線和登入超時時間，預設60秒。

_mssql.min_error_severity

丟擲異常的最小錯誤等級。預設值6在大部分情況下應該是合適的。

函式

_mssql.set_max_connections(number)

設定同一時刻處於開啟狀態的連結的最大數量。預設25。

_mssql.get_max_connections()

獲取同一時刻處於開啟狀態的連結的最大數量。

MSSQLConnection 類

class _mssql.MSSQLConnection

這個類代表一個MS SQL資料庫連結。你可以通過資料庫連結發出queries並獲取結果。

你可以通過呼叫_mssql.connect()來建立這個類的一個例項。它接收以下引數。注意，除了位置定位的引數外，你還可以使用關鍵字引數。

SET ARITHABORT ON;
SET CONCAT_NULL_YIELDS_NULL ON;
SET ANSI_NULLS ON;
SET ANSI_NULL_DFLT_ON ON;
SET ANSI_PADDING ON;
SET ANSI_WARNINGS ON;
SET ANSI_NULL_DFLT_ON ON;
SET CURSOR_CLOSE_ON_COMMIT ON;
SET QUOTED_IDENTIFIER ON;
SET TEXTSIZE 2147483647; -- http://msdn.microsoft.com/en-us/library/aa259190%28v=sql.80%29.aspx

版本2.1.1中新特性：conn_properties引數。
版本2.1.1的變化：在2.1.1之前，現在由conn_properties指定的初始化請求不是可定製的，其值硬編碼為以上文字。
版本2.1.1中新特性: 能連線Azure。
版本2.2.0的變化: 引數tds_version的預設值變為了None。在版本2.0.0與版本2.1.2之間，其預設值為’7.1’。

警告：

引數tds_version的預設值為None。這意味著：
1 .你不能依賴於舊的預設值’7.1’。
2 .你得做以下其中一件事：
· 通過傳遞值給這個引數直接指定它的值，或者
· 使用FreeTDS提供的方法配置它
可能這看起來很麻煩，但同時意味著你可以使用pymssql/_mssql完整地配置連結的特性，而不用再管freetds.conf了。從版本2.0.0到版本2.1.2，已經可以設定連線到伺服器時請求的TDS協議版本了，但如果沒有指定的話，則使用版本7.1。

警告：

FreeTDS在版本0.95中添加了對TDS協議版本7.3的支援。如果你知道由pymssql使用的底層FreeTDS的版本是0.91的話，要小心不要要求TDS7.3，因為這即不會引發任何錯誤也沒有機制阻止你傳遞這個無效值。

警告：

FreeTDS在版本0.95中添加了對TDS協議版本7.3的支援。如果你知道由pymssql使用的底層FreeTDS的版本更舊的話，要小心不要要求TDS7.3，因為這即不會引發任何錯誤也沒有機制阻止你傳遞這個無效值。

屬性

MSSQLConnection.connected

如果connection物件擁有一個已經開啟的資料庫連結則為True，否則為False。

MSSQLConnection.charset

傳遞給_mssql.connect()的字符集名。

MSSQLConnection.identity

返回上一個插入的行的標識值。如果之前的操作沒涉及向帶有標識列的表中插入行，則返回None。用例 - 假設persons表包含一個標識列加上一個name列：

conn.execute_non_query("INSERT INTO persons (name) VALUES('John Doe')")
print "Last inserted row has id = " + conn.identity

MSSQLConnection.query_timeout

用秒錶示的query超時時間，預設為0，0的意思是無限等待。由於DB庫的工作方式，設定這個屬性會影響所有從當前Python指令碼開啟的連結(或從技術上說，所有從這個dbinit()例項建立的連結) 。

MSSQLConnection.rows_affected

上一個query所影響的行數。對於SELECT語句，只有在讀了所有行後這個值才有意義。

MSSQLConnection.debug_queries

如果設為true，所有query都會在格式化並完成引數引用後列印到stderr，然後才傳送給SQL伺服器。如果你懷疑格式化或引數引用上出了問題的話，這應該會有幫助。

MSSQLConnection.tds_version

這個連結使用的TDS版本。可能為4.2、5.0、7.0、 7.1、7.2、7.3，或者如果沒有探測到任何TDS版本的話為None。
版本2.1.4的變化：為了正確性和一致性，在pymssql2.1.4中，用於指示TDS 7.1的值從8.0改為了7.1。
版本2.1.3的變化：加入了7.3這個選項。

MSSQLConnection.tds_version_tuple

這是版本 2.2.0. 中新加的特性。
元組形式的這條連結使用的TDS 版本，這樣在程式中更容易處理(轉換、比較)。可能為(4, 2)、 (5, 0)、 (7, 0)、 (7, 1)、 (7, 2)、 (7, 3) 或者如果沒有探測到任何TDS版本的話為None。
版本2.1.3的變化：加入了7.3這個選項。

方法

MSSQLConnection.cancel()

取消所有從上個SQL操作以來掛起的結果。可以在同一行上多次呼叫。這種情況下不會丟擲異常。

MSSQLConnection.close()

關閉連結並釋放所有記憶體。可以在同一行上多次呼叫。這種情況下不會丟擲異常。

MSSQLConnection.execute_query(query_string)
MSSQLConnection.execute_query(query_string, params)

這個方法傳送一條query給這個物件例項所連線的MS SQL資料庫。當失敗時會丟擲一條異常。如果在執行這個命令之前有掛起的結果或者行，它們會被默默地丟掉。
在呼叫這個方法之後，你可以迭代這個連結物件來獲取query返回的行。
你可以使用Python格式化，所有值都會被合理地引用。
這個方法應該用於會返回結果的query，即SELECT。

MSSQLConnection.execute_non_query(query_string)
MSSQLConnection.execute_non_query(query_string, params)

這個方法傳送一條query給這個物件例項所連線的MS SQL資料庫。它的結果(如果有)會被拋棄。當失敗時會丟擲一條異常。如果在執行這個命令之前有掛起的結果或者行，它們會被默默地丟掉。
你可以使用Python格式化，所有值都會被合理地引用。
這個方法很適合INSERT、 UPDATE、 DELETE和資料定義語言(Data Definition Language)，即當你想改變你的資料庫的schema時。

MSSQLConnection.execute_scalar(query_string)
MSSQLConnection.execute_scalar(query_string, params)

這個方法傳送一條query給這個物件例項所連線的MS SQL資料庫，然後返回結果的首行首列。當失敗時會丟擲一條異常。如果在執行這個命令之前有掛起的結果或者行，它們會被默默地丟掉。
你可以使用Python格式化，所有值都會被合理地引用。
如果你的query只返回一個值的話，這個方法就很有用了，如下例所示。這個方法的工作方式相當於iter(conn).next()[0]。如果還有剩下的行的話，你還是可以在呼叫這條命令後進行迭代。

count = conn.execute_scalar("SELECT COUNT(*) FROM employees")

MSSQLConnection.execute_row(query_string)
MSSQLConnection.execute_row(query_string, params)

這個方法傳送一條query給這個物件例項所連線的MS SQL資料庫，然後返回結果的首行。當失敗時會丟擲一條異常。如果在執行這個命令之前有掛起的結果或者行，它們會被默默地丟掉。
你可以使用Python格式化，所有值都會被合理地引用。
如果你的query只返回一行並且不想或不需要迭代連結物件的話，這個方法就很有用了。這個方法的工作方式相當於iter(conn).next()。如果還有剩下的行的話，你還是可以在呼叫這條命令後進行迭代。

empinfo = conn.execute_row("SELECT * FROM employees WHERE empid=10")

MSSQLConnection.get_header()

這個方法是一個基礎函式，不需要由你的程式碼呼叫。它獲取遵從Python DB-API的頭資訊。返回一個描述當前結果頭的一個有7個元素的元組。只填充了名字和遵從的DB-API型別，剩下的都是None，這是規範許可的。

MSSQLConnection.init_procedure(name)

建立一個MSSQLStoredProcedure物件，用於呼叫名字由name指定的儲存過程。

MSSQLConnection.nextresult()

移到下一個結果集，跳過所有掛起的結果。這個方法獲取並拋棄當前操作剩下的所有行，然後移到下一個結果(如果有的話)。如果有下一個結果集，則返回True，否則返回None。當失敗時會丟擲一條異常。

MSSQLConnection.select_db(dbname)

這個函式把指定資料庫變為當前資料庫。當失敗時會丟擲一條異常。

MSSQLConnection.iter()
MSSQLConnection.next()

這是版本 2.1.0. 中新加的特性。
這兩方法實現了Python迭代器協議。很可能你不會直接，而是間接使用迭代器呼叫它。

MSSQLConnection.set_msghandler(handler)

這是版本 2.1.1. 中新加的特性。

這個方法為連結設定一個訊息handler函式，這樣客戶端就可以訪問從伺服器返回的資訊了。
傳遞給這個方法的訊息handler函式的簽名應該是這樣的：

def my_msg_handler(msgstate, severity, srvname, procname, line, msgtext):
    # The body of the message handler.

msgstate、severity和line是整型值；srvname、procname和msgtext是字串.

MSSQLStoredProcedure 類

class _mssql.MSSQLStoredProcedure

這個類代表一個儲存過程。你可以通過呼叫MSSQLConnection物件上的init_procedure()方法來建立這個類的一個例項。

屬性

MSSQLStoredProcedure.connection

底層的MSSQLConnection物件。

這個物件代表的儲存過程的名字。

MSSQLStoredProcedure.parameters

繫結到這個儲存過程的引數們。

方法

MSSQLStoredProcedure.bind(value, dbtype, name=None, output=False, null=False, max_length=-1)

這個方法繫結一個引數到儲存過程。value和dbtype是強制的，剩下的都是可選的。

MSSQLStoredProcedure.execute()

執行這個儲存過程。

模組級異常

異常繼承樹：

MSSQLException
|
+-- MSSQLDriverException
|
+-- MSSQLDatabaseException

exception _mssql.MSSQLDriverException

只要_mssql內部發生了問題，就會丟擲MSSQLDriverException – 如資料結構的記憶體不足等。

exception _mssql.MSSQLDatabaseException

只要資料庫發生了問題，就會丟擲MSSQLDatabaseException – 如query語法錯誤、無效物件名等。這種情況下，你可以使用以下屬性來獲得錯誤細節：
number：錯誤碼，是由SQL伺服器返回的。
severity：嚴重級別，是由SQL伺服器返回的。如果這個屬性的值低於_mssql.min_error_severity的值，這個錯誤會被忽略，不會丟擲異常。
state：第三個錯誤碼，是由SQL伺服器返回的。
message：錯誤資訊，是由SQL伺服器返回的。