常數 (Microsoft Drivers for PHP for SQL Server)

下載 PHP 驅動程式

本主題討論 Microsoft Drivers for PHP for SQL Server 所定義的常數。

PDO_SQLSRV 驅動程式常數

PDO 網站上所列的常數在 Microsoft Drivers for PHP for SQL Server 中有效。

以下描述 PDO_SQLSRV 驅動程式中的 Microsoft 特定常數。

交易隔離等級常數

TransactionIsolation 索引鍵,可與 PDO::__construct搭配使用,並接受下列其中一個常數:

  • PDO::SQLSRV_TXN_READ_UNCOMMITTED

  • PDO::SQLSRV_TXN_READ_COMMITTED

  • PDO::SQLSRV_TXN_REPEATABLE_READ

  • PDO::SQLSRV_TXN_SNAPSHOT

  • PDO::SQLSRV_TXN_SERIALIZABLE

如需 TransactionIsolation 索引鍵的詳細資訊,請參閱 Connection Options。

輸入字串宣告常數

這些常數僅適用於 PDO_SQLSRV,不適用於 SQLSRV。

常數 Purpose
PDO::SQLSRV_ATTR_PARAM_METADATA 包含從 1 為基礎位置或唯一參數名稱到宣告陣列的對應的語句屬性。 在 prepare 之後設定它。
PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH 控制新語句初始自適應字串長度的連線屬性。 接受 0 到 8,000 的整數;預設值 0 會停用自適應大小設定。
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE SQL 字串類型的必填宣告金鑰。
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH SQL 長度所需的宣告金鑰。
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR 宣告 varchar。 有界長度為 1 到 8,000 位元組。
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR 宣告 nvarchar。 有界長度為 1 到 4,000 個 UTF-16 編碼單位。
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH_MAX 宣告所選類型及其 max 長度。

關於中繼資料形狀、編碼、優先順序、範例及限制,請參閱 「宣告輸入字串類型與長度 (PDO_SQLSRV)」。

編碼常數

PDO::SQLSRV_ATTR_ENCODING 屬性可以傳遞至 PDOStatement::setAttribute、PDO::setAttribute、PDO::prepare、PDOStatement::bindColumn 和 PDOStatement::bindParam。

可傳遞至 PDO::SQLSRV_ATTR_ENCODING 的值為

PDO_SQLSRV 驅動程式常數 描述
PDO::SQLSRV_ENCODING_BINARY 資料是來自伺服器的原始位元組資料流,未執行編碼或轉譯。

對 PDO::setAttribute 而言無效。
PDO::SQLSRV_ENCODING_SYSTEM 資料是 8 位元字元,如同在系統上設定之 Windows 地區設定的字碼頁所指定。 任何多位元組字元或無法對應到此字碼頁的字元,都會以單一位元組的問號 (?) 字元取代。
PDO::SQLSRV_ENCODING_UTF8 資料採用 UTF-8 編碼。 這是預設編碼。
PDO::SQLSRV_ENCODING_UTF8_VARCHAR 資料採用 UTF-8 編碼,且沒有明確 SQL 型別的字串參數會以 varchar 而非 nvarchar 傳送。 讀取回傳 UTF-8。 新增於 5.14.0 版本。 關於需求與優先順序規則,請參閱將 UTF-8 字串作為 varchar 參數傳送。
PDO::SQLSRV_ENCODING_DEFAULT 如果在連線時指定,則會使用 PDO::SQLSRV_ENCODING_SYSTEM。

若已在準備陳述式中指定編碼,則使用連線的編碼。

查詢逾時

PDO::SQLSRV_ATTR_QUERY_TIMEOUT 屬性是任何代表逾時期間 (秒) 的非負數整數。 零 (0) 預設值,表示沒有逾時。

您可以使用 PDOStatement::setAttribute、PDO::setAttribute 和 PDO::prepare 來指定 PDO::SQLSRV_ATTR_QUERY_TIMEOUT 屬性。

直接或預備執行

您可以使用 PDO::SQLSRV_ATTR_DIRECT_QUERY 屬性,選取直接查詢執行或備妥的陳述式執行。 PDO::SQLSRV_ATTR_DIRECT_QUERY 可以用 PDO::prepare 或 PDO::setAttribute 來設定。 如需 PDO::SQLSRV_ATTR_DIRECT_QUERY 的詳細資訊,請參閱 PDO_SQLSRV 驅動程式中的直接陳述式執行和已備妥的陳述式執行。

