PHP中 ADOdb 类库应用(三):参考手册(4)

ADORecordSet(资料集)

当一个SQL指令成功的被 ADOConnection->Execute($sql)执行后,一个 ADORecordSet 对象会被回传回来。这个对象提供了一个虚拟的指针,所以我们可以移动它,从一笔到一笔。也提供一些函数,以取得字段信息和字段类别,并有协助函数去格式化结果,以展示给使用者看。

ADORecordSet 属性

fields: 包含了目前记录的数组。不是关连式数组,但它的索引值是从 0 字段数 – 1。请参考函数 Fields ,这个函数的动作就像是一个关连式数组。

dataProvider: 连结数据库的底层机制,正常设定为 native ,除非是使用 odbc ado blobSize: 一个 char , string 或者 varchar object 在被转成 Blob 前的最大长度(Blob 在显示时应该使用 textarea)。其它请参考 MetaType 函数。

sql: 储存了建立本数据集所使用的 sql 指令。

canSeek: 如果 Move() 函数有作用,会被设成 true

EOF: 当指针被移动到最后一笔时,这个值会被设定成 true

ADORecordSet 函数

ADORecordSet( )

建构函数。一般来说你不需要自己呼叫这个函数。

GetAssoc([$force_array])

如果字段数大于 2 ,那么从资料集中产生一个关连式数组。这个数组是从目前的指针起一直到档尾(EOF)。这个资料集的第一个字段会成为数组的索引。如果字段数刚好是2,当这数组被每一个键值所建立时,那么索引会直接对应到值,除非 $force_array 被设成 true

范例:

以下是我们资料集的资料:

1: Apple, Fruit, Edible
2: Cactus, Plant, Inedible
3: Rose, Flower, Edible

GetAssociation 将会产生一个如下的关系型数组:

Apple => [Fruit, Edible]
Cactus => [Plant, Inedible]
Rose => [Flower,Edible]

回传值:

关连式数组,错误则传回 false

GetArray([$number_of_rows])

从目前指针位置产生一个数组,索引值从 0 $number_of_rows – 1 。如果 $number_of_rows 没有被定义,那会到档尾(EOF)

GetRows([$number_of_rows])

GetArray() 的同义函数,是为了与 Microsoft ADO 兼容才有的。

GetMenu($name, [$default_str=”], [$blank1stItem=true], [$multiple_select=false], [$size=0], [$moreAttr=”])

建立一个 HTML 选单 (<select><option><option></select>) 。资料集的第一栏 (fields[0]) 将会作为 <option> 里的显示字符串。如果资料集有超过一个以上的字段,第二栏 (fields[1]) 将设定成回传给WEB服务器的值( value)。选单将被给予 $name 为名称。

如果 $default_str 被定义了,那么如果 $default_str == fields[0] 那么这个字段将会被选取。 如果 $blank1stItem true ,那第一个选项将会是空值。$Default_str 在对于可多选清单盒时,可以是一个数组。

要产生一个选单区,设定 $size 为一个非 0 (或者传入 $default_str 为一个数组)。如果 $multiple_select true ,那么一个选单区将会被产生成有 $size 个项目可见的选单(如果 $size == 0 那预设为 5 ),而且ADODB将会回传一个数组给服务器。最后,你可以使用 $moreAttr 去增加其它的属性,像是 javascript 或样式表。

选单范例 1: GetMenu(‘menu1′,’A’,true) 将会产生一个像这样的选单 : A B C 这里的资料 (A,1), (B,2), (C,3). 请参考 范例 5

选单范例 2: 相同的资料, GetMenu(‘menu1’,array(‘A’,’B’),false) 将会产生一个 A B 被选取的选单 : A B C GetMenu2($name, [$default_str=”], [$blank1stItem=true], [$multiple_select=false], [$size=0], [$moreAttr=”])

近似于 GetMenu ,除了 $default_str 将会和 fields[1] 做比对也就是选项值。 选单范 3: 给予在范例 2 里的数据 , GetMenu2(‘menu1’,array(‘1′,’2’),false) 将会产生一个选单,AB将会被选取。然而,这一次的被选取的比对基准是第二个字段,也就是存放要被回传给服务器里的值。 UserDate($str, [$fmt])

