PHP ADODB 1.99版手册中文翻译

http://www.moocky.net/Manual/adodb.gb.htm

PHP ADODB 1.99版手册中文翻译(Tripc)
感谢
记事


PHP ADODB 1.99版手册中文翻译
翻译作者:Tripc
------------------

ADODB

PHP在资料库的支援上是很令人称道的,几乎所有的知名资料库系统都有对应的函数群支援,而且支援的很完整。但很不幸的,每一群资料库支援函数无论在名称或叁数结构上,都有很大的差异,这使得PHP的系统开发者在面临更换资料库时,总会觉得痛苦万分。难道这个问题就没有解决方法吗?呵呵,当然有,答案就是我现在要介绍的 ADODB 这个PHP物件。

ADODB提供了完整的方法和属性让工程师去控制资料库系统,更棒的是你只要记得它的功能就好了,因为不同的资料库系统,只要修改一个属性值就可以了,ADODB会自动依据设定取用正确的PHP函数。此外,最多再配合资料库系统修改修改SQL指令,你的PHP系统就可以在最短的时间内更换到另一个资料库系统了,如果在撰写程式时,对SQL指令能做妥善规划,那就更快了。

经过以上的介绍,相信你已经对ADODB的功用有所了解,以下为ADODB的详细介绍。

取得ADODB

你可以在 http://php.weblogs.com/ADOdb 取得最新版的ADODB。我在撰写本文时,最新版本是1.99版,版权采BSD-Style及LGPL双轨制,换句话就是Freeware,没有什麽限制。但在取得ADODB後,最好还是要看一下相关版权说明及用法,并和本文对照一下,以免错误。

使用ADODB

基本上使用ADODB是相当容易的,取得压缩档後解开,我建议将整个内容都解到ADODB的目录里。然後你可以一边叁考本文,一边研究里面的范例,就放在里面的test目录下。

由於ADODB附上的说明十分完整详实,以下的说明大部份来自ADODB的readme.htm,这里不是全部的内容,我把一些我认为没有用的内容都去掉了,像版本差异说明、何撰写支援ADODB的驱动程式等与应用无关的部份。想要了解全部内容的读者还是可以自己去叁考 readme.htm。


  • 简介

  • 特色

  • 安装

  • 启动ADODB

    • ADONewConnection

    • NewADOConnection

  • 支援的资料库

  • 学习手册

    • 范例 1 : Select

    • 范例 2 : 进阶 Select

    • 范例 3 : Insert

    • 范例 4 : 除错及 rs2html 范例

    • 范例 5 : MySQL 及选单

    • 范例 6 : 一次连结两个资料库

    • 范例 7 : 产生更新及新增的SQL指令

    • 范例 8 : 用下一笔及上一笔实作卷动

  • 客制化错误处理及PEAR错误

  • 资料集快取

  • 叁考手册

    • ADOConnection

      • 连结资料库:Connect PConnect

      • 执行SQL:Execute CacheExecute SelectLimit CacheSelectLimit Prepare PrepareSP GetOne GetRow

      • 产生 更新/新增:GetUpdateSQL GetInsertSQL

      • BLOB : UpdateBlob UpdateClob UpdateBlobFile

      • 换页/卷页 : PageExecute CachePageExecute

      • 清除 : CacheFlush Close

      • 交易 : BeginTrans CommitTrans RollbackTrans

      • 提取资料 : $ADODB_FETCH_MODE BlankRecordSet

      • 字串 : Concat qstr

      • 日期 : DBDate DBTimeStamp UnixDate UnixTimeStamp

      • "列"管理器 : Affected_Rows Insert_ID GenID

      • 错误处理 : ErrorMsg ErrorNo

      • 资料辞典 : MetaDatabases MetaTables MetaColumns MetaColumnNames

      • 反对 : Bind (? 没有说明)

    • ADORecordSet

      • 取单笔记录 : FetchRow FetchInto FetchObject FetchNextObject GetRowAssoc Fields GetAssoc

      • 取全部记录 : GetArray GetRows

      • 卷动 : Move MoveNext MoveFirst MoveLast AbsolutePosition CurrentRow AtFirstPage AtLastPage AbsolutePage

      • 选单制作 : GetMenu GetMenu2

      • 日期 : UserDate UserTimeStamp UnixDate UnixTimeStamp

      • 记录资讯 : RecordCount PO_RecordSet

      • 栏位资讯 : FieldCount FetchField MetaType

      • 清除 : Close

  • rs2html 公用函式说明  范例

简介

由於PHP的资料库存取函数没有标准化,所以我们需要一组函数库或是类别来隐藏不同资料库函数介面间的差异,让我们可以很简单的去切换资料库,而这,就是ADODB的目的。

ADODB目前支援MySQL, Oracle, Microsoft SQL Server, Sybase, Sybase SQL Anywhere, Informix, PostgreSQL, FrontBase, Interbase (Firebird 及 Borland 版本), Foxpro, Access, ADO 和 ODBC。ADODB也有透过ODBC成功连结Progress及DB2的报告,我们希望能有更的人提供驱动介面来支援更多的资料库。

