db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — 返回資料庫連線

說明

db2_connect(
    字串 $database,
    ?字串 $username,
    ?字串 $password,
    陣列 $options = []
): 資源|false

建立與 IBM DB2 Universal Database、IBM Cloudscape 或 Apache Derby 資料庫的新連線。

參數

database（資料庫）

對於已編目與資料庫的連線，database 表示 DB2 用戶端目錄中的資料庫別名。

對於未編目與資料庫的連線，database 表示以下格式的完整連線字串

DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

注意事項:
連線到 IBM i 上的 Db2 時，底層系統會呼叫 » SQLDriverConnect，它只接受 DSN、UID 和 PWD 作為 » 連線字串。像這樣
DSN=database;UID=username;PWD=password;

其中參數代表下列值

database（資料庫）: 資料庫的名稱。
hostname（主機名稱）: 資料庫伺服器的主機名稱或 IP 位址。
port（連接埠）: 資料庫正在監聽請求的 TCP/IP 連接埠。
username（使用者名稱）: 用於連線到資料庫的使用者名稱。
password（密碼）: 用於連線到資料庫的密碼。

username（使用者名稱）

用於連線到資料庫的使用者名稱。

對於未編目的連線，您必須傳遞 null 值或空字串。

password（密碼）

用於連線到資料庫的密碼。

對於未編目的連線，您必須傳遞 null 值或空字串。

options（選項）

一個包含影響連線行為的連線選項的關聯式陣列，其中有效的陣列鍵包含

autocommit（自動提交）

傳遞 DB2_AUTOCOMMIT_ON 值會開啟此連線控制代碼的自動提交。

傳遞 DB2_AUTOCOMMIT_OFF 值會關閉此連線控制代碼的自動提交。

DB2_ATTR_CASE

傳遞 DB2_CASE_NATURAL 值指定以自然大小寫傳回欄位名稱。

傳遞 DB2_CASE_LOWER 值指定以小寫傳回欄位名稱。

傳遞 DB2_CASE_UPPER 值指定以大寫傳回欄位名稱。

CURSOR（游標）

傳遞 DB2_FORWARD_ONLY 值會為陳述式資源指定僅向前游標。這是預設的游標類型，所有資料庫伺服器都支援。

傳遞 DB2_SCROLLABLE 值會為陳述式資源指定可捲動游標。此模式允許隨機存取結果集中的列，但目前僅 IBM DB2 Universal Database 支援。

ibm_db2 1.7.0 及更高版本提供以下新選項。

trustedcontext（信任的環境定義）

傳遞 DB2_TRUSTED_CONTEXT_ENABLE 值會開啟此連線控制代碼的信任的環境定義。無法使用 db2_set_option() 設定此參數。

只有在資料庫已編目（即使資料庫是本機的），或是您在建立連線時指定完整的 DSN，此鍵才會生效。

要編目資料庫，請使用以下指令

db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
db2 "update dbm cfg using svcename <SERVICENAME>"
db2set DB2COMM=TCPIP

ibm_db2 1.5.1 及更高版本提供以下新的 i5/OS 選項。

i5_lib

一個字元值，表示將用於解析非限定檔案參考的預設程式庫。如果連線使用系統命名模式，則此選項無效。

i5_naming

DB2_I5_NAMING_ON 值會開啟 DB2 UDB CLI iSeries 系統命名模式。檔案使用斜線 (/) 分隔符號來限定。非限定檔案使用作業的程式庫清單來解析。

設定 DB2_I5_NAMING_OFF 值會關閉 DB2 UDB CLI 預設的命名模式，即 SQL 命名模式。檔案名稱使用句點 (.) 作為分隔符號。未指定程式庫的檔案會使用預設程式庫或目前使用者 ID 來解析。

i5_commit

i5_commit 屬性應在呼叫 db2_connect() 之前設定。如果在連線建立後更改此值，且連線目標為遠端資料來源，則變更將在下一次成功呼叫該連線控制代碼的 db2_connect() 時才會生效。

注意事項:
php.ini 設定 ibm_db2.i5_allow_commit==0 或 DB2_I5_TXN_NO_COMMIT 為預設值，但可以使用 i5_commit 選項覆寫。

