Windows Note: flock() is buggy in PHP 4.0.5 and earlier on Windows. So we use a non-blocking technique with rename().

Class Reference

Function parameters with [ ] around them are optional.

$ADODB_FETCH_MODE

This is a global variable that determines how arrays are retrieved by Execute( ). You can change this variable between invocations of Execute( ) and the fetch mode will be modified.

The following constants are defined:

ADOConnection

Object that performs the connection to the database, executes SQL statements and has a set of utility functions for standardising the format of SQL statements for issues such as concatenation and date formats.

ADOConnection Fields

databaseType: Name of the database system we are connecting to. Eg. odbc or mssql or mysql.

dataProvider: The underlying mechanism used to connect to the database. Normally set to native, unless using odbc or ado.

host: Name of server or data source name (DSN) to connect to.

database: Name of the database or to connect to. If ado is used, it will hold the ado data provider.

user: Login id to connect to database. Password is not saved for security reasons.

debug: Set to true to make debug statements to appear.

concat_operator: Set to '+' or '||' normally. The operator used to concatenate strings in SQL. Used by the Concat function.

fmtDate: The format used by the DBDate function to send dates to the database. is '#Y-m-d#' for Microsoft Access, and '\'Y-m-d\'' for MySQL.

fmtTimeStamp: The format used by the DBTimeStamp function to send timestamps to the database.

true: The value used to represent true.Eg. '.T.'. for Foxpro, '1' for Microsoft SQL.

false: The value used to represent false. Eg. '.F.'. for Foxpro, '0' for Microsoft SQL.

replaceQuote: The string used to escape quotes. Eg. double single-quotes for Microsoft SQL, and backslash-quote for MySQL. Used by qstr.

autoCommit: indicates whether automatic commit is enabled. Default is true.

charSet: set the default charset to use. Currently only interbase supports this.

metaTablesSQL: SQL statement to return a list of available tables. Eg. SHOW TABLES in MySQL.

ADOConnection Main Functions

ADOConnection( )

Constructor function. Do not call this directly. Use ADONewConnection( ) instead.

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

Non-persistent connect to data source or server $host, using userid $user and password $password. If the server supports multiple databases, connect to database $database.

ADO Note: If you are using a Microsoft ADO and not OLEDB, you can set the $database parameter to the OLEDB data provider you are using.

PostgreSQL: An alternative way of connecting to the database is to pass the standard PostgreSQL connection string in the first parameter $host, and the other parameters will be ignored.

For Oracle and Oci8, the $host variable holds the optional ORACLE_HOME variable.

Returns true/false depending on connection.

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

Persistent connect to data source or server $host, using userid $user and password $password. If the server supports multiple databases, connect to database $database.

PostgreSQL and ADO: refer to notes to Connect function above.

For Oracle and Oci8, the $host variable holds the optional ORACLE_HOME variable.

Returns true/false depending on connection.

Execute($sql,$inputarr=false)

Execute SQL statement $sql and return derived class of ADORecordSet if successful. Note that a record set is always returned, even if we are executing an insert or update statement.

Returns derived class of ADORecordSet. Eg. if connecting via mysql, then ADORecordSet_mysql would be returned.False is returned if there was an error in executing the sql.

The $inputarr parameter can be used for binding variables to parameters. Below is an Oracle example:

 $conn->Execute("SELECT * FROM TABLE WHERE COND=:val", array('val'=> $val));
 

Another example, using ODBC,which uses the ? convention:

  $conn->Execute("SELECT * FROM TABLE WHERE COND=?", array($val));

Variable binding in ODBC:

$rs = $db->Execute('select * from table where val=?', array('10'));

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

CacheExecute($secs2cache,$sql,$inputarr=false)

Similar to Execute, except that the recordset is cached for $secs2cache seconds in the $ADODB_CACHE_DIR directory. If CacheExecute() is called again with the same parameters, same database, same userid, same password, and the cached recordset has not expired, the cached recordset is returned.

  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'); # cache 15 secs
  rs2html($rs); /* recordset to html table */  

