db2_set_option

(PECL ibm_db2 >= 1.0.0)

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

描述

db2_set_option(resource $resource, array $options, int $type): bool

为语句资源或连接资源设置选项。无法为结果集资源设置选项。

参数

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 为指定的语句资源关闭延迟准备。

以下新的 i5/OS 选项在 ibm_db2 版本 1.5.1 及更高版本中可用。这些选项仅在 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 ¶

17 年前

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

＋添加注释