DB2_I5_TXN_NO_COMMIT - 不使用提交控制。

DB2_I5_TXN_READ_UNCOMMITTED - 可能發生髒讀、不可重複讀和幻讀。

DB2_I5_TXN_READ_COMMITTED - 不會發生髒讀。可能發生不可重複讀和幻讀。

DB2_I5_TXN_REPEATABLE_READ - 不會發生髒讀和不可重複讀。可能發生幻讀。

DB2_I5_TXN_SERIALIZABLE - 交易是可序列化執行的。不會發生髒讀、不可重複讀和幻讀。

i5_query_optimize

DB2_FIRST_IO 所有查詢都會以儘快返回第一頁輸出為目標進行最佳化。當輸出由使用者控制，且使用者很可能在檢視第一頁輸出數據後取消查詢時，此目標效果最佳。使用 OPTIMIZE FOR nnn ROWS 子句編碼的查詢會遵循子句中指定的目標。

DB2_ALL_IO 所有查詢都會以在最短的經過時間內完成整個查詢執行為目標進行最佳化。當查詢的輸出被寫入檔案或報表，或者介面正在將輸出數據排入佇列時，這是一個不錯的選項。使用 OPTIMIZE FOR nnn ROWS 子句編碼的查詢會遵循子句中指定的目標。這是預設值。

i5_dbcs_alloc

設定 DB2_I5_DBCS_ALLOC_ON 值會開啟 DB2 6X 配置方案，以處理 DBCS 轉換欄位大小的增長。

設定 DB2_I5_DBCS_ALLOC_OFF 值會關閉 DB2 6X 配置方案，以處理 DBCS 轉換欄位大小的增長。

注意：php.ini 設定 ibm_db2.i5_dbcs_alloc==0 或 DB2_I5_DBCS_ALLOC_OFF 為預設值，但可以使用 i5_dbcs_alloc 選項覆寫。

i5_date_fmt

DB2_I5_FMT_ISO - 使用國際標準化組織 (ISO) 日期格式 yyyy-mm-dd。這是預設值。

DB2_I5_FMT_USA - 使用美國日期格式 mm/dd/yyyy。

DB2_I5_FMT_EUR - 使用歐洲日期格式 dd.mm.yyyy。

DB2_I5_FMT_JIS - 使用日本工業標準日期格式 yyyy-mm-dd。

DB2_I5_FMT_MDY - 使用日期格式 mm/dd/yyyy。

DB2_I5_FMT_DMY - 使用日期格式 dd/mm/yyyy。

DB2_I5_FMT_YMD - 使用日期格式 yy/mm/dd。

DB2_I5_FMT_JUL - 使用儒略日期格式 yy/ddd。

DB2_I5_FMT_JOB - 使用作業預設值。

i5_date_sep

DB2_I5_SEP_SLASH - 使用斜線 ( / ) 作為日期分隔符號。這是預設值。

DB2_I5_SEP_DASH - 使用破折號 ( - ) 作為日期分隔符號。

DB2_I5_SEP_PERIOD - 使用句點 (.) 作為日期分隔符號。

DB2_I5_SEP_COMMA - 使用逗號 (,) 作為日期分隔符號。

DB2_I5_SEP_BLANK - 使用空格作為日期分隔符號。

DB2_I5_SEP_JOB - 使用作業的預設值。

i5_time_fmt

DB2_I5_FMT_ISO - 使用國際標準化組織 (ISO) 時間格式 hh.mm.ss。這是預設值。

DB2_I5_FMT_USA - 使用美國時間格式 hh:mmxx，其中 xx 是 AM 或 PM。

DB2_I5_FMT_EUR - 使用歐洲時間格式 hh.mm.ss。

DB2_I5_FMT_JIS - 使用日本工業標準時間格式 hh:mm:ss。

DB2_I5_FMT_HMS - 使用 hh:mm:ss 格式。

i5_time_sep

DB2_I5_SEP_COLON - 使用冒號 (:) 作為時間分隔符號。這是預設值。

DB2_I5_SEP_PERIOD - 使用句點 (.) 作為時間分隔符號。