If multiple calls to CacheExecute() are made and the recordset is still cached, the $secs2cache parameter does not prolong the time the recordset is cached (it is ignored). Use CacheExecute() only with SELECT statements.

Performance note: I have done some benchmarks and found that they vary so greatly that it's better to talk about when caching is of benefit. When your database server is much slower than your Web server or the database is very overloaded then ADODB's caching is good because it reduces the load on your database server. If your database server is lightly loaded or much faster than your Web server, then caching could actually reduce performance.

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

Returns a recordset if successful. Returns false otherwise. Performs a select statement, simulating PostgreSQL's SELECT statement, LIMIT $numrows OFFSET $offset clause.

In PostgreSQL, SELECT * FROM TABLE LIMIT 3 will return the first 3 records only. The equivalent is $connection->SelectLimit('SELECT * FROM TABLE',3). This functionality is simulated for databases that do not possess this feature.

And SELECT * FROM TABLE LIMIT 3 OFFSET 2 will return records 3, 4 and 5 (eg. after record 2, return 3 rows). The equivalent in ADODB is $connection->SelectLimit('SELECT * FROM TABLE',3,2).

Note that this is the opposite of MySQL's LIMIT clause. You can also set $connection->SelectLimit('SELECT * FROM TABLE',-1,10) to get rows 11 to the last row.

The last parameter $inputarr is for databases that support variable binding such as Oracle oci8. This substantially reduces SQL compilation overhead. Below is an Oracle example:

 $conn->SelectLimit("SELECT * FROM TABLE WHERE COND=:val", 100,-1,array('val'=> $val));
 

Ron Wilson reports that SelectLimit does not work with UNIONs and suggested the following solution for mssql:

>In addition, I found a way to structure the Select Union so that it will
> work with the optimization in place.  It works under MS-SQL, don't know
> about the others...  When updating the help file, you could use this as an
> example of how to structure the SQL --
No it doesn't work with MySQL.
> 
> Change:
>  Select column1 From table1
>  Union
>  Select column2 From table2
> 
> To:
>  Select * From (
>   Select column1 From table1
>   Union
>   Select column2 From table2
>   )
>  As dummytable
> 
> Ron

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

Similar to SelectLimit, except that the recordset returned is cached for $secs2cache seconds in the $ADODB_CACHE_DIR directory.

CacheFlush($sql)

Flush (delete) any cached recordsets of the SQL statement $sql in $ADODB_CACHE_DIR.

ErrorMsg()

Returns the last status or error message. This can return a string even if no error occurs. Use ErrorNo to check if an error has occurred.

Note: If debug is enabled, the SQL error message is always displayed when the Execute function is called.

ErrorNo()

Returns the last error number. Note that this is not supported by some databases such as ODBC, and in this case returns 0.

GenID($seqName = 'adodbseq')

Generate a sequence number. Works for interbase, mysql, postgresql, oci8 drivers currently. Uses $seqName as the name of the sequence. GenID() will automatically create the sequence for you if it does not exist (provided the userid has permission to do so).

UpdateBlob($table,$column,$val,$where,$blobtype='BLOB')

Usage:

	$conn->Execute('INSERT INTO blobtable (id, blobcol) VALUES (1, null)');
	$conn->UpdateBlob('blobtable','blobcol',$blob,'id=1');

Returns true if succesful, false otherwise. Supported MySQL, PostgreSQL, Oci8 and Interbase drivers. Other drivers might work.

GetUpdateSQL(&$rs, $arrFields, $forceUpdate=false)

Generate SQL to update a table given a recordset $rs, and the modified fields of the array $arrFields (which must be an associative array holding the column names and the new values) are compared with the current recordset. If $forceUpdate is true, then we also generate the SQL even if $arrFields is identical to $rs->fields. Requires the recordset to be associative.