PHP4支援连结变数(session variables),使用者可以透过ADODB储存连结资讯,以达成真正的可携性及弹性,相关的用法及资讯请自行叁考ADOdb-session.php这个范例。

另外,如果要撰写一个具有高度可移植性的SQL码,也可以叁阅 http://php.weblogs.com/portable_sql 这篇文章。

特色

  • 对熟悉Windows的工程师而言,ADODB很容易使用,因为ADODB里的很多功能和Microsoft的ADO很像。

  • 与其它的PHP资料库类别不同,它们大多集中在处理与 select 指令有关的东西,而ADODB对於 inserts 及 update 也提供额外的支援,并且可以很快的连结到多资料库。所提供的方法更扩及日期的掌握,字串的连结及字串标记字元差异处理(在某些资料库间字串的连结和标记符号是有差异的)

  • 型别对照系统是内建的,所以我们可以设定或描述像CHAR,TEXT及STRING在不同的资料库间其实是相同的资料型别。

  • 更容易去移植,因为所有与资料库相依的程式码被都隐藏在後端,所以使用者不再需要去移植类别里的逻辑。

  • 支援 PHP4 连结变数,请叁考 ADOdb-session.php。

安装

首先要确定你所使用的PHP版本是 4.01pl2 或是之後的版本(因为ADODB使用到了 require_once及include_once两个函数)。解压缩全部的档案到你的Web伺服器可以存取的一个目录里。

要测试ADODB你需要一个资料库,开启 testdatabase.inc.php 这个档案,并且修改连结叁数,以适合你所使用的资料库。这个程式会建立一个新的资料表在你的资料库中,以支援我们提供的测试程式及范例。

就这样,你安装好了。

启动ADODB

当要执行ADODB时,至少有两个档案要被载进来,第一个是 ADOdb.inc.php ,这里面包含了所有资料库类中要被使用的函数。而对资料库实作的程式码则被置放在ADOdb-????.inc.php档案里。

例如说,要连结一个mysql资料库:

 

无论何时你需要连结到一个资料库时,你必需使用ADONewConnection()函数建立了一个连结物件。ADONewConnection接受一个选择性叁数, 。如果没有叁数被指定,它将会使用被 ADOLoadCode() 所载入的最後一个资料库。 NewADOConnection() 是另一个相同的函数。

当你建立好一个连结物件时,你并没有真的连结上你的资料库。你仍需要使用 $conn->Connect() 或者 $conn->PConnect() 两个方法来完成真正的连结。

你可以叁考教学手册里的范例,对上面的说明做更深入的了解。

支援的资料库

名称

测试状态

资料库

RecordCount() 支援与否

需安装的驱动程式

作业系统

access

B

Microsoft Access/Jet. 需要建立一个 ODBC/DSN。

Y/N

ODBC

Windows only

ado

B

一般未经特别指定的资料库系统, 透过ADO,允许不设定 DSN连结,使用OLEDB以提供较佳的效能。

? 视资料库而定

ADO or OLEDB provider

Windows only

ado_access

B

Microsoft Access/Jet 透过ADO,允许不设定 DSN连结,使用OLEDB以提供较佳的效能。

Y/N

ADO or OLEDB provider

Windows only

ado_mssql

B

Microsoft SQL Server 透过ADO,允许不设定 DSN连结,使用OLEDB以提供较佳的效能。

Y/N

ADO or OLEDB provider

Windows only

db2

C

DB2. 可以透过ODBC获得可以信赖的运作效果。

Y/N

DB2 CLI/ODBC interface

Unix and Windows. Unix install hints.

vfp

A

Microsoft Visual FoxPro,需要建立一个ODBC/DSN

Y/N

ODBC

Windows only

fbsql

C

FrontBase.

Y

?

Unix and Windows

ibase

B

Interbase 6或更早的版本。有些使用者报告必需使用如下的方式连结
$db->PConnect('localhost:c:/ibase/employee.gdb', "sysdba", "masterkey")目前没有支援 Affected_Rows 方法

Y/N

Interbase client

Unix and Windows

firebird

C

interbase的Firebird版本

Y/N

Interbase client

Unix and Windows

borland_ibase

C

Borland 的Interbase 6.5 或更新版

Y/N

Interbase client

Unix and Windows

informix

C

Informix

Y/N

Informix client

Unix and Windows

mssql

A

Microsoft SQL Server 7.也可以和Microsoft SQL Server 2000运作的很好。但在日期格式上仍有一些问题。例如在日期时间的回传值上,就不会回传秒数数值。

Y/N

Mssql client

Unix and Windows.
Unix install howto.

mysql

A

MySQL 不支援交易处理

Y/N

MySQL client

Unix and Windows

mysqltmaxsql

A

MySQL 支援交易处理

Y/N

MySQL client

Unix and Windows

oci8

A

Oracle 8/9. 支援比 oracle 驱动程式还多的功能 (例如: Affected_Rows). 在连结之前,你可能需要先配好环境变数('ORACLE_HOME=...')

有两个方式进行连结,用伺服器的IP或服务名称:
PConnect('serverip:1521','scott','tiger','service')
PConnect('', 'scott', 'tiger', 'tnsname').

