常量(Microsoft PHP SQL Server 驱动程序)

下载PHP驱动程序

本主题将讨论 Microsoft Drivers for PHP for SQL Server定义的常量。

PDO_SQLSRV 驱动程序常量

PDO 网站 上列出的常量在 Microsoft Drivers for PHP for SQL Server中有效。

下面介绍 PDO_SQLSRV 驱动程序中的 Microsoft 特定常量。

事务隔离级别常量

可与 PDO::__construct 结合使用的 TransactionIsolation键接受以下常量之一:

  • 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::prepare 或 PDO::setAttribute 来设置 PDO::SQLSRV_ATTR_DIRECT_QUERY。 有关 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,整数列的结果将表示为 int,而 SQL 浮点数和实数则表示为 float。 可以使用 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 的常量

下表列出了可用于确定某列是否可为空,或者此信息是否不可用的常量。 你可以通过比较 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 数据按照系统上设置的 Windows 区域设置的代码页规定,以 8 位字符形式返回。 任何多字节字符或未映射到此代码页中的字符都会替换为单字节问号 (?) 字符。

这是默认编码。
“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 bit
SQLSRV_SQLTYPE_CHAR char5
SQLSRV_SQLTYPE_CHAR($charCount) 字符型
SQLSRV_SQLTYPE_DATE date4
SQLSRV_SQLTYPE_DATETIME 日期/时间
SQLSRV_SQLTYPE_DATETIME2 datetime24
SQLSRV_SQLTYPE_DATETIMEOFFSET datetimeoffset4
SQLSRV_SQLTYPE_DECIMAL 十进制5
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) numeric
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 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
字符数 1 - 8000
SQLSRV_SQLTYPE_NCHAR、

SQLSRV_SQLTYPE_NVARCHAR
字符数 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 - 精度

事务隔离级别常量

用于 sqlsrv_connect 的 TransactionIsolation键接受以下常量之一:

  • 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。