db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — 设置连接或语句资源的选项

描述

db2_set_option(资源 $resource, 数组 $options, 整数 $type): 布尔值

设置语句资源或连接资源的选项。不能为结果集资源设置选项。

参数

resource

来自 db2_prepare() 的有效语句资源，或来自 db2_connect() 或 db2_pconnect() 的有效连接资源。

options

包含有效语句或连接选项的关联数组。此参数可用于更改自动提交值、游标类型（可滚动或向前），以及指定结果集中显示的列名的大小写（小写、大写或自然）。

autocommit

传递 DB2_AUTOCOMMIT_ON 将为指定的连接资源打开自动提交。

传递 DB2_AUTOCOMMIT_OFF 将为指定的连接资源关闭自动提交。

cursor

传递 DB2_FORWARD_ONLY 为语句资源指定一个只向前游标。这是默认游标类型，所有数据库服务器都支持。

传递 DB2_SCROLLABLE 为语句资源指定一个可滚动游标。可滚动游标允许以非顺序方式访问结果集行，但仅受 IBM DB2 通用数据库的支持。

binmode

传递 DB2_BINARY 指定二进制数据将按原样返回。这是默认模式。这相当于在 php.ini 中设置 ibm_db2.binmode=1。

传递 DB2_CONVERT 指定二进制数据将转换为十六进制编码，并将按此方式返回。这相当于在 php.ini 中设置 ibm_db2.binmode=2。

传递 DB2_PASSTHRU 指定二进制数据将转换为 null。这相当于在 php.ini 中设置 ibm_db2.binmode=3。

db2_attr_case

传递 DB2_CASE_LOWER 指定结果集的列名以小写形式返回。

传递 DB2_CASE_UPPER 指定结果集的列名以大写形式返回。

传递 DB2_CASE_NATURAL 指定结果集的列名以自然大小写形式返回。

deferred_prepare

传递 DB2_DEFERRED_PREPARE_ON 将为指定的语句资源打开延迟准备。

传递 DB2_DEFERRED_PREPARE_OFF 将为指定的语句资源关闭延迟准备。

ibm_db2 1.5.1 及更高版本中提供以下新的 i5/OS 选项。这些选项仅在 PHP 和 ibm_db2 在 i5 系统上原生运行时适用。

i5_fetch_only

DB2_I5_FETCH_ON - 游标是只读的，不能用于定位更新或删除。这是默认值，除非 SQL_ATTR_FOR_FETCH_ONLY 环境变量已设置为 SQL_FALSE。

DB2_I5_FETCH_OFF - 游标可用于定位更新和删除。

ibm_db2 1.8.0 及更高版本中提供以下新选项。

rowcount

DB2_ROWCOUNT_PREFETCH_ON - 客户端可以在获取之前请求完整的行数，这意味着即使使用 ROLLFORWARD_ONLY 游标，db2_num_rows() 也会返回已选择行的数量。

DB2_ROWCOUNT_PREFETCH_OFF - 客户端无法在获取之前请求完整的行数。

ibm_db2 1.7.0 及更高版本中提供以下新选项。

trusted_user: 要将用户切换到受信任用户，请将受信任用户的用户 ID（字符串）作为此键的值传递。此选项只能在连接资源上设置。要使用此选项，必须在连接资源上启用受信任上下文。
trusted_password: 与 trusted_user 键指定的用户相对应的密码（字符串）。

ibm_db2 1.6.0 及更高版本中提供以下新选项。这些选项提供有用的跟踪信息，可以使用 db2_get_option() 在执行期间访问。

注意:
设置每个选项的值时，某些服务器可能无法处理提供的全部长度，并可能截断该值。

为确保在将数据传输到主机系统时每个选项中指定的数据正确转换，请仅使用 A 到 Z、0 到 9 和下划线 (_) 或句点 (.) 字符。

userid

SQL_ATTR_INFO_USERID - 指向空终止字符字符串的指针，用于标识使用 DB2 Connect 时发送到主机数据库服务器的客户端用户 ID。

注意:
DB2 for z/OS 和 OS/390 服务器支持的最大长度为 16 个字符。此用户 ID 不要与身份验证用户 ID 混淆，它仅用于标识目的，不用于任何授权。

acctstr

SQL_ATTR_INFO_ACCTSTR - 指向空终止字符字符串的指针，用于标识使用 DB2 Connect 时发送到主机数据库服务器的客户端计费字符串。

注意:
DB2 for z/OS 和 OS/390 服务器支持的最大长度为 200 个字符。

applname

SQL_ATTR_INFO_APPLNAME - 指向空终止字符字符串的指针，用于标识使用 DB2 Connect 时发送到主机数据库服务器的客户端应用程序名称。

注意:
DB2 for z/OS 和 OS/390 服务器支持的最大长度为 32 个字符。