Y/N

Oracle client

Unix and Windows

oci8po

A

Oracle 8/9 可携式驱动程式

Y/N

Oracle client

Unix and Windows

odbc

A

标准 ODBC

用 PConnect('DSN','user','pwd').连结。

? depends on database

ODBC

Unix and Windows. Unix hints.

odbc_mssql

C

用 ODBC 连接 MSSQL

Y/N

ODBC

Unix and Windows.

odbc_oracle

C

用 ODBC 连接 ORACLE

Y/N

ODBC

Unix and Windows.

oracle

C

支援旧的 Oracle 7 client API. 不支援 $ADODB_FETCH_MODE.

Y/N

Oracle client

Unix and Windows

postgres

A

PostgreSQL 不支援 LIMIT 指令.

Y

PostgreSQL client

Unix and Windows.

postgres7

A

PostgreSQL 支援 LIMIT 及其它版本 7 功能

Y

PostgreSQL client

Unix and Windows.

sqlanywhere

C

Sybase SQL Anywhere. 

Y/N

SQL Anywhere ODBC client

?

sybase

C

Sybase.

Y/N

Sybase client

Unix and Windows. Unix hints.

 

测试状态栏的代码说明如下:

A=已经经过很多人验证及测试,可靠度最高。
B=已经测试并使用了,但可能仍有一些功能没有达成。
C=使用者自行配置或试用的驱动程式,可能没有完全支援ADODB的功能。

"RecordCount()支援与否",指的是RecordCount()函数是否会回传用SELECT指令取得的记录笔数(不支援时传回-1)。如果这个栏位的值出现了 Y/N ,那表示当全域变数 $ADODB_COUNTER=true 时,会以模拟的方式取得,而这是预设值。要注意的是,如果你预测记录笔数会很大时,最好把这个值设为false,也就是关掉这个模拟功能,因为这会耗掉非常多的记忆体,以做为快取之用。由於这个变数在每次执行时都会检查,所以你可以选择性的使用或不使用。

所有支援$ADODB_FETCH_MODE的资料库都支援 ADODB_FETCH_NUM(以栏位顺序存取) 及 ADODB_FETCH_ASSOC(以栏位名称存取),两种模式。而将值设为 ADODB_FETCH_DEFAULT(资料库预设模式存取),则是由资料库的功能来决定的,所以不具备可携性,而 ADODB_FETCH_BOTH(双模式存取) 也一样。


学习手册

范例 1: Select 指令

任务:连结到 Access 的 Northwind DSN,然後在每一列显示头2个栏位。(Northwind 北风资料库,在ODBC设定的DSN,是Access的标准范例资料库)

在这个范例中,我们建立一个 ADOConnection 物件,它代表了和资料库的连结。连结是以 PConnect 函数来初始化的,然後会持续的连结着。任何时候我们要查询资料库时,我们就呼叫 ADOConnection.Execute() 函数,这将会回传一个 ADORecordSet物件。事实上它只是一个指向在fields[]阵列中,目前记录的指标,我们使用MoveNext()来在记录间移动。

注意:另一个很有用的函数 SelectLimit 并没有在这个范例里使用,这个函数允许我们去限制显示的资料笔数。












在这个例子中,$recordSet回传了存在$recordSet->fields阵列里,目前所指向的记录。以栏位编号为索引,起始值为0。我们使用MoveNext()函数来移动到下一笔记录,当到了最後一笔时,EOF属性会被设定为true。当Execute()函数执行有错误时,会回传一个false值,而不是一个recordset物件。

$recordSet->fields[]阵列是由PHP资料库扩充函数库所产生的。有一些资料库扩充函数库仅支援以编号来进行索引,而不支援以栏位名为索引。要强迫使用栏位名索引,也就是要使用关连式阵列,请使用 $ADODB_FETCH_MODE 全域变数来设定。当一个资料集被Execute()或是SelectLimit()函数建立时,都会储存而且使用储如此类的设定模式。

 

上面的范例说明,如果要以顺序来存取栏位,就将 $ADODB_FETCH_MODE 的值设为 ADODB_FETCH_NUM,要以关连式阵列(以栏位名)存取栏位,就要将值设为 ADODB_FETCH_ASSOC。

要取得在被选到的记录笔数,你可以使用$recordSet->RecordCount()方法。注意,如果不能确定得到的记录笔数,会回传 -1 。

范例 2: 进阶的 Select 指令(使用 Field 物件)

任务:选取一个资料表,显示最前面的二栏。如果第二栏是一个日期或时间型态栏位,将它格式化成US格式。



















在这个例子中,我们使用 FetchField() 函数来检查第二个栏位的资料型别。这将会回传一个至少有三个栏位的物件,栏位说明如下:

  • name: 栏位名

  • type: 栏位的资料原生型别native field type of column

  • max_length: 栏位的最大长度,部份资料库像MySQL,并不回传栏位的正确值,以这个例子而言,就会回传 -1 。

然後我们使用 MetaType() 去转换原生型别成通用型别,目前通用型别定义如下:

  • C:  character 栏位,应该使用 标记来取值。

  • X: 文字栏位(Text) , 长文字栏位,使用