转换日期字符串 $str 为另一个格式,UserDate 呼叫 UnixDate 来解译 $str ,而 $fmt 默认值是 Y-m-d

UserTimeStamp($str, [$fmt])

转换时间字符串 $str 为另一个格式,时间字符串格式是 Y-m-d H:i:s 像是 “2002-02-28 23:00:12”UserTimeStamp 呼叫 UnixTimeStamp 来解译 $str ,而 $fmt 默认值为 Y-m-d H:i:s

UnixDate($str)

将日期字符串 $str 解译,并且转换成 unix mktime 格式( 1970.01.01 00:00:00 起到现在的秒数)后传回。预设日期是以 Y-m-d H:i:s 格式来传入的。而对于 Sybase Microsoft SQL Server 而言 M d Y 也是可以接受的(三个字符的月份表示法是被一个全域数组所控制的,这个部份可能需要在地化 )

1.91 版起,这个函数存在于 ADORecordSet ADOConnection两个地方。

UnixTimeStamp($str)

将时间字符串 $str 解译,并且转换成 unix mktime 格式( 1970.01.01 00:00:00 起到现在的秒数)后传回。预设日期是以 Y-m-d H:i:s 格式来传入的。而对于 Sybase Microsoft SQL Server 而言 M d Y 也是可以接受的(三个字符的月份表示法是被一个全域数组所控制的,这个部份可能需要在地化 )

1.91 版起,这个函数存在于 ADORecordSet ADOConnection两个地方。

MoveNext( )

移动内部指针到下一笔,fields 数组将会自动的更新。如果不能移动,会回传 false 值,其它情况则会回传 true

范例

$rs = $db->Execute($sql);
if ($rs) 
        while (!$rs->EOF) {
                 ProcessArray($rs->fields);
                 $rs->MoveNext();
         } 

Move($to)

移动内部指针到指定的列 ($to) 列数是零基的,例如,0是第一列。fields 数组将会自动更新。对于不支持内部卷动的数据库,ADODB将会自动仿真卷动。部份数据库不支持向后卷动。对大多数的数据库言,如果 $to 的位置在 EOF 之后,$to 将会被移动到资料集的最后一笔。有些无名的数据库使用 odbc 时,可能会没有动作。

注意:这个函数使用了绝对寻址,不像 Microsoft ADO

回传值是 true 或是 false。如果是 false ,这个内部指针在大多数的实际运作上并没有移动,所以 AbsolutePosition() 将会回传指针在执行 Move() 之前最后的位置

MoveFirst()

实际上是呼叫 Move(0) 。注意,有一些数据库并不支持这个函数。

MoveLast()

实际上是呼叫 Move(RecordCount() – 1)。注意,有一些数据库并不支持这个函数。

GetRowAssoc($toUpper=true)

这个函数并不能持续的以理想的方式维持关连数组的内容(每换一笔记录,就要重新执行一次)。使用 $ADODB_FETCH_MODE 共享变量来替代它。

回传一个包含了目前记录的关连式数组,数组的索引值就是字段名。字段名全都是大写的,以便存取。要取得下一笔记录,你要呼叫 MoveNext()

范例 :
Array ( [ID] => 1 [FIRSTNAME] => Caroline [LASTNAME] => Miranda [CREATED] => 2001-07-05 )

注意:不要同时使用 GetRowAssoc() $ADODB_FETCH_MODE = ADODB_FETCH_ASSOC 。因为他们有相同的功能,会彼此交互干扰。

AbsolutePage($page=-1)

回传目前的页码,需要先呼叫 PageExecute() / CachePageExecute()

AtFirstPage($status=”)

如果在第一页,回传 true (1基式),需要先呼叫 PageExecute() / CachePageExecute()

AtLastPage($status=”)

如果在最后一页,回传 true (1基式),需要先呼叫 PageExecute() / CachePageExecute()

Fields($colname)

不鼓励使用,请改以 $ADODB_FETCH_MODE 取代。