GetInsertSQL(&$rs, $arrFields)

Generate SQL to insert into a table given a recordset $rs. Requires the query to be associative.

Used for pagination of recordset. $page is 1-based. See Example 8.

Close( )

Close the database connection. PHP4 proudly states that we no longer have to clean up at the end of the connection because the reference counting mechanism of PHP4 will automatically clean up for us.

BeginTrans( )

Begin a transaction. Turns off autoCommit. Returns true if successful. Some databases will always return false if transaction support is not available. Interbase, Oracle and MSSQL support transactions. Note that transaction support is not available for Microsoft ADO due to some bugs in PHP 4.02. Use the native transaction support of your RDBMS. Any open transactions will be rolled back when the connection is closed.

CommitTrans( )

End a transaction successfully. Returns true if successful. If the database does not support transactions, will return true also as data is always committed.

RollbackTrans( )

End a transaction, rollback all changes. Returns true if successful. If the database does not support transactions, will return false as data is never rollbacked.

ADOConnection Utility Functions

BlankRecordSet([$queryid])

Returns an empty recordset. This is useful if you require the use of some ADORecordSet utility function such as UnixDate.

Concat($s1,$s2,....)

Generates the sql string used to concatenate $s1, $s2, etc together. Uses the string in the concat_operator field to generate the concatenation. Override this function if a concatenation operator is not used, eg. MySQL.

Returns the concatenated string.

DBDate($date)

Format the $date in the format the database accepts. Uses the fmtDate field, which holds the format to use..

Returns the date as a string.

DBTimeStamp($ts)

Format the timestamp $ts in the format the database accepts. Uses the fmtTimeStamp field, which holds the format to use..

Returns the timestamp as a string.

qstr($s,[$magic_quotes_enabled=false])

Quotes a string to be sent to the database. The $magic_quotes_enabled parameter may look funny, but the idea is if you are quoting a string extracted from a POST/GET variable, then pass get_magic_quotes_gpc() as the second parameter. This will ensure that the variable is not quoted twice, once by qstr and once by the magic_quotes_gpc.

Eg. $s = $db->qstr(HTTP_GET_VARS['name'],get_magic_quotes_gpc());

Returns the quoted string.

Affected_Rows( )

Returns the number of rows affected by a update or delete statement. Returns false if function not supported.

Only supported for MySQL, MSSQL and ODBC currently. This function might only give accurate results if you perform it in a transaction if you are using persistent connections. This is because the connection you are assigned for one Execute( ) might differ from the next Execute( ).

Insert_ID( )

Returns the last autonumbering ID inserted. Returns false if function not supported.

Only supported for PostgreSQL, MySQL and MSSQL currently. PostgreSQL returns the OID, which can change on a database reload. This function might only give accurate results if you perform it in a transaction if you are using persistent connections. This is because the connection you are assigned for one Execute( ) might differ from the next Execute( ).

MetaDatabases()

Returns a list of databases available on the server as an array. You have to connect to the server first. Only available for ODBC, MySQL and ADO.

MetaTables()

Returns an array of tables and views for the current database as an array. The array should exclude system catalog tables if possible.

MetaColumns($table)

Returns an array of ADODBFieldObject's, one field object for every column of $table. Currently Sybase does not recognise date types, and ADO cannot identify the correct data type (so we default to varchar)..

ADORecordSet

When an SQL statement successfully is executed by ADOConnection->Execute($sql),an ADORecordSet object is returned. This object contains a virtual cursor so we can move from row to row, functions to obtain information about the columns and column types, and helper functions to deal with formating the results to show to the user.

ADORecordSet Fields

fields: Array containing the current row. This is not associative, but is an indexed array from 0 to columns-1. See also the function Fields, which behaves like an associative array.

dataProvider: The underlying mechanism used to connect to the database. Normally set to native, unless using odbc or ado.