處理數值擷取

PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE 屬性可用來處理從採用數值 SQL 類型 (bit、integer、smallint、tinyint、float 和 real) 的資料行擷取數值資料。 當 PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE 設定為 true 時,來自整數資料行的結果會表示為 ints,而 SQL 浮點數和實數表示為浮點數。 此屬性可以使用 PDOStatement::setAttribute 來設定。

你可以用 PDO::SQLSRV_ATTR_FORMAT_DECIMALS 和 PDO::SQLSRV_ATTR_DECIMAL_PLACES 屬性來修改預設的十進位格式行為。 這些屬性的行為與 SQLSRV 端對應的選項(FormatDecimals 與 DecimalPlaces)相同,但格式化時不支援輸出參數。 您可以使用 PDO::setAttribute 或 PDOStatement::setAttribute,在連線或陳述式等級設定這些屬性,但任何陳述式屬性都會覆寫對應的連線屬性。 如需詳細資訊,請參閱將十進位字串及貨幣值格式化 (PDO_SQLSRV 驅動程式)。

處理日期與時間擷取作業

PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE 指定是否要以 PHP DateTime \(英文\) 物件形式擷取日期和時間類型。 如果保留 false,則預設行為是以字串形式傳回它們。 這個屬性可以在連線或陳述式等級使用 PDO::setAttribute 或 PDOStatement::setAttribute 來設定,但是陳述式屬性將會覆寫對應的連線屬性。 如需詳細資訊,請參閱如何:使用 PDO_SQLSRV 驅動程式以 PHP DateTime 物件形式擷取日期和時間類型。

SQLSRV 驅動程式常數

下列各節列出 SQLSRV 驅動程式所使用的常數。

ERR 常數

下表列出用來指定 sqlsrv_errors 會傳回錯誤、警告還是兩者都傳回的常數。

值 描述
SQLSRV_ERR_ALL 傳回上次呼叫 sqlsrv 函數時產生的錯誤和警告。 這是預設值。
SQLSRV_ERR_ERRORS 傳回上次呼叫 sqlsrv 函數時產生的錯誤。
SQLSRV_ERR_WARNINGS 傳回上次呼叫 sqlsrv 函數時產生的警告。

FETCH 常數

下表列出用來指定 sqlsrv_fetch_array所傳回之陣列類型的常數。

SQLSRV 常數 描述
SQLSRV_FETCH_ASSOC sqlsrv_fetch_array 會以關聯陣列的形式回傳下一列資料。
SQLSRV_FETCH_BOTH sqlsrv_fetch_array 會以陣列形式回傳下一列的資料,同時包含數值與關聯索引鍵。 這是預設值。
SQLSRV_FETCH_NUMERIC sqlsrv_fetch_array 以數值索引陣列的形式回傳下一列資料。

日誌常數

此節列出用來透過 sqlsrv_configure變更記錄設定的常數。 如需記錄活動的詳細資訊,請參閱 Logging Activity。

下表列出可做為 LogSubsystems 設定值的常數:

SQLSRV 常數(括號中的整數對應值) 描述
SQLSRV_LOG_SYSTEM_ALL(-1) 開啟所有子系統的記錄功能。
SQLSRV_LOG_SYSTEM_CONN(2) 啟用連線活動記錄。
SQLSRV_LOG_SYSTEM_INIT(1) 啟用初始化活動的記錄功能。
SQLSRV_LOG_SYSTEM_OFF (0) 關閉記錄功能。
SQLSRV_LOG_SYSTEM_STMT(4) 啟用陳述活動記錄。
SQLSRV_LOG_SYSTEM_UTIL(8) 啟用錯誤處理函式活動的記錄(例如 handle_error 和 handle_warning)。

下表列出可做為 LogSeverity 設定值的常數:

SQLSRV 常數(括號中的整數對應值) 描述
SQLSRV_LOG_SEVERITY_ALL(-1) 指定將會記錄錯誤、警告和通知。
SQLSRV_LOG_SEVERITY_ERROR (1) 指定將會記錄錯誤。
SQLSRV_LOG_SEVERITY_NOTICE(4) 指定會記錄通知。
SQLSRV_LOG_SEVERITY_WARNING(2) 指定將會記錄警告。

可為 Null 的常數

下表列出可用來判斷資料行是否可為 Null,或該資訊是否無法取得的常數。 您可以比較 sqlsrv_field_metadata 所傳回的 Nullable 索引鍵值,以判斷資料行可為 Null 的狀態。