当使用原生函数库时,有些数据库函数回传具名及索引双数组( MySQL)GetRowAssoc() 并不回传结合了具名及索引的数组元素。

本函数回传由 $colname 所指栏名,在目前记录里的的字段值。

字段名区分大小写。

FetchRow()

回传目前记录内容的数组,如果是文件尾(EOF),回传 false 。注意:不要把 FetchRow MoveNext() 混用。 用法 :

$rs = $db->Execute($sql);
if ($rs)
         while ($arr = $rs->FetchRow()) {
            # process $arr
         }

FetchInto(&$array)

设定 $array 到目前的记录里。如果在文件尾(EOF),回传 PEAR_Error 对象。如果成功,回传 1 (DB_OK 常数)

如果 PEAR 未定义,当 EOF 时回传 false FetchRow() 很容易使用,请参考之前的例子。

FetchField($column_number)

回传一个对象,包含了所指字段的名称,类别及最大长度。如果最大长度不能被明确决定,将会回传 -1 行号是以 0 基为计算起点的。

FieldCount( )

回传资料集里字段数。

RecordCount( )

回传资料集里的记录笔数。如果无法从数据库驱动程序API里取得正确的数字,ADODB将会把所有的记录内容,存放在内存里,等全部取完后,再回传记录总笔数。这个内存可以藉由设定全域变量 $ADODB_COUNTERECS = false 而被取消(基于执行效能的理由)。当取消后,对某些数据库,RecordCount() 将会回传 -1 。相关支持状况,请参考前面的数据库支持表有详细的说明。

RowCount RecordCount 是同义函数。

PO_RecordCount($table, $where)

回传在资料集里的记录笔数。如果数据库不支持,那么将回传对 $table 资料表下达以 $where 为条件的 SELECT COUNT(*) 指令后回传的值。

$numrows = $rs->PO_RecordCount(“articles_table”, “group=$group”);

会回传数据库执行 SELECT COUNT(*) FROM articles_table WHERE group=$group 的结果。

FetchObject($toupper=true)

回传目前的记录为一个对象。如果 $toupper true ,那么对象字段名将会设为大写。注意:较新的 FetchNextObject() 是取得记录对象较被建议的方式,请参看后续说明。

FetchNextObject($toupper=true)

取得目前的记录成一个对象,并且自动移动到下一个记录。如果在档尾,回传 false 。如果 $toupper true ,那么对象字段名将会设为大写。

$rs = $db->Execute('select firstname,lastname from table');
if ($rs) {
         while ($o = $rs->FetchNextObject()) {
                 print "$o->FIRSTNAME, $o->LASTNAME<BR>";
         }
}

在使用 FetchNextObject() 时会影响效能,如果效能很重要,你应该使用 fields[] 数组来存取。

CurrentRow( )

目传目前资料集的记录编号,0 表示是第一笔。

AbsolutePosition( )

CurrentRow 是相同的函数,是为了和 ADO 兼容而存在的。

MetaType($nativeDBType[,$field_max_length],[$fieldobj])

设定资生数据库里的原生型别 $nativeDBType 为那一种通用资料型别,以及它的最大长度。请注意,如果长度未知,可以设为 -1 。字段对象可以使用 $fieldobj 传入。这对于像是 mysql 这一类字段对象有较多属性的数据库来说,是很有用的。 使用字段 blobsize 及比较 $field_max_length 去决定目前的字段是否为 blob 回传值:

         C: character 字段,应该使用 <input type=”text”> 标记来取值。

         X: 文字字段(Text) , 长文字字段,使用 <textarea> 标记来显示资料。

         B: Blob 字段或者大型的二位对象(像程序,图文件等)

         D: 日期字段

         T: 时间字段

         L: 逻辑字段(真假值)或位字段

         N: 数字字段,包含自动进位、编号、整数、浮点数、实数等。

         I: 整数字段

         R: 序列字段,包含了序列、自动增进整数,只对被选择的数据库作用。

Close( )

关闭目前的资料集。

发表评论

电子邮件地址不会被公开。 必填项已用*标注