DB2_I5_SEP_COMMA - 使用逗號 (,) 作為時間分隔符號。

DB2_I5_SEP_BLANK - 使用空格作為時間分隔符號。

DB2_I5_SEP_JOB - 使用作業的預設值。

i5_decimal_sep

DB2_I5_SEP_PERIOD - 使用句點 (.) 作為小數點分隔符號。這是預設值。

DB2_I5_SEP_COMMA - 使用逗號 (,) 作為小數點分隔符號。

DB2_I5_SEP_JOB - 使用作業的預設值。

以下新的 i5/OS 選項在 ibm_db2 1.8.0 及更高版本中可用。

i5_libl: 一個字元值，指示用於解析未限定檔案參考的程式庫清單。使用空格分隔程式庫清單元素，例如 'i5_libl'=>"MYLIB YOURLIB ANYLIB"。

注意事項:
i5_libl 會呼叫 qsys2/qcmdexc('cmd',cmdlen)，這僅在 i5/OS V5R4 及更高版本中可用。

傳回值

如果連線嘗試成功，則傳回連線控制代碼資源。如果連線嘗試失敗，db2_connect() 會傳回 false。

範例

範例 #1 建立已編目連線

已編目連線需要您先前已透過 DB2 命令列處理器 (CLP) 或 DB2 配置小助手編目目標資料庫。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

$conn = db2_connect($database, $user, $password);

if ($conn) {
 echo "連線成功。";
 db2_close($conn);
}
else {
 echo "連線失敗。";
}
?>

以上範例將輸出

Connection succeeded.

範例 #2 建立未編目連線

未編目連線可讓您動態連線到資料庫。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$hostname = 'localhost';
$port = 50000;

$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
 "HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;";
$conn = db2_connect($conn_string, '', '');

if ($conn) {
 echo "連線成功。";
 db2_close($conn);
}
else {
 echo "連線失敗。";
}
?>

以上範例將輸出

Connection succeeded.

範例 #3 建立預設為 autocommit 關閉的連線

將選項陣列傳遞給 db2_connect() 讓您可以修改連線控制代碼的預設行為。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

$conn = db2_connect($database, $user, $password, $options);

if ($conn) {
 echo "連線成功。\n";
 if (db2_autocommit($conn)) {
 echo "Autocommit 已開啟。\n";
 }
 else {
 echo "Autocommit 已關閉。\n";
 }
 db2_close($conn);
}
else {
 echo "連線失敗。";
}
?>

以上範例將輸出

Connection succeeded.
Autocommit is off.

範例 #4 i5/OS 最佳效能

為了讓您的 i5/OS ibm_db2 1.5.1 PHP 應用程式達到最佳效能，請在 db2_connect() 中使用預設的主機、使用者 ID 和密碼。

<?php
 $library = "ADC";
 $i5 = db2_connect("", "", "", array("i5_lib"=>"qsys2"));
 $result = db2_exec($i5,
 "select * from systables where table_schema = '$library'");
 while ($row = db2_fetch_both($result)) {
 echo $row['TABLE_NAME']."</br>";
 }
 db2_close($i5);
?>

以上範例將輸出

ANIMALS
NAMES
PICTURES

範例 #5 使用信任的環境

以下範例顯示如何啟用信任的環境、切換使用者以及取得目前的使用者 ID。

<?php

$database = "SAMPLE";
$hostname = "localhost";
$port = 50000;
$authID = "db2inst1";
$auth_pass = "ibmdb2";

$tc_user = "tcuser";
$tc_pass = "tcpassword";

$dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
 PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
$options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

$tc_conn = db2_connect($dsn, "", "", $options);
if($tc_conn) {
 echo "Explicit trusted connection succeeded.\n";

 if(db2_get_option($tc_conn, "trustedcontext")) {
 $userBefore = db2_get_option($tc_conn, "trusted_user");

 //Do some work as user 1.

 //Switching to trusted user.
 $parameters = array("trusted_user" => $tc_user,
 "trusted_password" => $tcuser_pass);
 $res = db2_set_option ($tc_conn, $parameters, 1);

 $userAfter = db2_get_option($tc_conn, "trusted_user");
 //Do more work as trusted user.

 if($userBefore != $userAfter) {
 echo "User has been switched." . "\n";
 }
 }

 db2_close($tc_conn);
}
else {
 echo "Explicit trusted connection failed.\n";
}
?>

