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 Universal Database 資料庫支援。

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 選項。這些選項僅適用於在 i5 系統上原生執行 PHP 和 ibm_db2 時。

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 - 指向一個以 null 結尾的字串指標，用於識別使用 DB2 Connect 時傳送到主機資料庫伺服器的用戶端使用者 ID。

注意事項:
DB2 for z/OS 和 OS/390 伺服器最多支援 16 個字元。此使用者 ID 與驗證使用者 ID 不同，它僅用於識別目的，不用於任何授權。

acctstr

SQL_ATTR_INFO_ACCTSTR - 指向一個以 null 結尾的字串指標，用於識別使用 DB2 Connect 時傳送到主機資料庫伺服器的用戶端帳戶字串。

注意事項:
DB2 for z/OS 和 OS/390 伺服器最多支援 200 個字元。

applname

SQL_ATTR_INFO_APPLNAME - 指向一個以 null 結尾的字串指標，用於識別使用 DB2 Connect 時傳送到主機資料庫伺服器的用戶端應用程式名稱。

注意事項:
DB2 for z/OS 和 OS/390 伺服器最多支援 32 個字元。

wrkstnname

SQL_ATTR_INFO_WRKSTNNAME - 指向一個以 null 結尾的字串指標，用於識別使用 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 Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');

/* Create the associative options array with valid key-value pairs */
$options = array('db2_attr_case' => DB2_CASE_LOWER,
 'cursor' => DB2_SCROLLABLE);

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

/* Call the function using the correct resource, options array, and type values */
$option_result = db2_set_option($stmt, $options, 2);
$result = db2_execute($stmt, array('000130', '000140'));

/* Get Row 2 before Row 1 since Scrollable Cursor */
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 警告）。

＋新增註釋