wrkstnname

SQL_ATTR_INFO_WRKSTNNAME - 指向空终止字符字符串的指针，用于标识使用 DB2 Connect 时发送到主机数据库服务器的客户端工作站名称。

注意:
DB2 for z/OS 和 OS/390 服务器支持的最大长度为 18 个字符。

type

指定传递到函数的资源类型的整数值。资源类型和此值必须对应。

将 1 作为值传递指定已将连接资源传递到函数中。

将任何不等于 1 的整数作为值传递指定已将语句资源传递到函数中。

下表指定哪些选项与可用的资源类型兼容

**资源-参数矩阵**
键	值	资源类型
		连接	语句	结果集
autocommit	`DB2_AUTOCOMMIT_ON`	X	-	-
autocommit	`DB2_AUTOCOMMIT_OFF`	X	-	-
cursor	`DB2_SCROLLABLE`	-	X	-
cursor	`DB2_FORWARD_ONLY`	-	X	-
binmode	`DB2_BINARY`	X	X	-
binmode	`DB2_CONVERT`	X	X	-
binmode	`DB2_PASSTHRU`	X	X	-
db2_attr_case	`DB2_CASE_LOWER`	X	X	-
db2_attr_case	`DB2_CASE_UPPER`	X	X	-
db2_attr_case	`DB2_CASE_NATURAL`	X	X	-
deferred_prepare	`DB2_DEFERRED_PREPARE_ON`	-	X	-
deferred_prepare	`DB2_DEFERRED_PREPARE_OFF`	-	X	-
i5_fetch_only	`DB2_I5_FETCH_ON`	-	X	-
i5_fetch_only	`DB2_I5_FETCH_OFF`	-	X	-
rowcount	`DB2_ROWCOUNT_PREFETCH_ON`	-	X	-
rowcount	`DB2_ROWCOUNT_PREFETCH_OFF`	-	X	-
trusted_user	`<用户名> (字符串)`	X	-	-
trusted_password	`<密码> (字符串)`	X	-	-
userid	`SQL_ATTR_INFO_USERID`	X	X	-
acctstr	`SQL_ATTR_INFO_ACCTSTR`	X	X	-
applname	`SQL_ATTR_INFO_APPLNAME`	X	X	-
wrkstnname	`SQL_ATTR_INFO_WRKSTNNAME`	X	X	-

返回值

成功返回 true，失败返回 false。

示例

示例 #1 使用连接资源设置单个参数

<?php
/* 数据库连接参数 */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 连接字符串 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 获取连接资源 */
$conn = db2_connect($conn_string, '', '');

/* 创建包含有效键值对的关联数组 */
$options = array('autocommit' => DB2_AUTOCOMMIT_ON);

/* 使用正确的资源、选项数组和类型值调用函数 */
$result = db2_set_option($conn, $options, 1);

/* 检查是否所有选项都已正确设置 */
if($result)
{
 echo '选项设置成功';
}
else
{
 echo '无法设置选项';
}
?>

以上示例将输出

Options Set Successfully

示例 #2 使用连接资源设置多个参数

<?php
/* 数据库连接参数 */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 连接字符串 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 获取连接资源 */
$conn = db2_connect($conn_string, '', '');

/* 创建包含有效键值对的关联数组 */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
 'binmode' => DB2_PASSTHRU,
 'db2_attr_case' => DB2_CASE_UPPER,
 'cursor' => DB2_SCROLLABLE);

/* 使用正确的资源、选项数组和类型值调用函数 */
$result = db2_set_option($conn, $options, 1);

/* 检查是否所有选项都已正确设置 */
if($result)
{
 echo '选项设置成功';
}
else
{
 echo '无法设置选项';
}
?>

以上示例将输出

Options Set Successfully

示例 #3 使用无效键设置多个参数

<?php
/* 数据库连接参数 */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 连接字符串 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 获取连接资源 */
$conn = db2_connect($conn_string, '', '');

/* 创建包含有效键值对的关联数组 */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
 'MY_INVALID_KEY' => DB2_PASSTHRU,
 'db2_attr_case' => DB2_CASE_UPPER,
 'cursor' => DB2_SCROLLABLE);

/* 使用正确的资源、选项数组和类型值调用函数 */
$result = db2_set_option($conn, $options, 1);

/* 检查是否所有选项都已正确设置 */
if($result)
{
 echo '选项设置成功';
}
else
{
 echo '无法设置选项';
}
?>

以上示例将输出

Could Not Set Options

示例 #4 使用无效值设置多个参数

<?php
/* 数据库连接参数 */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 连接字符串 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 获取连接资源 */
$conn = db2_connect($conn_string, '', '');

/* 创建包含有效键值对的关联选项数组 */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
 'binmode' => 'INVALID_VALUE',
 'db2_attr_case' => DB2_CASE_UPPER,
 'cursor' => DB2_SCROLLABLE);

