PHP ADODB 入门教程(6)

ADOConnection 主要函数
ADOConnection( )

建构函数，请不要直接呼叫，使用 ADONewConnection() 来代替。

Connect($host,[$user],[$password],[$database])

对服务器或资料来源 $host 非持续性连结，使用者认证代码为 $user ，密码为 $password ,如果服务器支持多数据库，则指定连结到数据库 $database。

连结成功回传 true ， 失败则回传 false 。

注意：如果你使用的是 Microsoft ADO，而非 OLEDB，你可以设定 $database 参数为你正在使用的 OLEDB 资料供应器。

PostgreSQL：另一种选择性的连结方法是将标准的PostgreSQL连结字符串放在 $host 参数里，那么其它的参数都会被呼略。

对于 Oracle 及 Oci8，有两个方法可以连结。第一，使用你定义的区域 tnsnames.ora 里的 TNS 名称，将这个名称放在 $database 参数里，然后将 $host 设为 false。另一种方法，设定 $host 为服务器，而 $database 则设成数据库 SID ，这将会不透过 tnsnames.ora 连结。

范例：

 $conn->Connect(false, 'scott', 'tiger', 'name_in_tnsnames'); # 使用 tnsnames.ora
 $conn->Connect('server:1521', 'scott', 'tiger', 'OracleSID'); # 不使用 tnsnames.ora
还有许多的数据库连结范例在网站 php.weblogs.com/ADOdb 以及在本版所附的 testdatabase.inc.php 档案里。

PConnect($host,[$user],[$password],[$database])

对服务器或资料来源 $host 持续性连结，使用者认证代码为 $user ，密码为 $password ,如果服务器支持多数据库，则指定连结到数据库 $database。

连结成功回传 true ， 失败则回传 false 。其它资料请参考 Connect()。

Execute($sql,$inputarr=false)

执行 SQL 指令 $sql ，如果成功，就回传一个对应的 ADORecordSet 对象。要注意的是这个指令如果执行成功时，一定会回传一个数据集，即使是执行 insert 或 update 指令也一样。

回传对应的 ADORecordSet 对象。例如，如果连结的是 mysql ，那么 ADORecordSet_mysql 将会被回传。当SQL指令执行失败时会回传 false 值。

$inputarr 参数则用来做为传入的结合变量。以下是 Oracle 的范例：

 $conn->Execute("SELECT * FROM TABLE WHERE COND=:val", array('val'=> $val));
另一个例子，使用 ODBC ，以 '?' 符号做为协议。

  $conn->Execute("SELECT * FROM TABLE WHERE COND=?", array($val));
结合变量(Binding variables)
变量的结合可以加速SQL指令编译及快取的速度，产生较佳的效能。目前只有 Oracle 及 ODBC 支持变量结合。 ODBC 类的 ? 结合在不支持的数据库里，是以仿真的方式来做到的。

变量结合在 odbc 及 oci8po 驱动程序里的用法。

$rs = $db->Execute('select * from table where val=?', array('10'));
变量结合在 oci8 驱动程序里的用法。

$rs = $db->Execute('select name from table where val=:key',array('key' => 10));
CacheExecute($secs2cache,$sql,$inputarr=false)

类似于 Execute 函数，除了将资料集暂存在 $ADODB_CACHE_DIR 指定的目录里 $secs2cache 秒外。如果 CacheExecute() 被相同的参数、数据库、使用者ID及密码，而且快取也没有过期，那么快取中的资料集将会被传回。

  include('ADOdb.inc.php');
  include('tohtml.inc.php');
  $ADODB_CACHE_DIR = '/usr/local/ADOdbcache';
  $conn = &ADONewConnection('mysql');
  $conn->PConnect('localhost','userid','password','database');
  $rs = $conn->CacheExecute(15, 'select * from table'); # 快取15秒
  rs2html($rs); /* recordset to html table */ 
另外，从ADODB 1.80 版起，$secs2cache 参数成为选择性(也就是可以不加)

       $conn->Connect(...);
        $conn->cacheSecs = 3600*24; // cache 24 hours
        $rs = $conn->CacheExecute('select * from table');
如果 CacheExecute() 被多次呼叫，而且资料集也持续在快取中，$secs2cache 参数不会延长被快取的资料集保留时间(因为会被呼略掉)，CacheExecute()只能使用在 SELECT 指令上。

效能备注：我曾经作了一些效能测试，并且发现这些快取的效益极为显著。尤其是在数据库服务器运作效率慢于WEB服务器或数据库的负荷非常重的时候。ADODB的快取好在它减少了数据库服务器的负荷。当然，如果你的数据库服务器负荷不大，而且运作速度也比WEB服务器快，那快取反而会降低效能。

SelectLimit($sql,$numrows=-1,$offset=-1,$inputarr=false)

执行成功会回传一个资料集。完成一个SELECT指令，类似于 PostgreSQL中 SELECT 指令里的LIMIT $numrows OFFSET $offset 宣告。