SQLSRV 常數(括號中的整數對應值) 描述
SQLSRV_NULLABLE_YES (0) 此資料行可為 null。
SQLSRV_NULLABLE_NO (1) 資料欄不可為 NULL。
SQLSRV_NULLABLE_UNKNOWN(2) 不確定資料行是否可接受 Null 值。

PARAM 常數

下列清單包含在您呼叫 sqlsrv_query 或 sqlsrv_prepare時用來指定參數方向的常數。

SQLSRV 常數 描述
SQLSRV_PARAM_IN 表示輸入參數。
SQLSRV_PARAM_INOUT 表示雙向參數。
SQLSRV_PARAM_OUT 表示輸出參數。

PHPTYPE 常數

下表列出用來說明 PHP 資料類型的常數。 如需 PHP 資料類型的資訊,請參閱 PHP 類型。

SQLSRV 常數 PHP 資料類型
SQLSRV_PHPTYPE_INT 整數
SQLSRV_PHPTYPE_DATETIME 日期時間
SQLSRV_PHPTYPE_FLOAT Float
SQLSRV_PHPTYPE_STREAM($encoding1) Stream
SQLSRV_PHPTYPE_STRING($encoding1) 字串

1SQLSRV_PHPTYPE_STREAM 和 SQLSRV_PHPTYPE_STRING 接受指定串流編碼的參數。 下表列出可接受的 SQLSRV 常數,以及對應編碼的說明。

SQLSRV 常數 描述
SQLSRV_ENC_BINARY 資料會以原始位元組資料流形式從伺服器傳回,而不需執行編碼或轉譯。
SQLSRV_ENC_CHAR 資料會以 8 位元字元傳回,這些字元係依照系統上所設定的 Windows 地區設定字碼頁來指定。 任何多位元組字元或無法對應到此字碼頁的字元,都會以單一位元組的問號 (?) 字元取代。

這是預設編碼。
"UTF-8" 資料會以 UTF-8 編碼傳回。 已將此常數新增至 Microsoft Drivers for PHP for SQL Server 1.1 版。 如需 UTF-8 支援的詳細資訊,請參閱如何:使用內建的 UTF-8 支援傳送及接收 UTF-8 資料。
SQLSRV_ENC_UTF8_VARCHAR 資料採用 UTF-8 編碼,且沒有明確 SQL 型別的字串參數會以 varchar 而非 nvarchar 傳送。 讀取時會傳回 UTF-8。 常數的值為字串 "utf-8-varchar"。 新增於 5.14.0 版本。 關於需求與優先順序規則,請參閱 「將 UTF-8 字串作為 varchar 參數傳送」。

注意

當您使用 SQLSRV_PHPTYPE_STREAM 或 SQLSRV_PHPTYPE_STRING 時,必須要指定編碼。 如果未提供參數,將會傳回錯誤。

如需這些常數的詳細資訊,請參閱 如何:指定 PHP 資料類型、 如何:使用 SQLSRV 驅動程式以資料流的形式擷取字元資料。

SQLTYPE 常數

下表列出用來說明 SQL Server 資料類型的常數。 某些常數類似函式,可能接受分別對應於精確度、小數位數及/或長度的參數。 繫結參數時,應該使用類似函式的常數。 針對類型比較,需要標準 (非類似函式) 常數。 關於SQL Server資料型態的資訊,請參見資料型別(Transact-SQL)。 關於精度、比例與長度的資訊,請參見「 精度、比例與長度(Transact-SQL)」。