blobSize: Maximum size of a char, string or varchar object before it is treated as a Blob (Blob's should be shown with textarea's). See the MetaType function.

sql: Holds the sql statement used to generate this record set.

canSeek: Set to true if Move( ) function works.

EOF: True if we have scrolled the cursor past the last record.

ADORecordSet Functions

ADORecordSet( )

Constructer. Normally you never call this function yourself.

GetAssoc([$force_array])

Generates an associative array from the recordset if the number of columns is greater than 2. The array is generated from the current cursor position till EOF. The first column of the recordset becomes the key to the rest of the array. If the columns is equal to two, then the key directly maps to the value unless $force_array is set to true, when an array is created for each key. Inspired by PEAR's getAssoc.

Example:

We have the following data in a recordset:

row1: Apple, Fruit, Edible
row2: Cactus, Plant, Inedible
row3: Rose, Flower, Edible

GetAssociation will generate the following associative array:

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

Returns:

The associative array, or false if an error occurs.

GetArray([$number_of_rows])

Generate an array from the current cursor position, indexed from 0 to $number_of_rows - 1. If $number_of_rows is undefined, till EOF.

GetRows([$number_of_rows])

Synonym for GetArray() for compatibility with Microsoft ADO.

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

Generate a HTML menu (<select><option><option></select>). The first column of the recordset (fields[0]) will hold the string to display in the option tags. If the recordset has more than 1 column, the second column (fields[1]) is the value to send back to the web server.. The menu will be given the name $name.

If $default_str is defined, then if $default_str == fields[0], that field is selected. If $blank1stItem is true, the first option is empty. $Default_str can be array for a multiple select listbox.

To get a listbox, set the $size to a non-zero value (or pass $default_str as an array). If $multiple_select is true then a listbox will be generated with $size items (or if $size==0, then 5 items) visible, and we will return an array to a server. Lastly use $moreAttr to add additional attributes such as javascript or styles.

Menu Example 1: GetMenu('menu1','A',true) will generate a menu: A B C for the data (A,1), (B,2), (C,3). Also see example 5.

Menu Example 2: For the same data, GetMenu('menu1',array('A','B'),false) will generate a menu with both A and B selected:
A B C

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

This is nearly identical to GetMenu, except that the $default_str is matched to fields[1] (the option values).

Menu Example 3: Given the data in menu example 2, GetMenu2('menu1',array('1','2'),false) will generate a menu with both A and B selected in menu example 2, but this time the selection is based on the 2nd column, which holds the values to return to the Web server.

UserDate($str, [$fmt])

Converts the date string $str to another format.UserDate calls UnixDate to parse $str, and $fmt defaults to Y-m-d if not defined.

UserTimeStamp($str, [$fmt])

Converts the timestamp string $str to another format. UserTimeStamp calls UnixTimeStamp to parse $str, and $fmt defaults to Y-m-d H:i:s if not defined.

UnixDate($str)

Parses the date string $str and returns it in unix mktime format (eg. a number indicating the seconds after January 1st, 1970). Expects the date to be in Y-m-d h:i:s format, except for Sybase and Microsoft SQL Server, where M d Y is also accepted (the 3 letter month strings are controlled by a global array, which might need localisation).

UnixTimeStamp($str)

Parses the timestamp string $str and returns it in unix mktime format (eg. a number indicating the seconds after January 1st, 1970). Expects the date to be in Y-m-d H:i:s format, except for Sybase and Microsoft SQL Server, where M d Y h:i:sA is also accepted (the 3 letter month strings are controlled by a global array, which might need localisation)..

MoveNext( )

Move the internal cursor to the next row. The fields array is automatically updated. Return false if unable to do so, otherwise true..

Move($to)

Moves the internal cursor to a specific row $to. Rows are zero-based eg. 0 is the first row. The fields array is automatically updated. For databases that do not support scrolling internally, ADODB will simulate forward scrolling. Some databases do not support backward scrolling. If the $to position is after the EOF, $to will move to the end of the RecordSet for most databases. Some obscure databases using odbc might not behave this way.