在 PostgreSQL，SELECT * FROM TABLE LIMIT 3 将会只传回从头开始的三笔记录。相同的，$connection->SelectLimit('SELECT * FROM TABLE',3)也有同样的意思。

而 SELECT * FROM TABLE LIMIT 3 OFFSET 2 将会回传记录 3,4及5三笔(也就是在记录2之后，回传三笔记录)。相同的，在ADODB里是以 $connection->SelectLimit('SELECT * FROM TABLE',3,2) 来做的。

要注意，LIMIT宣告，在MySQL里是相反位置的。你可以设定 $connection->SelectLimit('select * from table',-1,10) 去取得从第11笔起到最后一笔的记录。

最后一个参数 $inputarr 是针对支持变量结合功能的数据库，像 Oracle oci8。这个大大的减少了 SQL 编译的负荷。底下是 Oracle 范例：

 $conn->SelectLimit("SELECT * FROM TABLE WHERE COND=:val", 100,-1,array('val'=> $val));
oci8po 驱动程序(oracle portable driver)使用更为标准的变量结合：

 $conn->SelectLimit("SELECT * FROM TABLE WHERE COND=?", 100,-1,array('val'=> $val));
Ron Wilson 报告说 SelectLimit 在SQL指令有含 UNION 时会无效，并且建议了针对 mssql 的对策：

> 事实上，我发现一个可以立即最佳化的建构 Select Union 方法。这适用于 MS-SQL，至于
其它数据库是否适合，就不确定了。当更新求助档时，你可以参考这个范例。注意，这个方
法不适用于 MySQL。
>
> 改变:
>  Select column1 From table1
>  Union
>  Select column2 From table2
>
> 成为:
>  Select * From (
>   Select column1 From table1
>   Union
>   Select column2 From table2
>   )
>  As dummytable
>
> Ron
CacheSelectLimit($secs2cache, $sql, $numrows=-1,$offset=-1,$inputarr=false)

类似于 SelectLimit，除了将资料集暂存在 $ADODB_CACHE_DIR 指定的目录里 $secs2cache 秒外。

自 1.80版起，$secs2cache成为了选择性参数：

 $conn->Connect(...);
        $conn->cacheSecs = 3600*24; // 快取24小时
        $rs = $conn->CacheSelectLimit('select * from table',10);
CacheFlush($sql)

更新 ( 删除 ) 以 $sql 指令存放在 $ADODB_CACHE_DIR 指定目录内的全部快取资料集。如果你企图更新所有的快取数据集，请执行如下的 PHP 指令码 ( 仅针对 Unix 有效 ) ： system("rm -f find ".ADODB_CACH_DIR." -name ADODB_*.cache") ;

ErrorMsg()

回传最后状态或是错误讯息。即使没有错误发生，本函数也会回传一个字符串。一般情况下，你不需要呼叫这个函数，除非ADODB函数因为错误状态回传了false值。

注意：如果 debug 旗标被激活了，SQL 错误讯息将会在Execute函数被呼叫时发生错误后出现。

ErrorNo()

回传最后的错误号码。注意一点，旧版本的 PHP(4.0.6以前)，不支持ODBC的错误编号。一般情况下，你不需要呼叫这个函数，除非ADODB函数因为错误状态回传了false值。

GenID($seqName = 'ADOdbseq',$startID=1)

产生一个顺序号码(在mssql是一个整数值)。对 interbase,mysql,postgresql,oci8,oci8po,ODBC核心类驱动程序(如 access,vfp,db2等等) 都支持。使用 $seqName做为顺序名。如果数据库没有值，那么GenID()将会自动为你产生一个序号(产生使用者 id 时允许如此)，换句话说，你必需自行建立序号。

如果你的数据库驱动程序要仿真序号，资料表的名称就是序号名(sequence name)，而这个资料表必需有一个字段"id"，而其资料型别为整数，或你需要更大些的 numeric(16)。

对于没有支持序号原生功能的ODBC及数据库(如 mssql,mysql)，我们对每一个序号建立一个资料表。如果序号没有被预先定义，那启如的号码值就设定成 $startID。

注意，mssql驱动程序的 GenID()会产生一个16位的GUID。自1.90版起，我们将回传整数。

UpdateBlob($table,$column,$val,$where)

允许你以 $where 条件储存一个BLOB(存在 $val里的)值到 $table 里的 $column 字段。

例:

       # for oracle
        $conn->Execute('INSERT INTO blobtable (id, blobcol) VALUES (1, empty_blob())');
        $conn->UpdateBlob('blobtable','blobcol',$blobvalue,'id=1');
 
        # non oracle databases
        $conn->Execute('INSERT INTO blobtable (id, blobcol) VALUES (1, null)');
        $conn->UpdateBlob('blobtable','blobcol',$blobvalue,'id=1');
如果成功，会回传 true ，否则回传 false 值。目前有 MySQL, PostgreSQL, Oci8, Oci8po 及 Interbase 支持。其它驱动程序可能有效，仍在持续开发中。