mirror of
https://github.com/EGroupware/egroupware.git
synced 2024-11-30 11:53:57 +01:00
3707 lines
196 KiB
HTML
3707 lines
196 KiB
HTML
<html>
|
||
<head>
|
||
<title>ADODB Manual</title>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||
|
||
|
||
<style>
|
||
pre {
|
||
background-color: #eee;
|
||
padding: 0.75em 1.5em;
|
||
font-size: 12px;
|
||
border: 1px solid #ddd;
|
||
}
|
||
</style>
|
||
</head>
|
||
<body bgcolor="#FFFFFF">
|
||
|
||
<h2>ADOdb Library for PHP</h2>
|
||
<p>V4.50 6 July 2004 (c) 2000-2004 John Lim (jlim#natsoft.com)</p>
|
||
<p><font size="1">This software is dual licensed using BSD-Style and LGPL. This
|
||
means you can use it in compiled proprietary and commercial products.</font></p>
|
||
|
||
|
||
<table border=1><tr><td><font color=red>Kindly note that the ADOdb home page has moved to <a href=http://adodb.sourceforge.net/>http://adodb.sourceforge.net/</a> because of the persistent
|
||
unreliability of http://php.weblogs.com. <b>Please change your links</b>!</font></td></tr></table>
|
||
<p>Useful ADOdb links: <a href=http://adodb.sourceforge.net/#download>Download</a> <a href=http://adodb.sourceforge.net/#docs>Other Docs</a>
|
||
|
||
<p><a href="#intro"><b>Introduction</b></a><b><br>
|
||
<a href="#features">Unique Features</a><br>
|
||
<a href="#users">How People are using ADOdb</a><br>
|
||
<a href="#bugs">Feature Requests and Bug Reports</a><br>
|
||
</b><b><a href="#install">Installation</a><br>
|
||
<a href="#mininstall">Minimum Install</a><br>
|
||
<a href="#coding">Initializing Code and Connectioning to Databases</a><br>
|
||
</b><font size="2"> <a href=#dsnsupport>Data Source Name (DSN) Support</a></font> <a href=#connect_ex>Connection Examples</a></font> <br>
|
||
<b><a href="#speed">High Speed ADOdb - tuning tips</a></b><br>
|
||
<b><a href="#hack">Hacking and Modifying ADOdb Safely</a><br>
|
||
<a href="#php5">PHP5 Features</a></b><br>
|
||
<font size="2"><a href=#php5iterators>foreach iterators</a> <a href=#php5exceptions>exceptions</a></font><br>
|
||
<b> <a href="#drivers">Supported Databases</a></b><br>
|
||
<b> <a href="#quickstart">Tutorials</a></b><br>
|
||
<a href="#ex1">Example 1: Select</a><br>
|
||
<a href="#ex2">Example 2: Advanced Select</a><br>
|
||
<a href="#ex3">Example 3: Insert</a><br>
|
||
<a href="#ex4">Example 4: Debugging</a> <a href="#exrs2html">rs2html
|
||
example</a><br>
|
||
<a href="#ex5">Example 5: MySQL and Menus</a><br>
|
||
<a href="#ex6">Example 6: Connecting to Multiple Databases at once</a> <br>
|
||
<a href="#ex7">Example 7: Generating Update and Insert SQL</a> <br>
|
||
<a href="#ex8">Example 8: Implementing Scrolling with Next and Previous</a><br>
|
||
<a href="#ex9">Example 9: Exporting in CSV or Tab-Delimited Format</a> <br>
|
||
<a href="#ex10">Example 10: Custom filters</a><br>
|
||
<a href="#ex11">Example 11: Smart Transactions</a><br>
|
||
<br>
|
||
<b> <a href="#errorhandling">Using Custom Error Handlers and PEAR_Error</a><br>
|
||
<a href="#DSN">Data Source Names</a><br>
|
||
<a href="#caching">Caching</a><br>
|
||
<a href="#pivot">Pivot Tables</a></b>
|
||
<p><a href="#ref"><b>REFERENCE</b></a>
|
||
<p> <font size="2">Variables: <a href="#adodb_countrecs">$ADODB_COUNTRECS</a>
|
||
<a href=#adodb_ansi_padding_off>$ADODB_ANSI_PADDING_OFF</a>
|
||
<a href="#adodb_cache_dir">$ADODB_CACHE_DIR</a> <BR>
|
||
<a href=#force_type>$ADODB_FORCE_TYPE</a>
|
||
<a href=#adodb_fetch_mode>$ADODB_FETCH_MODE</a>
|
||
<a href=#adodb_lang>$ADODB_LANG</a> <br>
|
||
Constants: </font><font size="2"><a href=#adodb_assoc_case>ADODB_ASSOC_CASE</a>
|
||
</font><br>
|
||
<a href="#ADOConnection"><b> ADOConnection</b></a><br>
|
||
<font size="2">Connections: <a href="#connect">Connect</a> <a href="#pconnect">PConnect</a>
|
||
<a href="#nconnect">NConnect</a> <br>
|
||
Executing SQL: <a href="#execute">Execute</a> <a href="#cacheexecute"><i>CacheExecute</i></a>
|
||
<a href="#SelectLimit">SelectLimit</a> <a href="#cacheSelectLimit"><i>CacheSelectLimit</i></a>
|
||
<a href="#param">Param</a> <a href="#prepare">Prepare</a> <a href=#preparesp>PrepareSP</a>
|
||
<a href="#inparameter">InParameter</a> <a href="#outparameter">OutParameter</a>
|
||
<br>
|
||
<a href="#getone">GetOne</a>
|
||
<a href="#cachegetone"><i>CacheGetOne</i></a> <a href="#getrow">GetRow</a> <a href="#cachegetrow"><i>CacheGetRow</i></a>
|
||
<a href="#getall">GetAll</a> <a href="#cachegetall"><i>CacheGetAll</i></a> <a href="#getcol">GetCol</a>
|
||
<a href="#cachegetcol"><i>CacheGetCol</i></a> <a href="#getassoc1">GetAssoc</a> <a href="#cachegetassoc"><i>CacheGetAssoc</i></a> <a href="#replace">Replace</a>
|
||
<br>
|
||
<a href="#executecursor">ExecuteCursor</a>
|
||
(oci8 only)<br>
|
||
Generates SQL strings: <a href="#getupdatesql">GetUpdateSQL</a> <a href="#getinsertsql">GetInsertSQL</a>
|
||
<a href="#concat">Concat</a> <a href="#ifnull">IfNull</a> <a href="#length">length</a> <a href="#random">random</a> <a href="#substr">substr</a>
|
||
<a href="#qstr">qstr</a> <a href="#param">Param</a>
|
||
<a href="#prepare"></a><a href="#OffsetDate">OffsetDate</a> <a href="#SQLDate">SQLDate</a>
|
||
<a href="#dbdate">DBDate</a> <a href="#dbtimestamp"></a> <a href="#dbtimestamp">DBTimeStamp</a>
|
||
<br>
|
||
Blobs: <a href="#updateblob">UpdateBlob</a> <a href="#updateclob">UpdateClob</a>
|
||
<a href="#updateblobfile">UpdateBlobFile</a> <a href="#blobencode">BlobEncode</a>
|
||
<a href="#blobdecode">BlobDecode</a><br>
|
||
Paging/Scrolling: <a href="#pageexecute">PageExecute</a> <a href="#cachepageexecute">CachePageExecute</a><br>
|
||
Cleanup: <a href="#cacheflush">CacheFlush</a> <a href="#Close">Close</a><br>
|
||
Transactions: <a href="#starttrans">StartTrans</a> <a href="#completetrans">CompleteTrans</a>
|
||
<a href="#failtrans">FailTrans</a> <a href="#hasfailedtrans">HasFailedTrans</a>
|
||
<a href="#begintrans">BeginTrans</a> <a href="#committrans">CommitTrans</a>
|
||
<a href="#rollbacktrans">RollbackTrans</a> <br>
|
||
Fetching Data: </font> <font size="2"><a href="#setfetchmode">SetFetchMode</a><br>
|
||
Strings: <a href="#concat">concat</a> <a href="#length">length</a> <a href="#qstr">qstr</a> <a href="#quote">quote</a> <a href="#substr">substr</a><br>
|
||
Dates: <a href="#dbdate">DBDate</a> <a href="#dbtimestamp">DBTimeStamp</a> <a href="#unixdate">UnixDate</a>
|
||
<a href="#unixtimestamp">UnixTimeStamp</a> <a href="#OffsetDate">OffsetDate</a>
|
||
<a href="#SQLDate">SQLDate</a> <br>
|
||
Row Management: <a href="#affected_rows">Affected_Rows</a> <a href="#inserted_id">Insert_ID</a> <a href=#rowlock>RowLock</a>
|
||
<a href="#genid">GenID</a> <a href=#createseq>CreateSequence</a> <a href=#dropseq>DropSequence</a>
|
||
<br>
|
||
Error Handling: <a href="#errormsg">ErrorMsg</a> <a href="#errorno">ErrorNo</a>
|
||
<a href="#metaerror">MetaError</a> <a href="#metaerrormsg">MetaErrorMsg</a><br>
|
||
Data Dictionary (metadata): <a href="#metadatabases">MetaDatabases</a> <a href="#metatables">MetaTables</a>
|
||
<a href="#metacolumns">MetaColumns</a> <a href="#metacolumnames">MetaColumnNames</a>
|
||
<a href="#metaprimarykeys">MetaPrimaryKeys</a> <a href="#metaforeignkeys">MetaForeignKeys</a>
|
||
<a href="#serverinfo">ServerInfo</a> <br>
|
||
Statistics and Query-Rewriting: <a href="#logsql">LogSQL</a> <a href="#fnexecute">fnExecute
|
||
and fnCacheExecute</a><br>
|
||
</font><font size="2">Deprecated: <a href="#bind">Bind</a> <a href="#blankrecordset">BlankRecordSet</a>
|
||
<a href="#parameter">Parameter</a></font>
|
||
<a href="#adorecordSet"><b><br>
|
||
ADORecordSet</b></a><br>
|
||
<font size="2">
|
||
Returns one field: <a href="#fields">Fields</a><br>
|
||
Returns one row:<a href="#fetchrow">FetchRow</a> <a href="#fetchinto">FetchInto</a>
|
||
<a href="#fetchobject">FetchObject</a> <a href="#fetchnextobject">FetchNextObject</a>
|
||
<a href="#fetchobj">FetchObj</a> <a href="#fetchnextobj">FetchNextObj</a>
|
||
<a href="#getrowassoc">GetRowAssoc</a> <br>
|
||
Returns all rows:<a href="#getarray">GetArray</a> <a href="#getrows">GetRows</a>
|
||
<a href="#getassoc">GetAssoc</a><br>
|
||
Scrolling:<a href="#move">Move</a> <a href="#movenext">MoveNext</a> <a href="#movefirst">MoveFirst</a>
|
||
<a href="#movelast">MoveLast</a> <a href="#abspos">AbsolutePosition</a> <a href="#currentrow">CurrentRow</a>
|
||
<a href="#atfirstpage">AtFirstPage</a> <a href="#atlastpage">AtLastPage</a>
|
||
<a href="#absolutepage">AbsolutePage</a> </font> <font size="2"><br>
|
||
Menu generation:<a href="#getmenu">GetMenu</a> <a href="#getmenu2">GetMenu2</a><br>
|
||
Dates:<a href="#userdate">UserDate</a> <a href="#usertimestamp">UserTimeStamp</a>
|
||
<a href="#unixdate">UnixDate</a> <a href="#unixtimestamp">UnixTimeStamp<br>
|
||
</a>Recordset Info:<a href="#recordcount">RecordCount</a> <a href="#po_recordcount">PO_RecordSet</a>
|
||
<a href="#nextrecordset">NextRecordSet</a><br>
|
||
Field Info:<a href="#fieldcount">FieldCount</a> <a href="#fetchfield">FetchField</a>
|
||
<a href="#metatype">MetaType</a><br>
|
||
Cleanup: <a href="#rsclose">Close</a></font> <font size="2"></font>
|
||
<p><font size="2"><a href="#rs2html"><b>rs2html</b></a> <a href="#exrs2html">example</a></font><br>
|
||
<a href="#adodiff">Differences between ADOdb and ADO</a><br>
|
||
<a href="#driverguide"><b>Database Driver Guide<br>
|
||
</b></a><b><a href="#changes">Change Log</a></b><br>
|
||
</p>
|
||
<h2>Introduction<a name="intro"></a></h2>
|
||
<p>PHP's database access functions are not standardised. This creates a need for
|
||
a database class library to hide the differences between the different database
|
||
API's (encapsulate the differences) so we can easily switch databases. PHP 4.0.5 or later
|
||
is now required (because we use array-based str_replace).</p>
|
||
<p>We currently support MySQL, Oracle, Microsoft SQL Server, Sybase, Sybase SQL Anywhere, Informix,
|
||
PostgreSQL, FrontBase, SQLite, Interbase (Firebird and Borland variants), Foxpro, Access, ADO, DB2, SAP DB and ODBC.
|
||
We have had successful reports of connecting to Progress and CacheLite via ODBC. We hope more people
|
||
will contribute drivers to support other databases.</p>
|
||
<p>PHP4 supports session variables. You can store your session information using
|
||
ADOdb for true portability and scalability. See adodb-session.php for more information.</p>
|
||
<p>Also read <a href="http://php.weblogs.com/portable_sql">http://php.weblogs.com/portable_sql</a>
|
||
(also available as tips_portable_sql.htm in the release) for tips on writing
|
||
portable SQL.</p>
|
||
<h2>Unique Features of ADOdb<a name="features"></a></h2>
|
||
<ul>
|
||
<li><b>Easy for Windows programmers</b> to adapt to because many of the conventions
|
||
are similar to Microsoft's ADO.</li>
|
||
<li>Unlike other PHP database classes which focus only on select statements,
|
||
<b>we provide support code to handle inserts and updates which can be adapted
|
||
to multiple databases quickly.</b> Methods are provided for date handling,
|
||
string concatenation and string quoting characters for differing databases.</li>
|
||
<li>A<b> metatype system </b>is built in so that we can figure out that types
|
||
such as CHAR, TEXT and STRING are equivalent in different databases.</li>
|
||
<li><b>Easy to port</b> because all the database dependant code are stored in
|
||
stub functions. You do not need to port the core logic of the classes.</li>
|
||
<li><b>Portable table and index creation</b> with the <a href=docs-datadict.htm>datadict</a> classes.
|
||
<li><b>Database performance monitoring and SQL tuning</b> with the <a href=docs-perf.htm>performance monitoring</a> classes.
|
||
<li><b>Database-backed sessions</b> with the <a href=docs-session.htm>session management</a> classes. Supports session expiry notification.
|
||
</ul>
|
||
<h2>How People are using ADOdb<a name="users"></a></h2>
|
||
Here are some examples of how people are using ADOdb (for a much longer list,
|
||
visit <a href="http://php.weblogs.com/adodb-cool-applications">http://php.weblogs.com/adodb-cool-applications</a>):
|
||
<ul>
|
||
<li><a href="http://phplens.com/">PhpLens</a> is a commercial data grid component that allows both cool Web designers and serious unshaved programmers to develop and maintain databases on the Web easily. Developed by the author of ADOdb.<p>
|
||
|
||
<li><a href="http://www.interakt.ro/phakt/">PHAkt: PHP Extension for DreamWeaver Ultradev</a> allows you to script PHP in the popular Web page editor. Database handling provided by ADOdb.<p>
|
||
|
||
<li><a href="http://www.andrew.cmu.edu/~rdanyliw/snort/snortacid.html">Analysis Console for Intrusion Databases</a> (ACID): PHP-based analysis engine to search and process a database of security incidents generated by security-related software such as IDSes and firewalls (e.g. Snort, ipchains). By Roman Danyliw.<p>
|
||
|
||
<li><a href="http://www.postnuke.com/">PostNuke</a> is a very popular free content management
|
||
system and weblog system. It offers full CSS support, HTML 4.01 transitional compliance throughout, an advanced blocks system, and is fully multi-lingual enabled. <p>
|
||
|
||
<li><a href=http://www.auto-net.no/easypublish.php?page=index&lang_id=2>EasyPublish CMS</a> is another free content management system for managing information and integrated modules on your internet, intranet- and extranet-sites. From Norway.<p>
|
||
|
||
<li><a href="http://nola.noguska.com/">NOLA</a> is a full featured accounting, inventory, and job tracking application. It is licensed under the GPL, and developed by Noguska.
|
||
</ul><p>
|
||
|
||
<h2>Feature Requests and Bug Reports<a name="bugs"></a></h2>
|
||
<p>Feature requests and bug reports can be emailed to <a href="mailto:jlim#natsoft.com.my">jlim#natsoft.com.my</a>
|
||
or posted to the ADOdb Help forums at <a href="http://phplens.com/lens/lensforum/topics.php?id=4">http://phplens.com/lens/lensforum/topics.php?id=4</a>.</p>
|
||
<h2>Installation Guide<a name="install"></a></h2>
|
||
<p>Make sure you are running PHP 4.0.5 or later.
|
||
Unpack all the files into a directory accessible by your webserver.</p>
|
||
<p>To test, try modifying some of the tutorial examples. Make sure you customize
|
||
the connection settings correctly. You can debug using <i>$db->debug = true</i> as shown below:</p>
|
||
<pre><?php
|
||
include('adodb/adodb.inc.php');
|
||
$db = <a href="#adonewconnection">ADONewConnection</a>($dbdriver); # eg 'mysql' or 'postgres'
|
||
$db->debug = true;
|
||
$db-><a href="#connect">Connect</a>($server, $user, $password, $database);
|
||
$rs = $db-><a href="#execute">Execute</a>('select * from some_small_table');
|
||
print "<pre>";
|
||
print_r($rs-><a href="#getrows">GetRows</a>());
|
||
print "</pre>";
|
||
?></pre>
|
||
|
||
<h3>Minimum Install<a name=mininstall></a></h3>
|
||
<p>For developers who want to release a minimal install of ADOdb, you will need:
|
||
<ul>
|
||
<li>adodb.inc.php
|
||
<li>adodb-lib.inc.php
|
||
<li>adodb-time.inc.php
|
||
<li>drivers/adodb-$database.inc.php
|
||
<li>license.txt (for legal reasons)
|
||
<li>adodb-php4.inc.php
|
||
<li>adodb-iterator.inc.php
|
||
</ul>
|
||
Optional:
|
||
<ul>
|
||
<li>adodb-error.inc.php and lang/adodb-$lang.inc.php (if you use MetaError())
|
||
<li>adodb-csvlib.inc.php (if you use cached recordsets - CacheExecute(), etc)
|
||
<li>adodb-exceptions.inc.php and adodb-errorhandler.inc.php (if you use adodb error handler or php5 exceptions).
|
||
</ul>
|
||
|
||
<h3>Code Initialization Examples<a name="coding"></a></h3>
|
||
<p>When running ADOdb, at least two files are loaded. First is adodb/adodb.inc.php,
|
||
which contains all functions used by all database classes. The code specific
|
||
to a particular database is in the adodb/driver/adodb-????.inc.php file.</p>
|
||
<a name="adonewconnection"></a>
|
||
<p>For example, to connect to a mysql database:</p>
|
||
<pre>
|
||
include('/path/to/set/here/adodb.inc.php');
|
||
$conn = &ADONewConnection('mysql');
|
||
</pre>
|
||
<p>Whenever you need to connect to a database, you create a Connection object
|
||
using the <b>ADONewConnection</b>($driver) function.
|
||
<b>NewADOConnection</b>($driver) is an alternative name for the same function.</p>
|
||
|
||
<p>At this point, you are not connected to the database (no longer true if you pass in a <a href=#dsnsupport>dsn</a>). You will first need to decide
|
||
whether to use <i>persistent</i> or <i>non-persistent</i> connections. The advantage of <i>persistent</i>
|
||
connections is that they are faster, as the database connection is never closed (even
|
||
when you call Close()). <i>Non-persistent </i>connections take up much fewer resources though,
|
||
reducing the risk of your database and your web-server becoming overloaded.
|
||
<p>For persistent connections,
|
||
use $conn-><a href="#pconnect">PConnect()</a>,
|
||
or $conn-><a href="#connect">Connect()</a> for non-persistent connections.
|
||
Some database drivers also support <a href="#nconnect">NConnect()</a>, which forces
|
||
the creation of a new connection.
|
||
|
||
<a name=connection_gotcha></a>
|
||
<p><b>Connection Gotcha</b>: If you create two connections, but both use the same userid and password,
|
||
PHP will share the same connection. This can cause problems if the connections are meant to
|
||
different databases. The solution is to always use different userid's for different databases,
|
||
or use NConnect().
|
||
|
||
<a name=dsnsupport></a>
|
||
<h3>Data Source Name (DSN) Support</h3>
|
||
<p> Since ADOdb 4.51, you can connect to a database by passing a dsn to NewADOConnection() (or ADONewConnection, which is
|
||
the same function). The dsn format is:
|
||
<pre>
|
||
$driver://$username:$password@hostname/$database?options[=value]
|
||
</pre><p>
|
||
NewADOConnection() calls Connect() or PConnect() internally for you. If the connection fails, false is returned.
|
||
<pre>
|
||
<font color=#008000># non-persistent connection</font>
|
||
$dsn = 'mysql://root:pwd@localhost/mydb';
|
||
$db = NewADOConnection($dsn);
|
||
if (!$db) die("Connection failed");
|
||
|
||
<font color=#008000># no need to call connect/pconnect!</font>
|
||
$arr = $db->GetArray("select * from table");
|
||
|
||
<font color=#008000># persistent connection</font>
|
||
$dsn2 = 'mysql://root:pwd@localhost/mydb?persist';
|
||
</pre>
|
||
<p>
|
||
If you have special characters such as /:? in your dsn, then you need to rawurlencode them first:
|
||
<pre>
|
||
$pwd = rawurlencode($pwd);
|
||
$dsn = "mysql://root:$pwd@localhost/mydb";
|
||
</pre>
|
||
<p>
|
||
Legal options are:
|
||
<p>
|
||
<table align=center border=1><tr><td>For all drivers<td>
|
||
'persist', 'persistent', 'debug', 'fetchmode'
|
||
<tr><td>Interbase/Firebird
|
||
<td>
|
||
'dialect',
|
||
'charset',
|
||
'buffers'
|
||
<tr><td>M'soft ADO<td>
|
||
'charpage'
|
||
|
||
<tr><td>MySQL<td>
|
||
'clientflags'
|
||
<tr><td>MySQLi<td>
|
||
'port', 'socket', 'clientflags'
|
||
</table>
|
||
<p>
|
||
For all drivers, when the options <i>persist</i> or <i>persistent</i> are set, a persistent connection is forced.
|
||
The <i>debug</i> option enables debugging. The <i>fetchmode</i> calls <a href=#setfetchmode>SetFetchMode()</a>.
|
||
If no value is defined for an option, then the value is set to 1.
|
||
<p>
|
||
ADOdb DSN's are compatible with version 1.0 of PEAR DB's DSN format.
|
||
<a name=connect_ex>
|
||
<h3>Examples of Connecting to Databases</h3>
|
||
<h4>MySQL and Most Other Database Drivers</h4>
|
||
<p>MySQL connections are very straightforward, and the parameters are identical
|
||
to mysql_connect:</p>
|
||
<pre>
|
||
$conn = &ADONewConnection('mysql');
|
||
$conn->PConnect('localhost','userid','password','database');
|
||
|
||
<font color=#008000># or dsn </font>
|
||
$dsn = 'mysql://user:pwd@localhost/mydb';
|
||
$conn = ADONewConnection($dsn); # no need for Connect()
|
||
|
||
<font color=#008000># or persistent dsn</font>
|
||
$dsn = 'mysql://user:pwd@localhost/mydb?persist';
|
||
$conn = ADONewConnection($dsn); # no need for PConnect()
|
||
|
||
<font color=#008000># a more complex example:</font>
|
||
$pwd = urlencode($pwd);
|
||
$flags = MYSQL_CLIENT_COMPRESS;
|
||
$dsn = "mysql://user:$pwd@localhost/mydb?persist&clientflags=$flags";
|
||
$conn = ADONewConnection($dsn); # no need for PConnect()
|
||
</pre>
|
||
<p> For most drivers, you can use the standard function: Connect($server, $user, $password, $database), or
|
||
a <a href=dsnsupport>DSN</a> since ADOdb 4.51. Exceptions to this are listed below.
|
||
<h4>PostgreSQL</h4>
|
||
<p>PostgreSQL accepts connections using: </p>
|
||
<p>a. the standard connection string:</p>
|
||
<pre>
|
||
$conn = &ADONewConnection('postgres7');
|
||
$conn->PConnect('host=localhost port=5432 dbname=mary');</pre>
|
||
<p> b. the classical 4 parameters:</p>
|
||
<pre>
|
||
$conn->PConnect('localhost','userid','password','database');
|
||
</pre>
|
||
<p>c. dsn:
|
||
<pre>
|
||
$dsn = 'postgres7://user:pwd@localhost/mydb?persist'; # persist is optional
|
||
$conn = ADONewConnection($dsn); # no need for Connect/PConnect
|
||
</pre>
|
||
<a name=ldap></a>
|
||
|
||
<h4>LDAP</h4>
|
||
<p>Here is an example of querying a LDAP server. Thanks to Josh Eldridge for the driver and this example:
|
||
<pre>
|
||
<?php
|
||
require('/path/to/adodb.inc.php');
|
||
|
||
$host = 'ldap.baylor.edu';
|
||
$ldapbase = 'ou=People,o=Baylor University,c=US';
|
||
|
||
$ldap = NewADOConnection( 'ldap' );
|
||
$ldap->Connect( $host, $user_name='', $password='', $ldapbase );
|
||
|
||
echo "<pre>";
|
||
|
||
print_r( $ldap->ServerInfo() );
|
||
$ldap->SetFetchMode(ADODB_FETCH_ASSOC);
|
||
$userName = 'eldridge';
|
||
$filter="(|(CN=$userName*)(sn=$userName*)(givenname=$userName*)(uid=$userName*))";
|
||
|
||
$rs = $ldap->Execute( $filter );
|
||
if ($rs)
|
||
while ($arr = $rs->FetchRow()) {
|
||
print_r($arr);
|
||
}
|
||
|
||
$rs = $ldap->Execute( $filter );
|
||
if ($rs)
|
||
while (!$rs->EOF) {
|
||
print_r($rs->fields);
|
||
$rs->MoveNext();
|
||
}
|
||
|
||
print_r( $ldap->GetArray( $filter ) );
|
||
|
||
print_r( $ldap->GetRow( $filter ) );
|
||
|
||
$ldap->Close();
|
||
echo "</pre>";
|
||
?></pre>
|
||
<h4>Interbase/Firebird</h4>
|
||
You define the database in the $host parameter:
|
||
<pre>
|
||
$conn = &ADONewConnection('ibase');
|
||
$conn->PConnect('localhost:c:\ibase\employee.gdb','sysdba','masterkey');
|
||
</pre>
|
||
<p>Or dsn:
|
||
<pre>
|
||
$dsn = 'firebird://user:pwd@localhost/mydb?persist&dialect=3'; # persist is optional
|
||
$conn = ADONewConnection($dsn); # no need for Connect/PConnect
|
||
</pre>
|
||
<h4>SQLite</h4>
|
||
Sqlite will create the database file if it does not exist.
|
||
<pre>
|
||
$conn = &ADONewConnection('sqlite');
|
||
$conn->PConnect('c:\path\to\sqlite.db'); # sqlite will create if does not exist
|
||
</pre>
|
||
<p>Or dsn:
|
||
<pre>
|
||
$dsn = 'sqlite://user:pwd@localhost/mydb?persist'; # persist is optional
|
||
$conn = ADONewConnection($dsn); # no need for Connect/PConnect
|
||
</pre>
|
||
<h4>Oracle (oci8)</h4>
|
||
<p>With oci8, you can connect in multiple ways. Note that oci8 works fine with
|
||
newer versions of the Oracle, eg. 9i and 10g.</p>
|
||
<p>a. PHP and Oracle reside on the same machine, use default SID.</p>
|
||
<pre> $conn->Connect(false, 'scott', 'tiger');</pre>
|
||
<p>b. TNS Name defined in tnsnames.ora (or ONAMES or HOSTNAMES), eg. 'myTNS'</p>
|
||
<pre> $conn->PConnect(false, 'scott', 'tiger', 'myTNS');</pre>
|
||
<p>or</p>
|
||
<pre> $conn->PConnect('myTNS', 'scott', 'tiger');</pre>
|
||
<p>c. Host Address and SID</p>
|
||
<pre> $conn->Connect('192.168.0.1', 'scott', 'tiger', 'SID');</pre>
|
||
<p>d. Host Address and Service Name</p>
|
||
<pre> $conn->Connect('192.168.0.1', 'scott', 'tiger', 'servicename');</pre>
|
||
<p>e. Oracle connection string:
|
||
<pre> $cstr = "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=$host)(PORT=$port))
|
||
(CONNECT_DATA=(SID=$sid)))";
|
||
$conn->Connect($cstr, 'scott', 'tiger');
|
||
</pre>
|
||
<p>f. ADOdb dsn:
|
||
<pre>
|
||
$dsn = 'oci8://user:pwd@tnsname?persist'; # persist is optional
|
||
$conn = ADONewConnection($dsn); # no need for Connect/PConnect
|
||
|
||
$dsn = 'oci8://user:pwd@host/sid';
|
||
$conn = ADONewConnection($dsn);
|
||
|
||
$dsn = 'oci8://user:pwd@/'; # oracle on local machine
|
||
$conn = ADONewConnection($dsn);
|
||
</pre>
|
||
<a name=dsnless></a>
|
||
<h4>DSN-less ODBC (access and mssql examples)</h4>
|
||
<p>ODBC DSN's can be created in the ODBC control panel, or you can use a DSN-less
|
||
connection.To use DSN-less connections with ODBC you need PHP 4.3 or later.
|
||
</p>
|
||
<p>For Microsoft Access:</p>
|
||
<pre>
|
||
$db =& ADONewConnection('access');
|
||
$dsn = <strong>"Driver={Microsoft Access Driver (*.mdb)};Dbq=d:\\northwind.mdb;Uid=Admin;Pwd=;";</strong>
|
||
$db->Connect($dsn);
|
||
</pre>
|
||
For Microsoft SQL Server:
|
||
<pre>
|
||
$db =& ADONewConnection('odbc_mssql');
|
||
$dsn = <strong>"Driver={SQL Server};Server=localhost;Database=northwind;"</strong>;
|
||
$db->Connect($dsn,'userid','password');
|
||
</pre>
|
||
or if you prefer to use the mssql extension (which is limited to mssql 6.5 functionality):
|
||
<pre>
|
||
$db =& ADONewConnection('mssql');
|
||
$db->Execute("localhost', 'userid', 'password', 'northwind');
|
||
</pre>
|
||
<b>DSN-less Connections with ADO</b><br>
|
||
If you are using versions of PHP earlier than PHP 4.3.0, DSN-less connections
|
||
only work with Microsoft's ADO, which is Microsoft's COM based API. An example
|
||
using the ADOdb library and Microsoft's ADO:
|
||
<pre>
|
||
<?php
|
||
include('adodb.inc.php');
|
||
$db = &ADONewConnection("ado_mssql");
|
||
print "<h1>Connecting DSN-less $db->databaseType...</h1>";
|
||
|
||
<b>$myDSN="PROVIDER=MSDASQL;DRIVER={SQL Server};"
|
||
. "SERVER=flipper;DATABASE=ai;UID=sa;PWD=;" ;</b>
|
||
$db->Connect($myDSN);
|
||
|
||
$rs = $db->Execute("select * from table");
|
||
$arr = $rs->GetArray();
|
||
print_r($arr);
|
||
?>
|
||
</pre><a name=speed></a>
|
||
<h2>High Speed ADOdb - tuning tips</h2>
|
||
<p>ADOdb is a big class library, yet it <a href=http://phplens.com/lens/adodb/>consistently beats</a> all other PHP class
|
||
libraries in performance. This is because it is designed in a layered fashion,
|
||
like an onion, with the fastest functions in the innermost layer. Stick to the
|
||
following functions for best performance:</p>
|
||
<table width="40%" border="1" align="center">
|
||
<tr>
|
||
<td><div align="center"><b>Innermost Layer</b></div></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p align="center">Connect, PConnect, NConnect<br>
|
||
Execute, CacheExecute<br>
|
||
SelectLimit, CacheSelectLimit<br>
|
||
MoveNext, Close <br>
|
||
qstr, Affected_Rows, Insert_ID</p></td>
|
||
</tr>
|
||
</table>
|
||
<p>The fastest way to access the field data is by accessing the array $recordset->fields
|
||
directly. Also set the global variables <a href="#adodb_fetch_mode">$ADODB_FETCH_MODE</a>
|
||
= ADODB_FETCH_NUM, and (for oci8, ibase/firebird and odbc) <a href="#adodb_countrecs">$ADODB_COUNTRECS</a> = false
|
||
before you connect to your database.</p>
|
||
<p>Consider using bind parameters if your database supports it, as it improves
|
||
query plan reuse. Use ADOdb's performance tuning system to identify bottlenecks
|
||
quickly. At the time of writing (Dec 2003), this means oci8 and odbc drivers.</p>
|
||
<p>Lastly make sure you have a PHP accelerator cache installed such as APC, Turck
|
||
MMCache, Zend Accelerator or ionCube.</p>
|
||
<p><b>Advanced Tips</b>
|
||
<p>If you have the <a href=http://adodb.sourceforge.net/#extension>ADOdb C extension</a> installed,
|
||
you can replace your calls to $rs->MoveNext() with adodb_movenext($rs).
|
||
This doubles the speed of this operation. For retrieving entire recordsets at once,
|
||
use GetArray(), which uses the high speed extension function adodb_getall($rs) internally.
|
||
<p>Execute() is the default way to run queries. You can use the low-level functions _Execute() and _query()
|
||
to reduce query overhead. Both these functions share the same parameters as Execute().
|
||
<p>If you do not have any bind parameters or your database supports binding (without emulation),
|
||
then you can call _Execute() directly. Calling this function bypasses bind emulation. Debugging is still supported in _Execute().
|
||
<p>If you do not require debugging facilities nor emulated binding, and do not require a recordset to be returned, then you can call _query. This is great for inserts, updates and deletes. Calling this function
|
||
bypasses emulated binding, debugging, and recordset handling. Either the resultid, true or false are returned by _query().
|
||
<p>For Informix, you can disable scrollable cursors with $db->cursorType = 0.
|
||
<p><a name=hack></a> </p>
|
||
<h2>Hacking ADOdb Safely</h2>
|
||
<p>You might want to modify ADOdb for your own purposes. Luckily you can
|
||
still maintain backward compatibility by sub-classing ADOdb and using the $ADODB_NEWCONNECTION
|
||
variable. $ADODB_NEWCONNECTION allows you to override the behaviour of ADONewConnection().
|
||
ADOConnection() checks for this variable and will call
|
||
the function-name stored in this variable if it is defined.
|
||
<p>In the following example, new functionality for the connection object
|
||
is placed in the <i>hack_mysql</i> and <i>hack_postgres7</i> classes. The recordset class naming convention
|
||
can be controlled using $rsPrefix. Here we set it to 'hack_rs_', which will make ADOdb use
|
||
<i>hack_rs_mysql</i> and <i>hack_rs_postgres7</i> as the recordset classes.
|
||
|
||
|
||
<pre>
|
||
class hack_mysql extends adodb_mysql {
|
||
var $rsPrefix = 'hack_rs_';
|
||
/* Your mods here */
|
||
}
|
||
|
||
class hack_rs_mysql extends ADORecordSet_mysql {
|
||
/* Your mods here */
|
||
}
|
||
|
||
class hack_postgres7 extends adodb_postgres7 {
|
||
var $rsPrefix = 'hack_rs_';
|
||
/* Your mods here */
|
||
}
|
||
|
||
class hack_rs_postgres7 extends ADORecordSet_postgres7 {
|
||
/* Your mods here */
|
||
}
|
||
|
||
$ADODB_NEWCONNECTION = 'hack_factory';
|
||
|
||
function& hack_factory($driver)
|
||
{
|
||
if ($driver !== 'mysql' && $driver !== 'postgres7') return false;
|
||
|
||
$driver = 'hack_'.$driver;
|
||
$obj = new $driver();
|
||
return $obj;
|
||
}
|
||
|
||
include_once('adodb.inc.php');
|
||
</pre>
|
||
<p><p>Don't forget to call the constructor of the parent class in your constructor. If you want to use the default ADOdb drivers return false in the above hack_factory() function.
|
||
<a name="php5"></a>
|
||
<h2>PHP5 Features</h2>
|
||
ADOdb 4.02 or later will transparently determine which version of PHP you are using.
|
||
If PHP5 is detected, the following features become available:
|
||
<ul>
|
||
<a name="php5iterators"></a>
|
||
<li><b>Foreach iterators</b>: This is a very natural way of going through a recordset:
|
||
<pre>
|
||
$ADODB_FETCH_MODE = ADODB_FETCH_NUM;
|
||
$rs = $db->Execute($sql);
|
||
foreach($rs as $k => $row) {
|
||
echo "r1=".$row[0]." r2=".$row[1]."<br>";
|
||
}
|
||
</pre>
|
||
<p>
|
||
<a name="php5exceptions"></a>
|
||
<li><b>Exceptions</b>: Just include <i>adodb-exceptions.inc.php</i> and you can now
|
||
catch exceptions on errors as they occur.
|
||
<pre>
|
||
<b>include("../adodb-exceptions.inc.php");</b>
|
||
include("../adodb.inc.php");
|
||
try {
|
||
$db = NewADOConnection("oci8");
|
||
$db->Connect('','scott','bad-password');
|
||
} catch (exception $e) {
|
||
var_dump($e);
|
||
adodb_backtrace($e->gettrace());
|
||
}
|
||
</pre>
|
||
<p>Note that reaching EOF is <b>not</b> considered an error nor an exception.
|
||
If you want to use the default ADOdb drivers return false.
|
||
</ul>
|
||
<h3><a name="drivers"></a>Databases Supported</h3>
|
||
The <i>name</i> below is the value you pass to NewADOConnection($name) to create a connection object for that database.
|
||
<p>
|
||
<table width="100%" border="1">
|
||
<tr valign="top">
|
||
<td><b>Name</b></td>
|
||
<td><b>Tested</b></td>
|
||
<td><b>Database</b></td>
|
||
<td><b><font size="2">RecordCount() usable</font></b></td>
|
||
<td><b>Prerequisites</b></td>
|
||
<td><b>Operating Systems</b></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">access</font></b></td>
|
||
<td><font size="2">B</font></td>
|
||
<td><font size="2">Microsoft Access/Jet. You need to create an ODBC DSN.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">ODBC </font></td>
|
||
<td><font size="2">Windows only</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">ado</font></b></td>
|
||
<td><font size="2">B</font></td>
|
||
<td><p><font size="2">Generic ADO, not tuned for specific databases. Allows
|
||
DSN-less connections. For best performance, use an OLEDB provider. This
|
||
is the base class for all ado drivers.</font></p>
|
||
<p><font size="2">You can set $db->codePage before connecting.</font></p></td>
|
||
<td><font size="2">? depends on database</font></td>
|
||
<td><font size="2">ADO or OLEDB provider</font></td>
|
||
<td><font size="2">Windows only</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">ado_access</font></b></td>
|
||
<td><font size="2">B</font></td>
|
||
<td><font size="2">Microsoft Access/Jet using ADO. Allows DSN-less connections.
|
||
For best performance, use an OLEDB provider.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">ADO or OLEDB provider</font></td>
|
||
<td><font size="2">Windows only</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">ado_mssql</font></b></td>
|
||
<td><font size="2">B</font></td>
|
||
<td><font size="2">Microsoft SQL Server using ADO. Allows DSN-less connections.
|
||
For best performance, use an OLEDB provider.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">ADO or OLEDB provider</font></td>
|
||
<td><font size="2">Windows only</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td height="54"><b><font size="2">db2</font></b></td>
|
||
<td height="54"><font size="2">A</font></td>
|
||
<td height="54"><font size="2">DB2. Should work reliably as based on ODBC
|
||
driver.</font></td>
|
||
<td height="54"><font size="2">Y/N</font></td>
|
||
<td height="54"><font size="2">DB2 CLI/ODBC interface</font></td>
|
||
<td height="54"> <p><font size="2">Unix and Windows. <a href="http://www.faqts.com/knowledge_base/view.phtml/aid/6283/fid/14">Unix
|
||
install hints</a>. I have had reports that the $host and $database params have to be reversed in Connect() when using the CLI interface.</font></p></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">vfp</font></b></td>
|
||
<td><font size="2">A</font></td>
|
||
<td><font size="2">Microsoft Visual FoxPro. You need to create an ODBC DSN.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">ODBC</font></td>
|
||
<td><font size="2">Windows only</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">fbsql</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">FrontBase. </font></td>
|
||
<td><font size="2">Y</font></td>
|
||
<td><font size="2">?</font></td>
|
||
<td> <p><font size="2">Unix and Windows</font></p></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">ibase</font></b></td>
|
||
<td><font size="2">B</font></td>
|
||
<td><font size="2">Interbase 6 or earlier. Some users report you might need
|
||
to use this<br>
|
||
$db->PConnect('localhost:c:/ibase/employee.gdb', "sysdba", "masterkey")
|
||
to connect. Lacks Affected_Rows currently.<br>
|
||
<br>
|
||
You can set $db->dialect, $db->buffers and $db->charSet before connecting.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">Interbase client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><i><font size="2">firebird</font></i></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Firebird version of interbase.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">Interbase client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><i><font size="2">borland_ibase</font></i></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Borland version of Interbase 6.5 or later. Very sad that
|
||
the forks differ.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">Interbase client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
|
||
<tr valign="top">
|
||
<td><b><font size="2">informix</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Generic informix driver. Use this if you are using Informix 7.3 or later.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">Informix client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">informix72</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2"> Informix databases before Informix 7.3 that do no support
|
||
SELECT FIRST.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">Informix client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">ldap</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">LDAP driver. See this example for usage information.</font></td>
|
||
<td> </td>
|
||
<td><font size="2">LDAP extension</font></td>
|
||
<td><font size="2">?</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td height="73"><b><font size="2">mssql</font></b></td>
|
||
<td height="73"><font size="2">A</font></td>
|
||
<td height="73"> <p><font size="2">Microsoft SQL Server 7 and later. Works
|
||
with Microsoft SQL Server 2000 also. Note that date formating is problematic
|
||
with this driver. For example, the PHP mssql extension does not return
|
||
the seconds for datetime!</font></p></td>
|
||
<td height="73"><font size="2">Y/N</font></td>
|
||
<td height="73"><font size="2">Mssql client</font></td>
|
||
<td height="73"> <p><font size="2">Unix and Windows. <br>
|
||
<a href="http://phpbuilder.com/columns/alberto20000919.php3">Unix install
|
||
howto</a> and <a href=http://linuxjournal.com/article.php?sid=6636&mode=thread&order=0>another
|
||
one</a>. </font></p></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td height="73"><b><font size="2">mssqlpo</font></b></td>
|
||
<td height="73"><font size="2">A</font></td>
|
||
<td height="73"> <p><font size="2">Portable mssql driver. Identical to above
|
||
mssql driver, except that '||', the concatenation operator, is converted
|
||
to '+'. Useful for porting scripts from most other sql variants that use
|
||
||.</font></p></td>
|
||
<td height="73"><font size="2">Y/N</font></td>
|
||
<td height="73"><font size="2">Mssql client</font></td>
|
||
<td height="73"> <p><font size="2">Unix and Windows. <a href="http://phpbuilder.com/columns/alberto20000919.php3"><br>
|
||
Unix install howto</a>.</font></p></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">mysql</font></b></td>
|
||
<td><font size="2">A</font></td>
|
||
<td><font size="2">MySQL without transaction support. You can also set $db->clientFlags
|
||
before connecting.</font></td>
|
||
<td><font size="2">Y</font></td>
|
||
<td><font size="2">MySQL client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><font size="2"><b>mysqlt</b> or <b>maxsql</b></font></td>
|
||
<td><font size="2">A</font></td>
|
||
<td> <p><font size="2">MySQL with transaction support. We recommend using
|
||
|| as the concat operator for best portability. This can be done by running
|
||
MySQL using: <br>
|
||
<i>mysqld --ansi</i> or <i>mysqld --sql-mode=PIPES_AS_CONCAT</i></font></p></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">MySQL client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">oci8</font></b></td>
|
||
<td><font size="2">A</font></td>
|
||
<td><font size="2">Oracle 8/9. Has more functionality than <i>oracle</i> driver
|
||
(eg. Affected_Rows). You might have to putenv('ORACLE_HOME=...') before
|
||
Connect/PConnect. </font> <p><font size="2"> There are 2 ways of connecting
|
||
- with server IP and service name: <br>
|
||
<i>PConnect('serverip:1521','scott','tiger','service'</i>)<br>
|
||
or using an entry in TNSNAMES.ORA or ONAMES or HOSTNAMES: <br>
|
||
<i>PConnect(false, 'scott', 'tiger', $oraname)</i>. </font>
|
||
<p><font size="2">Since 2.31, we support Oracle REF cursor variables directly
|
||
(see <a href="#executecursor">ExecuteCursor</a>).</font> </td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">Oracle client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">oci805</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Supports reduced Oracle functionality for Oracle 8.0.5.
|
||
SelectLimit is not as efficient as in the oci8 or oci8po drivers.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">Oracle client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">oci8po</font></b></td>
|
||
<td><font size="2">A</font></td>
|
||
<td><font size="2">Oracle 8/9 portable driver. This is nearly identical with
|
||
the oci8 driver except (a) bind variables in Prepare() use the ? convention,
|
||
instead of :bindvar, (b) field names use the more common PHP convention
|
||
of lowercase names. </font> <p><font size="2">Use this driver if porting
|
||
from other databases is important. Otherwise the oci8 driver offers better
|
||
performance. </font> </td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">Oracle client</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">odbc</font></b></td>
|
||
<td><font size="2">A</font></td>
|
||
<td><font size="2">Generic ODBC, not tuned for specific databases. To connect,
|
||
use <br>
|
||
PConnect('DSN','user','pwd'). This is the base class for all odbc derived
|
||
drivers.</font></td>
|
||
<td><font size="2">? depends on database</font></td>
|
||
<td><font size="2">ODBC</font></td>
|
||
<td><font size="2">Unix and Windows. <a href="http://phpbuilder.com/columns/alberto20000919.php3?page=4">Unix
|
||
hints.</a></font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">odbc_mssql</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Uses ODBC to connect to MSSQL</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">ODBC</font></td>
|
||
<td><font size="2">Unix and Windows. </font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">odbc_oracle</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Uses ODBC to connect to Oracle</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">ODBC</font></td>
|
||
<td><font size="2">Unix and Windows. </font></td>
|
||
</tr>
|
||
|
||
<tr valign="top">
|
||
<td><b><font size="2">odbtp</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Generic odbtp driver. <a href=http://odbtp.sourceforge.net/>Odbtp</a> is a software for
|
||
accessing Windows ODBC data sources from other operating systems.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">odbtp</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">odbtp_unicode</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Odtbp with unicode support</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">odbtp</font></td>
|
||
<td><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td height="34"><b><font size="2">oracle</font></b></td>
|
||
<td height="34"><font size="2">C</font></td>
|
||
<td height="34"><font size="2">Implements old Oracle 7 client API. Use oci8
|
||
driver if possible for better performance.</font></td>
|
||
<td height="34"><font size="2">Y/N</font></td>
|
||
<td height="34"><font size="2">Oracle client</font></td>
|
||
<td height="34"><font size="2">Unix and Windows</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td height="34"><b><font size="2">netezza</font></b></td>
|
||
<td height="34"><font size="2">C</font></td>
|
||
<td height="34"><font size="2">Netezza driver. Netezza is based on postgres code-base.</font></td>
|
||
<td height="34"><font size="2">Y</font></td>
|
||
<td height="34"><font size="2">?</font></td>
|
||
<td height="34"><font size="2">?</font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">postgres</font></b></td>
|
||
<td><font size="2">A</font></td>
|
||
<td><font size="2">Generic PostgreSQL driver. Currently identical to postgres7
|
||
driver. </font></td>
|
||
<td><font size="2">Y</font></td>
|
||
<td><font size="2">PostgreSQL client</font></td>
|
||
<td><font size="2">Unix and Windows. </font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">postgres64</font></b></td>
|
||
<td><font size="2">A</font></td>
|
||
<td><font size="2">For PostgreSQL 6.4 and earlier which does not support LIMIT
|
||
internally.</font></td>
|
||
<td><font size="2">Y</font></td>
|
||
<td><font size="2">PostgreSQL client</font></td>
|
||
<td><font size="2">Unix and Windows. </font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">postgres7</font></b></td>
|
||
<td><font size="2">A</font></td>
|
||
<td><font size="2">PostgreSQL which supports LIMIT and other version 7 functionality.</font></td>
|
||
<td><font size="2">Y</font></td>
|
||
<td><font size="2">PostgreSQL client</font></td>
|
||
<td><font size="2">Unix and Windows. </font></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">sapdb</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">SAP DB. Should work reliably as based on ODBC driver.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">SAP ODBC client</font></td>
|
||
<td> <p><font size="2">?</font></p></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td><b><font size="2">sqlanywhere</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Sybase SQL Anywhere. Should work reliably as based on ODBC
|
||
driver.</font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">SQL Anywhere ODBC client</font></td>
|
||
<td> <p><font size="2">?</font></p></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td height="54"><b><font size="2">sqlite</font></b></td>
|
||
<td height="54"><font size="2">B</font></td>
|
||
<td height="54"><font size="2">SQLite.</font></td>
|
||
<td height="54"><font size="2">Y</font></td>
|
||
<td height="54"><font size="2">-</font></td>
|
||
<td height="54"> <p><font size="2">Unix and Windows.</font></p></td>
|
||
</tr>
|
||
<tr valign="top">
|
||
<td height="54"><b><font size="2">sqlitepo</font></b></td>
|
||
<td height="54"><font size="2">B</font></td>
|
||
<td height="54"><font size="2">Portable SQLite driver. This is because assoc mode does not work like other drivers in sqlite.
|
||
Namely, when selecting (joining) multiple tables, the table
|
||
names are included in the assoc keys in the "sqlite" driver.<p>
|
||
In "sqlitepo" driver, the table names are stripped from the returned column names.
|
||
When this results in a conflict, the first field get preference.
|
||
</font></td>
|
||
<td height="54"><font size="2">Y</font></td>
|
||
<td height="54"><font size="2">-</font></td>
|
||
<td height="54"> <p><font size="2">Unix and Windows.</font></p></td>
|
||
</tr>
|
||
|
||
|
||
<tr valign="top">
|
||
<td><b><font size="2">sybase</font></b></td>
|
||
<td><font size="2">C</font></td>
|
||
<td><font size="2">Sybase. </font></td>
|
||
<td><font size="2">Y/N</font></td>
|
||
<td><font size="2">Sybase client</font></td>
|
||
<td> <p><font size="2">Unix and Windows.</font></p></td>
|
||
</tr>
|
||
<p>
|
||
</table>
|
||
|
||
<p>The "Tested" column indicates how extensively the code has been tested
|
||
and used. <br>
|
||
A = well tested and used by many people<br>
|
||
B = tested and usable, but some features might not be implemented<br>
|
||
C = user contributed or experimental driver. Might not fully support all of
|
||
the latest features of ADOdb. </p>
|
||
<p>The column "RecordCount() usable" indicates whether RecordCount()
|
||
return the number of rows, or returns -1 when a SELECT statement is executed.
|
||
If this column displays Y/N then the RecordCount() is emulated when the global
|
||
variable $ADODB_COUNTRECS=true (this is the default). Note that for large recordsets,
|
||
it might be better to disable RecordCount() emulation because substantial amounts
|
||
of memory are required to cache the recordset for counting. Also there is a
|
||
speed penalty of 40-50% if emulation is required. This is emulated in most databases
|
||
except for PostgreSQL and MySQL. This variable is checked every time a query
|
||
is executed, so you can selectively choose which recordsets to count.</p>
|
||
<p>
|
||
<hr>
|
||
<h1>Tutorials<a name="quickstart"></a></h1>
|
||
<h3>Example 1: Select Statement<a name="ex1"></a></h3>
|
||
<p>Task: Connect to the Access Northwind DSN, display the first 2 columns of each
|
||
row.</p>
|
||
<p>In this example, we create a ADOConnection object, which represents the connection
|
||
to the database. The connection is initiated with <a href="#pconnect"><font face="Courier New, Courier, mono">PConnect</font></a>,
|
||
which is a persistent connection. Whenever we want to query the database, we
|
||
call the <font face="Courier New, Courier, mono">ADOConnection.<a href="#execute">Execute</a>()</font>
|
||
function. This returns an ADORecordSet object which is actually a cursor that
|
||
holds the current row in the array <font face="Courier New, Courier, mono">fields[]</font>.
|
||
We use <font face="Courier New, Courier, mono"><a href="#movenext">MoveNext</a>()</font>
|
||
to move from row to row.</p>
|
||
<p>NB: A useful function that is not used in this example is <font face="Courier New, Courier, mono"><a href="#selectlimit">SelectLimit</a></font>,
|
||
which allows us to limit the number of rows shown.
|
||
<pre>
|
||
<?
|
||
<font face="Courier New, Courier, mono"><b>include</b>('adodb.inc.php'); # load code common to ADOdb
|
||
$<font color="#660000">conn</font> = &ADONewConnection('access'); # create a connection
|
||
$<font color="#660000">conn</font>->PConnect('northwind'); # connect to MS-Access, northwind DSN
|
||
$<font color="#660000">recordSet</font> = &$<font color="#660000">conn</font>->Execute('select * from products');
|
||
if (!$<font color="#660000">recordSet</font>)
|
||
print $<font color="#660000">conn</font>->ErrorMsg();
|
||
else
|
||
<b>while</b> (!$<font color="#660000">recordSet</font>->EOF) {
|
||
<b>print</b> $<font color="#660000">recordSet</font>->fields[0].' '.$<font color="#660000">recordSet</font>->fields[1].'<BR>';
|
||
$<font color="#660000">recordSet</font>->MoveNext();
|
||
}</font><font face="Courier New, Courier, mono">
|
||
|
||
$<font color="#660000">recordSet</font>->Close(); # optional
|
||
$<font color="#660000">conn</font>->Close(); # optional
|
||
</font>
|
||
?>
|
||
</pre>
|
||
<p>The $<font face="Courier New, Courier, mono">recordSet</font> returned stores
|
||
the current row in the <font face="Courier New, Courier, mono">$recordSet->fields</font>
|
||
array, indexed by column number (starting from zero). We use the <font face="Courier New, Courier, mono"><a href="#movenext">MoveNext</a>()</font>
|
||
function to move to the next row. The <font face="Courier New, Courier, mono">EOF</font>
|
||
property is set to true when end-of-file is reached. If an error occurs in Execute(),
|
||
we return false instead of a recordset.</p>
|
||
<p>The <code>$recordSet->fields[]</code> array is generated by the PHP database
|
||
extension. Some database extensions only index by number and do not index the
|
||
array by field name. To force indexing by name - that is associative arrays
|
||
- use the SetFetchMode function. Each recordset saves and uses whatever fetch
|
||
mode was set when the recordset was created in Execute() or SelectLimit().
|
||
<pre>
|
||
$db->SetFetchMode(ADODB_FETCH_NUM);
|
||
$rs1 = $db->Execute('select * from table');
|
||
$db->SetFetchMode(ADODB_FETCH_ASSOC);
|
||
$rs2 = $db->Execute('select * from table');
|
||
print_r($rs1->fields); # shows <i>array([0]=>'v0',[1] =>'v1')</i>
|
||
print_r($rs2->fields); # shows <i>array(['col1']=>'v0',['col2'] =>'v1')</i>
|
||
</pre>
|
||
<p> </p>
|
||
<p>To get the number of rows in the select statement, you can use <font face="Courier New, Courier, mono">$recordSet-><a href="#recordcount">RecordCount</a>()</font>.
|
||
Note that it can return -1 if the number of rows returned cannot be determined.</p>
|
||
<h3>Example 2: Advanced Select with Field Objects<a name="ex2"></a></h3>
|
||
<p>Select a table, display the first two columns. If the second column is a date
|
||
or timestamp, reformat the date to US format.</p>
|
||
<pre>
|
||
<?
|
||
<font face="Courier New, Courier, mono"><b>include</b>('adodb.inc.php'); # load code common to ADOdb
|
||
$<font color="#660000">conn</font> = &ADONewConnection('access'); # create a connection
|
||
$<font color="#660000">conn</font>->PConnect('northwind'); # connect to MS-Access, northwind dsn
|
||
$<font color="#660000">recordSet</font> = &$<font color="#660000">conn</font>->Execute('select CustomerID,OrderDate from Orders');
|
||
if (!$<font color="#660000">recordSet</font>)
|
||
print $<font color="#660000">conn</font>->ErrorMsg();
|
||
else
|
||
<b>while</b> (!$<font color="#660000">recordSet</font>->EOF) {
|
||
$<font color="#660000">fld</font> = <font color="#336600"><b>$</b><font color="#660000">recordSet</font><b>->FetchField</b></font><font color="#006600">(</font>1<font color="#006600">);</font>
|
||
$<font color="#660000">type</font> = <font color="#336600"><b>$</b><font color="#660000">recordSet</font><b>->MetaType</b></font>($fld->type);
|
||
|
||
<b>if</b> ( $<font color="#660000">type</font> == 'D' || $<font color="#660000">type</font> == 'T')
|
||
<b>print</b> $<font color="#660000">recordSet</font>->fields[0].' '.
|
||
<b><font color="#336600">$</font></b><font color="#660000">recordSet</font><b><font color="#336600">->UserDate</font></b>($<font color="#660000">recordSet</font>->fields[1],'<b>m/d/Y</b>').'<BR>';
|
||
<b>else </b>
|
||
<b>print</b> $<font color="#660000">recordSet</font>->fields[0].' '.$<font color="#660000">recordSet</font>->fields[1].'<BR>';
|
||
|
||
$<font color="#660000">recordSet</font>->MoveNext();
|
||
}</font><font face="Courier New, Courier, mono">
|
||
$<font color="#660000">recordSet</font>->Close(); # optional
|
||
$<font color="#660000">conn</font>->Close(); # optional
|
||
</font>
|
||
?>
|
||
</pre>
|
||
<p>In this example, we check the field type of the second column using <font face="Courier New, Courier, mono"><a href="#fetchfield">FetchField</a>().</font>
|
||
This returns an object with at least 3 fields.</p>
|
||
<ul>
|
||
<li><b>name</b>: name of column</li>
|
||
<li> <b>type</b>: native field type of column</li>
|
||
<li> <b>max_length</b>: maximum length of field. Some databases such as MySQL
|
||
do not return the maximum length of the field correctly. In these cases max_length
|
||
will be set to -1.</li>
|
||
</ul>
|
||
<p>We then use <font face="Courier New, Courier, mono"><a href="#metatype">MetaType</a>()</font>
|
||
to translate the native type to a <i>generic</i> type. Currently the following
|
||
<i>generic</i> types are defined:</p>
|
||
<ul>
|
||
<li><b>C</b>: character fields that should be shown in a <input type="text">
|
||
tag.</li>
|
||
<li><b>X</b>: TeXt, large text fields that should be shown in a <textarea></li>
|
||
<li><b>B</b>: Blobs, or Binary Large Objects. Typically images.
|
||
<li><b>D</b>: Date field</li>
|
||
<li><b>T</b>: Timestamp field</li>
|
||
<li><b>L</b>: Logical field (boolean or bit-field)</li>
|
||
<li><b>I</b>: Integer field</li>
|
||
<li><b>N</b>: Numeric field. Includes autoincrement, numeric, floating point,
|
||
real and integer. </li>
|
||
<li><b>R</b>: Serial field. Includes serial, autoincrement integers. This works
|
||
for selected databases. </li>
|
||
</ul>
|
||
<p>If the metatype is of type date or timestamp, then we print it using the user
|
||
defined date format with <font face="Courier New, Courier, mono"><a href="#userdate">UserDate</a>(),</font>
|
||
which converts the PHP SQL date string format to a user defined one. Another
|
||
use for <font face="Courier New, Courier, mono"><a href="#metatype">MetaType</a>()</font>
|
||
is data validation before doing an SQL insert or update.</p>
|
||
<h3>Example 3: Inserting<a name="ex3"></a></h3>
|
||
<p>Insert a row to the Orders table containing dates and strings that need to
|
||
be quoted before they can be accepted by the database, eg: the single-quote
|
||
in the word <i>John's</i>.</p>
|
||
<pre>
|
||
<?
|
||
<b>include</b>('adodb.inc.php'); # load code common to ADOdb
|
||
$<font color="#660000">conn</font> = &ADONewConnection('access'); # create a connection
|
||
|
||
$<font color="#660000">conn</font>->PConnect('northwind'); # connect to MS-Access, northwind dsn
|
||
$<font color="#660000">shipto</font> = <font color="#006600"><b>$conn->qstr</b></font>("<i>John's Old Shoppe</i>");
|
||
|
||
$<font color="#660000">sql</font> = "insert into orders (customerID,EmployeeID,OrderDate,ShipName) ";
|
||
$<font color="#660000">sql</font> .= "values ('ANATR',2,".<b><font color="#006600">$conn->DBDate(</font>time()<font color="#006600">)</font></b><font color="#006600">.</font>",$<font color="#660000">shipto</font>)";
|
||
|
||
<b>if</b> ($<font color="#660000">conn</font>->Execute($<font color="#660000">sql</font>) <font color="#336600"><b>=== false</b></font>) {
|
||
<b>print</b> 'error inserting: '.<font color="#336600"><b>$conn->ErrorMsg()</b></font>.'<BR>';
|
||
}
|
||
?>
|
||
</pre>
|
||
<p>In this example, we see the advanced date and quote handling facilities of
|
||
ADOdb. The unix timestamp (which is a long integer) is appropriately formated
|
||
for Access with <font face="Courier New, Courier, mono"><a href="#dbdate">DBDate</a>()</font>,
|
||
and the right escape character is used for quoting the <i>John's Old Shoppe</i>,
|
||
which is<b> </b><i>John'<b>'</b>s Old Shoppe</i> and not PHP's default <i>John<b>'</b>s
|
||
Old Shoppe</i> with <font face="Courier New, Courier, mono"><a href="#qstr">qstr</a>()</font>.
|
||
</p>
|
||
<p>Observe the error-handling of the Execute statement. False is returned by<font face="Courier New, Courier, mono">
|
||
<a href="#execute">Execute</a>() </font>if an error occured. The error message
|
||
for the last error that occurred is displayed in <font face="Courier New, Courier, mono"><a href="#errormsg">ErrorMsg</a>()</font>.
|
||
Note: <i>php_track_errors</i> might have to be enabled for error messages to
|
||
be saved.</p>
|
||
<h3> Example 4: Debugging<a name="ex4"></a></h3>
|
||
<pre><?
|
||
<b>include</b>('adodb.inc.php'); # load code common to ADOdb
|
||
$<font color="#663300">conn</font> = &ADONewConnection('access'); # create a connection
|
||
$<font color="#663300">conn</font>->PConnect('northwind'); # connect to MS-Access, northwind dsn
|
||
<font color="#000000">$<font color="#663300">shipto</font> = <b>$conn->qstr</b>("John's Old Shoppe");
|
||
$<font color="#663300">sql</font> = "insert into orders (customerID,EmployeeID,OrderDate,ShipName) ";
|
||
$<font color="#663300">sql</font> .= "values ('ANATR',2,".$<font color="#663300">conn</font>->FormatDate(time()).",$shipto)";
|
||
<b><font color="#336600">$<font color="#663300">conn</font>->debug = true;</font></b>
|
||
<b>if</b> ($<font color="#663300">conn</font>->Execute($sql) <b>=== false</b>) <b>print</b> 'error inserting';</font>
|
||
?>
|
||
</pre>
|
||
<p>In the above example, we have turned on debugging by setting <b>debug = true</b>.
|
||
This will display the SQL statement before execution, and also show any error
|
||
messages. There is no need to call <font face="Courier New, Courier, mono"><a href="#errormsg">ErrorMsg</a>()</font>
|
||
in this case. For displaying the recordset, see the <font face="Courier New, Courier, mono"><a href="#exrs2html">rs2html</a>()
|
||
</font>example.</p>
|
||
<p>Also see the section on <a href=#errorhandling>Custom Error Handlers</a>.</p>
|
||
<h3>Example 5: MySQL and Menus<a name="ex5"></a></h3>
|
||
<p>Connect to MySQL database <i>agora</i>, and generate a <select> menu
|
||
from an SQL statement where the <option> captions are in the 1st column,
|
||
and the value to send back to the server is in the 2nd column.</p>
|
||
<pre><?
|
||
<b>include</b>('adodb.inc.php'); # load code common to ADOdb
|
||
$<font color="#663300">conn</font> = &ADONewConnection('mysql'); # create a connection
|
||
$<font color="#663300">conn</font>->PConnect('localhost','userid','','agora');# connect to MySQL, agora db
|
||
<font color="#000000">$<font color="#663300">sql</font> = 'select CustomerName, CustomerID from customers';
|
||
$<font color="#663300">rs</font> = $<font color="#663300">conn</font>->Execute($sql);
|
||
<b>print</b> <b><font color="#336600">$<font color="#663300">rs</font>->GetMenu('GetCust','Mary Rosli');
|
||
?></font></b></font></pre>
|
||
<p>Here we define a menu named GetCust, with the menu option 'Mary Rosli' selected.
|
||
See <a href="#getmenu"><font face="Courier New, Courier, mono">GetMenu</font></a><font face="Courier New, Courier, mono">()</font>.
|
||
We also have functions that return the recordset as an array: <font face="Courier New, Courier, mono"><a href="#getarray">GetArray</a>()</font>,
|
||
and as an associative array with the key being the first column: <a href="#getassoc1">GetAssoc</a>().</p>
|
||
<h3>Example 6: Connecting to 2 Databases At Once<a name="ex6"></a></h3>
|
||
<pre><?
|
||
<b>include</b>('adodb.inc.php'); # load code common to ADOdb
|
||
$<font color="#663300">conn1</font> = &ADONewConnection('mysql'); # create a mysql connection
|
||
$<font color="#663300">conn2</font> = &ADONewConnection('oracle'); # create a oracle connection
|
||
|
||
$conn1->PConnect($server, $userid, $password, $database);
|
||
$conn2->PConnect(false, $ora_userid, $ora_pwd, $oraname);
|
||
|
||
$conn1->Execute('insert ...');
|
||
$conn2->Execute('update ...');
|
||
?></pre>
|
||
<p>
|
||
<h3>Example 7: Generating Update and Insert SQL<a name="ex7"></a></h3>
|
||
ADOdb 1.31 and later supports two new recordset functions: GetUpdateSQL( ) and
|
||
GetInsertSQL( ). This allow you to perform a "SELECT * FROM table query WHERE...",
|
||
make a copy of the $rs->fields, modify the fields, and then generate the SQL to
|
||
update or insert into the table automatically.
|
||
<p> We show how the functions can be used when accessing a table with the following
|
||
fields: (ID, FirstName, LastName, Created).
|
||
<p> Before these functions can be called, you need to initialize the recordset
|
||
by performing a select on the table. Idea and code by Jonathan Younger jyounger#unilab.com.
|
||
Since ADOdb 2.42, you can pass a table name instead of a recordset into
|
||
GetInsertSQL (in $rs), and it will generate an insert statement for that table.
|
||
<p>
|
||
<pre><?
|
||
#==============================================
|
||
# SAMPLE GetUpdateSQL() and GetInsertSQL() code
|
||
#==============================================
|
||
include('adodb.inc.php');
|
||
include('tohtml.inc.php');
|
||
|
||
#==========================
|
||
# This code tests an insert
|
||
|
||
$sql = "SELECT * FROM ADOXYZ WHERE id = -1";
|
||
# Select an empty record from the database
|
||
|
||
$conn = &ADONewConnection("mysql"); # create a connection
|
||
$conn->debug=1;
|
||
$conn->PConnect("localhost", "admin", "", "test"); # connect to MySQL, testdb
|
||
$rs = $conn->Execute($sql); # Execute the query and get the empty recordset
|
||
|
||
$record = array(); # Initialize an array to hold the record data to insert
|
||
|
||
# Set the values for the fields in the record
|
||
# Note that field names are case-insensitive
|
||
$record["firstname"] = "Bob";
|
||
$record["lastNamE"] = "Smith";
|
||
$record["creaTed"] = time();
|
||
|
||
# Pass the empty recordset and the array containing the data to insert
|
||
# into the GetInsertSQL function. The function will process the data and return
|
||
# a fully formatted insert sql statement.
|
||
$insertSQL = $conn->GetInsertSQL($rs, $record);
|
||
|
||
$conn->Execute($insertSQL); # Insert the record into the database
|
||
|
||
#==========================
|
||
# This code tests an update
|
||
|
||
$sql = "SELECT * FROM ADOXYZ WHERE id = 1";
|
||
# Select a record to update
|
||
|
||
$rs = $conn->Execute($sql); # Execute the query and get the existing record to update
|
||
|
||
$record = array(); # Initialize an array to hold the record data to update
|
||
|
||
# Set the values for the fields in the record
|
||
# Note that field names are case-insensitive
|
||
$record["firstname"] = "Caroline";
|
||
$record["LasTnAme"] = "Smith"; # Update Caroline's lastname from Miranda to Smith
|
||
|
||
# Pass the single record recordset and the array containing the data to update
|
||
# into the GetUpdateSQL function. The function will process the data and return
|
||
# a fully formatted update sql statement with the correct WHERE clause.
|
||
# If the data has not changed, no recordset is returned
|
||
$updateSQL = $conn->GetUpdateSQL($rs, $record);
|
||
|
||
$conn->Execute($updateSQL); # Update the record in the database
|
||
$conn->Close();
|
||
?>
|
||
</pre>
|
||
<a name=ADODB_FORCE_TYPE></a>
|
||
<b>$ADODB_FORCE_TYPE</b><p>
|
||
The behaviour of GetUpdateSQL() and GetInsertSQL()
|
||
when converting empty or null PHP variables to SQL is controlled by the
|
||
global $ADODB_FORCE_TYPE variable. Set it to one of the values below. Default
|
||
is ADODB_FORCE_VALUE (3):
|
||
<pre>
|
||
0 = ignore empty fields. All empty fields in array are ignored.
|
||
1 = force null. All empty, php null and string 'null' fields are changed to sql NULL values.
|
||
2 = force empty. All empty, php null and string 'null' fields are changed to sql empty '' or 0 values.
|
||
3 = force value. Value is left as it is. Php null and string 'null' are set to sql NULL values and
|
||
empty fields '' are set to empty '' sql values.
|
||
|
||
define('ADODB_FORCE_IGNORE',0);
|
||
define('ADODB_FORCE_NULL',1);
|
||
define('ADODB_FORCE_EMPTY',2);
|
||
define('ADODB_FORCE_VALUE',3);
|
||
</pre>
|
||
<p>
|
||
Thanks to Niko (nuko#mbnet.fi) for the $ADODB_FORCE_TYPE code.
|
||
<p>
|
||
Note: the constant ADODB_FORCE_NULLS is obsolete since 4.52 and is ignored. Set $ADODB_FORCE_TYPE = ADODB_FORCE_NULL
|
||
for equivalent behaviour.
|
||
|
||
<p>
|
||
<h3>Example 8: Implementing Scrolling with Next and Previous<a name="ex8"></a></h3>
|
||
<p> The following code creates a very simple recordset pager, where you can scroll
|
||
from page to page of a recordset.</p>
|
||
<pre>
|
||
include_once('../adodb.inc.php');
|
||
include_once('../adodb-pager.inc.php');
|
||
session_start();
|
||
|
||
$db = NewADOConnection('mysql');
|
||
|
||
$db->Connect('localhost','root','','xphplens');
|
||
|
||
$sql = "select * from adoxyz ";
|
||
|
||
$pager = new ADODB_Pager($db,$sql);
|
||
$pager->Render($rows_per_page=5);</pre>
|
||
<p>This will create a basic record pager that looks like this: <a name="scr"></a>
|
||
<p>
|
||
<table border=1 bgcolor=beige>
|
||
<tr>
|
||
<td> <a href="#scr"><code>|<</code></a> <a href="#scr"><code><<</code></a>
|
||
<a href="#scr"><code>>></code></a> <a href="#scr"><code>>|</code></a>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><TABLE COLS=4 width=100% border=1 bgcolor=white>
|
||
<TH>ID</TH>
|
||
<TH>First Name</TH>
|
||
<TH>Last Name</TH>
|
||
<TH>Date Created</TH>
|
||
<TR>
|
||
<TD align=right>36 </TD>
|
||
<TD>Alan </TD>
|
||
<TD>Turing </TD>
|
||
<TD>Sat 06, Oct 2001 </TD>
|
||
</TR>
|
||
<TR>
|
||
<TD align=right>37 </TD>
|
||
<TD>Serena </TD>
|
||
<TD>Williams </TD>
|
||
<TD>Sat 06, Oct 2001 </TD>
|
||
</TR>
|
||
<TR>
|
||
<TD align=right>38 </TD>
|
||
<TD>Yat Sun </TD>
|
||
<TD>Sun </TD>
|
||
<TD>Sat 06, Oct 2001 </TD>
|
||
</TR>
|
||
<TR>
|
||
<TD align=right>39 </TD>
|
||
<TD>Wai Hun </TD>
|
||
<TD>See </TD>
|
||
<TD>Sat 06, Oct 2001 </TD>
|
||
</TR>
|
||
<TR>
|
||
<TD align=right>40 </TD>
|
||
<TD>Steven </TD>
|
||
<TD>Oey </TD>
|
||
<TD>Sat 06, Oct 2001 </TD>
|
||
</TR>
|
||
</TABLE></td>
|
||
</tr>
|
||
<tr>
|
||
<td><font size=-1>Page 8/10</font></td>
|
||
</tr>
|
||
</table>
|
||
<p>The number of rows to display at one time is controled by the Render($rows)
|
||
method. If you do not pass any value to Render(), ADODB_Pager will default to
|
||
10 records per page.
|
||
<p>You can control the column titles by modifying your SQL (supported by most
|
||
databases):
|
||
<pre>$sql = 'select id as "ID", firstname as "First Name",
|
||
lastname as "Last Name", created as "Date Created" <br> from adoxyz';</pre>
|
||
<p>The above code can be found in the <i>adodb/tests/testpaging.php</i> example
|
||
included with this release, and the class ADODB_Pager in <i>adodb/adodb-pager.inc.php</i>.
|
||
The ADODB_Pager code can be adapted by a programmer so that the text links can
|
||
be replaced by images, and the dull white background be replaced with more interesting
|
||
colors.
|
||
<p>You can also allow display of html by setting $pager->htmlSpecialChars = false.
|
||
<p>Some of the code used here was contributed by Iván Oliva and Cornel
|
||
G. </p>
|
||
<h3><a name="ex9"></a>Example 9: Exporting in CSV or Tab-Delimited Format</h3>
|
||
<p>We provide some helper functions to export in comma-separated-value (CSV) and
|
||
tab-delimited formats:</p>
|
||
<pre><b>include_once('/path/to/adodb/toexport.inc.php');</b><br>include_once('/path/to/adodb/adodb.inc.php');<br>
|
||
$db = &NewADOConnection('mysql');<br>$db->Connect($server, $userid, $password, $database);<br><br>$rs = $db->Execute('select fname as "First Name", surname as "Surname" from table');
|
||
|
||
print "<pre>";<br>print <b>rs2csv</b>($rs); # return a string, CSV format<p>print '<hr>';
|
||
<br>$rs->MoveFirst(); # note, some databases do not support MoveFirst<br>print <b>rs2tab</b>($rs,<i>false</i>); # return a string, tab-delimited
|
||
# false == suppress field names in first line</p>print '<hr>';<br>$rs->MoveFirst();<br><b>rs2tabout</b>($rs); # send to stdout directly (there is also an rs2csvout function)
|
||
print "</pre>";
|
||
|
||
$rs->MoveFirst();<br><b></b>$fp = fopen($path, "w");
|
||
if ($fp) {<br> <b>rs2csvfile</b>($rs, $fp); # write to file (there is also an rs2tabfile function)
|
||
fclose($fp);<br>}
|
||
</pre>
|
||
<p> Carriage-returns or newlines are converted to spaces. Field names are returned
|
||
in the first line of text. Strings containing the delimiter character are quoted
|
||
with double-quotes. Double-quotes are double-quoted again. This conforms to
|
||
Excel import and export guide-lines.
|
||
<p>All the above functions take as an optional last parameter, $addtitles which
|
||
defaults to <i>true</i>. When set to <i>false</i> field names in the first line
|
||
are suppressed. <br>
|
||
<h3>Example 10: Recordset Filters<a name="ex10"></a></h3>
|
||
<p>Sometimes we want to pre-process all rows in a recordset before we use it.
|
||
For example, we want to ucwords all text in recordset.
|
||
<pre>
|
||
include_once('adodb/rsfilter.inc.php');
|
||
include_once('adodb/adodb.inc.php');
|
||
|
||
// ucwords() every element in the recordset
|
||
function do_ucwords(&$arr,$rs)
|
||
{
|
||
foreach($arr as $k => $v) {
|
||
$arr[$k] = ucwords($v);
|
||
}
|
||
}
|
||
|
||
$db = NewADOConnection('mysql');
|
||
$db->PConnect('server','user','pwd','db');
|
||
|
||
$rs = $db->Execute('select ... from table');
|
||
$rs = <b>RSFilter</b>($rs,'do_ucwords');
|
||
</pre>
|
||
<p>The <i>RSFilter</i> function takes 2 parameters, the recordset, and the name
|
||
of the <i>filter</i> function. It returns the processed recordset scrolled to
|
||
the first record. The <i>filter</i> function takes two parameters, the current
|
||
row as an array, and the recordset object. For future compatibility, you should
|
||
not use the original recordset object. </p>
|
||
<h3>Example 11:<a name="ex11"></a> Smart Transactions</h3>
|
||
The old way of doing transactions required you to use
|
||
<pre>
|
||
$conn-><b>BeginTrans</b>();
|
||
$ok = $conn->Execute($sql);
|
||
if ($ok) $ok = $conn->Execute($sql2);
|
||
if (!$ok) $conn-><b>RollbackTrans</b>();
|
||
else $conn-><b>CommitTrans</b>();
|
||
</pre>
|
||
This is very complicated for large projects because you have to track the error
|
||
status. Smart Transactions is much simpler. You start a smart transaction by calling
|
||
StartTrans():
|
||
<pre>
|
||
$conn-><b>StartTrans</b>();
|
||
$conn->Execute($sql);
|
||
$conn->Execute($Sql2);
|
||
$conn-><b>CompleteTrans</b>();
|
||
</pre>
|
||
CompleteTrans() detects when an SQL error occurs, and will Rollback/Commit as
|
||
appropriate. To specificly force a rollback even if no error occured, use FailTrans().
|
||
Note that the rollback is done in CompleteTrans(), and not in FailTrans().
|
||
<pre>
|
||
$conn-><b>StartTrans</b>();
|
||
$conn->Execute($sql);
|
||
if (!CheckRecords()) $conn-><strong>FailTrans</strong>();
|
||
$conn->Execute($Sql2);
|
||
$conn-><b>CompleteTrans</b>();
|
||
</pre>
|
||
<p>You can also check if a transaction has failed, using HasFailedTrans(), which
|
||
returns true if FailTrans() was called, or there was an error in the SQL execution.
|
||
Make sure you call HasFailedTrans() before you call CompleteTrans(), as it is
|
||
only works between StartTrans/CompleteTrans.
|
||
<p>Lastly, StartTrans/CompleteTrans is nestable, and only the outermost block
|
||
is executed. In contrast, BeginTrans/CommitTrans/RollbackTrans is NOT nestable.
|
||
<pre>
|
||
$conn-><strong>StartTrans</strong>();
|
||
$conn->Execute($sql);
|
||
$conn-><strong>StartTrans</strong>(); <font color="#006600"># ignored</font>
|
||
if (!CheckRecords()) $conn->FailTrans();
|
||
$conn-><strong>CompleteTrans</strong>(); <font color="#006600"># ignored</font>
|
||
$conn->Execute($Sql2);
|
||
$conn-><strong>CompleteTrans</strong>();
|
||
</pre>
|
||
<p>Note: Savepoints are currently not supported.
|
||
<h2><a name="errorhandling"></a>Using Custom Error Handlers and PEAR_Error</h2>
|
||
<p>ADOdb supports PHP5 exceptions. Just include <i>adodb-exceptions.inc.php</i> and you can now
|
||
catch exceptions on errors as they occur.
|
||
<pre>
|
||
<b>include("../adodb-exceptions.inc.php");</b>
|
||
include("../adodb.inc.php");
|
||
try {
|
||
$db = NewADOConnection("oci8://scott:bad-password@mytns/");
|
||
} catch (exception $e) {
|
||
var_dump($e);
|
||
adodb_backtrace($e->gettrace());
|
||
}
|
||
</pre>
|
||
<p> ADOdb also provides two custom handlers which you can modify for your needs. The
|
||
first one is in the <b>adodb-errorhandler.inc.php</b> file. This makes use of
|
||
the standard PHP functions <a href=http://php.net/error_reporting>error_reporting</a>
|
||
to control what error messages types to display, and <a href=http://php.net/trigger_error>trigger_error</a>
|
||
which invokes the default PHP error handler.
|
||
<p> Including the above file will cause <i>trigger_error($errorstring,E_USER_ERROR)</i>
|
||
to be called when<br>
|
||
(a) Connect() or PConnect() fails, or <br>
|
||
(b) a function that executes SQL statements such as Execute() or SelectLimit()
|
||
has an error.<br>
|
||
(c) GenID() appears to go into an infinite loop.
|
||
<p> The $errorstring is generated by ADOdb and will contain useful debugging information
|
||
similar to the error.log data generated below. This file adodb-errorhandler.inc.php
|
||
should be included before you create any ADOConnection objects.
|
||
<p> If you define error_reporting(0), no errors will be passed to the error handler.
|
||
If you set error_reporting(E_ALL), all errors will be passed to the error handler.
|
||
You still need to use <b>ini_set("display_errors", "0" or "1")</b> to control
|
||
the display of errors.
|
||
<pre>
|
||
<?php
|
||
<b>error_reporting(E_ALL); # pass any error messages triggered to error handler
|
||
include('adodb-errorhandler.inc.php');</b>
|
||
include('adodb.inc.php');
|
||
include('tohtml.inc.php');
|
||
$c = NewADOConnection('mysql');
|
||
$c->PConnect('localhost','root','','northwind');
|
||
$rs=$c->Execute('select * from productsz'); #invalid table productsz');
|
||
if ($rs) rs2html($rs);
|
||
?>
|
||
</pre>
|
||
<p> If you want to log the error message, you can do so by defining the following
|
||
optional constants ADODB_ERROR_LOG_TYPE and ADODB_ERROR_LOG_DEST. ADODB_ERROR_LOG_TYPE
|
||
is the error log message type (see <a href=http://php.net/error_log>error_log</a>
|
||
in the PHP manual). In this case we set it to 3, which means log to the file
|
||
defined by the constant ADODB_ERROR_LOG_DEST.
|
||
<pre>
|
||
<?php
|
||
<b>error_reporting(E_ALL); # report all errors
|
||
ini_set("display_errors", "0"); # but do not echo the errors
|
||
define('ADODB_ERROR_LOG_TYPE',3);
|
||
define('ADODB_ERROR_LOG_DEST','C:/errors.log');
|
||
include('adodb-errorhandler.inc.php');</b>
|
||
include('adodb.inc.php');
|
||
include('tohtml.inc.php');
|
||
|
||
$c = NewADOConnection('mysql');
|
||
$c->PConnect('localhost','root','','northwind');
|
||
$rs=$c->Execute('select * from productsz'); ## invalid table productsz
|
||
if ($rs) rs2html($rs);
|
||
?>
|
||
</pre>
|
||
The following message will be logged in the error.log file:
|
||
<pre>
|
||
(2001-10-28 14:20:38) mysql error: [1146: Table 'northwind.productsz' doesn't exist] in
|
||
EXECUTE("select * from productsz")
|
||
</pre>
|
||
The second error handler is <b>adodb-errorpear.inc.php</b>. This will create a
|
||
PEAR_Error derived object whenever an error occurs. The last PEAR_Error object
|
||
created can be retrieved using ADODB_Pear_Error().
|
||
<pre>
|
||
<?php
|
||
<b>include('adodb-errorpear.inc.php');</b>
|
||
include('adodb.inc.php');
|
||
include('tohtml.inc.php');
|
||
$c = NewADOConnection('mysql');
|
||
$c->PConnect('localhost','root','','northwind');
|
||
$rs=$c->Execute('select * from productsz'); #invalid table productsz');
|
||
if ($rs) rs2html($rs);
|
||
else {
|
||
<b>$e = ADODB_Pear_Error();
|
||
echo '<p>',$e->message,'</p>';</b>
|
||
}
|
||
?>
|
||
</pre>
|
||
<p> You can use a PEAR_Error derived class by defining the constant ADODB_PEAR_ERROR_CLASS
|
||
before the adodb-errorpear.inc.php file is included. For easy debugging, you
|
||
can set the default error handler in the beginning of the PHP script to PEAR_ERROR_DIE,
|
||
which will cause an error message to be printed, then halt script execution:
|
||
<pre>
|
||
include('PEAR.php');
|
||
PEAR::setErrorHandling('PEAR_ERROR_DIE');
|
||
</pre>
|
||
<p> Note that we do not explicitly return a PEAR_Error object to you when an error
|
||
occurs. We return false instead. You have to call ADODB_Pear_Error() to get
|
||
the last error or use the PEAR_ERROR_DIE technique.
|
||
<h4>Error Messages</h4>
|
||
<p>Error messages are outputted using the static method ADOConnnection::outp($msg,$newline=true).
|
||
By default, it sends the messages to the client. You can override this to perform
|
||
error-logging.
|
||
<h2><a name="dsn"></a> Data Source Names</h2>
|
||
<p>We now support connecting using PEAR style DSN's. A DSN is a connection string
|
||
of the form:</p>
|
||
<p>$dsn = <i>"$driver://$username:$password@$hostname/$databasename"</i>;</p>
|
||
<p>An example:</p>
|
||
<pre>
|
||
$username = 'root';
|
||
$password = '';
|
||
$hostname = 'localhost';
|
||
$databasename = 'xphplens';
|
||
$driver = 'mysql';
|
||
$dsn = "$driver://$username:$password@$hostname/$databasename"
|
||
$db = NewADOConnection();
|
||
# DB::Connect($dsn) also works if you include 'adodb/adodb-pear.inc.php' at the top
|
||
$rs = $db->query('select firstname,lastname from adoxyz');
|
||
$cnt = 0;
|
||
while ($arr = $rs->fetchRow()) {
|
||
print_r($arr); print "<br>";
|
||
}</pre>
|
||
</p>
|
||
<p> <a href="#dsnsupport">More info and connection examples</a> on the DSN format.
|
||
|
||
<h2><a name="pear"></a>PEAR Compatibility</h2>
|
||
We support DSN's (see above), and the following functions:
|
||
<pre>
|
||
<b> DB_Common</b>
|
||
query - returns PEAR_Error on error
|
||
limitQuery - return PEAR_Error on error
|
||
prepare - does not return PEAR_Error on error
|
||
execute - does not return PEAR_Error on error
|
||
setFetchMode - supports ASSOC and ORDERED
|
||
errorNative
|
||
quote
|
||
nextID
|
||
disconnect
|
||
|
||
getOne
|
||
getAssoc
|
||
getRow
|
||
getCol
|
||
|
||
<b> DB_Result</b>
|
||
numRows - returns -1 if not supported
|
||
numCols
|
||
fetchInto - does not support passing of fetchmode
|
||
fetchRows - does not support passing of fetchmode
|
||
free
|
||
</pre>
|
||
<h2><a name="caching"></a>Caching of Recordsets</h2>
|
||
<p>ADOdb now supports caching of recordsets using the CacheExecute( ), CachePageExecute(
|
||
) and CacheSelectLimit( ) functions. There are similar to the non-cache functions,
|
||
except that they take a new first parameter, $secs2cache.
|
||
<p> An example:
|
||
<pre>
|
||
<b>include</b>('adodb.inc.php'); # load code common to ADOdb
|
||
$ADODB_CACHE_DIR = '/usr/ADODB_cache';
|
||
$<font color="#663300">conn</font> = &ADONewConnection('mysql'); # create a connection
|
||
$<font color="#663300">conn</font>->PConnect('localhost','userid','','agora');# connect to MySQL, agora db
|
||
<font color="#000000">$<font color="#663300">sql</font> = 'select CustomerName, CustomerID from customers';
|
||
$<font color="#663300">rs</font> = $<font color="#663300">conn</font>->CacheExecute(15,$sql);</font></pre>
|
||
<p><font color="#000000"> The first parameter is the number of seconds to cache
|
||
the query. Subsequent calls to that query will used the cached version stored
|
||
in $ADODB_CACHE_DIR. To force a query to execute and flush the cache, call CacheExecute()
|
||
with the first parameter set to zero. Alternatively, use the CacheFlush($sql)
|
||
call. </font></p>
|
||
<p><font color="#000000">For the sake of security, we recommend you set <i>register_globals=off</i>
|
||
in php.ini if you are using $ADODB_CACHE_DIR.</font></p>
|
||
<p>In ADOdb 1.80 onwards, the secs2cache parameter is optional in CacheSelectLimit()
|
||
and CacheExecute(). If you leave it out, it will use the $connection->cacheSecs
|
||
parameter, which defaults to 60 minutes.
|
||
<pre>
|
||
$conn->Connect(...);
|
||
$conn->cacheSecs = 3600*24; # cache 24 hours
|
||
$rs = $conn->CacheExecute('select * from table');
|
||
</pre>
|
||
<p>Please note that magic_quotes_runtime should be turned off. <a href=http://phplens.com/lens/lensforum/msgs.php?LeNs#LensBM_forummsg>More
|
||
info</a>, and do not change $ADODB_FETCH_MODE (or SetFetchMode)
|
||
as the cached recordset will use the $ADODB_FETCH_MODE set when the query was executed. <font color="#000000">
|
||
<h2><a name="pivot"></a>Pivot Tables</h2>
|
||
</font> <p><font color="#000000">Since ADOdb 2.30, we support the generation of
|
||
SQL to create pivot tables, also known as cross-tabulations. For further explanation
|
||
read this DevShed <a href=http://www.devshed.com/Server_Side/MySQL/MySQLWiz/>Cross-Tabulation
|
||
tutorial</a>. We assume that your database supports the SQL case-when expression. </font></p>
|
||
<font color="#000000">
|
||
<p>In this example, we will use the Northwind database from Microsoft. In the
|
||
database, we have a products table, and we want to analyze this table by <i>suppliers
|
||
versus product categories</i>. We will place the suppliers on each row, and
|
||
pivot on categories. So from the table on the left, we generate the pivot-table
|
||
on the right:</p>
|
||
</font>
|
||
<table border="0" cellspacing="2" cellpadding="2" align="center">
|
||
<tr>
|
||
<td>
|
||
<table border="1" cellspacing="2" cellpadding="2" align="center" width="142">
|
||
<tr>
|
||
<td><i>Supplier</i></td>
|
||
<td><i>Category</i></td>
|
||
</tr>
|
||
<tr>
|
||
<td>supplier1</td>
|
||
<td>category1</td>
|
||
</tr>
|
||
<tr>
|
||
<td>supplier2</td>
|
||
<td>category1</td>
|
||
</tr>
|
||
<tr>
|
||
<td>supplier2</td>
|
||
<td>category2</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
<td> <font face="Courier New, Courier, mono">--></font></td>
|
||
<td>
|
||
<table border="1" cellspacing="2" cellpadding="2" align="center">
|
||
<tr>
|
||
<td> </td>
|
||
<td><i>category1</i></td>
|
||
<td><i>category2</i></td>
|
||
<td><i>total</i></td>
|
||
</tr>
|
||
<tr>
|
||
<td><i>supplier1</i></td>
|
||
<td align="right">1</td>
|
||
<td align="right">0</td>
|
||
<td align="right">1</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i>supplier2</i></td>
|
||
<td align="right">1</td>
|
||
<td align="right">1</td>
|
||
<td align="right">2</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<font color="#000000">
|
||
<p>The following code will generate the SQL for a cross-tabulation:
|
||
<pre>
|
||
# Query the main "product" table
|
||
# Set the rows to CompanyName
|
||
# and the columns to the values of Categories
|
||
# and define the joins to link to lookup tables
|
||
# "categories" and "suppliers"
|
||
#
|
||
include "adodb/pivottable.php";
|
||
$sql = PivotTableSQL(
|
||
$gDB, # adodb connection
|
||
'products p ,categories c ,suppliers s', # tables
|
||
'CompanyName', # rows (multiple fields allowed)
|
||
'CategoryName', # column to pivot on
|
||
'p.CategoryID = c.CategoryID and s.SupplierID= p.SupplierID' # joins/where
|
||
);
|
||
</pre>
|
||
</font>
|
||
<p><font color="#000000"> This will generate the following SQL:</font></p>
|
||
<p><code><font size="2">SELECT CompanyName, <br>
|
||
SUM(CASE WHEN CategoryName='Beverages' THEN 1 ELSE 0 END) AS "Beverages",
|
||
<br>
|
||
SUM(CASE WHEN CategoryName='Condiments' THEN 1 ELSE 0 END) AS "Condiments",
|
||
<br>
|
||
SUM(CASE WHEN CategoryName='Confections' THEN 1 ELSE 0 END) AS "Confections",
|
||
<br>
|
||
SUM(CASE WHEN CategoryName='Dairy Products' THEN 1 ELSE 0 END) AS "Dairy
|
||
Products", <br>
|
||
SUM(CASE WHEN CategoryName='Grains/Cereals' THEN 1 ELSE 0 END) AS "Grains/Cereals",
|
||
<br>
|
||
SUM(CASE WHEN CategoryName='Meat/Poultry' THEN 1 ELSE 0 END) AS "Meat/Poultry",
|
||
<br>
|
||
SUM(CASE WHEN CategoryName='Produce' THEN 1 ELSE 0 END) AS "Produce",
|
||
<br>
|
||
SUM(CASE WHEN CategoryName='Seafood' THEN 1 ELSE 0 END) AS "Seafood",
|
||
<br>
|
||
SUM(1) as Total <br>
|
||
FROM products p ,categories c ,suppliers s WHERE p.CategoryID = c.CategoryID
|
||
and s.SupplierID= p.SupplierID <br>
|
||
GROUP BY CompanyName</font></code></p>
|
||
<p> You can also pivot on <i>numerical columns</i> and <i>generate totals</i>
|
||
by using ranges. <font color="#000000">This code was revised in ADODB 2.41
|
||
and is not backward compatible.</font> The second example shows this:</p>
|
||
<pre>
|
||
$sql = PivotTableSQL(
|
||
$gDB, # adodb connection
|
||
'products p ,categories c ,suppliers s', # tables
|
||
'CompanyName', #<font color="#000000"> rows (multiple fields allowed)</font>
|
||
array( # column ranges
|
||
' 0 ' => 'UnitsInStock <= 0',
|
||
"1 to 5" => '0 < UnitsInStock and UnitsInStock <= 5',
|
||
"6 to 10" => '5 < UnitsInStock and UnitsInStock <= 10',
|
||
"11 to 15" => '10 < UnitsInStock and UnitsInStock <= 15',
|
||
"16+" => '15 < UnitsInStock'
|
||
),
|
||
' p.CategoryID = c.CategoryID and s.SupplierID= p.SupplierID', # joins/where
|
||
'UnitsInStock', # sum this field
|
||
'Sum ' # sum label prefix
|
||
);
|
||
</pre>
|
||
<p>Which generates: </p>
|
||
<p> <code> <font size="2">SELECT CompanyName, <br>
|
||
SUM(CASE WHEN UnitsInStock <= 0 THEN UnitsInStock ELSE 0 END) AS "Sum
|
||
0 ", <br>
|
||
SUM(CASE WHEN 0 < UnitsInStock and UnitsInStock <= 5 THEN UnitsInStock
|
||
ELSE 0 END) AS "Sum 1 to 5",<br>
|
||
SUM(CASE WHEN 5 < UnitsInStock and UnitsInStock <= 10 THEN UnitsInStock
|
||
ELSE 0 END) AS "Sum 6 to 10",<br>
|
||
SUM(CASE WHEN 10 < UnitsInStock and UnitsInStock <= 15 THEN UnitsInStock
|
||
ELSE 0 END) AS "Sum 11 to 15", <br>
|
||
SUM(CASE WHEN 15 < UnitsInStock THEN UnitsInStock ELSE 0 END) AS "Sum
|
||
16+", <br>
|
||
SUM(UnitsInStock) AS "Sum UnitsInStock", <br>
|
||
SUM(1) as Total,<br>
|
||
FROM products p ,categories c ,suppliers s WHERE p.CategoryID = c.CategoryID
|
||
and s.SupplierID= p.SupplierID <br>
|
||
GROUP BY CompanyName</font></code><font size="2"><br>
|
||
</font> </p>
|
||
<font color="#000000"><hr>
|
||
<h1>Class Reference<a name="ref"></a></h1>
|
||
<p>Function parameters with [ ] around them are optional.</p>
|
||
</font>
|
||
<h2>Global Variables</h2>
|
||
<h3><font color="#000000"><a name="adodb_countrecs"></a></font>$ADODB_COUNTRECS</h3>
|
||
<p>If the database driver API does not support counting the number of records
|
||
returned in a SELECT statement, the function RecordCount() is emulated when
|
||
the global variable $ADODB_COUNTRECS is set to true, which is the default.
|
||
We emulate this by buffering the records, which can take up large amounts
|
||
of memory for big recordsets. Set this variable to false for the best performance.
|
||
This variable is checked every time a query is executed, so you can selectively
|
||
choose which recordsets to count.</p>
|
||
<h3><font color="#000000"><a name="adodb_cache_dir"></a>$ADODB_CACHE_DIR</font></h3>
|
||
<font color="#000000">
|
||
<p>If you are using recordset caching, this is the directory to save your recordsets
|
||
in. Define this before you call any caching functions such as CacheExecute(
|
||
). We recommend setting <i>register_globals=off</i> in php.ini if you use this
|
||
feature for security reasons.</p>
|
||
<p>If you are using Unix and apache, you might need to set your cache directory
|
||
permissions to something similar to the following:</p>
|
||
</font>
|
||
<p>chown -R apache /path/to/adodb/cache<br>
|
||
chgrp -R apache /path/to/adodb/cache </p>
|
||
<font color="#000000">
|
||
<h3><a name="adodb_ansi_padding_off"></a>$ADODB_ANSI_PADDING_OFF</h3>
|
||
<p>Determines whether to right trim CHAR fields (and also VARCHAR for ibase/firebird).
|
||
Set to true to trim. Default is false. Currently works for oci8po, ibase and firebird
|
||
drivers. Added in ADOdb 4.01.
|
||
<h3><font color="#000000"><a name="adodb_lang"></a></font>$ADODB_LANG</h3>
|
||
<p>Determines the language used in MetaErrorMsg(). The default is 'en', for English.
|
||
To find out what languages are supported, see the files
|
||
in adodb/lang/adodb-$lang.inc.php, where $lang is the supported langauge.
|
||
<h3><a name="adodb_fetch_mode"></a>$ADODB_FETCH_MODE</h3>
|
||
<p>This is a global variable that determines how arrays are retrieved by recordsets.
|
||
The recordset saves this value on creation (eg. in Execute( ) or SelectLimit(
|
||
)), and any subsequent changes to $ADODB_FETCH_MODE have no affect on existing
|
||
recordsets, only on recordsets created in the future.</p>
|
||
<p>The following constants are defined:</p>
|
||
</font>
|
||
<p><font color="#000000">define('ADODB_FETCH_DEFAULT',0);<br>
|
||
define('ADODB_FETCH_NUM',1);<br>
|
||
define('ADODB_FETCH_ASSOC',2);<br>
|
||
define('ADODB_FETCH_BOTH',3); </font></p>
|
||
<font color="#000000">
|
||
<p> An example:
|
||
<pre>
|
||
$ADODB_<b>FETCH_MODE</b> = ADODB_FETCH_NUM;
|
||
$rs1 = $db->Execute('select * from table');
|
||
$ADODB_<b>FETCH_MODE</b> = ADODB_FETCH_ASSOC;
|
||
$rs2 = $db->Execute('select * from table');
|
||
print_r($rs1->fields); # shows <i>array([0]=>'v0',[1] =>'v1')</i>
|
||
print_r($rs2->fields); # shows <i>array(['col1']=>'v0',['col2'] =>'v1')</i>
|
||
</pre>
|
||
<p> As you can see in the above example, both recordsets store and use different
|
||
fetch modes based on the $ADODB_FETCH_MODE setting when the recordset was
|
||
created by Execute().</p>
|
||
<p>If no fetch mode is predefined, the fetch mode defaults to ADODB_FETCH_DEFAULT.
|
||
The behaviour of this default mode varies from driver to driver, so do not
|
||
rely on ADODB_FETCH_DEFAULT. For portability, we recommend sticking to ADODB_FETCH_NUM
|
||
or ADODB_FETCH_ASSOC. Many drivers do not support ADODB_FETCH_BOTH.</p>
|
||
<p><strong>SetFetchMode Function</strong></p>
|
||
<p>Some programmers prefer to use a more object-oriented solution, where the fetch
|
||
mode is set by a object function, <a href="#setfetchmode">SetFetchMode</a>.
|
||
Once this function is called for a connection object, that connection object
|
||
will ignore the global variable $ADODB_FETCH_MODE and will use the internal
|
||
fetchMode property exclusively.</p>
|
||
<pre>
|
||
$db->SetFetchMode(ADODB_FETCH_NUM);
|
||
$rs1 = $db->Execute('select * from table');
|
||
$db->SetFetchMode(ADODB_FETCH_ASSOC);
|
||
$rs2 = $db->Execute('select * from table');
|
||
print_r($rs1->fields); # shows <i>array([0]=>'v0',[1] =>'v1')</i>
|
||
print_r($rs2->fields); # shows <i>array(['col1']=>'v0',['col2'] =>'v1')</i></pre>
|
||
<p>To retrieve the previous fetch mode, you can use check the $db->fetchMode
|
||
property, or use the return value of SetFetchMode( ).
|
||
<p><strong><a name="adodb_assoc_case"></a>ADODB_ASSOC_CASE</strong></p>
|
||
<p>You can control the associative fetch case for certain drivers which behave
|
||
differently. For the sybase, oci8po, mssql, odbc and ibase drivers and all
|
||
drivers derived from them, ADODB_ASSOC_CASE will by default generate recordsets
|
||
where the field name keys are lower-cased. Use the constant ADODB_ASSOC_CASE
|
||
to change the case of the keys. There are 3 possible values:</p>
|
||
<p>0 = assoc lowercase field names. $rs->fields['orderid']<br>
|
||
1 = assoc uppercase field names. $rs->fields['ORDERID']<br>
|
||
2 = use native-case field names. $rs->fields['OrderID'] -- this is the
|
||
default since ADOdb 2.90</p>
|
||
<p>To use it, declare it before you incldue adodb.inc.php.</p>
|
||
<p>define('ADODB_ASSOC_CASE', 2); # use native-case for ADODB_FETCH_ASSOC<br>
|
||
include('adodb.inc.php'); </p>
|
||
<h3><font color="#000000"><a name="force_type"></a></font>$ADODB_FORCE_TYPE</h3>
|
||
<p>See the <a href=#ADODB_FORCE_TYPE>GetUpdateSQL tutorial</a>.
|
||
<hr>
|
||
<h2>ADOConnection<a name="adoconnection"></a></h2>
|
||
<p>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.</p>
|
||
<h3>ADOConnection Fields</h3>
|
||
<p><b>databaseType</b>: Name of the database system we are connecting to. Eg.
|
||
<b>odbc</b> or <b>mssql</b> or <b>mysql</b>.</p>
|
||
<p><b>dataProvider</b>: The underlying mechanism used to connect to the database.
|
||
Normally set to <b>native</b>, unless using <b>odbc</b> or <b>ado</b>.</p>
|
||
<p><b>host: </b>Name of server or data source name (DSN) to connect to.</p>
|
||
<p><b>database</b>: Name of the database or to connect to. If ado is used, it
|
||
will hold the ado data provider.</p>
|
||
<p><b>user</b>: Login id to connect to database. Password is not saved for security
|
||
reasons.</p>
|
||
<p><b>raiseErrorFn</b>: Allows you to define an error handling function. See adodb-errorhandler.inc.php
|
||
for an example.</p>
|
||
<p><b>debug</b>: Set to <i>true</i> to make debug statements to appear.</p>
|
||
<p><b>concat_operator</b>: Set to '+' or '||' normally. The operator used to concatenate
|
||
strings in SQL. Used by the <b><a href="#concat">Concat</a></b> function.</p>
|
||
<p><b>fmtDate</b>: The format used by the <b><a href="#dbdate">DBDate</a></b>
|
||
function to send dates to the database. is '#Y-m-d#' for Microsoft Access,
|
||
and ''Y-m-d'' for MySQL.</p>
|
||
<p><b>fmtTimeStamp: </b>The format used by the <b><a href="#dbtimestamp">DBTimeStamp</a></b>
|
||
function to send timestamps to the database. </p>
|
||
<p><b>true</b>: The value used to represent true.Eg. '.T.'. for Foxpro, '1' for
|
||
Microsoft SQL.</p>
|
||
<p><b>false: </b> The value used to represent false. Eg. '.F.'. for Foxpro, '0'
|
||
for Microsoft SQL.</p>
|
||
<p><b>replaceQuote</b>: The string used to escape quotes. Eg. double single-quotes
|
||
for Microsoft SQL, and backslash-quote for MySQL. Used by <a href="#qstr">qstr</a>.</p>
|
||
<p><b>autoCommit</b>: indicates whether automatic commit is enabled. Default is
|
||
true.</p>
|
||
<p><b>charSet</b>: set the default charset to use. Currently only interbase supports
|
||
this.</p>
|
||
<p><b>dialect</b>: set the default sql dialect to use. Currently only interbase
|
||
supports this.</p>
|
||
<p><b>metaTablesSQL</b>: SQL statement to return a list of available tables. Eg.
|
||
<i>SHOW TABLES</i> in MySQL.</p>
|
||
<p><b>genID</b>: The latest id generated by GenID() if supported by the database.</p>
|
||
<p><b>cacheSecs</b>: The number of seconds to cache recordsets if CacheExecute()
|
||
or CacheSelectLimit() omit the $secs2cache parameter. Defaults to 60 minutes.</p>
|
||
<p><b>sysDate</b>: String that holds the name of the database function to call
|
||
to get the current date. Useful for inserts and updates.</p>
|
||
<p><b>sysTimeStamp</b>: String that holds the name of the database function to
|
||
call to get the current timestamp/datetime value.</p>
|
||
<p><b>leftOuter</b>: String that holds operator for left outer join, if known.
|
||
Otherwise set to false.</p>
|
||
<p><b>rightOuter</b>: String that holds operator for left outer join, if known.
|
||
Otherwise set to false.</p>
|
||
<p><b>ansiOuter</b>: Boolean that if true indicates that ANSI style outer joins
|
||
are permitted. Eg. <i>select * from table1 left join table2 on p1=p2.</i></p>
|
||
<p><b>connectSID</b>: Boolean that indicates whether to treat the $database parameter
|
||
in connects as the SID for the oci8 driver. Defaults to false. Useful for
|
||
Oracle 8.0.5 and earlier.</p>
|
||
<p><b>autoRollback</b>: Persistent connections are auto-rollbacked in PConnect(
|
||
) if this is set to true. Default is false.</p>
|
||
<hr>
|
||
<h3>ADOConnection Main Functions</h3>
|
||
<p><b>ADOConnection( )</b></p>
|
||
<p>Constructor function. Do not call this directly. Use ADONewConnection( ) instead.</p>
|
||
<p><b>Connect<a name="connect"></a>($host,[$user],[$password],[$database])</b></p>
|
||
<p>Non-persistent connect to data source or server $<b>host</b>, using userid
|
||
$<b>user </b>and password $<b>password</b>. If the server supports multiple
|
||
databases, connect to database $<b>database</b>. </p>
|
||
<p>Returns true/false depending on connection success. Since 4.23, null is returned if the extension is not loaded.</p>
|
||
<p>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.</p>
|
||
<p>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.</p>
|
||
<p>For Oracle and Oci8, there are two ways to connect. First is to use the TNS
|
||
name defined in your local tnsnames.ora (or ONAMES or HOSTNAMES). Place the
|
||
name in the $database field, and set the $host field to false. Alternatively,
|
||
set $host to the server, and $database to the database SID, this bypassed
|
||
tnsnames.ora.
|
||
<p>Examples:
|
||
<pre> # $oraname in tnsnames.ora/ONAMES/HOSTNAMES
|
||
$conn->Connect(false, 'scott', 'tiger', $oraname);
|
||
$conn->Connect('server:1521', 'scott', 'tiger', 'ServiceName'); # bypass tnsnames.ora</pre>
|
||
<p>There are many examples of connecting to a database.
|
||
See <a href=#connect_ex>Connection Examples</a>, <a href="http://php.weblogs.com/adodb">php.weblogs.com/ADOdb</a>,
|
||
and in the testdatabases.inc.php file included in the release.</p>
|
||
|
||
<p><b>PConnect<a name="pconnect"></a>($host,[$user],[$password],[$database])</b></p>
|
||
<p>Persistent connect to data source or server $<b>host</b>, using userid $<b>user</b>
|
||
and password $<b>password</b>. If the server supports multiple databases,
|
||
connect to database $<b>database</b>.</p>
|
||
<p>We now perform a rollback on persistent connection for selected databases since
|
||
2.21, as advised in the PHP manual. See change log or source code for which
|
||
databases are affected.
|
||
<p>Returns true/false depending on connection. Since 4.23, null is returned if the extension is not loaded.
|
||
See Connect( ) above for more info.</p>
|
||
<p>Since ADOdb 2.21, we also support autoRollback. If you set:</p>
|
||
</font>
|
||
<pre> $conn = &NewADOConnection('mysql');
|
||
$conn->autoRollback = true; # default is false
|
||
$conn->PConnect(...); # rollback here</pre>
|
||
<p> Then when doing a persistent connection with PConnect( ), ADOdb will
|
||
perform a rollback first. This is because it is documented that PHP is
|
||
not guaranteed to rollback existing failed transactions when
|
||
persistent connections are used. This is implemented in Oracle,
|
||
MySQL, PgSQL, MSSQL, ODBC currently.
|
||
<p>Since ADOdb 3.11, you can force non-persistent
|
||
connections even if PConnect is called by defining the constant
|
||
ADODB_NEVER_PERSIST before you call PConnect.
|
||
<p>
|
||
Since 4.23, null is returned if the extension is not loaded.
|
||
<p><b>NConnect<a name="nconnect"></a>($host,[$user],[$password],[$database])</b></p>
|
||
<p>Always force a new connection. In contrast, PHP sometimes reuses connections
|
||
when you use Connect() or PConnect(). Currently works only on mysql (PHP 4.3.0
|
||
or later), postgresql and oci8-derived drivers. For other drivers, NConnect() works like
|
||
Connect().
|
||
<font color="#000000">
|
||
<p><b>Execute<a name="execute"></a>($sql,$inputarr=false)</b></p>
|
||
<p>Execute SQL statement $<b>sql</b> and return derived class of ADORecordSet
|
||
if successful. Note that a record set is always returned on success, even
|
||
if we are executing an insert or update statement. You can also pass in $sql a statement prepared
|
||
in <a href=#prepare>Prepare()</a>.</p>
|
||
<p>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.</p>
|
||
<p>The $inputarr parameter can be used for binding variables to parameters. Below
|
||
is an Oracle example:</p>
|
||
<pre>
|
||
$conn->Execute("SELECT * FROM TABLE WHERE COND=:val", array('val'=> $val));
|
||
</pre>
|
||
<p>Another example, using ODBC,which uses the ? convention:</p>
|
||
<pre>
|
||
$conn->Execute("SELECT * FROM TABLE WHERE COND=?", array($val));
|
||
</pre>
|
||
<a name="binding"></a>
|
||
<i>Binding variables</i><p>
|
||
Variable binding speeds the compilation and caching of SQL statements, leading
|
||
to higher performance. Currently Oracle, Interbase and ODBC supports variable binding.
|
||
Interbase/ODBC style ? binding is emulated in databases that do not support binding.
|
||
Note that you do not have to quote strings if you use binding.
|
||
<p> Variable binding in the odbc, interbase and oci8po drivers.
|
||
<pre>
|
||
$rs = $db->Execute('select * from table where val=?', array('10'));
|
||
</pre>
|
||
Variable binding in the oci8 driver:
|
||
<pre>
|
||
$rs = $db->Execute('select name from table where val=:key',
|
||
array('key' => 10));
|
||
</pre>
|
||
<a name="bulkbind"></a>
|
||
<i>Bulk binding</i>
|
||
<p>Since ADOdb 3.80, we support bulk binding in Execute(), in which you pass in a 2-dimensional array to
|
||
be bound to an INSERT/UPDATE or DELETE statement.
|
||
<pre>
|
||
$arr = array(
|
||
array('Ahmad',32),
|
||
array('Zulkifli', 24),
|
||
array('Rosnah', 21)
|
||
);
|
||
$ok = $db->Execute('insert into table (name,age) values (?,?)',$arr);
|
||
</pre>
|
||
<p>This provides very high performance as the SQL statement is prepared first.
|
||
The prepared statement is executed repeatedly for each array row until all rows are completed,
|
||
or until the first error. Very useful for importing data.
|
||
|
||
<p><b>CacheExecute<a name="cacheexecute"></a>([$secs2cache,]$sql,$inputarr=false)</b></p>
|
||
<p>Similar to Execute, except that the recordset is cached for $secs2cache seconds
|
||
in the $ADODB_CACHE_DIR directory, and $inputarr only accepts 1-dimensional arrays.
|
||
If CacheExecute() is called again with the same $sql, $inputarr,
|
||
and also the same database, same userid, and the cached recordset
|
||
has not expired, the cached recordset is returned.
|
||
<pre>
|
||
include('adodb.inc.php');
|
||
include('tohtml.inc.php');
|
||
$ADODB_<b>CACHE_DIR</b> = '/usr/local/ADOdbcache';
|
||
$conn = &ADONewConnection('mysql');
|
||
$conn->PConnect('localhost','userid','password','database');
|
||
$rs = $conn-><b>CacheExecute</b>(15, 'select * from table'); # cache 15 secs
|
||
rs2html($rs); /* recordset to html table */
|
||
</pre>
|
||
<p> Alternatively, since ADOdb 1.80, the $secs2cache parameter is optional:</p>
|
||
<pre> $conn->Connect(...);
|
||
$conn->cacheSecs = 3600*24; // cache 24 hours
|
||
$rs = $conn->CacheExecute('select * from table');
|
||
</pre>
|
||
If $secs2cache is omitted, we use the value
|
||
in $connection->cacheSecs (default is 3600 seconds, or 1 hour). Use CacheExecute()
|
||
only with SELECT statements.
|
||
<p>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 <i>much slower </i>than your Web server or the database is <i>very
|
||
overloaded </i>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. </p>
|
||
<p><b>ExecuteCursor<a name="executecursor"></a>($sql,$cursorName='rs',$parameters=false)</b></p>
|
||
<p>Execute an Oracle stored procedure, and returns an Oracle REF cursor variable as
|
||
a regular ADOdb recordset. Does not work with any other database except oci8.
|
||
Thanks to Robert Tuttle for the design.
|
||
<pre>
|
||
$db = ADONewConnection("oci8");
|
||
$db->Connect("foo.com:1521", "uid", "pwd", "FOO");
|
||
$rs = $db->ExecuteCursor("begin :cursorvar := getdata(:param1); end;",
|
||
'cursorvar',
|
||
array('param1'=>10));
|
||
# $rs is now just like any other ADOdb recordset object<br> rs2html($rs);</pre>
|
||
<p>ExecuteCursor() is a helper function that does the following internally:
|
||
<pre>
|
||
$stmt = $db->Prepare("begin :cursorvar := getdata(:param1); end;", true);
|
||
$db->Parameter($stmt, $cur, 'cursorvar', false, -1, OCI_B_CURSOR);
|
||
$rs = $db->Execute($stmt,$bindarr);
|
||
</pre>
|
||
<p>ExecuteCursor only accepts 1 out parameter. So if you have 2 out parameters, use:
|
||
<pre>
|
||
$vv = 'A%';
|
||
$stmt = $db->PrepareSP("BEGIN list_tabs(:crsr,:tt); END;");
|
||
$db->OutParameter($stmt, $cur, 'crsr', -1, OCI_B_CURSOR);
|
||
$db->OutParameter($stmt, $vv, 'tt', 32); # return varchar(32)
|
||
$arr = $db->GetArray($stmt);
|
||
print_r($arr);
|
||
echo " val = $vv"; ## outputs 'TEST'
|
||
</pre>
|
||
for the following PL/SQL:
|
||
<pre>
|
||
TYPE TabType IS REF CURSOR RETURN TAB%ROWTYPE;
|
||
|
||
PROCEDURE list_tabs(tabcursor IN OUT TabType,tablenames IN OUT VARCHAR) IS
|
||
BEGIN
|
||
OPEN tabcursor FOR SELECT * FROM TAB WHERE tname LIKE tablenames;
|
||
tablenames := 'TEST';
|
||
END list_tabs;
|
||
</pre>
|
||
<p><b>SelectLimit<a name="selectlimit"></a>($sql,$numrows=-1,$offset=-1,$inputarr=false)</b></p>
|
||
<p>Returns a recordset if successful. Returns false otherwise. Performs a select
|
||
statement, simulating PostgreSQL's SELECT statement, LIMIT $numrows OFFSET
|
||
$offset clause.</p>
|
||
<p>In PostgreSQL, SELECT * FROM TABLE LIMIT 3 will return the first 3 records
|
||
only. The equivalent is <code>$connection->SelectLimit('SELECT * FROM TABLE',3)</code>.
|
||
This functionality is simulated for databases that do not possess this feature.</p>
|
||
<p>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 <code>$connection->SelectLimit('SELECT
|
||
* FROM TABLE',3,2)</code>.</p>
|
||
<p>Note that this is the <i>opposite</i> of MySQL's LIMIT clause. You can also
|
||
set <code>$connection->SelectLimit('SELECT * FROM TABLE',-1,10)</code> to
|
||
get rows 11 to the last row.</p>
|
||
<p>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:</p>
|
||
<pre>
|
||
$conn->SelectLimit("SELECT * FROM TABLE WHERE COND=:val", 100,-1,array('val'=> $val));
|
||
</pre>
|
||
<p>The oci8po driver (oracle portable driver) uses the more standard bind variable
|
||
of ?:
|
||
<pre>
|
||
$conn->SelectLimit("SELECT * FROM TABLE WHERE COND=?", 100,-1,array('val'=> $val));
|
||
</pre>
|
||
<p>
|
||
<p>Ron Wilson reports that SelectLimit does not work with UNIONs.
|
||
<p><b>CacheSelectLimit<a name="cacheselectlimit"></a>([$secs2cache,] $sql, $numrows=-1,$offset=-1,$inputarr=false)</b></p>
|
||
<p>Similar to SelectLimit, except that the recordset returned is cached for $secs2cache
|
||
seconds in the $ADODB_CACHE_DIR directory. </p>
|
||
<p>Since 1.80, $secs2cache has been optional, and you can define the caching time
|
||
in $connection->cacheSecs.</p>
|
||
</font>
|
||
<pre><font color="#000000"> $conn->Connect(...);
|
||
$conn->cacheSecs = 3600*24; // cache 24 hours
|
||
$rs = $conn->CacheSelectLimit('select * from table',10);</font></pre>
|
||
<font color="#000000">
|
||
<p><b>CacheFlush<a name="cacheflush"></a>($sql=false,$inputarr=false)</b></p>
|
||
<p>Flush (delete) any cached recordsets for the SQL statement $sql in $ADODB_CACHE_DIR.
|
||
<p>If no parameter is passed in, then all adodb_*.cache files are deleted.
|
||
<p> If you want to flush all cached recordsets manually, execute the following
|
||
PHP code (works only under Unix): <br>
|
||
<code> system("rm -f `find ".$ADODB_CACHE_DIR." -name
|
||
adodb_*.cache`");</code></p>
|
||
<p>For general cleanup of all expired files, you should use <a href="http://www.superscripts.com/tutorial/crontab.html">crontab</a>
|
||
on Unix, or at.exe on Windows, and a shell script similar to the following:<font face="Courier New, Courier, mono"><br>
|
||
#------------------------------------------------------ <br>
|
||
# This particular example deletes files in the TMPPATH <br>
|
||
# directory with the string ".cache" in their name that <br>
|
||
# are more than 7 days old. <br>
|
||
#------------------------------------------------------ <br>
|
||
AGED=7 <br>
|
||
find ${TMPPATH} -mtime +$AGED | grep "\.cache" | xargs rm -f <br>
|
||
</font> </p>
|
||
<p><b>MetaError<a name="metaerror"></a>($errno=false)</b></p>
|
||
<p>Returns a virtualized error number, based on PEAR DB's error number system. You might
|
||
need to include adodb-error.inc.php before you call this function. The parameter $errno
|
||
is the native error number you want to convert. If you do not pass any parameter, MetaError
|
||
will call ErrorNo() for you and convert it. If the error number cannot be virtualized, MetaError
|
||
will return -1 (DB_ERROR).</p>
|
||
|
||
<p><b>MetaErrorMsg<a name="metaerrormsg"></a>($errno)</b></p>
|
||
<p>Pass the error number returned by MetaError() for the equivalent textual error message.</p>
|
||
<p><b>ErrorMsg<a name="errormsg"></a>()</b></p>
|
||
<p>Returns the last status or error message. The error message is reset after every
|
||
call to Execute().
|
||
<p>
|
||
This can return a string even if
|
||
no error occurs. In general you do not need to call this function unless an
|
||
ADOdb function returns false on an error. </p>
|
||
<p>Note: If <b>debug</b> is enabled, the SQL error message is always displayed
|
||
when the <b>Execute</b> function is called.</p>
|
||
<p><b>ErrorNo<a name="errorno"></a>()</b></p>
|
||
<p>Returns the last error number. The error number is reset after every call to Execute().
|
||
If 0 is returned, no error occurred.
|
||
<p>
|
||
Note that old versions of PHP (pre 4.0.6) do
|
||
not support error number for ODBC. In general you do not need to call this
|
||
function unless an ADOdb function returns false on an error.</p>
|
||
</font>
|
||
<p><font color="#000000"><b>SetFetchMode<a name="setfetchmode"></a>($mode)</b></font></p>
|
||
<p><font color="#000000">Sets the current fetch mode for the connection and stores
|
||
it in $db->fetchMode. Legal modes are ADODB_FETCH_ASSOC and ADODB_FETCH_NUM.
|
||
For more info, see <a href="#adodb_fetch_mode">$ADODB_FETCH_MODE</a>.</font></p>
|
||
<p><font color="#000000">Returns the previous fetch mode, which could be false
|
||
if SetFetchMode( ) has not been called before.</font></p>
|
||
<font color="#000000">
|
||
<p><b>CreateSequence<a name="createseq"></a>($seqName = 'adodbseq',$startID=1)</b></p>
|
||
<p>Create a sequence. The next time GenID( ) is called, the value returned will
|
||
be $startID. Added in 2.60.
|
||
<p><b>DropSequenceD<a name="dropseq"></a>($seqName = 'adodbseq')</b></p>
|
||
<p>Delete a sequence. Added in 2.60.
|
||
<p><b>GenID<a name="genid"></a>($seqName = 'adodbseq',$startID=1)</b></p>
|
||
<p>Generate a sequence number . Works for interbase,
|
||
mysql, postgresql, oci8, oci8po, mssql, ODBC based (access,vfp,db2,etc) 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). Otherwise you will have to create the sequence yourself.
|
||
<p> If your database driver emulates sequences, the name of the table is the sequence
|
||
name. The table has one column, "id" which should be of type integer, or if
|
||
you need something larger - numeric(16).
|
||
<p> For ODBC and databases that do not support sequences natively (eg mssql, mysql),
|
||
we create a table for each sequence. If the sequence has not been defined
|
||
earlier, it is created with the starting value set in $startID.</p>
|
||
<p>Note that the mssql driver's GenID() before 1.90 used to generate 16 byte GUID's.</p>
|
||
<p><b>UpdateBlob<a name="updateblob"></a>($table,$column,$val,$where)</b></p>
|
||
Allows you to store a blob (in $val) into $table into $column in a row at $where.
|
||
<p> Usage:
|
||
<p>
|
||
<pre>
|
||
# 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');
|
||
</pre>
|
||
<p> Returns true if succesful, false otherwise. Supported by MySQL, PostgreSQL,
|
||
Oci8, Oci8po and Interbase drivers. Other drivers might work, depending on
|
||
the state of development.</p>
|
||
<p>Note that when an Interbase blob is retrieved using SELECT, it still needs
|
||
to be decoded using $connection->DecodeBlob($blob); to derive the original
|
||
value in versions of PHP before 4.1.0.
|
||
<p>For PostgreSQL, you can store your blob using blob oid's or as a bytea field.
|
||
You can use bytea fields but not blob oid's currently with UpdateBlob( ).
|
||
Conversely UpdateBlobFile( ) supports oid's, but not bytea data.<br>
|
||
<br>
|
||
If you do not pass in an oid, then UpdateBlob() assumes that you are storing
|
||
in bytea fields.
|
||
<p><b>UpdateClob<a name="updateclob"></a>($table,$column,$val,$where)</b></p>
|
||
Allows you to store a clob (in $val) into $table into $column in a row at $where.
|
||
Similar to UpdateBlob (see above), but for Character Large OBjects.
|
||
<p> Usage:
|
||
<pre>
|
||
# for oracle
|
||
$conn->Execute('INSERT INTO clobtable (id, clobcol) VALUES (1, empty_clob())');
|
||
$conn->UpdateBlob('clobtable','clobcol',$clobvalue,'id=1');
|
||
|
||
# non oracle databases
|
||
$conn->Execute('INSERT INTO clobtable (id, clobcol) VALUES (1, null)');
|
||
$conn->UpdateBlob('clobtable','clobcol',$clobvalue,'id=1');
|
||
</pre>
|
||
<p><b>UpdateBlobFile<a name="updateblobfile"></a>($table,$column,$path,$where,$blobtype='BLOB')</b></p>
|
||
<p>Similar to UpdateBlob, except that we pass in a file path to where the blob
|
||
resides.
|
||
<p>For PostgreSQL, if you are using blob oid's, use this interface. This interface
|
||
does not support bytea fields.
|
||
<p>Returns true if successful, false otherwise.
|
||
<p><b>BlobEncode<a name="blobencode" id="blobencode"></a>($blob)</b>
|
||
<p>Some databases require blob's to be encoded manually before upload. Note if
|
||
you use UpdateBlob( ) or UpdateBlobFile( ) the conversion is done automatically
|
||
for you and you do not have to call this function. For PostgreSQL, currently,
|
||
BlobEncode() can only be used for bytea fields.
|
||
<p>Returns the encoded blob value.
|
||
<p>Note that there is a connection property called <em>blobEncodeType</em> which
|
||
has 3 legal values:
|
||
<p>false - no need to perform encoding or decoding.<br>
|
||
'I' - blob encoding required, and returned encoded blob is a numeric value
|
||
(no need to quote).<br>
|
||
'C' - blob encoding required, and returned encoded blob is a character value
|
||
(requires quoting).
|
||
<p>This is purely for documentation purposes, so that programs that accept multiple
|
||
database drivers know what is the right thing to do when processing blobs.
|
||
<p><strong>BlobDecode<a name="blobdecode"></a>($blob)</strong>
|
||
</font><p><font color="#000000">Some databases require blob's to be decoded manually after doing a select statement.
|
||
If the database does not require decoding, then this function will return
|
||
the blob unchanged. Currently BlobDecode is only required for one database,
|
||
PostgreSQL, and only if you are using blob oid's (if you are using bytea fields,
|
||
we auto-decode for you).</font><font color="#000000">
|
||
<pre>$rs = $db->Execute("select bloboid from postgres_table where id=$key");
|
||
$blob = $db->BlobDecode( reset($rs->fields) );</pre>
|
||
<p><b>Replace<a name="replace"></a>($table, $arrFields, $keyCols,$autoQuote=false)</b></p>
|
||
<p>Try to update a record, and if the record is not found, an insert statement
|
||
is generated and executed. Returns 0 on failure, 1 if update statement worked,
|
||
2 if no record was found and the insert was executed successfully. This differs
|
||
from MySQL's replace which deletes the record and inserts a new record. This
|
||
also means you cannot update the primary key. The only exception to this is
|
||
Interbase and its derivitives, which uses delete and insert because of some
|
||
Interbase API limitations.
|
||
<p>The parameters are $table which is the table name, the $keyCols which is an
|
||
associative array where the keys are the field names, and keyCols is the name
|
||
of the primary key, or an array of field names if it is a compound key. If
|
||
$autoQuote is set to true, then Replace() will quote all values that are non-numeric;
|
||
auto-quoting will not quote nulls. Note that auto-quoting will not work if
|
||
you use SQL functions or operators.
|
||
<p>Examples:
|
||
<pre>
|
||
# single field primary key
|
||
$ret = $db->Replace('atable',
|
||
array('id'=>1000,'firstname'=>'Harun','lastname'=>'Al-Rashid'),
|
||
'id',$autoquote = true);
|
||
# generates UPDATE atable SET firstname='Harun',lastname='Al-Rashid' WHERE id=1000
|
||
# or INSERT INTO atable (id,firstname,lastname) VALUES (1000,'Harun','Al-Rashid')
|
||
|
||
# compound key
|
||
$ret = $db->Replace('atable2',
|
||
array('firstname'=>'Harun','lastname'=>'Al-Rashid', 'age' => 33, 'birthday' => 'null'),
|
||
array('lastname','firstname'),
|
||
$autoquote = true);
|
||
|
||
# no auto-quoting
|
||
$ret = $db->Replace('atable2',
|
||
array('firstname'=>"'Harun'",'lastname'=>"'Al-Rashid'", 'age' => 'null'),
|
||
array('lastname','firstname'));
|
||
</pre>
|
||
<p><b>GetUpdateSQL<a name="getupdatesql"></a>(&$rs, $arrFields, $forceUpdate=false,$magicq=false, $force=null)</b></p>
|
||
<p>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. $magicq is used
|
||
to indicate whether magic quotes are enabled (see qstr()). The field names in the array
|
||
are case-insensitive.</p>
|
||
<p>Since 4.52, we allow you to pass the $force type parameter, and this overrides the <a href=#ADODB_FORCE_TYPE>$ADODB_FORCE_TYPE</a>
|
||
global variable.
|
||
<p><b>GetInsertSQL<a name="getinsertsql"></a>(&$rs, $arrFields,$magicq=false,$force=false)</b></p>
|
||
<p>Generate SQL to insert into a table given a recordset $rs. Requires the query
|
||
to be associative. $magicq is used to indicate whether magic quotes are enabled
|
||
(for qstr()). The field names in the array are case-insensitive.</p>
|
||
<p>
|
||
Since 2.42, you can pass a table name instead of a recordset into
|
||
GetInsertSQL (in $rs), and it will generate an insert statement for that table.
|
||
<p>Since 4.52, we allow you to pass the $force type parameter, and this overrides the <a href=#ADODB_FORCE_TYPE>$ADODB_FORCE_TYPE</a>
|
||
global variable.
|
||
<p><b>PageExecute<a name="pageexecute"></a>($sql, $nrows, $page, $inputarr=false)</b>
|
||
<p>Used for pagination of recordset. $page is 1-based. See <a href="#ex8">Example
|
||
8</a>.</p>
|
||
</font>
|
||
<p><font color="#000000"><b>CachePageExecute<a name="cachepageexecute"></a>($secs2cache,
|
||
$sql, $nrows, $page, $inputarr=false)</b> </font></p>
|
||
<p><font color="#000000">Used for pagination of recordset. $page is 1-based. See
|
||
<a href="#ex8">Example 8</a>. Caching version of PageExecute.</font></p>
|
||
<font color="#000000">
|
||
<p></p>
|
||
<p><b>Close<a name="close"></a>( )</b></p>
|
||
<p>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.</p>
|
||
<p><b>StartTrans<a name="starttrans"></a>( )</b></p>
|
||
<p>Start a monitored transaction. As SQL statements are executed, ADOdb will monitor
|
||
for SQL errors, and if any are detected, when CompleteTrans() is called, we auto-rollback.
|
||
<p>
|
||
<p> To understand why StartTrans() is superior to BeginTrans(),
|
||
let us examine a few ways of using BeginTrans().
|
||
The following is the wrong way to use transactions:
|
||
<pre>
|
||
$DB->BeginTrans();
|
||
$DB->Execute("update table1 set val=$val1 where id=$id");
|
||
$DB->Execute("update table2 set val=$val2 where id=$id");
|
||
$DB->CommitTrans();
|
||
</pre>
|
||
<p>because you perform no error checking. It is possible to update table1 and
|
||
for the update on table2 to fail. Here is a better way:
|
||
<pre>
|
||
$DB->BeginTrans();
|
||
$ok = $DB->Execute("update table1 set val=$val1 where id=$id");
|
||
if ($ok) $ok = $DB->Execute("update table2 set val=$val2 where id=$id");
|
||
if ($ok) $DB->CommitTrans();
|
||
else $DB->RollbackTrans();
|
||
</pre>
|
||
<p>Another way is (since ADOdb 2.0):
|
||
<pre>
|
||
$DB->BeginTrans();
|
||
$ok = $DB->Execute("update table1 set val=$val1 where id=$id");
|
||
if ($ok) $ok = $DB->Execute("update table2 set val=$val2 where id=$id");
|
||
$DB->CommitTrans($ok);
|
||
</pre>
|
||
<p> Now it is a headache monitoring $ok all over the place. StartTrans() is an
|
||
improvement because it monitors all SQL errors for you. This is particularly
|
||
useful if you are calling black-box functions in which SQL queries might be executed.
|
||
Also all BeginTrans, CommitTrans and RollbackTrans calls inside a StartTrans block
|
||
will be disabled, so even if the black box function does a commit, it will be ignored.
|
||
<pre>
|
||
$DB->StartTrans();
|
||
CallBlackBox();
|
||
$DB->Execute("update table1 set val=$val1 where id=$id");
|
||
$DB->Execute("update table2 set val=$val2 where id=$id");
|
||
$DB->CompleteTrans($ok);
|
||
</pre>
|
||
<p>Note that a StartTrans blocks are nestable, the inner blocks are ignored.
|
||
<p><b>CompleteTrans<a name="completetrans"></a>($autoComplete=true)</b></p>
|
||
<p>Complete a transaction called with StartTrans(). This function monitors
|
||
for SQL errors, and will commit if no errors have occured, otherwise it will rollback.
|
||
Returns true on commit, false on rollback. If the parameter $autoComplete is true
|
||
monitor sql errors and commit and rollback as appropriate. Set $autoComplete to false
|
||
to force rollback even if no SQL error detected.
|
||
<p><b>FailTrans<a name="failtrans"></a>( )</b></p>
|
||
<p>Fail a transaction started with StartTrans(). The rollback will only occur when
|
||
CompleteTrans() is called.
|
||
<p><b>HasFailedTrans<a name="hasfailedtrans"></a>( )</b></p>
|
||
<p>Check whether smart transaction has failed,
|
||
eg. returns true if there was an error in SQL execution or FailTrans() was called.
|
||
If not within smart transaction, returns false.
|
||
<p><b>BeginTrans<a name="begintrans"></a>( )</b></p>
|
||
<p>Begin a transaction. Turns off autoCommit. Returns true if successful. Some
|
||
databases will always return false if transaction support is not available.
|
||
Any open transactions will be rolled back when the connection is closed. Among the
|
||
databases that support transactions are Oracle, PostgreSQL, Interbase, MSSQL, certain
|
||
versions of MySQL, DB2, Informix, Sybase, etc.</p>
|
||
<p>Note that <a href=#starttrans>StartTrans()</a> and CompleteTrans() is a superior method of
|
||
handling transactions, available since ADOdb 3.40. For a explanation, see the <a href=#starttrans>StartTrans()</a> documentation.
|
||
|
||
<p>You can also use the ADOdb <a href=#errorhandling>error handler</a> to die
|
||
and rollback your transactions for you transparently. Some buggy database extensions
|
||
are known to commit all outstanding tranasactions, so you might want to explicitly
|
||
do a $DB->RollbackTrans() in your error handler for safety.
|
||
<h4>Detecting Transactions</h4>
|
||
<p>Since ADOdb 2.50, you are able to detect when you are inside a transaction. Check
|
||
that $connection->transCnt > 0. This variable is incremented whenever BeginTrans() is called,
|
||
and decremented whenever RollbackTrans() or CommitTrans() is called.
|
||
<p><b>CommitTrans<a name="committrans"></a>($ok=true)</b></p>
|
||
<p>End a transaction successfully. Returns true if successful. If the database
|
||
does not support transactions, will return true also as data is always committed.
|
||
</p>
|
||
<p>If you pass the parameter $ok=false, the data is rolled back. See example in
|
||
BeginTrans().</p>
|
||
<p><b>RollbackTrans<a name="rollbacktrans"></a>( )</b></p>
|
||
<p>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.
|
||
</p>
|
||
</font><font color="#000000">
|
||
<p><b>GetAssoc<a name=getassoc1></a>($sql,$inputarr=false,$force_array=false,$first2cols=false)</b></p>
|
||
<p>Returns an associative array for the given query $sql with optional bind parameters
|
||
in $inputarr. If the number of columns returned is greater to two, a 2-dimensional
|
||
array is returned, with the first column of the recordset becomes the keys
|
||
to the rest of the rows. If the columns is equal to two, a 1-dimensional array
|
||
is created, where the the keys directly map to the values (unless $force_array
|
||
is set to true, when an array is created for each value).
|
||
<p> <font color="#000000">Examples:<a name=getassocex></a></font></p>
|
||
</font>
|
||
<p><font color="#000000">We have the following data in a recordset:</font></p>
|
||
<p><font color="#000000">row1: Apple, Fruit, Edible<br>
|
||
row2: Cactus, Plant, Inedible<br>
|
||
row3: Rose, Flower, Edible</font></p>
|
||
<p><font color="#000000">GetAssoc will generate the following 2-dimensional associative
|
||
array:</font></p>
|
||
<p><font color="#000000">Apple => array[Fruit, Edible]<br>
|
||
Cactus => array[Plant, Inedible]<br>
|
||
Rose => array[Flower,Edible]</font></p>
|
||
<p><font color="#000000">If the dataset is:</font></p>
|
||
<p><font color="#000000"><font color="#000000"><font color="#000000">row1: Apple,
|
||
Fruit<br>
|
||
row2: Cactus, Plant<br>
|
||
row3: Rose, Flower</font> </font></font></p>
|
||
<p><font color="#000000"><font color="#000000">GetAssoc will generate the following
|
||
1-dimensional associative array (with $force_array==false):</font></font></p>
|
||
<p><font color="#000000">Apple => Fruit</font><br>
|
||
Cactus=>Plant<br>
|
||
Rose=>Flower <font color="#000000"><font color="#000000"> </font></font><font color="#000000"><font color="#000000"></font></font></p>
|
||
<p><font color="#000000">The function returns:</font></p>
|
||
<p><font color="#000000">The associative array, or false if an error occurs.</font></p>
|
||
<font color="#000000">
|
||
<p><b>CacheGetAssoc<a name="cachegetassoc"></a>([$secs2cache,] $sql,$inputarr=false,$force_array=false,$first2cols=false)</b></p>
|
||
</font><font color="#000000">
|
||
<p>Caching version of <a href=#getassoc1>GetAssoc</a> function above.
|
||
<p><b>GetOne<a name="getone"></a>($sql,$inputarr=false)</b></p>
|
||
<p>Executes the SQL and returns the first field of the first row. The recordset
|
||
and remaining rows are discarded for you automatically. If an error occur, false
|
||
is returned.</p>
|
||
<p><b>GetRow<a name="getrow"></a>($sql,$inputarr=false)</b></p>
|
||
<p>Executes the SQL and returns the first row as an array. The recordset and remaining
|
||
rows are discarded for you automatically. If an error occurs, false is returned.</p>
|
||
<p><b>GetAll<a name="getall"></a>($sql)</b></p>
|
||
</font>
|
||
<p><font color="#000000">Executes the SQL and returns the all the rows as a 2-dimensional
|
||
array. The recordset is discarded for you automatically. If an error occurs,
|
||
false is returned.</font></p>
|
||
<p><b>GetCol<a name="getcol"></a>($sql,$inputarr=false,$trim=false)</b></p>
|
||
|
||
<p><font color="#000000">Executes the SQL and returns all elements of the first column as a
|
||
1-dimensional array. The recordset is discarded for you automatically. If an error occurs,
|
||
false is returned.</font></p>
|
||
<p><font color="#000000"><b>CacheGetOne<a name="cachegetone"></a>([$secs2cache,]
|
||
$sql,$inputarr=false), CacheGetRow<a name="cachegetrow"></a>([$secs2cache,] $sql,$inputarr=false), CacheGetAll<a name="cachegetall"></a>([$secs2cache,]
|
||
$sql,$inputarr=false), CacheGetCol<a name="cachegetcol"></a>([$secs2cache,]
|
||
$sql,$inputarr=false,$trim=false)</b></font></p>
|
||
<font color="#000000">
|
||
<p>Similar to above Get* functions, except that the recordset is serialized and
|
||
cached in the $ADODB_CACHE_DIR directory for $secs2cache seconds. Good for speeding
|
||
up queries on rarely changing data. Note that the $secs2cache parameter is optional.
|
||
If omitted, we use the value in $connection->cacheSecs (default is 3600 seconds,
|
||
or 1 hour).</p>
|
||
<p><b>Prepare<a name="prepare"></a>($sql )</b></p>
|
||
</font>
|
||
<p><font color="#000000">Prepares (compiles) an SQL query for repeated execution. Bind parameters
|
||
are denoted by ?, except for the oci8 driver, which uses the traditional Oracle :varname
|
||
convention.
|
||
</font></p>
|
||
<p><font color="#000000">Returns an array containing the original sql statement
|
||
in the first array element; the remaining elements of the array are driver dependent.
|
||
If there is an error, or we are emulating Prepare( ), we return the original
|
||
$sql string. This is because all error-handling has been centralized in Execute(
|
||
).</font></p>
|
||
<p><font color="#000000">Prepare( ) cannot be used with functions that use SQL
|
||
query rewriting techniques, e.g. PageExecute( ) and SelectLimit( ).</font></p>
|
||
<p>Example:</p>
|
||
<pre><font color="#000000">$stmt = $DB->Prepare('insert into table (col1,col2) values (?,?)');
|
||
for ($i=0; $i < $max; $i++)<br></font> $DB-><font color="#000000">Execute($stmt,array((string) rand(), $i));
|
||
</font></pre>
|
||
<font color="#000000">
|
||
<p>Also see InParameter(), OutParameter() and PrepareSP() below. Only supported internally by interbase,
|
||
oci8 and selected ODBC-based drivers, otherwise it is emulated. There is no
|
||
performance advantage to using Prepare() with emulation.
|
||
<p> Important: Due to limitations or bugs in PHP, if you are getting errors when
|
||
you using prepared queries, try setting $ADODB_COUNTRECS = false before preparing.
|
||
This behaviour has been observed with ODBC.
|
||
<p><b>IfNull<a name="ifnull"></a>($field, $nullReplacementValue)</b></p>
|
||
<p>Portable IFNULL function (NVL in Oracle). Returns a string that represents
|
||
the function that checks whether a $field is null for the given database, and
|
||
if null, change the value returned to $nullReplacementValue. Eg.</p>
|
||
<pre>$sql = <font color="#993300">'SELECT '</font>.$db->IfNull('name', <font color="#993300">"'- unknown -'"</font>).<font color="#993300"> ' FROM table'</font>;</pre>
|
||
|
||
<p><b>length<a name="length"></a></b></p>
|
||
<p>This is not a function, but a property. Some databases have "length" and others "len"
|
||
as the function to measure the length of a string. To use this property:
|
||
<pre>
|
||
$sql = <font color="#993300">"SELECT "</font>.$db->length.<font color="#993300">"(field) from table"</font>;
|
||
$rs = $db->Execute($sql);
|
||
</pre>
|
||
|
||
<p><b>random<a name="random"></a></b></p>
|
||
<p>This is not a function, but a property. This is a string that holds the sql to
|
||
generate a random number between 0.0 and 1.0 inclusive.
|
||
|
||
<p><b>substr<a name="substr"></a></b></p>
|
||
<p>This is not a function, but a property. Some databases have "substr" and others "substring"
|
||
as the function to retrieve a sub-string. To use this property:
|
||
<pre>
|
||
$sql = <font color="#993300">"SELECT "</font>.$db->substr.<font color="#993300">"(field, $offset, $length) from table"</font>;
|
||
$rs = $db->Execute($sql);
|
||
</pre>
|
||
<p>For all databases, the 1st parameter of <i>substr</i> is the field, the 2nd is the
|
||
offset (1-based) to the beginning of the sub-string, and the 3rd is the length of the sub-string.
|
||
|
||
|
||
<p><b>Param<a name="param"></a>($name)</b></p>
|
||
<p>Generates a bind placeholder portably. For most databases, the bind placeholder
|
||
is "?". However some databases use named bind parameters such as Oracle, eg
|
||
":somevar". This allows us to portably define an SQL statement with bind parameters:
|
||
<pre><font color="#000000">$sql = <font color="#993300">'insert into table (col1,col2) values ('</font>.$DB->Param('a').<font color="#993300">','</font>.$DB->Param('b').<font color="#993300">')'</font>;
|
||
<font color="#006600"># generates 'insert into table (col1,col2) values (?,?)'
|
||
# or 'insert into table (col1,col2) values (:a,:b)</font>'
|
||
$stmt = $DB->Prepare($sql);
|
||
$stmt = $DB->Execute($stmt,array('one','two'));
|
||
</font></pre>
|
||
<font color="#000000">
|
||
<p></p>
|
||
<p><b>PrepareSP</b><b><a name="preparesp"></a></b><b>($sql, $cursor=false )</b></p>
|
||
<p>When calling stored procedures in mssql and oci8 (oracle), and you might want
|
||
to directly bind to parameters that return values, or for special LOB handling.
|
||
PrepareSP() allows you to do so.
|
||
<p>Returns the same array or $sql string as Prepare( ) above. If you do not need
|
||
to bind to return values, you should use Prepare( ) instead.</p>
|
||
<p>The 2nd parameter, $cursor is not used except with oci8. Setting it to true will
|
||
force OCINewCursor to be called; this is to support output REF CURSORs.
|
||
<p>For examples of usage of PrepareSP( ), see InParameter( ) below.
|
||
<p>Note: in the mssql driver, preparing stored procedures requires a special function
|
||
call, mssql_init( ), which is called by this function. PrepareSP( ) is available
|
||
in all other drivers, and is emulated by calling Prepare( ). </p>
|
||
<p><b> InParameter<a name="inparameter"></a>($stmt, $var, $name,
|
||
$maxLen = 4000, $type = false )</b></p>
|
||
Binds a PHP variable as input to a stored procedure variable. The parameter <i>$stmt</i>
|
||
is the value returned by PrepareSP(), <i>$var</i> is the PHP variable you want to bind, $name
|
||
is the name of the stored procedure variable. Optional is <i>$maxLen</i>, the maximum length of the
|
||
data to bind, and $type which is database dependant.
|
||
Consult <a href=http://php.net/mssql_bind>mssql_bind</a> and <a href=http://php.net/ocibindbyname>ocibindbyname</a> docs
|
||
at php.net for more info on legal values for $type.
|
||
<p>
|
||
InParameter() is a wrapper function that calls Parameter() with $isOutput=false.
|
||
The advantage of this function is that it is self-documenting, because
|
||
the $isOutput parameter is no longer needed. Only for mssql
|
||
and oci8 currently.
|
||
<p>Here is an example using oci8:
|
||
<pre><font color="green"># For oracle, Prepare and PrepareSP are identical</font>
|
||
$stmt = $db->PrepareSP(
|
||
<font color="#993300">"declare RETVAL integer;
|
||
begin
|
||
:RETVAL := </font><font color="#993300">SP_RUNSOMETHING</font><font color="#993300">(:myid,:group);
|
||
end;"</font>);
|
||
$db->InParameter($stmt,$id,'myid');
|
||
$db->InParameter($stmt,$group,'group',64);
|
||
$db->OutParameter($stmt,$ret,'RETVAL');<br>$db->Execute($stmt);
|
||
</pre>
|
||
<p> The same example using mssql:</p>
|
||
</font>
|
||
<pre><font color="#000000"><font color="green"># @RETVAL = SP_RUNSOMETHING @myid,@group</font>
|
||
$stmt = $db->PrepareSP(<font color="#993333">'<font color="#993300">SP_RUNSOMETHING</font>'</font>); <br><font color="green"># note that the parameter name does not have @ in front!</font>
|
||
$db->InParameter($stmt,$id,'myid');
|
||
$db->InParameter($stmt,$group,'group',64);
|
||
<font color="green"># return value in mssql - RETVAL is hard-coded name</font>
|
||
$db->OutParameter($stmt,$ret,'RETVAL');
|
||
$db->Execute($stmt); </font></pre>
|
||
|
||
<p>Note that the only difference between the oci8 and mssql implementations is $sql.</p>
|
||
<p>
|
||
If $type parameter is set to false, in mssql, $type will be dynamicly determined
|
||
based on the type of the PHP variable passed <font face="Courier New, Courier, mono">(string
|
||
=> SQLCHAR, boolean =>SQLINT1, integer =>SQLINT4 or float/double=>SQLFLT8)</font>.
|
||
<p>
|
||
In oci8, $type can be set to OCI_B_FILE (Binary-File), OCI_B_CFILE (Character-File),
|
||
OCI_B_CLOB (Character-LOB), OCI_B_BLOB (Binary-LOB) and OCI_B_ROWID (ROWID). To
|
||
pass in a null, use<font face="Courier New, Courier, mono"> $db->Parameter($stmt,
|
||
$null=null, 'param')</font>.
|
||
<p><b> OutParameter<a name="outparameter"></a>($stmt, $var, $name,
|
||
$maxLen = 4000, $type = false )</b></p>
|
||
Binds a PHP variable as output from a stored procedure variable. The parameter <i>$stmt</i>
|
||
is the value returned by PrepareSP(), <i>$var</i> is the PHP variable you want to bind, <i>$name</i>
|
||
is the name of the stored procedure variable. Optional is <i>$maxLen</i>, the maximum length of the
|
||
data to bind, and <i>$type</i> which is database dependant.
|
||
<p>
|
||
OutParameter() is a wrapper function that calls Parameter() with $isOutput=true.
|
||
The advantage of this function is that it is self-documenting, because
|
||
the $isOutput parameter is no longer needed. Only for mssql
|
||
and oci8 currently.
|
||
<p>
|
||
For an example, see <a href=#inparameter>InParameter</a>.
|
||
|
||
<p><b> Parameter<a name="parameter"></a>($stmt, $var, $name, $isOutput=false,
|
||
$maxLen = 4000, $type = false )</b></p>
|
||
<p>Note: This function is deprecated, because of the new InParameter() and OutParameter() functions.
|
||
These are superior because they are self-documenting, unlike Parameter().
|
||
<p>Adds a bind parameter suitable for return values or special data handling (eg.
|
||
LOBs) after a statement has been prepared using PrepareSP(). Only for mssql
|
||
and oci8 currently. The parameters are:<br>
|
||
<br>
|
||
$<i><b>stmt</b></i> Statement returned by Prepare() or PrepareSP().<br>
|
||
$<i><b>var</b></i> PHP variable to bind to. Make sure you pre-initialize it!<br>
|
||
$<i><b>name</b></i> Name of stored procedure variable name to bind to.<br>
|
||
[$<i><b>isOutput</b></i>] Indicates direction of parameter 0/false=IN 1=OUT
|
||
2= IN/OUT. This is ignored in oci8 as this driver auto-detects the direction.<br>
|
||
[$<b>maxLen</b>] Maximum length of the parameter variable.<br>
|
||
[$<b>type</b>] Consult <a href="http://php.net/mssql_bind">mssql_bind</a> and
|
||
<a href="http://php.net/ocibindbyname">ocibindbyname</a> docs at php.net for
|
||
more info on legal values for type.</p>
|
||
<p>Lastly, in oci8, bind parameters can be reused without calling PrepareSP( )
|
||
or Parameters again. This is not possible with mssql. An oci8 example:</p>
|
||
<pre>$id = 0; $i = 0;
|
||
$stmt = $db->PrepareSP( <font color="#993300">"update table set val=:i where id=:id"</font>);
|
||
$db->Parameter($stmt,$id,'id');
|
||
$db->Parameter($stmt,$i, 'i');
|
||
for ($cnt=0; $cnt < 1000; $cnt++) {
|
||
$id = $cnt; <br> $i = $cnt * $cnt; <font color="green"># works with oci8!</font>
|
||
$db->Execute($stmt); <br>}</pre>
|
||
<p><b>Bind<a name="bind"></a>($stmt, $var, $size=4001, $type=false, $name=false)</b></p>
|
||
</font>
|
||
<p><font color="#000000">This is a low-level function supported only by the oci8
|
||
driver. <b>Avoid using</b> unless you only want to support Oracle. The Parameter(
|
||
) function is the recommended way to go with bind variables.</font></p>
|
||
<p><font color="#000000">Bind( ) allows you to use bind variables in your sql
|
||
statement. This binds a PHP variable to a name defined in an Oracle sql statement
|
||
that was previously prepared using Prepare(). Oracle named variables begin with
|
||
a colon, and ADOdb requires the named variables be called :0, :1, :2, :3, etc.
|
||
The first invocation of Bind() will match :0, the second invocation will match
|
||
:1, etc. Binding can provide 100% speedups for insert, select and update statements.
|
||
</font></p>
|
||
<p>The other variables, $size sets the buffer size for data storage, $type is
|
||
the optional descriptor type OCI_B_FILE (Binary-File), OCI_B_CFILE (Character-File),
|
||
OCI_B_CLOB (Character-LOB), OCI_B_BLOB (Binary-LOB) and OCI_B_ROWID (ROWID).
|
||
Lastly, instead of using the default :0, :1, etc names, you can define your
|
||
own bind-name using $name.
|
||
<p><font color="#000000">The following example shows 3 bind variables being used:
|
||
p1, p2 and p3. These variables are bound to :0, :1 and :2.</font></p>
|
||
<pre>$stmt = $DB->Prepare("insert into table (col0, col1, col2) values (:0, :1, :2)");
|
||
$DB->Bind($stmt, $p1);
|
||
$DB->Bind($stmt, $p2);
|
||
$DB->Bind($stmt, $p3);
|
||
for ($i = 0; $i < $max; $i++) {
|
||
$p1 = ?; $p2 = ?; $p3 = ?;
|
||
$DB->Execute($stmt);
|
||
}</pre>
|
||
<p>You can also use named variables:</p>
|
||
<pre>
|
||
$stmt = $DB->Prepare("insert into table (col0, col1, col2) values (:name0, :name1, :name2)");
|
||
$DB->Bind($stmt, $p1, "name0");
|
||
$DB->Bind($stmt, $p2, "name1");
|
||
$DB->Bind($stmt, $p3, "name2");
|
||
for ($i = 0; $i < $max; $i++) {
|
||
$p1 = ?; $p2 = ?; $p3 = ?;
|
||
$DB->Execute($stmt);
|
||
}</pre>
|
||
<p><b>LogSQL($enable=true)<a name=logsql></a></b></p>
|
||
Call this method to install a SQL logging and timing function (using fnExecute).
|
||
Then all SQL statements are logged into an adodb_logsql table in a database. If
|
||
the adodb_logsql table does not exist, ADOdb will create the table if you have
|
||
the appropriate permissions. Returns the previous logging value (true for enabled,
|
||
false for disabled). Here are samples of the DDL for selected databases:
|
||
<p>
|
||
<pre>
|
||
<b>mysql:</b>
|
||
CREATE TABLE adodb_logsql (
|
||
created datetime NOT NULL,
|
||
sql0 varchar(250) NOT NULL,
|
||
sql1 text NOT NULL,
|
||
params text NOT NULL,
|
||
tracer text NOT NULL,
|
||
timer decimal(16,6) NOT NULL
|
||
)
|
||
|
||
<b>postgres:</b>
|
||
CREATE TABLE adodb_logsql (
|
||
created timestamp NOT NULL,
|
||
sql0 varchar(250) NOT NULL,
|
||
sql1 text NOT NULL,
|
||
params text NOT NULL,
|
||
tracer text NOT NULL,
|
||
timer decimal(16,6) NOT NULL
|
||
)
|
||
|
||
<b>mssql:</b>
|
||
CREATE TABLE adodb_logsql (
|
||
created datetime NOT NULL,
|
||
sql0 varchar(250) NOT NULL,
|
||
sql1 varchar(4000) NOT NULL,
|
||
params varchar(3000) NOT NULL,
|
||
tracer varchar(500) NOT NULL,
|
||
timer decimal(16,6) NOT NULL
|
||
)
|
||
|
||
<b>oci8:</b>
|
||
CREATE TABLE adodb_logsql (
|
||
created date NOT NULL,
|
||
sql0 varchar(250) NOT NULL,
|
||
sql1 varchar(4000) NOT NULL,
|
||
params varchar(4000),
|
||
tracer varchar(4000),
|
||
timer decimal(16,6) NOT NULL
|
||
)
|
||
</pre>
|
||
Usage:
|
||
<pre>
|
||
$conn->LogSQL(); // turn on logging
|
||
:
|
||
$conn->Execute(...);
|
||
:
|
||
$conn->LogSQL(false); // turn off logging
|
||
|
||
# output summary of SQL logging results
|
||
$perf = NewPerfMonitor($conn);
|
||
echo $perf->SuspiciousSQL();
|
||
echo $perf->ExpensiveSQL();
|
||
</pre>
|
||
<p>One limitation of logging is that rollback also prevents SQL from being logged.
|
||
<p>
|
||
If you prefer to use another name for the table used to store the SQL, you can override it by calling
|
||
adodb_perf::table($tablename), where $tablename is the new table name (you will still need to manually
|
||
create the table yourself). An example:
|
||
<pre>
|
||
include('adodb.inc.php');
|
||
include('adodb-perf.inc.php');
|
||
adodb_perf::table('my_logsql_table');
|
||
</pre>
|
||
Also see <a href=docs-perf.htm>Performance Monitor</a>.
|
||
<p><font color="#000000"><b>fnExecute and fnCacheExecute properties<a name="fnexecute" id="fnexecute"></a></b></font></p>
|
||
<p>These two properties allow you to define bottleneck functions for all sql statements
|
||
processed by ADOdb. This allows you to perform statistical analysis and query-rewriting
|
||
of your sql.
|
||
<p><b>Examples of fnExecute</b></p>
|
||
<p>Here is an example of using fnExecute, to count all cached queries and non-cached
|
||
queries, you can do this:</p>
|
||
<pre><font color="#006600"># $db is the connection object</font>
|
||
function CountExecs($db, $sql, $inputarray)
|
||
{
|
||
global $EXECS;
|
||
|
||
if (!is_array(inputarray)) $EXECS++;
|
||
<font color="#006600"># handle 2-dimensional input arrays</font>
|
||
else if (is_array(reset($inputarray))) $EXECS += sizeof($inputarray);
|
||
else $EXECS++;
|
||
}
|
||
|
||
<font color="#006600"># $db is the connection object</font>
|
||
function CountCachedExecs($db, $secs2cache, $sql, $inputarray)
|
||
{<br>global $CACHED; $CACHED++;
|
||
}
|
||
<br>$db = NewADOConnection('mysql');
|
||
$db->Connect(...);
|
||
$db-><strong>fnExecute</strong> = 'CountExecs';
|
||
$db-><strong>fnCacheExecute</strong> = 'CountCachedExecs';
|
||
:
|
||
:<br><font color="#006600"># After many sql statements:</font>`
|
||
printf("<p>Total queries=%d; total cached=%d</p>",$EXECS+$CACHED, $CACHED);
|
||
</pre>
|
||
<p>The fnExecute function is called before the sql is parsed and executed, so
|
||
you can perform a query rewrite. If you are passing in a prepared statement,
|
||
then $sql is an array (see <a href="#prepare">Prepare</a>). The fnCacheExecute
|
||
function is only called if the recordset returned was cached.<font color="#000000">
|
||
The function parameters match the Execute and CacheExecute functions respectively,
|
||
except that $this (the connection object) is passed as the first parameter.</font></p>
|
||
<p>Since ADOdb 3.91, the behaviour of fnExecute varies depending on whether the
|
||
defined function returns a value. If it does not return a value, then the $sql
|
||
is executed as before. This is useful for query rewriting or counting sql queries.
|
||
<p> On the other hand, you might want to replace the Execute function with one
|
||
of your own design. If this is the case, then have your function return a value.
|
||
If a value is returned, that value is returned immediately, without any further
|
||
processing. This is used internally by ADOdb to implement LogSQL() functionality.
|
||
<p> <font color="#000000">
|
||
<hr>
|
||
<h3>ADOConnection Utility Functions</h3>
|
||
<p><b>BlankRecordSet<a name="blankrecordset"></a>([$queryid])</b></p>
|
||
<p>No longer available - removed since 1.99.</p>
|
||
<p><b>Concat<a name="concat"></a>($s1,$s2,....)</b></p>
|
||
<p>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.</p>
|
||
<p>Returns the concatenated string.</p>
|
||
<p><b>DBDate<a name="dbdate"></a>($date)</b></p>
|
||
<p>Format the $<b>date</b> in the format the database accepts. This is used in
|
||
INSERT/UPDATE statements; for SELECT statements, use <a href="#sqldate">SQLDate</a>.
|
||
The $<b>date</b> parameter can be a Unix integer timestamp or an ISO format
|
||
Y-m-d. Uses the fmtDate field, which holds the format to use. If null or false
|
||
or '' is passed in, it will be converted to an SQL null.</p>
|
||
<p>Returns the date as a quoted string.</p>
|
||
<p><b>DBTimeStamp<a name="dbtimestamp"></a>($ts)</b></p>
|
||
<p>Format the timestamp $<b>ts</b> in the format the database accepts; this can
|
||
be a Unix integer timestamp or an ISO format Y-m-d H:i:s. Uses the fmtTimeStamp
|
||
field, which holds the format to use. If null or false or '' is passed in, it
|
||
will be converted to an SQL null.</p>
|
||
<p>Returns the timestamp as a quoted string.</p>
|
||
<p><b>qstr<a name="qstr"></a>($s,[$magic_quotes_enabled</b>=false]<b>)</b></p>
|
||
<p>Quotes a string to be sent to the database. The $<b>magic_quotes_enabled</b>
|
||
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 <i>qstr</i>
|
||
and once by the <i>magic_quotes_gpc</i>.</p>
|
||
<p>Eg.<font face="Courier New, Courier, mono"> $s = $db->qstr(HTTP_GET_VARS['name'],get_magic_quotes_gpc());</font></p>
|
||
<p>Returns the quoted string.</p>
|
||
<p><b>Quote<a name="quote"></a>($s)</b></p>
|
||
<p>Quotes the string $s, escaping the database specific quote character as appropriate.
|
||
Formerly checked magic quotes setting, but this was disabled since 3.31 for
|
||
compatibility with PEAR DB.
|
||
<p><b>Affected_Rows<a name="affected_rows"></a>( )</b></p>
|
||
<p>Returns the number of rows affected by a update or delete statement. Returns
|
||
false if function not supported.</p>
|
||
<p>Not supported by interbase/firebird currently. </p>
|
||
<p><b>Insert_ID<a name="inserted_id"></a>( )</b></p>
|
||
<p>Returns the last autonumbering ID inserted. Returns false if function not supported.
|
||
</p>
|
||
<p>Only supported by databases that support auto-increment or object id's, such
|
||
as PostgreSQL, MySQL and MS SQL Server currently. PostgreSQL returns the OID, which
|
||
can change on a database reload.</p>
|
||
<p><b>RowLock<a name="rowlock"></a>($table,$where)</b></p>
|
||
<p>Lock a table row for the duration of a transaction. For example to lock record $id in table1:
|
||
<pre>
|
||
$DB->StartTrans();
|
||
$DB->RowLock("table1","rowid=$id");
|
||
$DB->Execute($sql1);
|
||
$DB->Execute($sql2);
|
||
$DB->CompleteTrans();
|
||
</pre>
|
||
<p>Supported in db2, interbase, informix, mssql, oci8, postgres, sybase.
|
||
<p><b>MetaDatabases<a name="metadatabases"></a>()</b></p>
|
||
<p>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.</p>
|
||
<p><b>MetaTables<a name="metatables"></a>($ttype = false, $showSchema = false,
|
||
$mask=false)</b></p>
|
||
<p>Returns an array of tables and views for the current database as an array.
|
||
The array should exclude system catalog tables if possible. To only show tables,
|
||
use $db->MetaTables('TABLES'). To show only views, use $db->MetaTables('VIEWS').
|
||
The $showSchema parameter currently works only for DB2, and when set to true,
|
||
will add the schema name to the table, eg. "SCHEMA.TABLE". </p>
|
||
<p>You can define a mask for matching. For example, setting $mask = 'TMP%' will
|
||
match all tables that begin with 'TMP'. Currently only mssql, oci8, odbc_mssql
|
||
and postgres* support $mask.
|
||
<p><b>MetaColumns<a name="metacolumns"></a>($table,$toupper=true)</b></p>
|
||
<p>Returns an array of ADOFieldObject's, one field object for every column of
|
||
$table. A field object is a class instance with (name, type, max_length) defined.
|
||
Currently Sybase does not recognise date types, and ADO cannot identify
|
||
the correct data type (so we default to varchar).
|
||
<p> The $toupper parameter determines whether we uppercase the table name
|
||
(required for some databases).
|
||
<p>For schema support, pass in the $table parameter, "$schema.$tablename". This is only
|
||
supported for selected databases.
|
||
<p><b>MetaColumnNames<a name="metacolumnames"></a>($table,$numericIndex=false)</b></p>
|
||
<p>Returns an array of column names for $table. Since ADOdb 4.22, this is an associative array, with the
|
||
keys in uppercase. Set $numericIndex=true if you want the old behaviour of numeric indexes (since 4.23).
|
||
<p>
|
||
e.g. array('FIELD1' => 'Field1', 'FIELD2'=>'Field2')
|
||
<p>
|
||
<p><font color="#000000"><b>MetaPrimaryKeys<a name="metaprimarykeys"></a>($table,
|
||
$owner=false)</b></font></font>
|
||
<p><font color="#000000">Returns an array containing column names that are the
|
||
primary keys of $table. Supported by mysql, odbc (including db2, odbc_mssql,
|
||
etc), mssql, postgres, interbase/firebird, oci8 currently. </font><font color="#000000">
|
||
<p>Views (and some tables) have primary keys, but sometimes this information is not available from the
|
||
database. You can define a function ADODB_View_PrimaryKeys($databaseType, $database, $view, $owner) that
|
||
should return an array containing the fields that make up the primary key. If that function exists,
|
||
it will be called when MetaPrimaryKeys() cannot find a primary key for a table or view.
|
||
<pre>
|
||
// In this example: dbtype = 'oci8', $db = 'mydb', $view = 'dataView', $owner = false
|
||
function ADODB_View_PrimaryKeys($dbtype,$db,$view,$owner)
|
||
{
|
||
switch(strtoupper($view)) {
|
||
case 'DATAVIEW': return array('DATAID');
|
||
default: return false;
|
||
}
|
||
}
|
||
|
||
$db = NewADOConnection('oci8');
|
||
$db->Connect('localhost','root','','mydb');
|
||
$db->MetaPrimaryKeys('dataView');
|
||
</pre>
|
||
<p><font color="#000000"><b>ServerInfo<a name="serverinfo" id="serverinfo"></a>($table)</b></font></font>
|
||
<p><font color="#000000">Returns an array of containing two elements 'description'
|
||
and 'version'. The 'description' element contains the string description of
|
||
the database. The 'version' naturally holds the version number (which is also
|
||
a string).</font><font color="#000000">
|
||
<p><b>MetaForeignKeys<a name="metaforeignkeys"></a>($table, $owner=false, $upper=false)</b>
|
||
<p>Returns an associate array of foreign keys, or false if not supported. For
|
||
example, if table employee has a foreign key where employee.deptkey points to
|
||
dept_table.deptid, and employee.posn=posn_table.postionid and employee.poscategory=posn_table.category,
|
||
then $conn->MetaForeignKeys('employee') will return
|
||
<pre>
|
||
array(
|
||
'dept_table' => array('deptkey=deptid'),
|
||
'posn_table' => array('posn=positionid','poscategory=category')
|
||
)
|
||
</pre>
|
||
<p>The optional schema or owner can be defined in $owner. If $upper is true, then
|
||
the table names (array keys) are upper-cased.
|
||
<hr>
|
||
<h2>ADORecordSet<a name="adorecordset"></a></h2>
|
||
<p>When an SQL statement successfully is executed by <font face="Courier New, Courier, mono">ADOConnection->Execute($sql),</font>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.</p>
|
||
<h3>ADORecordSet Fields</h3>
|
||
<p><b>fields: </b>Array containing the current row. This is not associative, but
|
||
is an indexed array from 0 to columns-1. See also the function <b><a href="#fields">Fields</a></b>,
|
||
which behaves like an associative array.</p>
|
||
<p><b>dataProvider</b>: The underlying mechanism used to connect to the database.
|
||
Normally set to <b>native</b>, unless using <b>odbc</b> or <b>ado</b>.</p>
|
||
<p><b>blobSize</b>: 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 <a href="#metatype">MetaType</a>
|
||
function.</p>
|
||
<p><b>sql</b>: Holds the sql statement used to generate this record set.</p>
|
||
<p><b>canSeek</b>: Set to true if Move( ) function works.</p>
|
||
<p><b>EOF</b>: True if we have scrolled the cursor past the last record.</p>
|
||
<h3>ADORecordSet Functions</h3>
|
||
<p><b>ADORecordSet( )</b></p>
|
||
<p>Constructer. Normally you never call this function yourself.</p>
|
||
<p><b>GetAssoc<a name="getassoc"></a>([$force_array])</b></p>
|
||
<p>Generates an associative array from the recordset. Note that is this function
|
||
is also <a href="#getassoc1">available</a> in the connection object. More details
|
||
can be found there.</p>
|
||
</font></font><font color="#000000"><font color="#000000"> </font></font><font color="#000000"><font color="#000000">
|
||
<p><b>GetArray<a name="getarray"></a>([$number_of_rows])</b></p>
|
||
<p>Generate a 2-dimensional array of records from the current cursor position,
|
||
indexed from 0 to $number_of_rows - 1. If $number_of_rows is undefined, till
|
||
EOF.</p>
|
||
<p><b>GetRows<a name="getrows"></a>([$number_of_rows])</b></p>
|
||
Generate a 2-dimensional array of records from the current cursor position. Synonym
|
||
for GetArray() for compatibility with Microsoft ADO.
|
||
<p> <b>GetMenu<a name="getmenu"></a>($name, [$default_str=''], [$blank1stItem=true],
|
||
[$multiple_select=false], [$size=0], [$moreAttr=''])</b></p>
|
||
<p>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 $<i>name</i>.
|
||
<p> If $<i>default_str</i> is defined, then if $<i>default_str</i> == fields[0],
|
||
that field is selected. If $<i>blank1stItem</i> is true, the first option is
|
||
empty. You can also set the first option strings by setting $blank1stItem =
|
||
"$value:$text".</p>
|
||
<p>$<i>Default_str</i> can be array for a multiple select listbox.</p>
|
||
<p>To get a listbox, set the $<i>size</i> to a non-zero value (or pass $default_str
|
||
as an array). If $<i>multiple_select</i> is true then a listbox will be generated
|
||
with $<i>size</i> items (or if $size==0, then 5 items) visible, and we will
|
||
return an array to a server. Lastly use $<i>moreAttr </i> to add additional
|
||
attributes such as javascript or styles. </p>
|
||
<p>Menu Example 1: <code>GetMenu('menu1','A',true)</code> will generate a menu:
|
||
<select name='menu1'>
|
||
<option>
|
||
<option value=1 selected>A
|
||
<option value=2>B
|
||
<option value=3>C
|
||
</select>
|
||
for the data (A,1), (B,2), (C,3). Also see <a href="#ex5">example 5</a>.</p>
|
||
<p>Menu Example 2: For the same data, <code>GetMenu('menu1',array('A','B'),false)</code>
|
||
will generate a menu with both A and B selected: <br>
|
||
<select name='menu1' multiple size=3>
|
||
<option value=1 selected>A
|
||
<option value=2 selected>B
|
||
<option value=3>C
|
||
</select>
|
||
<p> <b>GetMenu2<a name="getmenu2"></a>($name, [$default_str=''], [$blank1stItem=true],
|
||
[$multiple_select=false], [$size=0], [$moreAttr=''])</b></p>
|
||
<p>This is nearly identical to GetMenu, except that the $<i>default_str</i> is
|
||
matched to fields[1] (the option values).</p>
|
||
<p>Menu Example 3: Given the data in menu example 2, <code>GetMenu2('menu1',array('1','2'),false)</code>
|
||
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.
|
||
<p><b>UserDate<a name="userdate"></a>($str, [$fmt])</b></p>
|
||
<p>Converts the date string $<i>str</i> to another format. The date format is Y-m-d,
|
||
or Unix timestamp format. The default $<i>fmt</i> is Y-m-d.</p>
|
||
<p><b>UserTimeStamp<a name="usertimestamp"></a>($str, [$fmt])</b></p>
|
||
<p>Converts the timestamp string $<b>str</b> to another format. The timestamp
|
||
format is Y-m-d H:i:s, as in '2002-02-28 23:00:12', or Unix timestamp format.
|
||
UserTimeStamp calls UnixTimeStamp to parse $<i>str</i>, and $<i>fmt</i> defaults to Y-m-d H:i:s if not defined.
|
||
</p>
|
||
<p><b>UnixDate<a name="unixdate"></a>($str)</b></p>
|
||
<p>Parses the date string $<b>str</b> 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).</p>
|
||
<p>This function is available in both ADORecordSet and ADOConnection since 1.91.</p>
|
||
<p><b>UnixTimeStamp<a name="unixtimestamp"></a>($str)</b></p>
|
||
<p>Parses the timestamp string $<b>str</b> 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" (1970-12-24, 00:00:00) or "Y-m-d H:i:s" (1970-12-24 00:00:00) or "YmdHis" (19701225000000) format, except for Sybase and Microsoft SQL Server, where
|
||
"M d Y h:i:sA" (Dec 25 1970 00:00:00AM) is also accepted (the 3 letter month strings are controlled by
|
||
a global array, which might need localisation).</p>
|
||
</font>
|
||
<p><font color="#000000">This function is available in both ADORecordSet and ADOConnection
|
||
since 1.91. </font></p>
|
||
<p><font color="#000000"><b>OffsetDate<a name="offsetdate"></a>($dayFraction,
|
||
$basedate=false)</b></font></p>
|
||
<p><font color="#000000"><font color="#000000">Returns a string </font>with the
|
||
native SQL functions to calculate future and past dates based on $basedate in
|
||
a portable fashion. If $basedate is not defined, then the current date (at 12
|
||
midnight) is used. Returns the SQL string that performs the calculation when
|
||
passed to Execute(). </font></p>
|
||
<p><font color="#000000">For example, in Oracle, to find the date and time that
|
||
is 2.5 days from today, you can use:</font></p>
|
||
<pre><font color="#000000"># get date one week from now
|
||
$fld = $conn->OffsetDate(7); // returns "(trunc(sysdate)+7")</font></pre>
|
||
<pre><font color="#000000"># get date and time that is 60 hours from current date and time
|
||
$fld = $conn->OffsetDate(2.5, $conn->sysTimeStamp); // returns "(sysdate+2.5)"</font>
|
||
|
||
$conn->Execute("UPDATE TABLE SET dodate=$fld WHERE ID=$id");</pre>
|
||
<p> This function is available for mysql, mssql, oracle, oci8 and postgresql drivers
|
||
since 2.13. It might work with other drivers<font color="#000000"> provided
|
||
they allow performing numeric day arithmetic on dates.</font></p>
|
||
<font color="#000000">
|
||
<p><font color="#000000"><b>SQLDate<a name="sqldate"></a>($dateFormat, $basedate=false)</b></font></p>
|
||
Returns a string which contains the native SQL functions to format a date or date
|
||
column $basedate. This is used in SELECT statements. For INSERT/UPDATE statements,
|
||
use <a href="#dbdate">DBDate</a>. It uses a case-sensitive $dateFormat, which
|
||
supports:
|
||
<pre>
|
||
Y: 4-digit Year
|
||
Q: Quarter (1-4)
|
||
M: Month (Jan-Dec)
|
||
m: Month (01-12)
|
||
d: Day (01-31)
|
||
H: Hour (00-23)
|
||
h: Hour (1-12)
|
||
i: Minute (00-59)
|
||
s: Second (00-60)
|
||
A: AM/PM indicator</pre>
|
||
<p>All other characters are treated as strings. You can also use \ to escape characters.
|
||
Available on selected databases, including mysql, postgresql, mssql, oci8 and
|
||
DB2.
|
||
<p>This is useful in writing portable sql statements that GROUP BY on dates. For
|
||
example to display total cost of goods sold broken by quarter (dates are stored
|
||
in a field called postdate):
|
||
<pre>
|
||
$sqlfn = $db->SQLDate('Y-\QQ','postdate'); # get sql that formats postdate to output 2002-Q1
|
||
$sql = "SELECT $sqlfn,SUM(cogs) FROM table GROUP BY $sqlfn ORDER BY 1 desc";
|
||
</pre>
|
||
<p><b>MoveNext<a name="movenext"></a>( )</b></p>
|
||
<p>Move the internal cursor to the next row. The <i>$this->fields</i> array is
|
||
automatically updated. Returns false if unable to do so (normally because EOF
|
||
has been reached), otherwise true.
|
||
<p> If EOF is reached, then the $this->fields array is set to false (this was
|
||
only implemented consistently in ADOdb 3.30). For the pre-3.30 behaviour of
|
||
$this->fields (at EOF), set the global variable $ADODB_COMPAT_FETCH = true.</p>
|
||
<p>Example:</p>
|
||
<pre>$rs = $db->Execute($sql);
|
||
if ($rs)
|
||
while (!$rs->EOF) {
|
||
ProcessArray($rs->fields);
|
||
$rs->MoveNext();
|
||
} </pre>
|
||
<p><b>Move<a name="move"></a>($to)</b></p>
|
||
<p>Moves the internal cursor to a specific row $<b>to</b>. Rows are zero-based
|
||
eg. 0 is the first row. The <b>fields</b> 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 $<b>to</b>
|
||
position is after the EOF, $<b>to</b> will move to the end of the RecordSet
|
||
for most databases. Some obscure databases using odbc might not behave this
|
||
way.</p>
|
||
<p>Note: This function uses <i>absolute positioning</i>, unlike Microsoft's ADO.</p>
|
||
<p>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(
|
||
). </p>
|
||
<p><b>MoveFirst<a name="movefirst"></a>()</b></p>
|
||
<p>Internally calls Move(0). Note that some databases do not support this function.</p>
|
||
<p><b>MoveLast<a name="movelast"></a>()</b></p>
|
||
<p>Internally calls Move(RecordCount()-1). Note that some databases do not support
|
||
this function.</p>
|
||
<p><b>GetRowAssoc</b><a name="getrowassoc"></a>($toUpper=true)</p>
|
||
<p>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(). </p>
|
||
<p>For example:<br>
|
||
Array ( [ID] => 1 [FIRSTNAME] => Caroline [LASTNAME] => Miranda [CREATED] =>
|
||
2001-07-05 ) </p>
|
||
<p>Note: do not use GetRowAssoc() with $ADODB_FETCH_MODE = ADODB_FETCH_ASSOC.
|
||
Because they have the same functionality, they will interfere with each other.</p>
|
||
</font>
|
||
<p><font color="#000000"><b>AbsolutePage<a name="absolutepage"></a>($page=-1)
|
||
</b></font></p>
|
||
<p>Returns the current page. Requires PageExecute()/CachePageExecute() to be called.
|
||
See <a href=#ex8>Example 8</a>.</p>
|
||
<font color="#000000">
|
||
<p><b>AtFirstPage<a name="atfirstpage">($status='')</a></b></p>
|
||
<p>Returns true if at first page (1-based). Requires PageExecute()/CachePageExecute()
|
||
to be called. See <a href=#ex8>Example 8</a>.</p>
|
||
<p><b>AtLastPage<a name="atlastpage">($status='')</a></b></p>
|
||
<p>Returns true if at last page (1-based). Requires PageExecute()/CachePageExecute()
|
||
to be called. See <a href=#ex8>Example 8</a>.</p>
|
||
<p><b>Fields</b><a name="fields"></a>(<b>$colname</b>)</p>
|
||
<p>Returns the value of the
|
||
associated column $<b>colname</b> for the current row. The column name is case-insensitive.</p>
|
||
<p>This is a convenience function. For higher performance, use <a href="#adodb_fetch_mode">$ADODB_FETCH_MODE</a>. </p>
|
||
<p><b>FetchRow</b><a name="fetchrow"></a>()</p>
|
||
</font>
|
||
<p><font color="#000000">Returns array containing current row, or false if EOF.
|
||
FetchRow( ) internally moves to the next record after returning the current
|
||
row. </font></p>
|
||
<p><font color="#000000">Warning: Do not mix using FetchRow() with MoveNext().</font></p>
|
||
<p><font color="#000000">Usage:</font></p>
|
||
<pre><font color="#000000">$rs = $db->Execute($sql);
|
||
if ($rs)
|
||
while ($arr = $rs->FetchRow()) {
|
||
# process $arr
|
||
</font><font color="#000000"> }</font></pre>
|
||
<p><font color="#000000"><b>FetchInto</b><a name="fetchinto"></a>(<b>&$array</b>)</font></p>
|
||
<p><font color="#000000"> Sets $array to the current row. Returns PEAR_Error object
|
||
if EOF, 1 if ok (DB_OK constant). If PEAR is undefined, false is returned when
|
||
EOF. </font><font color="#000000">FetchInto( ) internally moves to the next
|
||
record after returning the current row. </font></p>
|
||
<p><font color="#000000"> FetchRow() is easier to use. See above.</font></p>
|
||
<font color="#000000">
|
||
<p><b>FetchField<a name="fetchfield"></a>($column_number)</b></p>
|
||
<p>Returns an object containing the <b>name</b>, <b>type</b> and <b>max_length</b>
|
||
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 <a href="#ex2">example
|
||
2.</a></p>
|
||
<p><b>FieldCount<a name="fieldcount"></a>( )</b></p>
|
||
<p>Returns the number of fields (columns) in the record set.</p>
|
||
<p><b>RecordCount<a name="recordcount"></a>( )</b></p>
|
||
<p>Returns the number of rows in the record set. If the number of records returned
|
||
cannot be determined from the database driver API, we will buffer all rows and
|
||
return a count of the rows after all the records have been retrieved. This buffering
|
||
can be disabled (for performance reasons) by setting the global variable $ADODB_COUNTRECS
|
||
= false. When disabled, RecordCount( ) will return -1 for certain databases.
|
||
See the supported databases list above for more details. </p>
|
||
<p> RowCount is a synonym for RecordCount.</p>
|
||
<p><b>PO_RecordCount<a name="po_recordcount"></a>($table, $where)</b></p>
|
||
<p>Returns the number of rows in the record set. If the database does not support
|
||
this, it will perform a SELECT COUNT(*) on the table $table, with the given
|
||
$where condition to return an estimate of the recordset size.</p>
|
||
<p>$numrows = $rs->PO_RecordCount("articles_table", "group=$group");</p>
|
||
<b> NextRecordSet<a name="nextrecordset" id="nextrecordset"></a>()</b>
|
||
<p>For databases that allow multiple recordsets to be returned in one query, this
|
||
function allows you to switch to the next recordset. Currently only supported
|
||
by mssql driver.</p>
|
||
<pre>
|
||
$rs = $db->Execute('execute return_multiple_rs');
|
||
$arr1 = $rs->GetArray();
|
||
$rs->NextRecordSet();
|
||
$arr2 = $rs->GetArray();</pre>
|
||
<p><b>FetchObject<a name="fetchobject"></a>($toupper=true)</b></p>
|
||
<p>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.</p>
|
||
<p><b>FetchNextObject<a name="fetchnextobject"></a>($toupper=true)</b></p>
|
||
<p>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.</p>
|
||
<pre>
|
||
$rs = $db->Execute('select firstname,lastname from table');
|
||
if ($rs) {
|
||
while ($o = $rs->FetchNextObject()) {
|
||
print "$o->FIRSTNAME, $o->LASTNAME<BR>";
|
||
}
|
||
}
|
||
</pre>
|
||
<p>There is some trade-off in speed in using FetchNextObject(). If performance
|
||
is important, you should access rows with the <code>fields[]</code> array. <b>FetchObj<a name="fetchobj" id="fetchobj"></a>()</b>
|
||
<p>Returns the current record as an object. Fields are not upper-cased, unlike
|
||
FetchObject. </font>
|
||
<p><font color="#000000"><b>FetchNextObj<a name="fetchnextobj" id="fetchnextobj"></a>()</b>
|
||
</font></p>
|
||
<p><font color="#000000">Returns the current record as an object and moves to
|
||
the next record. If EOF, false is returned. Fields are not upper-cased, unlike
|
||
FetctNextObject. </font></p>
|
||
<font color="#000000">
|
||
<p><b>CurrentRow<a name="currentrow"></a>( )</b></p>
|
||
<p>Returns the current row of the record set. 0 is the first row.</p>
|
||
<p><b>AbsolutePosition<a name="abspos"></a>( )</b></p>
|
||
<p>Synonym for <b>CurrentRow</b> for compatibility with ADO. Returns the current
|
||
row of the record set. 0 is the first row.</p>
|
||
<p><b>MetaType<a name="metatype"></a>($nativeDBType[,$field_max_length],[$fieldobj])</b></p>
|
||
<p>Determine what <i>generic</i> meta type a database field type is given its
|
||
native type $<b>nativeDBType</b> as a string and the length of the field $<b>field_max_length</b>.
|
||
Note that field_max_length can be -1 if it is not known. The field object returned
|
||
by FetchField() can be passed in $<b>fieldobj</b> or as the 1st parameter <b>$nativeDBType</b>.
|
||
This is useful for databases such as <i>mysql</i> which has additional properties
|
||
in the field object such as <i>primary_key</i>. </p>
|
||
<p>Uses the field <b>blobSize</b> and compares it with $<b>field_max_length</b>
|
||
to determine whether the character field is actually a blob.</p>
|
||
For example, $db->MetaType('char') will return 'C'.
|
||
<p>Returns:</p>
|
||
<ul>
|
||
<li><b>C</b>: Character fields that should be shown in a <input type="text">
|
||
tag. </li>
|
||
<li><b>X</b>: Clob (character large objects), or large text fields that should
|
||
be shown in a <textarea></li>
|
||
<li><b>D</b>: Date field</li>
|
||
<li><b>T</b>: Timestamp field</li>
|
||
<li><b>L</b>: Logical field (boolean or bit-field)</li>
|
||
<li><b>N</b>: Numeric field. Includes decimal, numeric, floating point, and
|
||
real. </li>
|
||
<li><b>I</b>: Integer field. </li>
|
||
<li><b>R</b>: Counter or Autoincrement field. Must be numeric.</li>
|
||
<li><b>B</b>: Blob, or binary large objects.<font color="#000000"> </font></li>
|
||
</ul>
|
||
</font>
|
||
<p><font color="#000000"> Since ADOdb 3.0, MetaType accepts $fieldobj as the first
|
||
parameter, instead of $nativeDBType. </font></p>
|
||
<font color="#000000">
|
||
<p><b>Close( )<a name="rsclose"></a></b></p>
|
||
<p>Closes the recordset, cleaning all memory and resources associated with the recordset.
|
||
<p>
|
||
If memory management is not an issue, you do not need to call this function as recordsets
|
||
are closed for you by PHP at the end of the script.
|
||
SQL statements such as INSERT/UPDATE/DELETE do not really return a recordset, so you do not have to call Close()
|
||
for such SQL statements.</p>
|
||
<hr>
|
||
<h3>function rs2html<a name="rs2html"></a>($adorecordset,[$tableheader_attributes],
|
||
[$col_titles])</h3>
|
||
<p>This is a standalone function (rs2html = recordset to html) that is similar
|
||
to PHP's <i>odbc_result_all</i> function, it prints a ADORecordSet, $<b>adorecordset</b>
|
||
as a HTML table. $<b>tableheader_attributes</b> allow you to control the table
|
||
<i>cellpadding</i>, <i>cellspacing</i> and <i>border</i> attributes. Lastly
|
||
you can replace the database column names with your own column titles with the
|
||
array $<b>col_titles</b>. This is designed more as a quick debugging mechanism,
|
||
not a production table recordset viewer.</p>
|
||
<p>You will need to include the file <i>tohtml.inc.php</i>.</p>
|
||
<p>Example of rs2html:<b><font color="#336600"><a name="exrs2html"></a></font></b></p>
|
||
<pre><b><font color="#336600"><?
|
||
include('tohtml.inc.php')</font></b>; # load code common to ADOdb
|
||
<b>include</b>('adodb.inc.php'); # load code common to ADOdb
|
||
$<font color="#663300">conn</font> = &ADONewConnection('mysql'); # create a connection
|
||
$<font color="#663300">conn</font>->PConnect('localhost','userid','','agora');# connect to MySQL, agora db
|
||
$<font color="#663300">sql</font> = 'select CustomerName, CustomerID from customers';
|
||
$<font color="#663300">rs</font> = $<font color="#663300">conn</font>->Execute($sql);
|
||
<font color="#336600"><b>rs2html</b></font><b>($<font color="#663300">rs</font>,'<i>border=2 cellpadding=3</i>',array('<i>Customer Name','Customer ID</i>'));
|
||
?></b></pre>
|
||
<hr>
|
||
<h3>Differences between this ADOdb library and Microsoft ADO<a name="adodiff"></a></h3>
|
||
<ol>
|
||
<li>ADOdb only supports recordsets created by a connection object. Recordsets
|
||
cannot be created independently.</li>
|
||
<li>ADO properties are implemented as functions in ADOdb. This makes it easier
|
||
to implement any enhanced ADO functionality in the future.</li>
|
||
<li>ADOdb's <font face="Courier New, Courier, mono">ADORecordSet->Move()</font>
|
||
uses absolute positioning, not relative. Bookmarks are not supported.</li>
|
||
<li><font face="Courier New, Courier, mono">ADORecordSet->AbsolutePosition()
|
||
</font>cannot be used to move the record cursor.</li>
|
||
<li>ADO Parameter objects are not supported. Instead we have the ADOConnection::<a href="#parameter">Parameter</a>(
|
||
) function, which provides a simpler interface for calling preparing parameters
|
||
and calling stored procedures.</li>
|
||
<li>Recordset properties for paging records are available, but implemented as
|
||
in <a href=#ex8>Example 8</a>.</li>
|
||
</ol>
|
||
<hr>
|
||
<h1>Database Driver Guide<a name="driverguide"></a></h1>
|
||
<p>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.</p>
|
||
<p>First decide on a name in lower case to call the database type. Let's say we
|
||
call it xbase. </p>
|
||
<p>Then we need to create two classes ADODB_xbase and ADORecordSet_xbase in the
|
||
file adodb-xbase.inc.php.</p>
|
||
<p>The simplest form of database driver is an adaptation of an existing ODBC driver.
|
||
Then we just need to create the class <i>ADODB_xbase extends ADODB_odbc</i>
|
||
to support the new <b>date</b> and <b>timestamp</b> formats, the <b>concatenation</b>
|
||
operator used, <b>true</b> and <b>false</b>. For the<i> ADORecordSet_xbase extends
|
||
ADORecordSet_odbc </i>we need to change the <b>MetaType</b> function. See<b>
|
||
adodb-vfp.inc.php</b> as an example.</p>
|
||
<p>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 <b>adodb-mysql.inc.php</b> for example.</p>
|
||
<p>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.</p>
|
||
<p><b>ADOConnection Functions to Override</b></p>
|
||
<p>Defining a constructor for your ADOConnection derived function is optional.
|
||
There is no need to call the base class constructor.</p>
|
||
<p>_<b>connect</b>: Low level implementation of Connect. Returns true or false.
|
||
Should set the _<b>connectionID</b>.</p>
|
||
<p>_<b>pconnect:</b> Low level implemention of PConnect. Returns true or false.
|
||
Should set the _<b>connectionID</b>.</p>
|
||
<p>_<b>query</b>: Execute a query. Returns the queryID, or false.</p>
|
||
<p>_<b>close: </b>Close the connection -- PHP should clean up all recordsets.
|
||
</p>
|
||
<p><b>ErrorMsg</b>: Stores the error message in the private variable _errorMsg.
|
||
</p>
|
||
<p><b>ADOConnection Fields to Set</b></p>
|
||
<p>_<b>bindInputArray</b>: Set to true if binding of parameters for SQL inserts
|
||
and updates is allowed using ?, eg. as with ODBC.</p>
|
||
<p><b>fmtDate</b></p>
|
||
<p><b>fmtTimeStamp</b></p>
|
||
<p><b>true</b></p>
|
||
<p><b>false</b></p>
|
||
<p><b>concat_operator</b></p>
|
||
<p><b>replaceQuote</b></p>
|
||
<p><b>hasLimit</b> support SELECT * FROM TABLE LIMIT 10 of MySQL.</p>
|
||
<p><b>hasTop</b> support Microsoft style SELECT TOP 10 * FROM TABLE.</p>
|
||
<p><b>ADORecordSet Functions to Override</b></p>
|
||
<p>You will need to define a constructor for your ADORecordSet derived class that
|
||
calls the parent class constructor.</p>
|
||
<p><b>FetchField: </b> as documented above in ADORecordSet</p>
|
||
<p>_<b>initrs</b>: low level initialization of the recordset: setup the _<b>numOfRows</b>
|
||
and _<b>numOfFields</b> fields -- called by the constructor.</p>
|
||
<p>_<b>seek</b>: 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.</p>
|
||
<p>_<b>fetch</b>: fetch a row using the database extension function and then move
|
||
to the next row. Sets the <b>fields</b> array. If the parameter $ignore_fields
|
||
is true then there is no need to populate the <b>fields</b> array, just move
|
||
to the next row. then Returns true or false.</p>
|
||
<p>_<b>close</b>: close the recordset</p>
|
||
<p><b>Fields</b>: 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.</p>
|
||
<p><b>ADOConnection Fields to Set</b></p>
|
||
<p>canSeek: Set to true if the _seek function works.</p>
|
||
<h2>ToDo:</h2>
|
||
<p>See the <a href=http://php.weblogs.com/adodb-todo-roadmap>RoadMap</a> article.</p>
|
||
<p>Also see the ADOdb <a href=http://php.weblogs.com/adodb_csv>proxy</a> article
|
||
for bridging Windows and Unix databases using http remote procedure calls. For
|
||
your education, visit <a href=http://palslib.com/>palslib.com</a> for database info,
|
||
and read this article on <a href=http://phplens.com/lens/php-book/optimizing-debugging-php.php>Optimizing
|
||
PHP</a>. </p>
|
||
</font>
|
||
<h2>Change Log<a name="Changes"></a><a name="changes"></a><a name="changelog"></a></h2>
|
||
<p><a name=4.52></a><b>4.52 ?? 2004</b>
|
||
<p>Bug found in Replace() when performance logging enabled, introduced in ADOdb 4.50. Fixed.
|
||
<p>Replace() checks update stmt. If update stmt fails, we now return immediately. Thx to alex.
|
||
<p>Added support for $ADODB_FORCE_TYPE in GetUpdateSQL/GetInsertSQL. Thx to niko.
|
||
<p>Added ADODB_ASSOC_CASE support to postgres/postgres7 driver.
|
||
<p><a name=4.51></a><b>4.51 29 July 2004</b>
|
||
<p>Added adodb-xmlschema 1.0.2. Thx dan and richard.
|
||
<p>Added new adorecordset_ext_* classes. If ADOdb extension installed for mysql, mysqlt and oci8
|
||
(but not oci8po), we use the superfast ADOdb extension code for movenext.
|
||
<p>Added schema support to mssql and odbc_mssql MetaPrimaryKeys().
|
||
<p>Patched MSSQL driver to support PHP NULL and Boolean values
|
||
while binding the input array parameters in the _query() function. By Stephen Farmer.
|
||
<p>Added support for clob's for mssql, UpdateBlob(). Thx to gfran#directa.com.br
|
||
<p>Added normalize support for postgresql (true=lowercase table name, or false=case-sensitive table names)
|
||
to MetaColumns($table, $normalize=true).
|
||
<p>PHP5 variant dates in ADO not working. Fixed in adodb-ado.inc.php.
|
||
<p>Constant ADODB_FORCE_NULLS was not working properly for many releases (for GetUpdateSQL). Fixed.
|
||
Also GetUpdateSQL strips off ORDER BY now - thx Elieser Le<4C>o.
|
||
<p>Perf Monitor for oci8 now dynamically highlights optimizer_* params if too high/low.
|
||
<p>Added dsn support to NewADOConnection/ADONewConnection.
|
||
<p>Fixed out of page bounds bug in _adodb_pageexecute_all_rows() Thx to "Sergio Strampelli" sergio#rir.it
|
||
<p>Speedup of movenext for mysql and oci8 drivers.
|
||
<p>Moved debugging code _adodb_debug_execute() to adodb-lib.inc.php.
|
||
<p>Fixed postgresql bytea detection bug. See http://phplens.com/lens/lensforum/msgs.php?id=9849.
|
||
<p>Fixed ibase datetimestamp typo in PHP5. Thx stefan.
|
||
<p>Removed whitespace at end of odbtp drivers.
|
||
<p>Added db2 metaprimarykeys fix.
|
||
<p>Optimizations to MoveNext() for mysql and oci8. Misc speedups to Get* functions.
|
||
<p><a name=4.50></a><b>4.50 6 July 2004</b>
|
||
<p>Bumped it to 4.50 to avoid confusion with PHP 4.3.x series.
|
||
<p>Added db2 metatables and metacolumns extensions.
|
||
<p>Added alpha PDO driver. Very buggy, only works with odbc.
|
||
<p>Tested mysqli. Set poorAffectedRows = true. Cleaned up movenext() and _fetch().
|
||
<p>PageExecute does not work properly with php5 (return val not a variable). Reported Dmytro Sychevsky sych#php.com.ua. Fixed.
|
||
<p>MetaTables() for mysql, $showschema parameter was not backward compatible with older versions of adodb. Fixed.
|
||
<p>Changed mysql GetOne() to work with mysql 3.23 when using with non-select stmts (e.g. SHOW TABLES).
|
||
<p>Changed TRIG_ prefix to a variable in datadict-oci8.inc.php. Thx to Luca.Gioppo#csi.it.
|
||
<p>New to adodb-time code. We allow you to define your own daylights savings function,
|
||
adodb_daylight_sv for pre-1970 dates. If the function is defined
|
||
(somewhere in an include), then you can correct
|
||
for daylights savings. See http://phplens.com/phpeverywhere/node/view/16#daylightsavings
|
||
for more info.
|
||
<p>New sqlitepo driver. This is because assoc mode does not work like other drivers in sqlite.
|
||
Namely, when selecting (joining) multiple tables, in assoc mode the table
|
||
names are included in the assoc keys in the "sqlite" driver.
|
||
In "sqlitepo" driver, the table names are stripped from the returned column names.
|
||
When this results in a conflict, the first field get preference.
|
||
Contributed by Herman Kuiper herman#ozuzo.net
|
||
<p>Added $forcenull parameter to GetInsertSQL/GetUpdateSQL. Idea by Marco Aurelio Silva.
|
||
<p>More XHTML changes for GetMenu. By Jeremy Evans.
|
||
<p>Fixes some ibase date issues. Thx to stefan bogdan.
|
||
<p>Improvements to mysqli driver to support $ADODB_COUNTRECS.
|
||
<p>Fixed adodb-csvlib.inc.php problem when reading stream from socket. We need to poll stream continiously.
|
||
<p><a name=4.23></a><b>4.23 16 June 2004</b>
|
||
<p>
|
||
New interbase/firebird fixes thx to Lester Caine.
|
||
Driver fixes a problem with getting field names in the result array, and
|
||
corrects a couple of data conversions. Also we default to dialect3 for firebird.
|
||
Also ibase sysDate property was wrong. Changed to cast as timestamp.
|
||
<p>
|
||
The datadict driver is set up to give quoted tables and fields as this
|
||
was the only way round reserved words being used as field names in
|
||
TikiWiki. TikiPro is tidying that up, and I hope to be able to produce a
|
||
build of THAT which uses what I consider proper UPPERCASE field and
|
||
table names. The conversion of TikiWiki to ADOdb helped in that, but
|
||
until the database is completely tidied up in TikiPro ...
|
||
<p>Modified _gencachename() to include fetchmode in name hash.
|
||
This means you should clear your cache directory after installing this release as the
|
||
cache name algorithm has changed.
|
||
<p>Now Cache* functions work in safe mode, because we do not create sub-directories in the $ADODB_CACHE_DIR in safe mode. In non-safe mode we still create sub-directories. Done by modifying _gencachename().
|
||
<p>Added $gmt parameter (true/false) to UserDate and UserTimeStamp in connection class, to force conversion of input (in local time) to be converted to UTC/GMT.
|
||
<p>Mssql datadict did not support INT types properly (no size param allowed).
|
||
Added _GetSize() to datadict-mssql.inc.php.
|
||
<p>For borland_ibase, BeginTrans(), changed:<br>
|
||
<pre> $this->_transactionID = $this->_connectionID;</pre>
|
||
to<br>
|
||
<pre> $this->_transactionID = ibase_trans($this->ibasetrans, $this->_connectionID);</pre>
|
||
|
||
<p>Fixed typo in mysqi_field_seek(). Thx to Sh4dow (sh4dow#php.pl).
|
||
<p>LogSQL did not work with Firebird/Interbase. Fixed.
|
||
<p>Postgres: made errorno() handling more consistent. Thx to Michael Jahn, Michael.Jahn#mailbox.tu-dresden.de.
|
||
<p>Added informix patch to better support metatables, metacolumns by "Cecilio Albero" c-albero#eos-i.com
|
||
<p>Cyril Malevanov contributed patch to oci8 to support passing of LOB parameters:
|
||
<pre>
|
||
$text = 'test test test';
|
||
$sql = "declare rs clob; begin :rs := lobinout(:sa0); end;";
|
||
$stmt = $conn -> PrepareSP($sql);
|
||
$conn -> InParameter($stmt,$text,'sa0', -1, OCI_B_CLOB);
|
||
$rs = '';
|
||
$conn -> OutParameter($stmt,$rs,'rs', -1, OCI_B_CLOB);
|
||
$conn -> Execute($stmt);
|
||
echo "return = ".$rs."<br>";
|
||
</pre>
|
||
As he says, the LOBs limitations are:
|
||
<pre>
|
||
- use OCINewDescriptor before binding
|
||
- if Param is IN, uses save() before each execute. This is done automatically for you.
|
||
- if Param is OUT, uses load() after each execute. This is done automatically for you.
|
||
- when we bind $var as LOB, we create new descriptor and return it as a
|
||
Bind Result, so if we want to use OUT parameters, we have to store
|
||
somewhere &$var to load() data from LOB to it.
|
||
- IN OUT params are not working now (should not be a big problem to fix it)
|
||
- now mass binding not working too (I've wrote about it before)
|
||
</pre>
|
||
<p>Simplified Connect() and PConnect() error handling.
|
||
<p>When extension not loaded, Connect() and PConnect() will return null. On connect error, the fns will return false.
|
||
<p>CacheGetArray() added to code.
|
||
<p>Added Init() to adorecordset_empty().
|
||
<p>Changed postgres64 driver, MetaColumns() to not strip off quotes in default value if :: detected (type-casting of default).
|
||
<p>Added test: if (!defined('ADODB_DIR')) die(). Useful to prevent hackers from detecting file paths.
|
||
<p>Changed metaTablesSQL to ignore Postgres 7.4 information schemas (sql_*).
|
||
<p>New polish language file by Grzegorz Pacan
|
||
<p>Added support for UNION in _adodb_getcount().
|
||
<p>Added security check for ADODB_DIR to limit path disclosure issues. Requested by postnuke team.
|
||
<p>Added better error message support to oracle driver. Thx to Gaetano Giunta.
|
||
<p>Added showSchema support to mysql.
|
||
<p>Bind in oci8 did not handle $name=false properly. Fixed.
|
||
<p>If extension not loaded, Connect(), PConnect(), NConnect() will return null.
|
||
<p><b>4.22 15 Apr 2004</b>
|
||
<p>Moved docs to own adodb/docs folder.
|
||
<p>Fixed session bug when quoting compressed/encrypted data in Replace().
|
||
<p>Netezza Driver and LDAP drivers contributed by Josh Eldridge.
|
||
<p>GetMenu now uses rtrim() on values instead of trim().
|
||
<p>Changed MetaColumnNames to return an associative array, keys being the field names in uppercase.
|
||
<p>Suggested fix to adodb-ado.inc.php affected_rows to support PHP5 variants. Thx to Alexios Fakos.
|
||
<p>Contributed bulgarian language file by Valentin Sheiretsky valio#valio.eu.org.
|
||
<p>Contributed romanian language file by stefan bogdan.
|
||
<p>GetInsertSQL now checks for table name (string) in $rs, and will create a recordset for that
|
||
table automatically. Contributed by Walt Boring. Also added OCI_B_BLOB in bind on Walt's request - hope
|
||
it doesn't break anything :-)
|
||
<p>Some minor postgres speedups in _initrs().
|
||
<p> ChangeTableSQL checks now if MetaColumns returns empty. Thx Jason Judge.
|
||
<p>Added ADOConnection::Time(), returns current database time in unix timestamp format, or false.
|
||
<p><b>4.21 20 Mar 2004</b>
|
||
<p>We no longer in SelectLimit for VFP driver add SELECT TOP X unless an ORDER BY exists.
|
||
<p>Pim Koeman contributed dutch language file adodb-nl.inc.php.
|
||
<p>Rick Hickerson added CLOB support to db2 datadict.
|
||
<p>Added odbtp driver. Thx to "stefan bogdan" sbogdan#rsb.ro.
|
||
<p>Changed PrepareSP() 2nd parameter, $cursor, to default to true (formerly false). Fixes oci8 backward
|
||
compat problems with OUT params.
|
||
<p>Fixed month calculation error in adodb-time.inc.php. 2102-June-01 appeared as 2102-May-32.
|
||
<p>Updated PHP5 RC1 iterator support. API changed, hasMore() renamed to valid().
|
||
<p>Changed internal format of serialized cache recordsets. As we store a version number, this should be
|
||
backward compatible.
|
||
<p>Error handling when driver file not found was flawed in ADOLoadCode(). Fixed.
|
||
<p><b>4.20 27 Feb 2004</b>
|
||
<p>Updated to AXMLS 1.01.
|
||
<p>MetaForeignKeys for postgres7 modified by Edward Jaramilla, works on pg 7.4.
|
||
<p>Now numbers accepts function calls or sequences for GetInsertSQL/GetUpdateSQL numeric fields.
|
||
<p>Changed quotes of 'delete from $perf_table' to "". Thx Kehui (webmaster#kehui.net)
|
||
<p>Added ServerInfo() for ifx, and putenv trim fix. Thx Fernando Ortiz.
|
||
<p>Added addq(), which is analogous to addslashes().
|
||
<p>Tested with php5b4. Fix some php5 compat problems with exceptions and sybase.
|
||
<P>Carl-Christian Salvesen added patch to mssql _query to support binds greater than 4000 chars.
|
||
<p>Mike suggested patch to PHP5 exception handler. $errno must be numeric.
|
||
<p>Added double quotes (") to ADODB_TABLE_REGEX.
|
||
<p>For oci8, Prepare(...,$cursor), $cursor's meaning was accidentally inverted in 4.11. This causes problems with ExecuteCursor() too, which calls Prepare() internally. Thx to William Lovaton.
|
||
<p>Now dateHasTime property in connection object renamed to datetime for consistency. This could break bc.
|
||
<p>Csongor Halmai reports that db2 SelectLimit with input array is not working. Fixed..
|
||
<p><b>4.11 27 Jan 2004</b>
|
||
<p>Csongor Halmai reports db2 binding not working. Reverted back to emulated binding.
|
||
<p>Dan Cech modifies datadict code. Adds support for DropIndex. Minor cleanups.
|
||
<p>Table misspelt in perf-oci8.inc.php. Changed v$conn_cache_advice to v$db_cache_advice. Reported by Steve W.
|
||
<p>UserTimeStamp and DBTimeStamp did not handle YYYYMMDDHHMMSS format properly. Reported by Mike Muir. Fixed.
|
||
<p>Changed oci8 Prepare(). Does not auto-allocate OCINewCursor automatically, unless 2nd param is set to true.
|
||
This will break backward compat, if Prepare/Execute is used instead of ExecuteCursor. Reported by Chris Jones.
|
||
<p>Added InParameter() and OutParameter(). Wrapper functions to Parameter(), but nicer because they
|
||
are self-documenting.
|
||
<p>Added 'R' handling in ActualType() to datadict-mysql.inc.php
|
||
<p>Added ADOConnection::SerializableRS($rs). Returns a recordset that can be serialized in a session.
|
||
<p>Added "Run SQL" to performance UI().
|
||
<p>Misc spelling corrections in adodb-mysqli.inc.php, adodb-oci8.inc.php and datadict-oci8.inc.php, from Heinz Hombergs.
|
||
<p>MetaIndexes() for ibase contributed by Heinz Hombergs.
|
||
<p><b>4.10 12 Jan 2004</b>
|
||
<p>Dan Cech contributed extensive changes to data dictionary to support name quoting (with `), and drop table/index.
|
||
<p>Informix added cursorType property. Default remains IFX_SCROLL, but you can change to 0 (non-scrollable cursor) for performance.
|
||
<p>Added ADODB_View_PrimaryKeys() for returning view primary keys to MetaPrimaryKeys().
|
||
<p>Simplified chinese file, adodb-cn.inc.php from cysoft.
|
||
<p>Added check for ctype_alnum in adodb-datadict.inc.php. Thx to Jason Judge.
|
||
<p>Added connection parameter to ibase Prepare(). Fix by Daniel Hassan.
|
||
<p>Added nameQuote for quoting identifiers and names to connection obj. Requested by Jason Judge. Also the
|
||
data dictionary parser now detects `field name` and generates column names with spaces correctly.
|
||
<p>BOOL type not recognised correctly as L. Fixed.
|
||
<p>Fixed paths in ADODB_DIR for session files, and back-ported it to 4.05 (15 Dec 2003)
|
||
<p>Added Schema to postgresql MetaTables. Thx to col#gear.hu
|
||
<p>Empty postgresql recordsets that had blob fields did not set EOF properly. Fixed.
|
||
<p>CacheSelectLimit internal parameters to SelectLimit were wrong. Thx to Nio.
|
||
<p>Modified adodb_pr() and adodb_backtrace() to support command-line usage (eg. no html).
|
||
<p>Fixed some fr and it lang errors. Thx to Gaetano G.
|
||
<p>Added contrib directory, with adodb rs to xmlrpc convertor by Gaetano G.
|
||
<p>Fixed array recordset bugs when _skiprow1 is true. Thx to Gaetano G.
|
||
<p>Fixed pivot table code when count is false.
|
||
<p>
|
||
|
||
<p><b>4.05 13 Dec 2003 </b>
|
||
<p>Added MetaIndexes - thx to Dan Cech.
|
||
<p>Rewritten session code by Ross Smith. Moved code to adodb/session directory.
|
||
<p>Added function exists check on connecting to most drivers, so we don't crash with the unknown function error.
|
||
<p>Smart Transactions failed with GenID() when it no seq table has been created because the sql
|
||
statement fails. Fix by Mark Newnham.
|
||
<p>Added $db->length, which holds name of function that returns strlen.
|
||
<p>Fixed error handling for bad driver in ADONewConnection - passed too few params to error-handler.
|
||
<p>Datadict did not handle types like 16.0 properly in _GetSize. Fixed.
|
||
<p>Oci8 driver SelectLimit() bug &= instead of =& used. Thx to Swen Th<54>mmler.
|
||
<p>Jesse Mullan suggested not flushing outp when output buffering enabled. Due to Apache 2.0 bug. Added.
|
||
<p>MetaTables/MetaColumns return ref bug with PHP5 fixed in adodb-datadict.inc.php.
|
||
<p>New mysqli driver contributed by Arjen de Rijke. Based on adodb 3.40 driver.
|
||
Then jlim added BeginTrans, CommitTrans, RollbackTrans, IfNull, SQLDate. Also fixed return ref bug.
|
||
<p>$ADODB_FLUSH added, if true then force flush in debugging outp. Default is false. In earlier
|
||
versions, outp defaulted to flush, which is not compat with apache 2.0.
|
||
<p>Mysql driver's GenID() function did not work when when sql logging is on. Fixed.
|
||
<p>$ADODB_SESSION_TBL not declared as global var. Not available if adodb-session.inc.php included in function. Fixed.
|
||
<p>The input array not passed to Execute() in _adodb_getcount(). Fixed.
|
||
<p><b>4.04 13 Nov 2003 </b>
|
||
<p>Switched back to foreach - faster than list-each.
|
||
<p>Fixed bug in ado driver - wiping out $this->fields with date fields.
|
||
<p>Performance Monitor, View SQL, Explain Plan did not work if strlen($SQL)>max($_GET length). Fixed.
|
||
<p>Performance monitor, oci8 driver added memory sort ratio.
|
||
<p>Added random property, returns SQL to generate a floating point number between 0 and 1;
|
||
<p><b>4.03 6 Nov 2003 </b>
|
||
<p>The path to adodb-php4.inc.php and adodb-iterators.inc.php was not setup properly.
|
||
<p>Patched SQLDate in interbase to support hours/mins/secs. Thx to ari kuorikoski.
|
||
<p>Force autorollback for pgsql persistent connections -
|
||
apparently pgsql did not autorollback properly before 4.3.4. See http://bugs.php.net/bug.php?id=25404
|
||
<p><b>4.02 5 Nov 2003 </b>
|
||
<p>Some errors in adodb_error_pg() fixed. Thx to Styve.
|
||
<p>Spurious Insert_ID() error was generated by LogSQL(). Fixed.
|
||
<p>Insert_ID was interfering with Affected_Rows() and Replace() when LogSQL() enabled. Fixed.
|
||
<p>More foreach loops optimized with list/each.
|
||
<p>Null dates not handled properly in ADO driver (it becomes 31 Dec 1969!).
|
||
<p>Heinz Hombergs contributed patches for mysql MetaColumns - adding scale, made
|
||
interbase MetaColumns work with firebird/interbase, and added lang/adodb-de.inc.php.
|
||
<p>Added INFORMIXSERVER environment variable.
|
||
<p>Added $ADODB_ANSI_PADDING_OFF for interbase/firebird.
|
||
<p>PHP 5 beta 2 compat check. Foreach (Iterator) support. Exceptions support.
|
||
<p><b>4.01 23 Oct 2003 </b>
|
||
<p>Fixed bug in rs2html(), tohtml.inc.php, that generated blank table cells.
|
||
<p>Fixed insert_id() incorrectly generated when logsql() enabled.
|
||
<p>Modified PostgreSQL _fixblobs to use list/each instead of foreach.
|
||
<p>Informix ErrorNo() implemented correctly.
|
||
<p>Modified several places to use list/each, including GetRowAssoc().
|
||
<p>Added UserTimeStamp() to connection class.
|
||
<p>Added $ADODB_ANSI_PADDING_OFF for oci8po.
|
||
<p><b>4.00 20 Oct 2003 </b>
|
||
<p>Upgraded adodb-xmlschema to 1 Oct 2003 snapshot.
|
||
<p>Fix to rs2html warning message. Thx to Filo.
|
||
<p>Fix for odbc_mssql/mssql SQLDate(), hours was wrong.
|
||
<p>Added MetaColumns and MetaPrimaryKeys for sybase. Thx to Chris Phillipson.
|
||
<p>Added autoquoting to datadict for MySQL and PostgreSQL. Suggestion by Karsten Dambekalns
|
||
<p><b>3.94 11 Oct 2003 </b>
|
||
<p>Create trigger in datadict-oci8.inc.php did not work, because all cr/lf's must be removed.
|
||
<p>ErrorMsg()/ErrorNo() did not work for many databases when logging enabled. Fixed.
|
||
<p>Removed global variable $ADODB_LOGSQL as it does not work properly with multiple connections.
|
||
<p>Added SQLDate support for sybase. Thx to Chris Phillipson
|
||
<p>Postgresql checking of pgsql resultset resource was incorrect. Fix by Bharat Mediratta bharat#menalto.com.
|
||
Same patch applied to _insertid and _affectedrows for adodb-postgres64.inc.php.
|
||
<p>Added support for NConnect for postgresql.
|
||
<p>Added Sybase data dict support. Thx to Chris Phillipson
|
||
<p>Extensive improvements in $perf->UI(), eg. Explain now opens in new window, we show scripts
|
||
which call sql, etc.
|
||
<p>Perf Monitor UI works with magic quotes enabled.
|
||
<p>rsPrefix was declared twice. Removed.
|
||
<p>Oci8 stored procedure support, eg. "begin func(); end;" was incorrect in _query. Fixed.
|
||
<p>Tiraboschi Massimiliano contributed italian language file.
|
||
<p>Fernando Ortiz, fortiz#lacorona.com.mx, contributed informix performance monitor.
|
||
<p>Added _varchar (varchar arrays) support for postgresql. Reported by PREVOT St<53>phane.
|
||
<p><b>3.92 22 Sept 2003</b>
|
||
<p>Added GetAssoc and CacheGetAssoc to connection object.
|
||
<p>Removed TextMax and CharMax functions from adodb.inc.php.
|
||
<p>HasFailedTrans() returned false when trans failed. Fixed.
|
||
<p>Moved perf driver classes into adodb/perf/*.php.
|
||
<p>Misc improvements to performance monitoring, including UI().
|
||
<p>RETVAL in mssql Parameter(), we do not append @ now.
|
||
<p>Added Param($name) to connection class, returns '?' or ":$name", for defining
|
||
bind parameters portably.
|
||
<p>LogSQL traps affected_rows() and saves its value properly now. Also fixed oci8
|
||
_stmt and _affectedrows() bugs.
|
||
<p>Session code timestamp check for oci8 works now. Formerly default NLS_DATE_FORMAT
|
||
stripped off time portion. Thx to Tony Blair (tonanbarbarian#hotmail.com). Also
|
||
added new $conn->datetime field to oci8, controls whether MetaType() returns
|
||
'D' ($this->datetime==false) or 'T' ($this->datetime == true) for DATE type.
|
||
<p>Fixed bugs in adodb-cryptsession.inc.php and adodb-session-clob.inc.php.
|
||
<p>Fixed misc bugs in adodb_key_exists, GetInsertSQL() and GetUpdateSQL().
|
||
<p>Tuned include_once handling to reduce file-system checking overhead.
|
||
<p><b>3.91 9 Sept 2003</b>
|
||
<p>Only released to InterAkt
|
||
<p>Added LogSQL() for sql logging and $ADODB_NEWCONNECTION to override factory
|
||
for driver instantiation.
|
||
<p>Added IfNull($field,$ifNull) function, thx to johnwilk#juno.com
|
||
<p>Added portable substr support.
|
||
<p>Now rs2html() has new parameter, $echo. Set to false to return $html instead
|
||
of echoing it.
|
||
<p><b>3.90 5 Sept 2003</b>
|
||
<p>First beta of performance monitoring released.
|
||
<p>MySQL supports MetaTable() masking.
|
||
<p>Fixed key_exists() bug in adodb-lib.inc.php
|
||
<p>Added sp_executesql Prepare() support to mssql.
|
||
<p>Added bind support to db2.
|
||
<p>Added swedish language file - Christian Tiberg" christian#commsoft.nu
|
||
<p>Bug in drop index for mssql data dict fixed. Thx to Gert-Rainer Bitterlich.
|
||
<p>Left join setting for oci8 was wrong. Thx to johnwilk#juno.com
|
||
<p><b>3.80 27 Aug 2003</b>
|
||
<p>Patch for PHP 4.3.3 cached recordset csv2rs() fread loop incompatibility.
|
||
<p>Added matching mask for MetaTables. Only for oci8, mssql and postgres currently.
|
||
<p>Rewrite of "oracle" driver connection code, merging with "oci8", by Gaetano.
|
||
<p>Added better debugging for Smart Transactions.
|
||
<p>Postgres DBTimeStamp() was wrongly using TO_DATE. Changed to TO_TIMESTAMP.
|
||
<p>ADODB_FETCH_CASE check pushed to ADONewConnection to allow people to define
|
||
it after including adodb.inc.php.
|
||
<p>Added portugese (brazilian) to languages. Thx to "Levi Fukumori".
|
||
<p>Removed arg3 parameter from Execute/SelectLimit/Cache* functions.
|
||
<p>Execute() now accepts 2-d array as $inputarray. Also changed docs of fnExecute()
|
||
to note change in sql query counting with 2-d arrays.
|
||
<p>Added MONEY to MetaType in PostgreSQL.
|
||
<p>Added more debugging output to CacheFlush().
|
||
<p><b>3.72 9 Aug 2003</b>
|
||
<p>Added qmagic($str), which is a qstr($str) that auto-checks for magic quotes
|
||
and does the right thing...
|
||
<p>Fixed CacheFlush() bug - Thx to martin#gmx.de
|
||
<p>Walt Boring contributed MetaForeignKeys for postgres7.
|
||
<p>_fetch() called _BlobDecode() wrongly in interbase. Fixed.
|
||
<p>adodb_time bug fixed with dates after 2038 fixed by Jason Pell. http://phplens.com/lens/lensforum/msgs.php?id=6980
|
||
<p><b>3.71 4 Aug 2003</b>
|
||
<p>The oci8 driver, MetaPrimaryKeys() did not check the owner correctly when $owner
|
||
== false.
|
||
<p>Russian language file contributed by "Cyrill Malevanov" cyrill#malevanov.spb.ru.
|
||
<p>Spanish language file contributed by "Horacio Degiorgi" horaciod#codigophp.com.
|
||
<p>Error handling in oci8 bugfix - if there was an error in Execute(), then when
|
||
calling ErrorNo() and/or ErrorMsg(), the 1st call would return the error, but
|
||
the 2nd call would return no error.
|
||
<p>Error handling in odbc bugfix. ODBC would always return the last error, even
|
||
if it happened 5 queries ago. Now we reset the errormsg to '' and errorno to
|
||
0 everytime before CacheExecute() and Execute().
|
||
<p><b>3.70 29 July 2003</b>
|
||
<p>Added new SQLite driver. Tested on PHP 4.3 and PHP 5.
|
||
<p>Added limited "sapdb" driver support - mainly date support.
|
||
<p>The oci8 driver did not identify NUMBER with no defined precision correctly.
|
||
<p>Added ADODB_FORCE_NULLS, if set, then PHP nulls are converted to SQL nulls
|
||
in GetInsertSQL/GetUpdateSQL.
|
||
<p>DBDate() and DBTimeStamp() format for postgresql had problems. Fixed.
|
||
<p>Added tableoptions to ChangeTableSQL(). Thx to Mike Benoit.
|
||
<p>Added charset support to postgresql. Thx to Julian Tarkhanov.
|
||
<p>Changed OS check for MS-Windows to prevent confusion with darWIN (MacOS)
|
||
<p>Timestamp format for db2 was wrong. Changed to yyyy-mm-dd-hh.mm.ss.nnnnnn.
|
||
<p>adodb-cryptsession.php includes wrong. Fixed.
|
||
<p>Added MetaForeignKeys(). Supported by mssql, odbc_mssql and oci8.
|
||
<p>Fixed some oci8 MetaColumns/MetaPrimaryKeys bugs. Thx to Walt Boring.
|
||
<p>adodb_getcount() did not init qryRecs to 0. Missing "WHERE" clause checking
|
||
in GetUpdateSQL fixed. Thx to Sebastiaan van Stijn.
|
||
<p>Added support for only 'VIEWS' and "TABLES" in MetaTables. From Walt Boring.
|
||
<p>Upgraded to adodb-xmlschema.inc.php 0.0.2.
|
||
<p>NConnect for mysql now returns value. Thx to Dennis Verspuij.
|
||
<p>ADODB_FETCH_BOTH support added to interbase/firebird.
|
||
<p>Czech language file contributed by Kamil Jakubovic jake#host.sk.
|
||
<p>PostgreSQL BlobDecode did not use _connectionID properly. Thx to Juraj Chlebec.
|
||
<p>Added some new initialization stuff for Informix. Thx to "Andrea Pinnisi" pinnisi#sysnet.it
|
||
<p>ADODB_ASSOC_CASE constant wrong in sybase _fetch(). Fixed.
|
||
<p><b>3.60 16 June 2003</b>
|
||
<p>We now SET CONCAT_NULL_YIELDS_NULL OFF for odbc_mssql driver to be compat with
|
||
mssql driver.
|
||
<p>The property $emptyDate missing from connection class. Also changed 1903 to
|
||
constant (TIMESTAMP_FIRST_YEAR=100). Thx to Sebastiaan van Stijn.
|
||
<p>ADOdb speedup optimization - we now return all arrays by reference.
|
||
<p>Now DBDate() and DBTimeStamp() now accepts the string 'null' as a parameter.
|
||
Suggested by vincent.
|
||
<p>Added GetArray() to connection class.
|
||
<p>Added not_null check in informix metacolumns().
|
||
<p>Connection parameters for postgresql did not work correctly when port was defined.
|
||
<p>DB2 is now a tested driver, making adodb 100% compatible. Extensive changes
|
||
to odbc driver for DB2, including implementing serverinfo() and SQLDate(), switching
|
||
to SQL_CUR_USE_ODBC as the cursor mode, and lastAffectedRows and SelectLimit()
|
||
fixes.
|
||
<p>The odbc driver's FetchField() field names did not obey ADODB_ASSOC_CASE. Fixed.
|
||
<p>Some bugs in adodb_backtrace() fixed.
|
||
<p>Added "INT IDENTITY" type to adorecordset::MetaType() to support odbc_mssql
|
||
properly.
|
||
<p>MetaColumns() for oci8, mssql, odbc revised to support scale. Also minor revisions
|
||
to odbc MetaColumns() for vfp and db2 compat.
|
||
<p>Added unsigned support to mysql datadict class. Thx to iamsure.
|
||
<p>Infinite loop in mssql MoveNext() fixed when ADODB_FETCH_ASSOC used. Thx to
|
||
Josh R, Night_Wulfe#hotmail.com.
|
||
<p>ChangeTableSQL contributed by Florian Buzin.
|
||
<p>The odbc_mssql driver now sets CONCAT_NULL_YIELDS_NULL OFF for compat with
|
||
mssql driver.
|
||
<hr>
|
||
<p><strong>0.10 Sept 9 2000</strong> First release
|
||
<h3><strong>Old changelog history moved to <a href=old-changelog.htm>old-changelog.htm</a>.
|
||
</strong></h3>
|
||
<p> </p>
|
||
<p> </font>
|
||
</body>
|
||
</html>
|