Note: This function uses absolute positioning, unlike Microsoft's ADO.

Returns true or false. If false, the internal cursor is not moved in most implementations, so AbsolutePosition( ) will return the last cursor position before the Move( ).

MoveFirst()

Internally calls Move(0). Note that some databases do not support this function.

MoveLast()

Internally calls Move(RecordCount()-1). Note that some databases do not support this function.

GetRowAssoc()

Returns an associative array containing the current row. The keys to the array are the column names. The column names are upper-cased for easy access. To get the next row, you will still need to call MoveNext().

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

AtFirstPage($status='')

Returns true if at first page (1-based). Requires PageExecute()/CachePageExecute() to be called. See Example 8.

AtLastPage($status='')

Returns true if at last page (1-based). Requires PageExecute()/CachePageExecute() to be called. See Example 8.

Fields($colname)

Some database extensions (eg. MySQL) return arrays that are both associative and indexed if you use the native extensions. GetRowAssoc() does not return arrays that combine associative and indexed elements.

Returns the value of the associated column $colname for the current row. The column name is case-insensitive.

FetchField($column_number)

Returns an object containing the name, type and max_length of the associated field. If the max_length cannot be determined reliably, it will be set to -1. The column numbers are zero-based. See example 2.

FieldCount( )

Returns the number of fields (columns) in the record set.

RecordCount( )

Returns the number of rows in the record set. Note that some databases do not support this, and will return -1. RowCount is a synonym for RecordCount.

The following databases are known to return -1. Oci8, Oracle, Interbase.

FetchObject($toupper=true)

Returns the current row as an object. If you set $toupper to true, then the object fields are set to upper-case. Note: The newer FetchNextObject() is the recommended way of accessing rows as objects. See below.

FetchNextObject($toupper=true)

Gets the current row as an object and moves to the next row automatically. Returns false if at end-of-file. If you set $toupper to true, then the object fields are set to upper-case.

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

There is some trade-off in speed in using FetchNextObject(). If performance is important, you should access rows with the fields[] array.

CurrentRow( )

Returns the current row of the record set. 0 is the first row.

AbsolutePosition( )

Synonym for CurrentRow for compatibility with ADO. Returns the current row of the record set. 0 is the first row.

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

Determine what generic meta type a database field type is given its native type $nativeDBType and the length of the field $field_max_length. Note that field_max_length can be -1 if it is not known. The field object returned by the database driver can be passed in $fieldobj. This is useful for databases such as mysql which has additional properties in the field object such as primary_key.

Uses the field blobSize and compares it with $field_max_length to determine whether the character field is actually a blob.

Returns:

• C: Character fields that should be shown in a <input type="text"> tag.
• B: Blob, or large text fields that should be shown in a <textarea>
• D: Date field
• T: Timestamp field
• L: Logical field (boolean or bit-field)
• N: Numeric field. Includes decimal, numeric, floating point, and real.
• I: Integer field.
• R: Counter or Autoincrement field. Must be numeric.

Close( )

Close the recordset.

function rs2html($adorecordset,[$tableheader_attributes], [$col_titles])

This is a standalone function (rs2html = recordset to html) that is similar to PHP's odbc_result_all function, it prints a ADORecordSet, $adorecordset as a HTML table. $tableheader_attributes allow you to control the table cellpadding, cellspacing and border attributes. Lastly you can replace the database column names with your own column titles with the array $col_titles. This is designed more as a quick debugging mechanism, not a production table recordset viewer.

You will need to include the file tohtml.inc.php.

Example of rs2html:

<?
include('tohtml.inc.php'); // load code common to ADODB 
include('adodb.inc.php'); // load code common to ADODB 
$conn = &ADONewConnection('mysql');   // create a connection 
$conn->PConnect('localhost','userid','','agora');// connect to MySQL, agora db
$sql = 'select CustomerName, CustomerID from customers'; 
$rs   = $conn->Execute($sql); 
rs2html($rs,'border=2 cellpadding=3',array('Customer Name','Customer ID'));
?>

Differences Between this ADODB library and Microsoft ADO

1. ADODB only supports recordsets created by a connection object. Recordsets cannot be created independently.
2. ADO properties are implemented as functions in ADODB. This makes it easier to implement any enhanced ADO functionality in the future.
3. ADODB's ADORecordSet->Move() uses absolute positioning, not relative. Bookmarks are not supported.
4. ADORecordSet->AbsolutePosition() cannot be used to move the record cursor.
5. ADO Parameter objects are not supported.
6. Recordset properties for paging records are not supported.

Database Driver Guide

This describes how to create a class to connect to a new database. To ensure there is no duplication of work, kindly email me at jlim@natsoft.com.my if you decide to create such a class.

First decide on a name in lower case to call the database type. Let's say we call it xbase.

Then we need to create two classes ADOConnection_xbase and ADORecordSet_xbase in the file adodb-xbase.inc.php.

The simplest form of database driver is an adaptation of an existing ODBC driver. Then we just need to create the class ADOConnection_xbase extends ADOConnection_odbc to support the new date and timestamp formats, the concatenation operator used, true and false. For the ADORecordSet_xbase extends ADORecordSet_odbc we need to change the MetaType function. See adodb-vfp.inc.php as an example.

More complicated is a totally new database driver that connects to a new PHP extension. Then you will need to implement several functions. Fortunately, you do not have to modify most of the complex code. You only need to override a few stub functions. See adodb-mysql.inc.php for example.

The default date format of ADODB internally is YYYY-MM-DD (Ansi-92). All dates should be converted to that format when passing to an ADODB date function. See Oracle for an example how we use ALTER SESSION to change the default date format in _pconnect _connect.

ADOConnection Functions to Override

Defining a constructor for your ADOConnection derived function is optional. There is no need to call the base class constructor.

_connect: Low level implementation of Connect. Returns true or false. Should set the _connectionID.

_pconnect: Low level implemention of PConnect. Returns true or false. Should set the _connectionID.

_query: Execute a query. Returns the queryID, or false.

_close: Close the connection -- PHP should clean up all recordsets.

ErrorMsg: Stores the error message in the private variable _errorMsg.

The ADOConnection functions BeginTrans( ), CommitTrans( ), RollbackTrans( ) are reserved for future expansion.

ADOConnection Fields to Set

_bindInputArray: Set to true if binding of parameters for SQL inserts and updates is allowed using ?, eg. as with ODBC.

fmtDate

fmtTimeStamp

true

false

concat_operator

replaceQuote

hasLimit support SELECT * FROM TABLE LIMIT 10 of MySQL.

hasTop support Microsoft style SELECT TOP 10 * FROM TABLE.

ADORecordSet Functions to Override

You will need to define a constructor for your ADORecordSet derived class that calls the parent class constructor.

FetchField: as documented above in ADORecordSet

_initrs: low level initialization of the recordset: setup the _numOfRows and _numOfFields fields -- called by the constructor.

_seek: seek to a particular row. Do not load the data into the fields array. This is done by _fetch. Returns true or false. Note that some implementations such as Interbase do not support seek. Set canSeek to false.

_fetch: fetch a row using the database extension function and then move to the next row. Sets the fields array. If the parameter $ignore_fields is true then there is no need to populate the fields array, just move to the next row. then Returns true or false.

_close: close the recordset

Fields: If the array row returned by the PHP extension is not an associative one, you will have to override this. See adodb-odbc.inc.php for an example. For databases such as MySQL and MSSQL where an associative array is returned, there is no need to override this function.

ADOConnection Fields to Set

canSeek: Set to true if the _seek function works.

ToDo:

See the RoadMap article.