SQLSRV 常數 SQL Server 資料類型
SQLSRV_SQLTYPE_BIGINT Bigint
SQLSRV_SQLTYPE_BINARY 二進位
SQLSRV_SQLTYPE_BIT 位元
SQLSRV_SQLTYPE_CHAR char5
SQLSRV_SQLTYPE_CHAR($charCount) Char
SQLSRV_SQLTYPE_DATE date4
SQLSRV_SQLTYPE_DATETIME 日期時間
SQLSRV_SQLTYPE_DATETIME2 datetime24
SQLSRV_SQLTYPE_DATETIMEOFFSET datetimeoffset4
SQLSRV_SQLTYPE_DECIMAL decimal5
SQLSRV_SQLTYPE_DECIMAL($precision,$scale) 十進位
SQLSRV_SQLTYPE_FLOAT float
SQLSRV_SQLTYPE_IMAGE image1
SQLSRV_SQLTYPE_INT int
SQLSRV_SQLTYPE_MONEY 金錢
SQLSRV_SQLTYPE_NCHAR nchar5
SQLSRV_SQLTYPE_NCHAR($charCount) NCHAR
SQLSRV_SQLTYPE_NUMERIC numeric5
SQLSRV_SQLTYPE_NUMERIC($precision,$scale) 數值
SQLSRV_SQLTYPE_NVARCHAR nvarchar5
SQLSRV_SQLTYPE_NVARCHAR($charCount) nvarchar
SQLSRV_SQLTYPE_NVARCHAR('max') nvarchar(MAX)
SQLSRV_SQLTYPE_NTEXT ntext2
SQLSRV_SQLTYPE_REAL 真實
SQLSRV_SQLTYPE_SMALLDATETIME smalldatetime
SQLSRV_SQLTYPE_SMALLINT smallint
SQLSRV_SQLTYPE_SMALLMONEY smallmoney
SQLSRV_SQLTYPE_TEXT text3
SQLSRV_SQLTYPE_TIME time4
SQLSRV_SQLTYPE_TIMESTAMP 時間戳記
SQLSRV_SQLTYPE_TINYINT Tinyint
SQLSRV_SQLTYPE_UNIQUEIDENTIFIER 唯一識別碼
SQLSRV_SQLTYPE_UDT UDT
SQLSRV_SQLTYPE_VARBINARY varbinary5
SQLSRV_SQLTYPE_VARBINARY($byteCount) varbinary
SQLSRV_SQLTYPE_VARBINARY('max') varbinary(MAX)
SQLSRV_SQLTYPE_VARCHAR varchar5
SQLSRV_SQLTYPE_VARCHAR($charCount) varchar
SQLSRV_SQLTYPE_VARCHAR('max') varchar(MAX)
SQLSRV_SQLTYPE_XML Xml

1 這是一種舊有型別,對應到 varbinary(max) 型別。

2 這是一個舊有型別,對應到較新的 nvarchar 型別。

3 這是一個舊有型別,對應到較新的 varchar 型態。

4 對此類型的支援是在 Microsoft Drivers for PHP for SQL Server 1.1 版中新增的。

5 這些常數應用於型別比較操作,且不會取代具有類似語法的類函式常數。 對於綁定參數,請使用函數式常數。

下表列出接受參數的 SQLTYPE 常數,以及允許的參數值範圍。

SQLTYPE 參數 允許的參數範圍
SQLSRV_SQLTYPE_CHAR,

SQLSRV_SQLTYPE_VARCHAR
charCount 1 - 8000
SQLSRV_SQLTYPE_NCHAR、

SQLSRV_SQLTYPE_NVARCHAR
charCount 1 - 4000
SQLSRV_SQLTYPE_BINARY,

SQLSRV_SQLTYPE_VARBINARY
byteCount 1 - 8000
SQLSRV_SQLTYPE_DECIMAL、

SQLSRV_SQLTYPE_NUMERIC
精確度 1 - 38
SQLSRV_SQLTYPE_DECIMAL、

SQLSRV_SQLTYPE_NUMERIC
級別 1 - 精確度

交易隔離等級常數

TransactionIsolation 索引鍵,可與 sqlsrv_connect搭配使用,並接受下列其中一個常數:

  • SQLSRV_TXN_READ_UNCOMMITTED

  • SQLSRV_TXN_READ_COMMITTED

  • SQLSRV_TXN_REPEATABLE_READ

  • SQLSRV_TXN_SNAPSHOT

  • SQLSRV_TXN_SERIALIZABLE

游標和捲動常數

下列常數指定您可以在結果集中使用的游標類型:

  • SQLSRV_CURSOR_FORWARD

  • SQLSRV_CURSOR_STATIC

  • SQLSRV_CURSOR_DYNAMIC

  • SQLSRV_CURSOR_KEYSET

  • SQLSRV_CURSOR_CLIENT_BUFFERED

下列常數指定要在結果集內選取的資料列:

  • SQLSRV_SCROLL_NEXT

  • SQLSRV_SCROLL_PRIOR

  • SQLSRV_SCROLL_FIRST

  • SQLSRV_SCROLL_LAST

  • SQLSRV_SCROLL_ABSOLUTE

  • SQLSRV_SCROLL_RELATIVE

如需使用這些常數的相關資訊,請參閱 Specifying a Cursor Type and Selecting Rows。