/* 使用正确的资源、选项数组和类型值调用函数 */
$result = db2_set_option($conn, $options, 1);

/* 检查是否所有选项都设置正确 */
if($result)
{
 echo '选项设置成功';
}
else
{
 echo '无法设置选项';
}
?>

以上示例将输出

Could Not Set Options

示例 #5 使用连接资源和错误的类型设置多个参数

<?php
/* 数据库连接参数 */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 连接字符串 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 获取连接资源 */
$conn = db2_connect($conn_string, '', '');

/* 创建包含有效键值对的关联选项数组 */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
 'binmode' => DB2_PASSTHRU,
 'db2_attr_case' => DB2_CASE_UPPER,
 'cursor' => DB2_SCROLLABLE);

/* 使用正确的资源、选项数组和错误的类型值调用函数 */
$result = db2_set_option($conn, $options, 2);

/* 检查是否所有选项都设置正确 */
if($result)
{
 echo '选项设置成功';
}
else
{
 echo '无法设置选项';
}
?>

以上示例将输出

Could Not Set Options

示例 #6 使用错误的资源设置多个参数

<?php
/* 数据库连接参数 */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 连接字符串 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 获取连接资源 */
$conn = db2_connect($conn_string, '', '');

/* 创建包含有效键值对的关联选项数组 */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
 'binmode' => DB2_PASSTHRU,
 'db2_attr_case' => DB2_CASE_UPPER,
 'cursor' => DB2_SCROLLABLE);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

/* 使用错误的资源、正确的选项数组和类型值调用函数 */
$result = db2_set_option($stmt, $options, 1);

/* 检查是否所有选项都设置正确 */
if($result)
{
 echo '选项设置成功';
}
else
{
 echo '无法设置选项';
}
?>

以上示例将输出

Could Not Set Options

示例 #7 集成所有内容

<?php
/* 数据库连接参数 */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 连接字符串 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 获取连接资源 */
$conn = db2_connect($conn_string, '', '');

/* 创建包含有效键值对的关联数组 */
$options = array('db2_attr_case' => DB2_CASE_LOWER,
 'cursor' => DB2_SCROLLABLE);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

/* 使用正确的资源、选项数组和类型值调用函数 */
$option_result = db2_set_option($stmt, $options, 2);
$result = db2_execute($stmt, array('000130', '000140'));

/* 由于可滚动游标，先获取第 2 行，再获取第 1 行 */
print_r(db2_fetch_assoc($stmt, 2));
print '<br /><br />';
print_r(db2_fetch_assoc($stmt, 1));

?>

以上示例将输出

Array
(
    [empno] => 000140
    [firstnme] => HEATHER
    [midinit] => A
    [lastname] => NICHOLLS
    [workdept] => C01
    [phoneno] => 1793
    [hiredate] => 1976-12-15
    [job] => ANALYST
    [edlevel] => 18
    [sex] => F
    [birthdate] => 1946-01-19
    [salary] => 28420.00
    [bonus] => 600.00
    [comm] => 2274.00
)

Array
(
    [empno] => 000130
    [firstnme] => DELORES
    [midinit] => M
    [lastname] => QUINTANA
    [workdept] => C01
    [phoneno] => 4578
    [hiredate] => 1971-07-28
    [job] => ANALYST
    [edlevel] => 16
    [sex] => F
    [birthdate] => 1925-09-15
    [salary] => 23800.00
    [bonus] => 500.00
    [comm] => 1904.00
)

示例 #8 i5/OS 游标是只读的

<?php
 $conn = db2_connect("", "", "", array("i5_lib"=>"nobody"));
 $stmt = db2_prepare($conn, 'select * from names where first = ?');
 $name = "first2";
 db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
 $options = array("i5_fetch_only"=>DB2_I5_FETCH_ON);
 db2_set_option($stmt,$options,0);
 if (db2_execute($stmt)) {
 while ($row = db2_fetch_array($stmt)) {
 echo "{$row[0]} {$row[1]}";
 }
 }
?>

以上示例将输出

first2 last2

参见

db2_connect() - 返回数据库连接
db2_pconnect() - 返回持久数据库连接
db2_exec() - 直接执行 SQL 语句
db2_prepare() - 准备要执行的 SQL 语句
db2_cursor_type() - 返回语句资源使用的游标类型

发现问题？

了解如何改进此页面 • 提交拉取请求 • 报告错误

＋添加注释

用户贡献的注释 1 条注释

上

下

-1

rtejpar at ca dot ibm dot com ¶

18 年前

示例 3 和 4 应该输出“选项设置成功”。这是因为，只有一个选项的键/值设置不正确（其他选项仍然正确），因此函数必须成功返回。（相反，很可能会发出 PHP 警告）。

＋添加注释