以上範例將輸出

Explicit trusted connection succeeded.
User has been switched.

另請參閱

db2_close() - 關閉資料庫連線
db2_pconnect() - 傳回一個永久的資料庫連線

發現問題了嗎？

了解如何改進此頁面 • 提交拉取請求 • 回報錯誤

＋新增註解

使用者提供的註解 1 則註解

向上

向下

d dot lanza38 at gmail dot com ¶

9 年前

截至 2015 年 9 月 29 日，當使用 ibm_db2 驅動程式並使用 'i5_libl' 選項指定無效的程式庫清單時，連線將會成功建立，但會使用預設的程式庫清單。發生的情況是先建立連線，然後嘗試更改程式庫清單。連線會成功，但程式庫清單的更改將會失敗，而且 "db2_conn_error()" 或 "db2_conn_errormsg()" 不會回報任何錯誤，並會使用預設的程式庫清單。然而，"db2_stmt_error()" 和 "db2_stmt_errormsg()" 將會註冊一個值。此外，如果啟用錯誤報告，警告將會輸出到螢幕上。根據 Zend 的說法（我開了一個 ticket），這不是一個 bug，而是一個預期的行為，根據所使用/交換的程式庫清單，可能會導致重大問題（開發環境 VS 正式環境）。當一個異常現象（我仍然無法解釋）在我的程式庫清單中插入字元 'Z' 時，我偶然發現了這個行為。我意識到我是在我的開發環境中，但結果卻是存取正式環境的資料。今後，為了保險起見，我會確保新增這項額外的檢查。

請參閱以下內容以重現此行為

<?php
ini_set("display_errors", 1);

$systemName = 'systemName';
$userID = 'userName';
$password = 'password';

$options['i5_libl'] = implode('Z', array(
 'INVALID', 
 'LIB', 
 'LIST', 
 'IMPLODED', 
 'WITH', 
 'THE', 
 'LETTER', 
 'Z'
 ));

$options['i5_naming'] = DB2_I5_NAMING_ON;

$conn = db2_connect($systemName, $userID, $password, $options);
//This line causes "ini_set("display_errors", 1)" to dislay this warning on the screen:
//Warning: db2_connect(): Statement Execute Failed in /PATH/TO/FILE/test.php on line 58

if (db2_stmt_error()) { //Evaluates to true
 echo "error ID: " . (db2_stmt_error()); //Displays error code: 38501
 echo "<br>error message: " . (db2_stmt_errormsg()); //Displays: Trigger program or external routine detected an error. SQLCODE=-443
}

echo "<br />|".db2_conn_error()." ||| ".db2_conn_errormsg()."|<br />"; //Only "| ||| |" is displayed
print_r($conn); //A resource ID is displayed
echo "<br />";

if(isset($conn) && $conn === true){
 echo "Boolean true<br />";
 //never executes, but not expected since either false or a resource ID should be returned.
 //Plus it is clear $conn contains a resource ID from above.
}
if(isset($conn) && $conn == true){
 echo "Non-Boolean true 2<br />"; 
 //This always executes regardless of an accurate library list or not
 //I suppose "if($conn)" would evaluate to non-boolean true so this makes sense.
}
if(isset($conn) && $conn == "true"){
 echo "String true";
 //Never executes, but not expected.
}
if(isset($conn) && $conn === false){
 echo "Boolean false<br />";
 //never executes because the connection itself was a success.
 //If invalid credentials were provided this executes.
}
if(isset($conn) && $conn == false){
 echo "Non-Boolean false 2<br />";
 //never executes because the connection itself was a success.
 //Added this here because I was unsure if a boolean false would be returned or not.
 //If invalid credentials were provided this executes as well.
}
if(isset($conn) && $conn == "false"){
 echo "String false";
 //never executes because the connection itself was a success.
 //Added this here because I was unsure if a String "false" would be returned
}
?>

＋新增註解