1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
---|
2 | <html><head><title>ADODB Manual</title> |
---|
3 | |
---|
4 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
---|
5 | |
---|
6 | |
---|
7 | <style> |
---|
8 | pre { |
---|
9 | background-color: #eee; |
---|
10 | padding: 0.75em 1.5em; |
---|
11 | font-size: 12px; |
---|
12 | border: 1px solid #ddd; |
---|
13 | } |
---|
14 | </style></head> |
---|
15 | <body bgcolor="#ffffff" text="black"> |
---|
16 | |
---|
17 | <h2>ADOdb Library for PHP</h2> |
---|
18 | <p>V4.94 23 Jan 2007 (c) 2000-2007 John Lim (jlim#natsoft.com)</p> |
---|
19 | <p><font size="1">This software is dual licensed using BSD-Style and LGPL. This |
---|
20 | means you can use it in compiled proprietary and commercial products.</font></p> |
---|
21 | |
---|
22 | |
---|
23 | <p>Useful ADOdb links: <a href="http://adodb.sourceforge.net/#download">Download</a> <a href="http://adodb.sourceforge.net/#docs">Other Docs</a> |
---|
24 | |
---|
25 | </p><p><a href="#intro"><b>Introduction</b></a><b><br> |
---|
26 | <a href="#features">Unique Features</a><br> |
---|
27 | <a href="#users">How People are using ADOdb</a><br> |
---|
28 | <a href="#bugs">Feature Requests and Bug Reports</a><br> |
---|
29 | </b><b><a href="#install">Installation</a><br> |
---|
30 | <a href="#mininstall">Minimum Install</a><br> |
---|
31 | <a href="#coding">Initializing Code and Connectioning to Databases</a><br> |
---|
32 | </b><font size="2"> <a href="#dsnsupport">Data Source Name (DSN) Support</a></font> <a href="#connect_ex">Connection Examples</a> <br> |
---|
33 | <b><a href="#speed">High Speed ADOdb - tuning tips</a></b><br> |
---|
34 | <b><a href="#hack">Hacking and Modifying ADOdb Safely</a><br> |
---|
35 | <a href="#php5">PHP5 Features</a></b><br> |
---|
36 | <font size="2"><a href="#php5iterators">foreach iterators</a> <a href="#php5exceptions">exceptions</a></font><br> |
---|
37 | <b> <a href="#drivers">Supported Databases</a></b><br> |
---|
38 | <b> <a href="#quickstart">Tutorials</a></b><br> |
---|
39 | <a href="#ex1">Example 1: Select</a><br> |
---|
40 | <a href="#ex2">Example 2: Advanced Select</a><br> |
---|
41 | <a href="#ex3">Example 3: Insert</a><br> |
---|
42 | <a href="#ex4">Example 4: Debugging</a> <a href="#exrs2html">rs2html |
---|
43 | example</a><br> |
---|
44 | <a href="#ex5">Example 5: MySQL and Menus</a><br> |
---|
45 | <a href="#ex6">Example 6: Connecting to Multiple Databases at once</a> <br> |
---|
46 | <a href="#ex7">Example 7: Generating Update and Insert SQL</a> <br> |
---|
47 | <a href="#ex8">Example 8: Implementing Scrolling with Next and Previous</a><br> |
---|
48 | <a href="#ex9">Example 9: Exporting in CSV or Tab-Delimited Format</a> <br> |
---|
49 | <a href="#ex10">Example 10: Custom filters</a><br> |
---|
50 | <a href="#ex11">Example 11: Smart Transactions</a><br> |
---|
51 | <br> |
---|
52 | <b> <a href="#errorhandling">Using Custom Error Handlers and PEAR_Error</a><br> |
---|
53 | <a href="#DSN">Data Source Names</a><br> |
---|
54 | <a href="#caching">Caching</a><br> |
---|
55 | <a href="#pivot">Pivot Tables</a></b> |
---|
56 | </p><p><a href="#ref"><b>REFERENCE</b></a> |
---|
57 | </p><p> <font size="2">Variables: <a href="#adodb_countrecs">$ADODB_COUNTRECS</a> |
---|
58 | <a href="#adodb_ansi_padding_off">$ADODB_ANSI_PADDING_OFF</a> |
---|
59 | <a href="#adodb_cache_dir">$ADODB_CACHE_DIR</a> <br> |
---|
60 | <a href="#force_type">$ADODB_FORCE_TYPE</a> |
---|
61 | <a href="#adodb_fetch_mode">$ADODB_FETCH_MODE</a> |
---|
62 | <a href="#adodb_lang">$ADODB_LANG</a> <a href=#adodb_auto_quote>ADODB_QUOTE_FIELDNAMES</a> <br> |
---|
63 | Constants: </font><font size="2"><a href="#adodb_assoc_case">ADODB_ASSOC_CASE</a> |
---|
64 | </font><br> |
---|
65 | <a href="#ADOConnection"><b> ADOConnection</b></a><br> |
---|
66 | <font size="2">Connections: <a href="#connect">Connect</a> <a href="#pconnect">PConnect</a> |
---|
67 | <a href="#nconnect">NConnect</a> <a href="#isconnected">IsConnected</a><br> |
---|
68 | Executing SQL: <a href="#execute">Execute</a> <a href="#cacheexecute"><i>CacheExecute</i></a> |
---|
69 | <a href="#selectlimit">SelectLimit</a> <a href="#cacheSelectLimit"><i>CacheSelectLimit</i></a> |
---|
70 | <a href="#param">Param</a> <a href="#prepare">Prepare</a> <a href="#preparesp">PrepareSP</a> |
---|
71 | <a href="#inparameter">InParameter</a> <a href="#outparameter">OutParameter</a> <a href="#autoexecute">AutoExecute</a> |
---|
72 | <br> |
---|
73 | <a href="#getone">GetOne</a> |
---|
74 | <a href="#cachegetone"><i>CacheGetOne</i></a> <a href="#getrow">GetRow</a> <a href="#cachegetrow"><i>CacheGetRow</i></a> |
---|
75 | <a href="#getall">GetAll</a> <a href="#cachegetall"><i>CacheGetAll</i></a> <a href="#getcol">GetCol</a> |
---|
76 | <a href="#cachegetcol"><i>CacheGetCol</i></a> <a href="#getassoc1">GetAssoc</a> <a href="#cachegetassoc"><i>CacheGetAssoc</i></a> <a href="#replace">Replace</a> |
---|
77 | <br> |
---|
78 | <a href="#executecursor">ExecuteCursor</a> |
---|
79 | (oci8 only)<br> |
---|
80 | Generates SQL strings: <a href="#getupdatesql">GetUpdateSQL</a> <a href="#getinsertsql">GetInsertSQL</a> |
---|
81 | <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> |
---|
82 | <a href="#qstr">qstr</a> <a href="#param">Param</a> <a href="#OffsetDate">OffsetDate</a> <a href="#sqldate">SQLDate</a> |
---|
83 | <a href="#dbdate">DBDate</a> <a href="#dbtimestamp">DBTimeStamp</a> |
---|
84 | <a href="#binddate">BindDate</a> <a href="#bindtimestamp">BindTimeStamp</a> |
---|
85 | <br> |
---|
86 | Blobs: <a href="#updateblob">UpdateBlob</a> <a href="#updateclob">UpdateClob</a> |
---|
87 | <a href="#updateblobfile">UpdateBlobFile</a> <a href="#blobencode">BlobEncode</a> |
---|
88 | <a href="#blobdecode">BlobDecode</a><br> |
---|
89 | Paging/Scrolling: <a href="#pageexecute">PageExecute</a> <a href="#cachepageexecute">CachePageExecute</a><br> |
---|
90 | Cleanup: <a href="#cacheflush">CacheFlush</a> <a href="#Close">Close</a><br> |
---|
91 | Transactions: <a href="#starttrans">StartTrans</a> <a href="#completetrans">CompleteTrans</a> |
---|
92 | <a href="#failtrans">FailTrans</a> <a href="#hasfailedtrans">HasFailedTrans</a> |
---|
93 | <a href="#begintrans">BeginTrans</a> <a href="#committrans">CommitTrans</a> |
---|
94 | <a href="#rollbacktrans">RollbackTrans</a> <a href=#SetTransactionMode>SetTransactionMode</a><br> |
---|
95 | Fetching Data: </font> <font size="2"><a href="#setfetchmode">SetFetchMode</a><br> |
---|
96 | 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> |
---|
97 | Dates: <a href="#dbdate">DBDate</a> <a href="#dbtimestamp">DBTimeStamp</a> <a href="#unixdate">UnixDate</a> |
---|
98 | <a href="#binddate">BindDate</a> <a href="#bindtimestamp">BindTimeStamp</a> |
---|
99 | <a href="#unixtimestamp">UnixTimeStamp</a> <a href="#OffsetDate">OffsetDate</a> |
---|
100 | <a href="#SQLDate">SQLDate</a> <br> |
---|
101 | Row Management: <a href="#affected_rows">Affected_Rows</a> <a href="#inserted_id">Insert_ID</a> <a href="#rowlock">RowLock</a> |
---|
102 | <a href="#genid">GenID</a> <a href="#createseq">CreateSequence</a> <a href="#dropseq">DropSequence</a> |
---|
103 | <br> |
---|
104 | Error Handling: <a href="#errormsg">ErrorMsg</a> <a href="#errorno">ErrorNo</a> |
---|
105 | <a href="#metaerror">MetaError</a> <a href="#metaerrormsg">MetaErrorMsg</a> <a href="#ignoreerrors">IgnoreErrors</a><br> |
---|
106 | Data Dictionary (metadata): <a href="#metadatabases">MetaDatabases</a> <a href="#metatables">MetaTables</a> |
---|
107 | <a href="#metacolumns">MetaColumns</a> <a href="#metacolumnames">MetaColumnNames</a> |
---|
108 | <a href="#metaprimarykeys">MetaPrimaryKeys</a> <a href="#metaforeignkeys">MetaForeignKeys</a> |
---|
109 | <a href="#serverinfo">ServerInfo</a> <br> |
---|
110 | Statistics and Query-Rewriting: <a href="#logsql">LogSQL</a> <a href="#fnexecute">fnExecute |
---|
111 | and fnCacheExecute</a><br> |
---|
112 | </font><font size="2">Deprecated: <a href="#bind">Bind</a> <a href="#blankrecordset">BlankRecordSet</a> |
---|
113 | <a href="#parameter">Parameter</a></font> |
---|
114 | <a href="#adorecordSet"><b><br> |
---|
115 | ADORecordSet</b></a><br> |
---|
116 | <font size="2"> |
---|
117 | Returns one field: <a href="#fields">Fields</a><br> |
---|
118 | Returns one row:<a href="#fetchrow">FetchRow</a> <a href="#fetchinto">FetchInto</a> |
---|
119 | <a href="#fetchobject">FetchObject</a> <a href="#fetchnextobject">FetchNextObject</a> |
---|
120 | <a href="#fetchobj">FetchObj</a> <a href="#fetchnextobj">FetchNextObj</a> |
---|
121 | <a href="#getrowassoc">GetRowAssoc</a> <br> |
---|
122 | Returns all rows:<a href="#getarray">GetArray</a> <a href="#getrows">GetRows</a> |
---|
123 | <a href="#getassoc">GetAssoc</a><br> |
---|
124 | Scrolling:<a href="#move">Move</a> <a href="#movenext">MoveNext</a> <a href="#movefirst">MoveFirst</a> |
---|
125 | <a href="#movelast">MoveLast</a> <a href="#abspos">AbsolutePosition</a> <a href="#currentrow">CurrentRow</a> |
---|
126 | <a href="#atfirstpage">AtFirstPage</a> <a href="#atlastpage">AtLastPage</a> |
---|
127 | <a href="#absolutepage">AbsolutePage</a> </font> <font size="2"><br> |
---|
128 | Menu generation:<a href="#getmenu">GetMenu</a> <a href="#getmenu2">GetMenu2</a><br> |
---|
129 | Dates:<a href="#userdate">UserDate</a> <a href="#usertimestamp">UserTimeStamp</a> |
---|
130 | <a href="#unixdate">UnixDate</a> <a href="#unixtimestamp">UnixTimeStamp<br> |
---|
131 | </a>Recordset Info:<a href="#recordcount">RecordCount</a> <a href="#po_recordcount">PO_RecordCount</a> |
---|
132 | <a href="#nextrecordset">NextRecordSet</a><br> |
---|
133 | Field Info:<a href="#fieldcount">FieldCount</a> <a href="#fetchfield">FetchField</a> |
---|
134 | <a href="#metatype">MetaType</a><br> |
---|
135 | Cleanup: <a href="#rsclose">Close</a></font> |
---|
136 | </p> |
---|
137 | <p><font size="2"><a href="#rs2html"><b>rs2html</b></a> <a href="#exrs2html">example</a></font><br> |
---|
138 | <a href="#adodiff">Differences between ADOdb and ADO</a><br> |
---|
139 | <a href="#driverguide"><b>Database Driver Guide<br> |
---|
140 | </b></a><b><a href="#changes">Change Log</a></b><br> |
---|
141 | </p> |
---|
142 | <h2>Introduction<a name="intro"></a></h2> |
---|
143 | <p>PHP's database access functions are not standardised. This creates a need for |
---|
144 | a database class library to hide the differences between the different database |
---|
145 | API's (encapsulate the differences) so we can easily switch databases. PHP 4.0.5 or later |
---|
146 | is now required (because we use array-based str_replace).</p> |
---|
147 | <p>We currently support MySQL, Oracle, Microsoft SQL Server, Sybase, Sybase SQL Anywhere, Informix, |
---|
148 | PostgreSQL, FrontBase, SQLite, Interbase (Firebird and Borland variants), Foxpro, Access, ADO, DB2, SAP DB and ODBC. |
---|
149 | We have had successful reports of connecting to Progress and CacheLite via ODBC. We hope more people |
---|
150 | will contribute drivers to support other databases.</p> |
---|
151 | <p>PHP4 supports session variables. You can store your session information using |
---|
152 | ADOdb for true portability and scalability. See adodb-session.php for more information.</p> |
---|
153 | <p>Also read <a href="http://phplens.com/lens/adodb/tips_portable_sql.htm">tips_portable_sql.htm</a> |
---|
154 | for tips on writing |
---|
155 | portable SQL.</p> |
---|
156 | <h2>Unique Features of ADOdb<a name="features"></a></h2> |
---|
157 | <ul> |
---|
158 | <li><b>Easy for Windows programmers</b> to adapt to because many of the conventions |
---|
159 | are similar to Microsoft's ADO.</li> |
---|
160 | <li>Unlike other PHP database classes which focus only on select statements, |
---|
161 | <b>we provide support code to handle inserts and updates which can be adapted |
---|
162 | to multiple databases quickly.</b> Methods are provided for date handling, |
---|
163 | string concatenation and string quoting characters for differing databases.</li> |
---|
164 | <li>A<b> metatype system </b>is built in so that we can figure out that types |
---|
165 | such as CHAR, TEXT and STRING are equivalent in different databases.</li> |
---|
166 | <li><b>Easy to port</b> because all the database dependant code are stored in |
---|
167 | stub functions. You do not need to port the core logic of the classes.</li> |
---|
168 | <li><b>Portable table and index creation</b> with the <a href="docs-datadict.htm">datadict</a> classes. |
---|
169 | </li><li><b>Database performance monitoring and SQL tuning</b> with the <a href="docs-perf.htm">performance monitoring</a> classes. |
---|
170 | </li><li><b>Database-backed sessions</b> with the <a href="docs-session.htm">session management</a> classes. Supports session expiry notification. |
---|
171 | <li><b>Object-Relational Mapping</b> using <a href="docs-active-record.htm">ADOdb_Active_Record</a> classes. |
---|
172 | </li></ul> |
---|
173 | <h2>How People are using ADOdb<a name="users"></a></h2> |
---|
174 | Here are some examples of how people are using ADOdb (for a much longer list, |
---|
175 | visit <a href="http://phplens.com/phpeverywhere/adodb-cool-apps">adodb-cool-apps</a>): |
---|
176 | <ul> |
---|
177 | <li><a href="http://phplens.com/">PhpLens</a> is a commercial data grid |
---|
178 | component that allows both cool Web designers and serious unshaved |
---|
179 | programmers to develop and maintain databases on the Web easily. |
---|
180 | Developed by the author of ADOdb.<p> |
---|
181 | |
---|
182 | </p></li><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> |
---|
183 | |
---|
184 | </p></li><li><a href="http://www.andrew.cmu.edu/%7Erdanyliw/snort/snortacid.html">Analysis Console for Intrusion Databases</a> |
---|
185 | (ACID): PHP-based analysis engine to search and process a database of |
---|
186 | security incidents generated by security-related software such as IDSes |
---|
187 | and firewalls (e.g. Snort, ipchains). By Roman Danyliw.<p> |
---|
188 | |
---|
189 | </p></li><li><a href="http://www.postnuke.com/">PostNuke</a> is a very |
---|
190 | popular free content management system and weblog system. It offers |
---|
191 | full CSS support, HTML 4.01 transitional compliance throughout, an |
---|
192 | advanced blocks system, and is fully multi-lingual enabled. <p> |
---|
193 | |
---|
194 | </p></li><li><a href="http://www.auto-net.no/easypublish.php?page=index&lang_id=2">EasyPublish CMS</a> |
---|
195 | is another free content management system for managing information and |
---|
196 | integrated modules on your internet, intranet- and extranet-sites. From |
---|
197 | Norway.<p> |
---|
198 | |
---|
199 | </p></li><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. |
---|
200 | </li></ul><p> |
---|
201 | |
---|
202 | </p><h2>Feature Requests and Bug Reports<a name="bugs"></a></h2> |
---|
203 | <p>Feature requests and bug reports can be emailed to <a href="mailto:jlim#natsoft.com.my">jlim#natsoft.com.my</a> |
---|
204 | 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> |
---|
205 | <h2>Installation Guide<a name="install"></a></h2> |
---|
206 | <p>Make sure you are running PHP 4.0.5 or later. |
---|
207 | Unpack all the files into a directory accessible by your webserver.</p> |
---|
208 | <p>To test, try modifying some of the tutorial examples. Make sure you customize |
---|
209 | the connection settings correctly. You can debug using <i>$db->debug = true</i> as shown below:</p> |
---|
210 | <pre><?php<br> include('adodb/adodb.inc.php');<br> $db = <a href="#adonewconnection">ADONewConnection</a>($dbdriver); # eg 'mysql' or 'postgres'<br> $db->debug = true;<br> $db-><a href="#connect">Connect</a>($server, $user, $password, $database);<br> $rs = $db-><a href="#execute">Execute</a>('select * from some_small_table');<br> print "<pre>";<br> print_r($rs-><a href="#getrows">GetRows</a>());<br> print "</pre>";<br>?></pre> |
---|
211 | |
---|
212 | <h3>Minimum Install<a name="mininstall"></a></h3> |
---|
213 | <p>For developers who want to release a minimal install of ADOdb, you will need: |
---|
214 | </p><ul> |
---|
215 | <li>adodb.inc.php |
---|
216 | </li><li>adodb-lib.inc.php |
---|
217 | </li><li>adodb-time.inc.php |
---|
218 | </li><li>drivers/adodb-$database.inc.php |
---|
219 | </li><li>license.txt (for legal reasons) |
---|
220 | </li><li>adodb-php4.inc.php |
---|
221 | </li><li>adodb-iterator.inc.php (php5 functionality) |
---|
222 | </li></ul> |
---|
223 | Optional: |
---|
224 | <ul> |
---|
225 | <li>adodb-error.inc.php and lang/adodb-$lang.inc.php (if you use MetaError()) |
---|
226 | </li><li>adodb-csvlib.inc.php (if you use cached recordsets - CacheExecute(), etc) |
---|
227 | </li><li>adodb-exceptions.inc.php and adodb-errorhandler.inc.php (if you use adodb error handler or php5 exceptions). |
---|
228 | <li>adodb-active-record.inc.php if you use <a href=docs-active-record.htm>Active Records</a>. |
---|
229 | </li></ul> |
---|
230 | |
---|
231 | <h3>Code Initialization Examples<a name="coding"></a></h3> |
---|
232 | <p>When running ADOdb, at least two files are loaded. First is adodb/adodb.inc.php, |
---|
233 | which contains all functions used by all database classes. The code specific |
---|
234 | to a particular database is in the adodb/driver/adodb-????.inc.php file.</p> |
---|
235 | <a name="adonewconnection"></a> |
---|
236 | <p>For example, to connect to a mysql database:</p> |
---|
237 | <pre>include('/path/to/set/here/adodb.inc.php');<br>$conn = &ADONewConnection('mysql');<br></pre> |
---|
238 | <p>Whenever you need to connect to a database, you create a Connection object |
---|
239 | using the <b>ADONewConnection</b>($driver) function. |
---|
240 | <b>NewADOConnection</b>($driver) is an alternative name for the same function.</p> |
---|
241 | |
---|
242 | <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 |
---|
243 | whether to use <i>persistent</i> or <i>non-persistent</i> connections. The advantage of <i>persistent</i> |
---|
244 | connections is that they are faster, as the database connection is never closed (even |
---|
245 | when you call Close()). <i>Non-persistent </i>connections take up much fewer resources though, |
---|
246 | reducing the risk of your database and your web-server becoming overloaded. |
---|
247 | </p><p>For persistent connections, |
---|
248 | use $conn-><a href="#pconnect">PConnect()</a>, |
---|
249 | or $conn-><a href="#connect">Connect()</a> for non-persistent connections. |
---|
250 | Some database drivers also support <a href="#nconnect">NConnect()</a>, which forces |
---|
251 | the creation of a new connection. |
---|
252 | |
---|
253 | <a name="connection_gotcha"></a> |
---|
254 | </p><p><b>Connection Gotcha</b>: If you create two connections, but both use the same userid and password, |
---|
255 | PHP will share the same connection. This can cause problems if the connections are meant to |
---|
256 | different databases. The solution is to always use different userid's for different databases, |
---|
257 | or use NConnect(). |
---|
258 | |
---|
259 | <a name="dsnsupport"></a> |
---|
260 | </p><h3>Data Source Name (DSN) Support</h3> |
---|
261 | <p> Since ADOdb 4.51, you can connect to a database by passing a dsn to NewADOConnection() (or ADONewConnection, which is |
---|
262 | the same function). The dsn format is: |
---|
263 | </p><pre> $driver://$username:$password@hostname/$database?options[=value]<br></pre><p> |
---|
264 | NewADOConnection() calls Connect() or PConnect() internally for you. If the connection fails, false is returned. |
---|
265 | </p><pre> <font color="#008000"># non-persistent connection</font> |
---|
266 | $dsn = 'mysql://root:pwd@localhost/mydb'; |
---|
267 | $db = NewADOConnection($dsn); |
---|
268 | if (!$db) die("Connection failed"); |
---|
269 | |
---|
270 | <font color="#008000"># no need to call connect/pconnect!</font> |
---|
271 | $arr = $db->GetArray("select * from table"); |
---|
272 | |
---|
273 | <font color="#008000"># persistent connection</font> |
---|
274 | $dsn2 = 'mysql://root:pwd@localhost/mydb?persist'; |
---|
275 | </pre> |
---|
276 | <p> |
---|
277 | If you have special characters such as /:?_ in your dsn, then you need to rawurlencode them first: |
---|
278 | </p><pre> $pwd = rawurlencode($pwd);<br> $dsn = "mysql://root:$pwd@localhost/mydb"; |
---|
279 | $dsn2=rawurlencode("sybase_ase")."://user:pass@host/path?query";<br></pre> |
---|
280 | <p> |
---|
281 | Legal options are: |
---|
282 | </p><p> |
---|
283 | <table align="center" border="1"><tbody><tr><td>For all drivers</td><td> |
---|
284 | 'persist', 'persistent', 'debug', 'fetchmode', 'new' |
---|
285 | </td></tr><tr><td>Interbase/Firebird |
---|
286 | </td><td> |
---|
287 | 'dialect','charset','buffers','role' |
---|
288 | </td></tr><tr><td>M'soft ADO</td><td> |
---|
289 | 'charpage' |
---|
290 | |
---|
291 | </td></tr><tr><td>MySQL</td><td> |
---|
292 | 'clientflags' |
---|
293 | </td></tr><tr><td>MySQLi</td><td> |
---|
294 | 'port', 'socket', 'clientflags' |
---|
295 | </td></tr><tr><td>Oci8</td><td> |
---|
296 | 'nls_date_format','charset' |
---|
297 | </td></tr></tbody></table> |
---|
298 | </p><p> |
---|
299 | For all drivers, when the options <i>persist</i> or <i>persistent</i> are set, a persistent connection is forced; similarly, when <i>new</i> is set, then |
---|
300 | a new connection will be created using NConnect if the underlying driver supports it. |
---|
301 | The <i>debug</i> option enables debugging. The <i>fetchmode</i> calls <a href="#setfetchmode">SetFetchMode()</a>. |
---|
302 | If no value is defined for an option, then the value is set to 1. |
---|
303 | </p><p> |
---|
304 | ADOdb DSN's are compatible with version 1.0 of PEAR DB's DSN format. |
---|
305 | <a name="connect_ex"> |
---|
306 | </a></p><h3><a name="connect_ex">Examples of Connecting to Databases</a></h3> |
---|
307 | <h4><a name="connect_ex">MySQL and Most Other Database Drivers</a></h4> |
---|
308 | <p><a name="connect_ex">MySQL connections are very straightforward, and the parameters are identical |
---|
309 | to mysql_connect:</a></p> |
---|
310 | <pre><a name="connect_ex"> $conn = &ADONewConnection('mysql'); <br> $conn->PConnect('localhost','userid','password','database');<br> <br> <font color="#008000"># or dsn </font> |
---|
311 | $dsn = 'mysql://user:pwd@localhost/mydb'; |
---|
312 | $conn = ADONewConnection($dsn); # no need for Connect() |
---|
313 | |
---|
314 | <font color="#008000"># or persistent dsn</font> |
---|
315 | $dsn = 'mysql://user:pwd@localhost/mydb?persist'; |
---|
316 | $conn = ADONewConnection($dsn); # no need for PConnect() |
---|
317 | |
---|
318 | <font color="#008000"># a more complex example:</font> |
---|
319 | $pwd = urlencode($pwd); |
---|
320 | $flags = MYSQL_CLIENT_COMPRESS; |
---|
321 | $dsn = "mysql://user:$pwd@localhost/mydb?persist&clientflags=$flags"; |
---|
322 | $conn = ADONewConnection($dsn); # no need for PConnect() |
---|
323 | </a></pre> |
---|
324 | <p><a name="connect_ex"> For most drivers, you can use the standard function: Connect($server, $user, $password, $database), or |
---|
325 | a </a><a href="dsnsupport">DSN</a> since ADOdb 4.51. Exceptions to this are listed below. |
---|
326 | </p> |
---|
327 | <a name=pdo> |
---|
328 | <h4>PDO</h4> |
---|
329 | <p>PDO, which only works with PHP5, accepts a driver specific connection string: |
---|
330 | <pre> |
---|
331 | $conn =& NewADConnection('pdo'); |
---|
332 | $conn->Connect('mysql:host=localhost',$user,$pwd,$mydb); |
---|
333 | $conn->Connect('mysql:host=localhost;dbname=mydb',$user,$pwd); |
---|
334 | $conn->Connect("mysql:host=localhost;dbname=mydb;username=$user;password=$pwd"); |
---|
335 | </pre> |
---|
336 | <p>The DSN mechanism is also supported: |
---|
337 | <pre> |
---|
338 | $conn =& NewADConnection("pdo_mysql://user:pwd@localhost/mydb?persist"); # persist is optional |
---|
339 | </pre> |
---|
340 | <h4>PostgreSQL</h4> |
---|
341 | <p>PostgreSQL 7 and 8 accepts connections using: </p> |
---|
342 | <p>a. the standard connection string:</p> |
---|
343 | <pre> $conn = &ADONewConnection('postgres'); <br> $conn->PConnect('host=localhost port=5432 dbname=mary');</pre> |
---|
344 | <p> b. the classical 4 parameters:</p> |
---|
345 | <pre> $conn->PConnect('localhost','userid','password','database');<br> </pre> |
---|
346 | <p>c. dsn: |
---|
347 | </p><pre> $dsn = 'postgres://user:pwd@localhost/mydb?persist'; # persist is optional |
---|
348 | $conn = ADONewConnection($dsn); # no need for Connect/PConnect<br></pre> |
---|
349 | <a name="ldap"></a> |
---|
350 | |
---|
351 | <h4>LDAP</h4> |
---|
352 | <p>Here is an example of querying a LDAP server. Thanks to Josh Eldridge for the driver and this example: |
---|
353 | </p><pre> |
---|
354 | require('/path/to/adodb.inc.php'); |
---|
355 | |
---|
356 | /* Make sure to set this BEFORE calling Connect() */ |
---|
357 | $LDAP_CONNECT_OPTIONS = Array( |
---|
358 | Array ("OPTION_NAME"=>LDAP_OPT_DEREF, "OPTION_VALUE"=>2), |
---|
359 | Array ("OPTION_NAME"=>LDAP_OPT_SIZELIMIT,"OPTION_VALUE"=>100), |
---|
360 | Array ("OPTION_NAME"=>LDAP_OPT_TIMELIMIT,"OPTION_VALUE"=>30), |
---|
361 | Array ("OPTION_NAME"=>LDAP_OPT_PROTOCOL_VERSION,"OPTION_VALUE"=>3), |
---|
362 | Array ("OPTION_NAME"=>LDAP_OPT_ERROR_NUMBER,"OPTION_VALUE"=>13), |
---|
363 | Array ("OPTION_NAME"=>LDAP_OPT_REFERRALS,"OPTION_VALUE"=>FALSE), |
---|
364 | Array ("OPTION_NAME"=>LDAP_OPT_RESTART,"OPTION_VALUE"=>FALSE) |
---|
365 | ); |
---|
366 | $host = 'ldap.baylor.edu'; |
---|
367 | $ldapbase = 'ou=People,o=Baylor University,c=US'; |
---|
368 | |
---|
369 | $ldap = NewADOConnection( 'ldap' ); |
---|
370 | $ldap->Connect( $host, $user_name='', $password='', $ldapbase ); |
---|
371 | |
---|
372 | echo "<pre>"; |
---|
373 | |
---|
374 | print_r( $ldap->ServerInfo() ); |
---|
375 | $ldap->SetFetchMode(ADODB_FETCH_ASSOC); |
---|
376 | $userName = 'eldridge'; |
---|
377 | $filter="(|(CN=$userName*)(sn=$userName*)(givenname=$userName*)(uid=$userName*))"; |
---|
378 | |
---|
379 | $rs = $ldap->Execute( $filter ); |
---|
380 | if ($rs) |
---|
381 | while ($arr = $rs->FetchRow()) { |
---|
382 | print_r($arr); |
---|
383 | } |
---|
384 | |
---|
385 | $rs = $ldap->Execute( $filter ); |
---|
386 | if ($rs) |
---|
387 | while (!$rs->EOF) { |
---|
388 | print_r($rs->fields); |
---|
389 | $rs->MoveNext(); |
---|
390 | } |
---|
391 | |
---|
392 | print_r( $ldap->GetArray( $filter ) ); |
---|
393 | print_r( $ldap->GetRow( $filter ) ); |
---|
394 | |
---|
395 | $ldap->Close(); |
---|
396 | echo "</pre>"; |
---|
397 | </pre> |
---|
398 | <p>Using DSN: |
---|
399 | <pre> |
---|
400 | $dsn = "ldap://ldap.baylor.edu/ou=People,o=Baylor University,c=US"; |
---|
401 | $db = NewADOConnection($dsn); |
---|
402 | </pre> |
---|
403 | <h4>Interbase/Firebird</h4> |
---|
404 | You define the database in the $host parameter: |
---|
405 | <pre> $conn = &ADONewConnection('ibase'); <br> $conn->PConnect('localhost:c:\ibase\employee.gdb','sysdba','masterkey');<br></pre> |
---|
406 | <p>Or dsn: |
---|
407 | </p><pre> $dsn = 'firebird://user:pwd@localhost/mydb?persist&dialect=3'; # persist is optional<br> $conn = ADONewConnection($dsn); # no need for Connect/PConnect<br></pre> |
---|
408 | <h4>SQLite</h4> |
---|
409 | Sqlite will create the database file if it does not exist. |
---|
410 | <pre> $conn = &ADONewConnection('sqlite'); |
---|
411 | $conn->PConnect('c:\path\to\sqlite.db'); # sqlite will create if does not exist<br></pre> |
---|
412 | <p>Or dsn: |
---|
413 | </p><pre> $path = urlencode('c:\path\to\sqlite.db'); |
---|
414 | $dsn = "sqlite://$path/?persist"; # persist is optional |
---|
415 | $conn = ADONewConnection($dsn); # no need for Connect/PConnect<br></pre> |
---|
416 | <h4>Oracle (oci8)</h4> |
---|
417 | <p>With oci8, you can connect in multiple ways. Note that oci8 works fine with |
---|
418 | newer versions of the Oracle, eg. 9i and 10g.</p> |
---|
419 | <p>a. PHP and Oracle reside on the same machine, use default SID.</p> |
---|
420 | <pre> $conn->Connect(false, 'scott', 'tiger');</pre> |
---|
421 | <p>b. TNS Name defined in tnsnames.ora (or ONAMES or HOSTNAMES), eg. 'myTNS'</p> |
---|
422 | <pre> $conn->PConnect(false, 'scott', 'tiger', 'myTNS');</pre> |
---|
423 | <p>or</p> |
---|
424 | <pre> $conn->PConnect('myTNS', 'scott', 'tiger');</pre> |
---|
425 | <p>c. Host Address and SID</p> |
---|
426 | <pre> |
---|
427 | $conn->connectSID = true; |
---|
428 | $conn->Connect('192.168.0.1', 'scott', 'tiger', 'SID');</pre> |
---|
429 | <p>d. Host Address and Service Name</p> |
---|
430 | <pre> $conn->Connect('192.168.0.1', 'scott', 'tiger', 'servicename');</pre> |
---|
431 | <p>e. Oracle connection string: |
---|
432 | </p><pre> $cstr = "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=$host)(PORT=$port))<br> (CONNECT_DATA=(SID=$sid)))";<br> $conn->Connect($cstr, 'scott', 'tiger');<br></pre> |
---|
433 | <p>f. ADOdb dsn: |
---|
434 | </p><pre> $dsn = 'oci8://user:pwd@tnsname/?persist'; # persist is optional<br> $conn = ADONewConnection($dsn); # no need for Connect/PConnect<br> <br> $dsn = 'oci8://user:pwd@host/sid';<br> $conn = ADONewConnection($dsn);<br> <br> $dsn = 'oci8://user:pwd@/'; # oracle on local machine<br> $conn = ADONewConnection($dsn);<br></pre> |
---|
435 | <p>You can also set the charSet for Oracle 9.2 and later, supported since PHP 4.3.2, ADOdb 4.54: |
---|
436 | </p><pre> $conn->charSet = 'we8iso8859p1';<br> $conn->Connect(...);<br> <br> # or<br> $dsn = 'oci8://user:pwd@tnsname/?charset=WE8MSWIN1252';<br> $db = ADONewConnection($dsn);<br></pre> |
---|
437 | <a name="dsnless"></a> |
---|
438 | <h4>DSN-less ODBC ( Access, MSSQL and DB2 examples)</h4> |
---|
439 | <p>ODBC DSN's can be created in the ODBC control panel, or you can use a DSN-less |
---|
440 | connection.To use DSN-less connections with ODBC you need PHP 4.3 or later. |
---|
441 | </p> |
---|
442 | <p>For Microsoft Access:</p> |
---|
443 | <pre> $db =& ADONewConnection('access');<br> $dsn = <strong>"Driver={Microsoft Access Driver (*.mdb)};Dbq=d:\\northwind.mdb;Uid=Admin;Pwd=;";</strong> |
---|
444 | $db->Connect($dsn); |
---|
445 | </pre> |
---|
446 | For Microsoft SQL Server: |
---|
447 | <pre> $db =& ADONewConnection('odbc_mssql');<br> $dsn = <strong>"Driver={SQL Server};Server=localhost;Database=northwind;"</strong>;<br> $db->Connect($dsn,'userid','password');<br></pre> |
---|
448 | or if you prefer to use the mssql extension (which is limited to mssql 6.5 functionality): |
---|
449 | <pre> $db =& ADONewConnection('mssql');<br> $db->Execute('localhost', 'userid', 'password', 'northwind');<br></pre> |
---|
450 | For DB2: |
---|
451 | <pre> |
---|
452 | $dbms = 'db2'; # or 'odbc_db2' if db2 extension not available |
---|
453 | $db =& ADONewConnection($dbms); |
---|
454 | $dsn = "driver={IBM db2 odbc DRIVER};Database=sample;hostname=localhost;port=50000;protocol=TCPIP;". |
---|
455 | "uid=root; pwd=secret";<br> $db->Connect($dsn); |
---|
456 | </pre> |
---|
457 | <b>DSN-less Connections with ADO</b><br> |
---|
458 | If you are using versions of PHP earlier than PHP 4.3.0, DSN-less connections |
---|
459 | only work with Microsoft's ADO, which is Microsoft's COM based API. An example |
---|
460 | using the ADOdb library and Microsoft's ADO: |
---|
461 | <pre><?php<br> include('adodb.inc.php'); <br> $db = &ADONewConnection("ado_mssql");<br> print "<h1>Connecting DSN-less $db->databaseType...</h1>";<br> <br> <b>$myDSN="PROVIDER=MSDASQL;DRIVER={SQL Server};"<br> . "SERVER=flipper;DATABASE=ai;UID=sa;PWD=;" ;</b> |
---|
462 | $db->Connect($myDSN); |
---|
463 | |
---|
464 | $rs = $db->Execute("select * from table"); |
---|
465 | $arr = $rs->GetArray(); |
---|
466 | print_r($arr); |
---|
467 | ?> |
---|
468 | </pre><a name="speed"></a> |
---|
469 | <h2>High Speed ADOdb - tuning tips</h2> |
---|
470 | <p>ADOdb is a big class library, yet it <a href="http://phplens.com/lens/adodb/">consistently beats</a> all other PHP class |
---|
471 | libraries in performance. This is because it is designed in a layered fashion, |
---|
472 | like an onion, with the fastest functions in the innermost layer. Stick to the |
---|
473 | following functions for best performance:</p> |
---|
474 | <table align="center" border="1" width="40%"> |
---|
475 | <tbody><tr> |
---|
476 | <td><div align="center"><b>Innermost Layer</b></div></td> |
---|
477 | </tr> |
---|
478 | <tr> |
---|
479 | <td><p align="center">Connect, PConnect, NConnect<br> |
---|
480 | Execute, CacheExecute<br> |
---|
481 | SelectLimit, CacheSelectLimit<br> |
---|
482 | MoveNext, Close <br> |
---|
483 | qstr, Affected_Rows, Insert_ID</p></td> |
---|
484 | </tr> |
---|
485 | </tbody></table> |
---|
486 | <p>The fastest way to access the field data is by accessing the array $recordset->fields |
---|
487 | directly. Also set the global variables <a href="#adodb_fetch_mode">$ADODB_FETCH_MODE</a> |
---|
488 | = ADODB_FETCH_NUM, and (for oci8, ibase/firebird and odbc) <a href="#adodb_countrecs">$ADODB_COUNTRECS</a> = false |
---|
489 | before you connect to your database.</p> |
---|
490 | <p>Consider using bind parameters if your database supports it, as it improves |
---|
491 | query plan reuse. Use ADOdb's performance tuning system to identify bottlenecks |
---|
492 | quickly. At the time of writing (Dec 2003), this means oci8 and odbc drivers.</p> |
---|
493 | <p>Lastly make sure you have a PHP accelerator cache installed such as APC, Turck |
---|
494 | MMCache, Zend Accelerator or ionCube.</p> |
---|
495 | <p>Some examples:</p> |
---|
496 | <table align="center" border="1"><tbody><tr><td><b>Fastest data retrieval using PHP</b></td><td><b>Fastest data retrieval using ADOdb extension</b></td></tr> |
---|
497 | <tr><td> |
---|
498 | <pre>$rs =& $rs->Execute($sql);<br>while (!$rs->EOF) {<br> var_dump($rs->fields);<br> $rs->MoveNext();<br>}</pre></td><td> |
---|
499 | <pre>$rs =& $rs->Execute($sql);<br>$array = adodb_getall($rs);<br>var_dump($array);<br><br><br></pre></td></tr></tbody></table> |
---|
500 | <p><b>Advanced Tips</b> |
---|
501 | </p><p>If you have the <a href="http://adodb.sourceforge.net/#extension">ADOdb C extension</a> installed, |
---|
502 | you can replace your calls to $rs->MoveNext() with adodb_movenext($rs). |
---|
503 | This doubles the speed of this operation. For retrieving entire recordsets at once, |
---|
504 | use GetArray(), which uses the high speed extension function adodb_getall($rs) internally. |
---|
505 | </p><p>Execute() is the default way to run queries. You can use the low-level functions _Execute() and _query() |
---|
506 | to reduce query overhead. Both these functions share the same parameters as Execute(). |
---|
507 | </p><p>If you do not have any bind parameters or your database supports |
---|
508 | binding (without emulation), |
---|
509 | then you can call _Execute() directly. Calling this function bypasses |
---|
510 | bind emulation. Debugging is still supported in _Execute(). |
---|
511 | </p><p>If you do not require debugging facilities nor emulated |
---|
512 | binding, and do not require a recordset to be returned, then you can |
---|
513 | call _query. This is great for inserts, updates and deletes. Calling |
---|
514 | this function |
---|
515 | bypasses emulated binding, debugging, and recordset handling. Either |
---|
516 | the resultid, true or false are returned by _query(). </p><p>For Informix, you can disable scrollable cursors with $db->cursorType = 0. |
---|
517 | </p><p><a name="hack"></a> </p> |
---|
518 | <h2>Hacking ADOdb Safely</h2> |
---|
519 | <p>You might want to modify ADOdb for your own purposes. Luckily you can |
---|
520 | still maintain backward compatibility by sub-classing ADOdb and using the $ADODB_NEWCONNECTION |
---|
521 | variable. $ADODB_NEWCONNECTION allows you to override the behaviour of ADONewConnection(). |
---|
522 | ADOConnection() checks for this variable and will call |
---|
523 | the function-name stored in this variable if it is defined. |
---|
524 | </p><p>In the following example, new functionality for the connection object |
---|
525 | is placed in the <i>hack_mysql</i> and <i>hack_postgres7</i> classes. The recordset class naming convention |
---|
526 | can be controlled using $rsPrefix. Here we set it to 'hack_rs_', which will make ADOdb use |
---|
527 | <i>hack_rs_mysql</i> and <i>hack_rs_postgres7</i> as the recordset classes. |
---|
528 | |
---|
529 | |
---|
530 | </p><pre>class hack_mysql extends adodb_mysql {<br>var $rsPrefix = 'hack_rs_';<br> /* Your mods here */<br>}<br><br>class hack_rs_mysql extends ADORecordSet_mysql {<br> /* Your mods here */<br>}<br><br>class hack_postgres7 extends adodb_postgres7 {<br>var $rsPrefix = 'hack_rs_';<br> /* Your mods here */<br>}<br><br>class hack_rs_postgres7 extends ADORecordSet_postgres7 {<br> /* Your mods here */<br>}<br><br>$ADODB_NEWCONNECTION = 'hack_factory';<br><br>function& hack_factory($driver)<br>{<br> if ($driver !== 'mysql' && $driver !== 'postgres7') return false;<br> <br> $driver = 'hack_'.$driver;<br> $obj = new $driver();<br> return $obj;<br>}<br><br>include_once('adodb.inc.php');<br></pre> |
---|
531 | <p></p><p>Don't forget to call the constructor of the parent class in |
---|
532 | your constructor. If you want to use the default ADOdb drivers return |
---|
533 | false in the above hack_factory() function. |
---|
534 | <a name="php5"></a> |
---|
535 | </p><h2>PHP5 Features</h2> |
---|
536 | ADOdb 4.02 or later will transparently determine which version of PHP you are using. |
---|
537 | If PHP5 is detected, the following features become available: |
---|
538 | <ul> |
---|
539 | |
---|
540 | <li><b>PDO</b>: PDO drivers are available. See the <a href=#pdo>connection examples</a>. Currently PDO drivers are |
---|
541 | not as powerful as native drivers, and should be treated as experimental.<br><br> |
---|
542 | <a name="php5iterators"></a> |
---|
543 | <li><b>Foreach iterators</b>: This is a very natural way of going through a recordset: |
---|
544 | <pre> $ADODB_FETCH_MODE = ADODB_FETCH_NUM;<br> $rs = $db->Execute($sql);<br> foreach($rs as $k => $row) {<br> echo "r1=".$row[0]." r2=".$row[1]."<br>";<br> }<br></pre> |
---|
545 | <p> |
---|
546 | <a name="php5exceptions"></a> |
---|
547 | </p></li><li><b>Exceptions</b>: Just include <i>adodb-exceptions.inc.php</i> and you can now |
---|
548 | catch exceptions on errors as they occur. |
---|
549 | <pre> <b>include("../adodb-exceptions.inc.php");</b> <br> include("../adodb.inc.php"); <br> try { <br> $db = NewADOConnection("oci8"); <br> $db->Connect('','scott','bad-password'); <br> } catch (exception $e) { <br> var_dump($e); <br> adodb_backtrace($e->gettrace());<br> } <br></pre> |
---|
550 | <p>Note that reaching EOF is <b>not</b> considered an error nor an exception. |
---|
551 | </p></li></ul> |
---|
552 | <h3><a name="drivers"></a>Databases Supported</h3> |
---|
553 | The <i>name</i> below is the value you pass to NewADOConnection($name) to create a connection object for that database. |
---|
554 | <p> |
---|
555 | </p><p> |
---|
556 | </p><table border="1" width="100%"> |
---|
557 | <tbody><tr valign="top"> |
---|
558 | <td><b>Name</b></td> |
---|
559 | <td><b>Tested</b></td> |
---|
560 | <td><b>Database</b></td> |
---|
561 | <td><b><font size="2">RecordCount() usable</font></b></td> |
---|
562 | <td><b>Prerequisites</b></td> |
---|
563 | <td><b>Operating Systems</b></td> |
---|
564 | </tr> |
---|
565 | <tr valign="top"> |
---|
566 | <td><b><font size="2">access</font></b></td> |
---|
567 | <td><font size="2">B</font></td> |
---|
568 | <td><font size="2">Microsoft Access/Jet. You need to create an ODBC DSN.</font></td> |
---|
569 | <td><font size="2">Y/N</font></td> |
---|
570 | <td><font size="2">ODBC </font></td> |
---|
571 | <td><font size="2">Windows only</font></td> |
---|
572 | </tr> |
---|
573 | <tr valign="top"> |
---|
574 | <td><b><font size="2">ado</font></b></td> |
---|
575 | <td><font size="2">B</font></td> |
---|
576 | <td><p><font size="2">Generic ADO, not tuned for specific databases. Allows |
---|
577 | DSN-less connections. For best performance, use an OLEDB provider. This |
---|
578 | is the base class for all ado drivers.</font></p> |
---|
579 | <p><font size="2">You can set $db->codePage before connecting.</font></p></td> |
---|
580 | <td><font size="2">? depends on database</font></td> |
---|
581 | <td><font size="2">ADO or OLEDB provider</font></td> |
---|
582 | <td><font size="2">Windows only</font></td> |
---|
583 | </tr> |
---|
584 | <tr valign="top"> |
---|
585 | <td><b><font size="2">ado_access</font></b></td> |
---|
586 | <td><font size="2">B</font></td> |
---|
587 | <td><font size="2">Microsoft Access/Jet using ADO. Allows DSN-less connections. |
---|
588 | For best performance, use an OLEDB provider.</font></td> |
---|
589 | <td><font size="2">Y/N</font></td> |
---|
590 | <td><font size="2">ADO or OLEDB provider</font></td> |
---|
591 | <td><font size="2">Windows only</font></td> |
---|
592 | </tr> |
---|
593 | <tr valign="top"> |
---|
594 | <td><b><font size="2">ado_mssql</font></b></td> |
---|
595 | <td><font size="2">B</font></td> |
---|
596 | <td><font size="2">Microsoft SQL Server using ADO. Allows DSN-less connections. |
---|
597 | For best performance, use an OLEDB provider.</font></td> |
---|
598 | <td><font size="2">Y/N</font></td> |
---|
599 | <td><font size="2">ADO or OLEDB provider</font></td> |
---|
600 | <td><font size="2">Windows only</font></td> |
---|
601 | </tr> |
---|
602 | <tr valign="top"> |
---|
603 | <td height="54"><b><font size="2">db2</font></b></td> |
---|
604 | <td height="54"><font size="2">C</font></td> |
---|
605 | <td height="54"><font size="2">Uses PHP's db2-specific extension for better performance.</font></td> |
---|
606 | <td height="54"><font size="2">Y/N</font></td> |
---|
607 | <td height="54"><font size="2">DB2 CLI/ODBC interface</font></td> |
---|
608 | <td height="54"> <p><font size="2">Unix and Windows. Requires IBM DB2 Universal Database client.</font></p></td> |
---|
609 | </tr> |
---|
610 | <tr valign="top"> |
---|
611 | <td height="54"><b><font size="2">odbc_db2</font></b></td> |
---|
612 | <td height="54"><font size="2">C</font></td> |
---|
613 | <td height="54"><font size="2">Connects to DB2 using generic ODBC extension.</font></td> |
---|
614 | <td height="54"><font size="2">Y/N</font></td> |
---|
615 | <td height="54"><font size="2">DB2 CLI/ODBC interface</font></td> |
---|
616 | <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 |
---|
617 | 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> |
---|
618 | </tr> |
---|
619 | <tr valign="top"> |
---|
620 | <td><b><font size="2">vfp</font></b></td> |
---|
621 | <td><font size="2">A</font></td> |
---|
622 | <td><font size="2">Microsoft Visual FoxPro. You need to create an ODBC DSN.</font></td> |
---|
623 | <td><font size="2">Y/N</font></td> |
---|
624 | <td><font size="2">ODBC</font></td> |
---|
625 | <td><font size="2">Windows only</font></td> |
---|
626 | </tr> |
---|
627 | <tr valign="top"> |
---|
628 | <td><b><font size="2">fbsql</font></b></td> |
---|
629 | <td><font size="2">C</font></td> |
---|
630 | <td><font size="2">FrontBase. </font></td> |
---|
631 | <td><font size="2">Y</font></td> |
---|
632 | <td><font size="2">?</font></td> |
---|
633 | <td> <p><font size="2">Unix and Windows</font></p></td> |
---|
634 | </tr> |
---|
635 | <tr valign="top"> |
---|
636 | <td><b><font size="2">ibase</font></b></td> |
---|
637 | <td><font size="2">B</font></td> |
---|
638 | <td><font size="2">Interbase 6 or earlier. Some users report you might need |
---|
639 | to use this<br> |
---|
640 | $db->PConnect('localhost:c:/ibase/employee.gdb', "sysdba", "masterkey") |
---|
641 | to connect. Lacks Affected_Rows currently.<br> |
---|
642 | <br> |
---|
643 | You can set $db->role, $db->dialect, $db->buffers and $db->charSet before connecting.</font></td> |
---|
644 | <td><font size="2">Y/N</font></td> |
---|
645 | <td><font size="2">Interbase client</font></td> |
---|
646 | <td><font size="2">Unix and Windows</font></td> |
---|
647 | </tr> |
---|
648 | <tr valign="top"> |
---|
649 | <td><b><i><font size="2">firebird</font></i></b></td> |
---|
650 | <td><font size="2">C</font></td> |
---|
651 | <td><font size="2">Firebird version of interbase.</font></td> |
---|
652 | <td><font size="2">Y/N</font></td> |
---|
653 | <td><font size="2">Interbase client</font></td> |
---|
654 | <td><font size="2">Unix and Windows</font></td> |
---|
655 | </tr> |
---|
656 | <tr valign="top"> |
---|
657 | <td><b><i><font size="2">borland_ibase</font></i></b></td> |
---|
658 | <td><font size="2">C</font></td> |
---|
659 | <td><font size="2">Borland version of Interbase 6.5 or later. Very sad that |
---|
660 | the forks differ.</font></td> |
---|
661 | <td><font size="2">Y/N</font></td> |
---|
662 | <td><font size="2">Interbase client</font></td> |
---|
663 | <td><font size="2">Unix and Windows</font></td> |
---|
664 | </tr> |
---|
665 | |
---|
666 | <tr valign="top"> |
---|
667 | <td><b><font size="2">informix</font></b></td> |
---|
668 | <td><font size="2">C</font></td> |
---|
669 | <td><font size="2">Generic informix driver. Use this if you are using Informix 7.3 or later.</font></td> |
---|
670 | <td><font size="2">Y/N</font></td> |
---|
671 | <td><font size="2">Informix client</font></td> |
---|
672 | <td><font size="2">Unix and Windows</font></td> |
---|
673 | </tr> |
---|
674 | <tr valign="top"> |
---|
675 | <td><b><font size="2">informix72</font></b></td> |
---|
676 | <td><font size="2">C</font></td> |
---|
677 | <td><font size="2"> Informix databases before Informix 7.3 that do no support |
---|
678 | SELECT FIRST.</font></td> |
---|
679 | <td><font size="2">Y/N</font></td> |
---|
680 | <td><font size="2">Informix client</font></td> |
---|
681 | <td><font size="2">Unix and Windows</font></td> |
---|
682 | </tr> |
---|
683 | <tr valign="top"> |
---|
684 | <td><b><font size="2">ldap</font></b></td> |
---|
685 | <td><font size="2">C</font></td> |
---|
686 | <td><font size="2">LDAP driver. See this example for usage information.</font></td> |
---|
687 | <td> </td> |
---|
688 | <td><font size="2">LDAP extension</font></td> |
---|
689 | <td><font size="2">?</font></td> |
---|
690 | </tr> |
---|
691 | <tr valign="top"> |
---|
692 | <td height="73"><b><font size="2">mssql</font></b></td> |
---|
693 | <td height="73"><font size="2">A</font></td> |
---|
694 | <td height="73"> <p><font size="2">Microsoft SQL Server 7 and later. Works |
---|
695 | with Microsoft SQL Server 2000 also. Note that date formating is problematic |
---|
696 | with this driver. For example, the PHP mssql extension does not return |
---|
697 | the seconds for datetime!</font></p></td> |
---|
698 | <td height="73"><font size="2">Y/N</font></td> |
---|
699 | <td height="73"><font size="2">Mssql client</font></td> |
---|
700 | <td height="73"> <p><font size="2">Unix and Windows. <br> |
---|
701 | <a href="http://phpbuilder.com/columns/alberto20000919.php3">Unix install |
---|
702 | howto</a> and <a href="http://linuxjournal.com/article.php?sid=6636&mode=thread&order=0">another |
---|
703 | one</a>. </font></p></td> |
---|
704 | </tr> |
---|
705 | <tr valign="top"> |
---|
706 | <td height="73"><b><font size="2">mssqlpo</font></b></td> |
---|
707 | <td height="73"><font size="2">A</font></td> |
---|
708 | <td height="73"> <p><font size="2">Portable mssql driver. Identical to above |
---|
709 | mssql driver, except that '||', the concatenation operator, is converted |
---|
710 | to '+'. Useful for porting scripts from most other sql variants that use |
---|
711 | ||.</font></p></td> |
---|
712 | <td height="73"><font size="2">Y/N</font></td> |
---|
713 | <td height="73"><font size="2">Mssql client</font></td> |
---|
714 | <td height="73"> <p><font size="2">Unix and Windows. <a href="http://phpbuilder.com/columns/alberto20000919.php3"><br> |
---|
715 | Unix install howto</a>.</font></p></td> |
---|
716 | </tr> |
---|
717 | <tr valign="top"> |
---|
718 | <td><b><font size="2">mysql</font></b></td> |
---|
719 | <td><font size="2">A</font></td> |
---|
720 | <td><font size="2">MySQL without transaction support. You can also set $db->clientFlags |
---|
721 | before connecting.</font></td> |
---|
722 | <td><font size="2">Y</font></td> |
---|
723 | <td><font size="2">MySQL client</font></td> |
---|
724 | <td><font size="2">Unix and Windows</font></td> |
---|
725 | </tr> |
---|
726 | <tr valign="top"> |
---|
727 | <td><font size="2"><b>mysqlt</b> or <b>maxsql</b></font></td> |
---|
728 | <td><font size="2">A</font></td> |
---|
729 | <td> <p><font size="2">MySQL with transaction support. We recommend using |
---|
730 | || as the concat operator for best portability. This can be done by running |
---|
731 | MySQL using: <br> |
---|
732 | <i>mysqld --ansi</i> or <i>mysqld --sql-mode=PIPES_AS_CONCAT</i></font></p></td> |
---|
733 | <td><font size="2">Y/N</font></td> |
---|
734 | <td><font size="2">MySQL client</font></td> |
---|
735 | <td><font size="2">Unix and Windows</font></td> |
---|
736 | </tr> |
---|
737 | <tr valign="top"> |
---|
738 | <td><b><font size="2">oci8</font></b></td> |
---|
739 | <td><font size="2">A</font></td> |
---|
740 | <td><font size="2">Oracle 8/9. Has more functionality than <i>oracle</i> driver |
---|
741 | (eg. Affected_Rows). You might have to putenv('ORACLE_HOME=...') before |
---|
742 | Connect/PConnect. </font> <p><font size="2"> There are 2 ways of connecting |
---|
743 | - with server IP and service name: <br> |
---|
744 | <i>PConnect('serverip:1521','scott','tiger','service'</i>)<br> |
---|
745 | or using an entry in TNSNAMES.ORA or ONAMES or HOSTNAMES: <br> |
---|
746 | <i>PConnect(false, 'scott', 'tiger', $oraname)</i>. </font> |
---|
747 | </p><p><font size="2">Since 2.31, we support Oracle REF cursor variables directly |
---|
748 | (see <a href="#executecursor">ExecuteCursor</a>).</font> </p></td> |
---|
749 | <td><font size="2">Y/N</font></td> |
---|
750 | <td><font size="2">Oracle client</font></td> |
---|
751 | <td><font size="2">Unix and Windows</font></td> |
---|
752 | </tr> |
---|
753 | <tr valign="top"> |
---|
754 | <td><b><font size="2">oci805</font></b></td> |
---|
755 | <td><font size="2">C</font></td> |
---|
756 | <td><font size="2">Supports reduced Oracle functionality for Oracle 8.0.5. |
---|
757 | SelectLimit is not as efficient as in the oci8 or oci8po drivers.</font></td> |
---|
758 | <td><font size="2">Y/N</font></td> |
---|
759 | <td><font size="2">Oracle client</font></td> |
---|
760 | <td><font size="2">Unix and Windows</font></td> |
---|
761 | </tr> |
---|
762 | <tr valign="top"> |
---|
763 | <td><b><font size="2">oci8po</font></b></td> |
---|
764 | <td><font size="2">A</font></td> |
---|
765 | <td><font size="2">Oracle 8/9 portable driver. This is nearly identical with |
---|
766 | the oci8 driver except (a) bind variables in Prepare() use the ? convention, |
---|
767 | instead of :bindvar, (b) field names use the more common PHP convention |
---|
768 | of lowercase names. </font> <p><font size="2">Use this driver if porting |
---|
769 | from other databases is important. Otherwise the oci8 driver offers better |
---|
770 | performance. </font> </p></td> |
---|
771 | <td><font size="2">Y/N</font></td> |
---|
772 | <td><font size="2">Oracle client</font></td> |
---|
773 | <td><font size="2">Unix and Windows</font></td> |
---|
774 | </tr> |
---|
775 | <tr valign="top"> |
---|
776 | <td><b><font size="2">odbc</font></b></td> |
---|
777 | <td><font size="2">A</font></td> |
---|
778 | <td><font size="2">Generic ODBC, not tuned for specific databases. To connect, |
---|
779 | use <br> |
---|
780 | PConnect('DSN','user','pwd'). This is the base class for all odbc derived |
---|
781 | drivers.</font></td> |
---|
782 | <td><font size="2">? depends on database</font></td> |
---|
783 | <td><font size="2">ODBC</font></td> |
---|
784 | <td><font size="2">Unix and Windows. <a href="http://phpbuilder.com/columns/alberto20000919.php3?page=4">Unix |
---|
785 | hints.</a></font></td> |
---|
786 | </tr> |
---|
787 | <tr valign="top"> |
---|
788 | <td><b><font size="2">odbc_mssql</font></b></td> |
---|
789 | <td><font size="2">C</font></td> |
---|
790 | <td><font size="2">Uses ODBC to connect to MSSQL</font></td> |
---|
791 | <td><font size="2">Y/N</font></td> |
---|
792 | <td><font size="2">ODBC</font></td> |
---|
793 | <td><font size="2">Unix and Windows. </font></td> |
---|
794 | </tr> |
---|
795 | <tr valign="top"> |
---|
796 | <td><b><font size="2">odbc_oracle</font></b></td> |
---|
797 | <td><font size="2">C</font></td> |
---|
798 | <td><font size="2">Uses ODBC to connect to Oracle</font></td> |
---|
799 | <td><font size="2">Y/N</font></td> |
---|
800 | <td><font size="2">ODBC</font></td> |
---|
801 | <td><font size="2">Unix and Windows. </font></td> |
---|
802 | </tr> |
---|
803 | |
---|
804 | <tr valign="top"> |
---|
805 | <td><b><font size="2">odbtp</font></b></td> |
---|
806 | <td><font size="2">C</font></td> |
---|
807 | <td><font size="2">Generic odbtp driver. <a href="http://odbtp.sourceforge.net/">Odbtp</a> is a software for |
---|
808 | accessing Windows ODBC data sources from other operating systems.</font></td> |
---|
809 | <td><font size="2">Y/N</font></td> |
---|
810 | <td><font size="2">odbtp</font></td> |
---|
811 | <td><font size="2">Unix and Windows</font></td> |
---|
812 | </tr> |
---|
813 | <tr valign="top"> |
---|
814 | <td><b><font size="2">odbtp_unicode</font></b></td> |
---|
815 | <td><font size="2">C</font></td> |
---|
816 | <td><font size="2">Odtbp with unicode support</font></td> |
---|
817 | <td><font size="2">Y/N</font></td> |
---|
818 | <td><font size="2">odbtp</font></td> |
---|
819 | <td><font size="2">Unix and Windows</font></td> |
---|
820 | </tr> |
---|
821 | <tr valign="top"> |
---|
822 | <td height="34"><b><font size="2">oracle</font></b></td> |
---|
823 | <td height="34"><font size="2">C</font></td> |
---|
824 | <td height="34"><font size="2">Implements old Oracle 7 client API. Use oci8 |
---|
825 | driver if possible for better performance.</font></td> |
---|
826 | <td height="34"><font size="2">Y/N</font></td> |
---|
827 | <td height="34"><font size="2">Oracle client</font></td> |
---|
828 | <td height="34"><font size="2">Unix and Windows</font></td> |
---|
829 | </tr> |
---|
830 | <tr valign="top"> |
---|
831 | <td height="34"><b><font size="2">netezza</font></b></td> |
---|
832 | <td height="34"><font size="2">C</font></td> |
---|
833 | <td height="34"><font size="2">Netezza driver. Netezza is based on postgres code-base.</font></td> |
---|
834 | <td height="34"><font size="2">Y</font></td> |
---|
835 | <td height="34"><font size="2">?</font></td> |
---|
836 | <td height="34"><font size="2">?</font></td> |
---|
837 | </tr> |
---|
838 | <tr valign="top"> |
---|
839 | <td><b><font size="2">pdo</font></b></td> |
---|
840 | <td><font size="2">C</font></td> |
---|
841 | <td><font size="2">Generic PDO driver for PHP5. </font></td> |
---|
842 | <td><font size="2">Y</font></td> |
---|
843 | <td><font size="2">PDO extension and database specific drivers</font></td> |
---|
844 | <td><font size="2">Unix and Windows. </font></td> |
---|
845 | </tr> |
---|
846 | <tr valign="top"> |
---|
847 | <td><b><font size="2">postgres</font></b></td> |
---|
848 | <td><font size="2">A</font></td> |
---|
849 | <td><font size="2">Generic PostgreSQL driver. Currently identical to postgres7 |
---|
850 | driver.</font></td> |
---|
851 | <td><font size="2">Y</font></td> |
---|
852 | <td><font size="2">PostgreSQL client</font></td> |
---|
853 | <td><font size="2">Unix and Windows. </font></td> |
---|
854 | </tr> |
---|
855 | <tr valign="top"> |
---|
856 | <td><b><font size="2">postgres64</font></b></td> |
---|
857 | <td><font size="2">A</font></td> |
---|
858 | <td><font size="2">For PostgreSQL 6.4 and earlier which does not support LIMIT |
---|
859 | internally.</font></td> |
---|
860 | <td><font size="2">Y</font></td> |
---|
861 | <td><font size="2">PostgreSQL client</font></td> |
---|
862 | <td><font size="2">Unix and Windows. </font></td> |
---|
863 | </tr> |
---|
864 | <tr valign="top"> |
---|
865 | <td><b><font size="2">postgres7</font></b></td> |
---|
866 | <td><font size="2">A</font></td> |
---|
867 | <td><font size="2">PostgreSQL which supports LIMIT and other version 7 functionality.</font></td> |
---|
868 | <td><font size="2">Y</font></td> |
---|
869 | <td><font size="2">PostgreSQL client</font></td> |
---|
870 | <td><font size="2">Unix and Windows. </font></td> |
---|
871 | </tr> |
---|
872 | <tr valign="top"> |
---|
873 | <td><b><font size="2">postgres8</font></b></td> |
---|
874 | <td><font size="2">A</font></td> |
---|
875 | <td><font size="2">PostgreSQL which supports version 8 functionality.</font></td> |
---|
876 | <td><font size="2">Y</font></td> |
---|
877 | <td><font size="2">PostgreSQL client</font></td> |
---|
878 | <td><font size="2">Unix and Windows. </font></td> |
---|
879 | </tr> |
---|
880 | <tr valign="top"> |
---|
881 | <td><b><font size="2">sapdb</font></b></td> |
---|
882 | <td><font size="2">C</font></td> |
---|
883 | <td><font size="2">SAP DB. Should work reliably as based on ODBC driver.</font></td> |
---|
884 | <td><font size="2">Y/N</font></td> |
---|
885 | <td><font size="2">SAP ODBC client</font></td> |
---|
886 | <td> <p><font size="2">?</font></p></td> |
---|
887 | </tr> |
---|
888 | <tr valign="top"> |
---|
889 | <td><b><font size="2">sqlanywhere</font></b></td> |
---|
890 | <td><font size="2">C</font></td> |
---|
891 | <td><font size="2">Sybase SQL Anywhere. Should work reliably as based on ODBC |
---|
892 | driver.</font></td> |
---|
893 | <td><font size="2">Y/N</font></td> |
---|
894 | <td><font size="2">SQL Anywhere ODBC client</font></td> |
---|
895 | <td> <p><font size="2">?</font></p></td> |
---|
896 | </tr> |
---|
897 | <tr valign="top"> |
---|
898 | <td height="54"><b><font size="2">sqlite</font></b></td> |
---|
899 | <td height="54"><font size="2">B</font></td> |
---|
900 | <td height="54"><font size="2">SQLite.</font></td> |
---|
901 | <td height="54"><font size="2">Y</font></td> |
---|
902 | <td height="54"><font size="2">-</font></td> |
---|
903 | <td height="54"> <p><font size="2">Unix and Windows.</font></p></td> |
---|
904 | </tr> |
---|
905 | <tr valign="top"> |
---|
906 | <td height="54"><b><font size="2">sqlitepo</font></b></td> |
---|
907 | <td height="54"><font size="2">B</font></td> |
---|
908 | <td height="54"><font size="2">Portable SQLite driver. This is because assoc mode does not work like other drivers in sqlite. |
---|
909 | Namely, when selecting (joining) multiple tables, the table |
---|
910 | names are included in the assoc keys in the "sqlite" driver.</font><p> |
---|
911 | <font size="2"> In "sqlitepo" driver, the table names are stripped from the returned column names. |
---|
912 | When this results in a conflict, the first field get preference. |
---|
913 | </font></p></td> |
---|
914 | <td height="54"><font size="2">Y</font></td> |
---|
915 | <td height="54"><font size="2">-</font></td> |
---|
916 | <td height="54"> <p><font size="2">Unix and Windows.</font></p></td> |
---|
917 | </tr> |
---|
918 | |
---|
919 | |
---|
920 | <tr valign="top"> |
---|
921 | <td><b><font size="2">sybase</font></b></td> |
---|
922 | <td><font size="2">C</font></td> |
---|
923 | <td><font size="2">Sybase. </font></td> |
---|
924 | <td><font size="2">Y/N</font></td> |
---|
925 | <td><font size="2">Sybase client</font></td> |
---|
926 | <td> <p><font size="2">Unix and Windows.</font></p></td> |
---|
927 | </tr> |
---|
928 | |
---|
929 | <tr valign="top"> |
---|
930 | <td><b><font size="2">sybase_ase</font></b></td> |
---|
931 | <td><font size="2">C</font></td> |
---|
932 | <td><font size="2">Sybase ASE. </font></td> |
---|
933 | <td><font size="2">Y/N</font></td> |
---|
934 | <td><font size="2">Sybase client</font></td> |
---|
935 | <td> <p><font size="2">Unix and Windows.</font></p></td> |
---|
936 | </tr> |
---|
937 | </tbody></table> |
---|
938 | |
---|
939 | <p></p><p>The "Tested" column indicates how extensively the code has been tested |
---|
940 | and used. <br> |
---|
941 | A = well tested and used by many people<br> |
---|
942 | B = tested and usable, but some features might not be implemented<br> |
---|
943 | C = user contributed or experimental driver. Might not fully support all of |
---|
944 | the latest features of ADOdb. </p> |
---|
945 | <p>The column "RecordCount() usable" indicates whether RecordCount() |
---|
946 | return the number of rows, or returns -1 when a SELECT statement is executed. |
---|
947 | If this column displays Y/N then the RecordCount() is emulated when the global |
---|
948 | variable $ADODB_COUNTRECS=true (this is the default). Note that for large recordsets, |
---|
949 | it might be better to disable RecordCount() emulation because substantial amounts |
---|
950 | of memory are required to cache the recordset for counting. Also there is a |
---|
951 | speed penalty of 40-50% if emulation is required. This is emulated in most databases |
---|
952 | except for PostgreSQL and MySQL. This variable is checked every time a query |
---|
953 | is executed, so you can selectively choose which recordsets to count.</p> |
---|
954 | <p> |
---|
955 | </p><hr /> |
---|
956 | <h1>Tutorials<a name="quickstart"></a></h1> |
---|
957 | <h3>Example 1: Select Statement<a name="ex1"></a></h3> |
---|
958 | <p>Task: Connect to the Access Northwind DSN, display the first 2 columns of each |
---|
959 | row.</p> |
---|
960 | <p>In this example, we create a ADOConnection object, which represents the connection |
---|
961 | to the database. The connection is initiated with <a href="#pconnect"><font face="Courier New, Courier, mono">PConnect</font></a>, |
---|
962 | which is a persistent connection. Whenever we want to query the database, we |
---|
963 | call the <font face="Courier New, Courier, mono">ADOConnection.<a href="#execute">Execute</a>()</font> |
---|
964 | function. This returns an ADORecordSet object which is actually a cursor that |
---|
965 | holds the current row in the array <font face="Courier New, Courier, mono">fields[]</font>. |
---|
966 | We use <font face="Courier New, Courier, mono"><a href="#movenext">MoveNext</a>()</font> |
---|
967 | to move from row to row.</p> |
---|
968 | <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>, |
---|
969 | which allows us to limit the number of rows shown. |
---|
970 | </p><pre><?<br><font face="Courier New, Courier, mono"><b>include</b>('adodb.inc.php'); # load code common to ADOdb<br>$<font color="#660000">conn</font> = &ADONewConnection('access'); # create a connection<br>$<font color="#660000">conn</font>->PConnect('northwind'); # connect to MS-Access, northwind DSN<br>$<font color="#660000">recordSet</font> = &$<font color="#660000">conn</font>->Execute('select * from products');<br>if (!$<font color="#660000">recordSet</font>) <br> print $<font color="#660000">conn</font>->ErrorMsg();<br>else<br><b>while</b> (!$<font color="#660000">recordSet</font>->EOF) {<br> <b>print</b> $<font color="#660000">recordSet</font>->fields[0].' '.$<font color="#660000">recordSet</font>->fields[1].'<BR>';<br> $<font color="#660000">recordSet</font>->MoveNext();<br>}</font><font face="Courier New, Courier, mono"> |
---|
971 | |
---|
972 | $<font color="#660000">recordSet</font>->Close(); # optional<br>$<font color="#660000">conn</font>->Close(); # optional<br></font> |
---|
973 | ?> |
---|
974 | </pre> |
---|
975 | <p>The $<font face="Courier New, Courier, mono">recordSet</font> returned stores |
---|
976 | the current row in the <font face="Courier New, Courier, mono">$recordSet->fields</font> |
---|
977 | array, indexed by column number (starting from zero). We use the <font face="Courier New, Courier, mono"><a href="#movenext">MoveNext</a>()</font> |
---|
978 | function to move to the next row. The <font face="Courier New, Courier, mono">EOF</font> |
---|
979 | property is set to true when end-of-file is reached. If an error occurs in Execute(), |
---|
980 | we return false instead of a recordset.</p> |
---|
981 | <p>The <code>$recordSet->fields[]</code> array is generated by the PHP database |
---|
982 | extension. Some database extensions only index by number and do not index the |
---|
983 | array by field name. To force indexing by name - that is associative arrays |
---|
984 | - use the SetFetchMode function. Each recordset saves and uses whatever fetch |
---|
985 | mode was set when the recordset was created in Execute() or SelectLimit(). |
---|
986 | </p><pre> $db->SetFetchMode(ADODB_FETCH_NUM);<br> $rs1 = $db->Execute('select * from table');<br> $db->SetFetchMode(ADODB_FETCH_ASSOC);<br> $rs2 = $db->Execute('select * from table');<br> print_r($rs1->fields); # shows <i>array([0]=>'v0',[1] =>'v1')</i> |
---|
987 | print_r($rs2->fields); # shows <i>array(['col1']=>'v0',['col2'] =>'v1')</i> |
---|
988 | </pre> |
---|
989 | <p> </p> |
---|
990 | <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>. |
---|
991 | Note that it can return -1 if the number of rows returned cannot be determined.</p> |
---|
992 | <h3>Example 2: Advanced Select with Field Objects<a name="ex2"></a></h3> |
---|
993 | <p>Select a table, display the first two columns. If the second column is a date |
---|
994 | or timestamp, reformat the date to US format.</p> |
---|
995 | <pre><?<br><font face="Courier New, Courier, mono"><b>include</b>('adodb.inc.php'); # load code common to ADOdb<br>$<font color="#660000">conn</font> = &ADONewConnection('access'); # create a connection<br>$<font color="#660000">conn</font>->PConnect('northwind'); # connect to MS-Access, northwind dsn<br>$<font color="#660000">recordSet</font> = &$<font color="#660000">conn</font>->Execute('select CustomerID,OrderDate from Orders');<br>if (!$<font color="#660000">recordSet</font>) <br> print $<font color="#660000">conn</font>->ErrorMsg();<br>else<br><b>while</b> (!$<font color="#660000">recordSet</font>->EOF) {<br> $<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> |
---|
996 | $<font color="#660000">type</font> = <font color="#336600"><b>$</b><font color="#660000">recordSet</font><b>->MetaType</b></font>($fld->type);<br><br> <b>if</b> ( $<font color="#660000">type</font> == 'D' || $<font color="#660000">type</font> == 'T') <br> <b>print</b> $<font color="#660000">recordSet</font>->fields[0].' '.<br> <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>';<br> <b>else </b> |
---|
997 | <b>print</b> $<font color="#660000">recordSet</font>->fields[0].' '.$<font color="#660000">recordSet</font>->fields[1].'<BR>';<br><br> $<font color="#660000">recordSet</font>->MoveNext();<br>}</font><font face="Courier New, Courier, mono"> |
---|
998 | $<font color="#660000">recordSet</font>->Close(); # optional<br>$<font color="#660000">conn</font>->Close(); # optional<br></font> |
---|
999 | ?> |
---|
1000 | </pre> |
---|
1001 | <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> |
---|
1002 | This returns an object with at least 3 fields.</p> |
---|
1003 | <ul> |
---|
1004 | <li><b>name</b>: name of column</li> |
---|
1005 | <li> <b>type</b>: native field type of column</li> |
---|
1006 | <li> <b>max_length</b>: maximum length of field. Some databases such as MySQL |
---|
1007 | do not return the maximum length of the field correctly. In these cases max_length |
---|
1008 | will be set to -1.</li> |
---|
1009 | </ul> |
---|
1010 | <p>We then use <font face="Courier New, Courier, mono"><a href="#metatype">MetaType</a>()</font> |
---|
1011 | to translate the native type to a <i>generic</i> type. Currently the following |
---|
1012 | <i>generic</i> types are defined:</p> |
---|
1013 | <ul> |
---|
1014 | <li><b>C</b>: character fields that should be shown in a <input type="text"> |
---|
1015 | tag.</li> |
---|
1016 | <li><b>X</b>: TeXt, large text fields that should be shown in a <textarea></li> |
---|
1017 | <li><b>B</b>: Blobs, or Binary Large Objects. Typically images. |
---|
1018 | </li><li><b>D</b>: Date field</li> |
---|
1019 | <li><b>T</b>: Timestamp field</li> |
---|
1020 | <li><b>L</b>: Logical field (boolean or bit-field)</li> |
---|
1021 | <li><b>I</b>: Integer field</li> |
---|
1022 | <li><b>N</b>: Numeric field. Includes autoincrement, numeric, floating point, |
---|
1023 | real and integer. </li> |
---|
1024 | <li><b>R</b>: Serial field. Includes serial, autoincrement integers. This works |
---|
1025 | for selected databases. </li> |
---|
1026 | </ul> |
---|
1027 | <p>If the metatype is of type date or timestamp, then we print it using the user |
---|
1028 | defined date format with <font face="Courier New, Courier, mono"><a href="#userdate">UserDate</a>(),</font> |
---|
1029 | which converts the PHP SQL date string format to a user defined one. Another |
---|
1030 | use for <font face="Courier New, Courier, mono"><a href="#metatype">MetaType</a>()</font> |
---|
1031 | is data validation before doing an SQL insert or update.</p> |
---|
1032 | <h3>Example 3: Inserting<a name="ex3"></a></h3> |
---|
1033 | <p>Insert a row to the Orders table containing dates and strings that need to |
---|
1034 | be quoted before they can be accepted by the database, eg: the single-quote |
---|
1035 | in the word <i>John's</i>.</p> |
---|
1036 | <pre><?<br><b>include</b>('adodb.inc.php'); # load code common to ADOdb<br>$<font color="#660000">conn</font> = &ADONewConnection('access'); # create a connection<br><br>$<font color="#660000">conn</font>->PConnect('northwind'); # connect to MS-Access, northwind dsn<br>$<font color="#660000">shipto</font> = <font color="#006600"><b>$conn->qstr</b></font>("<i>John's Old Shoppe</i>");<br><br>$<font color="#660000">sql</font> = "insert into orders (customerID,EmployeeID,OrderDate,ShipName) ";<br>$<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>)";<br><br><b>if</b> ($<font color="#660000">conn</font>->Execute($<font color="#660000">sql</font>) <font color="#336600"><b>=== false</b></font>) {<br> <b>print</b> 'error inserting: '.<font color="#336600"><b>$conn->ErrorMsg()</b></font>.'<BR>';<br>}<br>?><br></pre> |
---|
1037 | <p>In this example, we see the advanced date and quote handling facilities of |
---|
1038 | ADOdb. The unix timestamp (which is a long integer) is appropriately formated |
---|
1039 | for Access with <font face="Courier New, Courier, mono"><a href="#dbdate">DBDate</a>()</font>, |
---|
1040 | and the right escape character is used for quoting the <i>John's Old Shoppe</i>, |
---|
1041 | which is<b> </b><i>John'<b>'</b>s Old Shoppe</i> and not PHP's default <i>John<b>'</b>s |
---|
1042 | Old Shoppe</i> with <font face="Courier New, Courier, mono"><a href="#qstr">qstr</a>()</font>. |
---|
1043 | </p> |
---|
1044 | <p>Observe the error-handling of the Execute statement. False is returned by<font face="Courier New, Courier, mono"> |
---|
1045 | <a href="#execute">Execute</a>() </font>if an error occured. The error message |
---|
1046 | for the last error that occurred is displayed in <font face="Courier New, Courier, mono"><a href="#errormsg">ErrorMsg</a>()</font>. |
---|
1047 | Note: <i>php_track_errors</i> might have to be enabled for error messages to |
---|
1048 | be saved.</p> |
---|
1049 | <h3> Example 4: Debugging<a name="ex4"></a></h3> |
---|
1050 | <pre><?<br><b>include</b>('adodb.inc.php'); # load code common to ADOdb<br>$<font color="#663300">conn</font> = &ADONewConnection('access'); # create a connection<br>$<font color="#663300">conn</font>->PConnect('northwind'); # connect to MS-Access, northwind dsn<br><font>$<font color="#663300">shipto</font> = <b>$conn->qstr</b>("John's Old Shoppe");<br>$<font color="#663300">sql</font> = "insert into orders (customerID,EmployeeID,OrderDate,ShipName) ";<br>$<font color="#663300">sql</font> .= "values ('ANATR',2,".$<font color="#663300">conn</font>->FormatDate(time()).",$shipto)";<br><b><font color="#336600">$<font color="#663300">conn</font>->debug = true;</font></b> |
---|
1051 | <b>if</b> ($<font color="#663300">conn</font>->Execute($sql) <b>=== false</b>) <b>print</b> 'error inserting';</font> |
---|
1052 | ?> |
---|
1053 | </pre> |
---|
1054 | <p>In the above example, we have turned on debugging by setting <b>debug = true</b>. |
---|
1055 | This will display the SQL statement before execution, and also show any error |
---|
1056 | messages. There is no need to call <font face="Courier New, Courier, mono"><a href="#errormsg">ErrorMsg</a>()</font> |
---|
1057 | in this case. For displaying the recordset, see the <font face="Courier New, Courier, mono"><a href="#exrs2html">rs2html</a>() |
---|
1058 | </font>example.</p> |
---|
1059 | <p>Also see the section on <a href="#errorhandling">Custom Error Handlers</a>.</p> |
---|
1060 | <h3>Example 5: MySQL and Menus<a name="ex5"></a></h3> |
---|
1061 | <p>Connect to MySQL database <i>agora</i>, and generate a <select> menu |
---|
1062 | from an SQL statement where the <option> captions are in the 1st column, |
---|
1063 | and the value to send back to the server is in the 2nd column.</p> |
---|
1064 | <pre><?<br><b>include</b>('adodb.inc.php'); # load code common to ADOdb<br>$<font color="#663300">conn</font> = &ADONewConnection('mysql'); # create a connection<br>$<font color="#663300">conn</font>->PConnect('localhost','userid','','agora');# connect to MySQL, agora db<br><font>$<font color="#663300">sql</font> = 'select CustomerName, CustomerID from customers';<br>$<font color="#663300">rs</font> = $<font color="#663300">conn</font>->Execute($sql);<br><b>print</b> <b><font color="#336600">$<font color="#663300">rs</font>->GetMenu('GetCust','Mary Rosli');<br>?></font></b></font></pre> |
---|
1065 | <p>Here we define a menu named GetCust, with the menu option 'Mary Rosli' selected. |
---|
1066 | See <a href="#getmenu"><font face="Courier New, Courier, mono">GetMenu</font></a><font face="Courier New, Courier, mono">()</font>. |
---|
1067 | We also have functions that return the recordset as an array: <font face="Courier New, Courier, mono"><a href="#getarray">GetArray</a>()</font>, |
---|
1068 | and as an associative array with the key being the first column: <a href="#getassoc1">GetAssoc</a>().</p> |
---|
1069 | <h3>Example 6: Connecting to 2 Databases At Once<a name="ex6"></a></h3> |
---|
1070 | <pre><?<br><b>include</b>('adodb.inc.php'); # load code common to ADOdb<br>$<font color="#663300">conn1</font> = &ADONewConnection('mysql'); # create a mysql connection<br>$<font color="#663300">conn2</font> = &ADONewConnection('oracle'); # create a oracle connection<br><br>$conn1->PConnect($server, $userid, $password, $database);<br>$conn2->PConnect(false, $ora_userid, $ora_pwd, $oraname);<br><br>$conn1->Execute('insert ...');<br>$conn2->Execute('update ...');<br>?></pre> |
---|
1071 | <p> |
---|
1072 | </p><h3>Example 7: Generating Update and Insert SQL<a name="ex7"></a></h3> |
---|
1073 | <p>Since ADOdb 4.56, we support <a href="reference.functions.getupdatesql.html#autoexecute">AutoExecute()</a>, |
---|
1074 | which simplifies things by providing an advanced wrapper for GetInsertSQL() and GetUpdateSQL(). For example, |
---|
1075 | an INSERT can be carried out with: |
---|
1076 | |
---|
1077 | <pre> |
---|
1078 | $record["firstname"] = "Bob"; |
---|
1079 | $record["lastname"] = "Smith"; |
---|
1080 | $record["created"] = time(); |
---|
1081 | $insertSQL = $conn->AutoExecute($rs, $record, 'INSERT'); |
---|
1082 | </pre> |
---|
1083 | |
---|
1084 | and an UPDATE with: |
---|
1085 | <pre> |
---|
1086 | $record["firstname"] = "Caroline"; |
---|
1087 | $record["lastname"] = "Smith"; # Update Caroline's lastname from Miranda to Smith |
---|
1088 | $insertSQL = $conn->AutoExecute($rs, $record, 'UPDATE', 'id = 1'); |
---|
1089 | </pre> |
---|
1090 | <p> |
---|
1091 | The rest of this section is out-of-date: |
---|
1092 | <p>ADOdb 1.31 and later supports two new recordset functions: GetUpdateSQL( ) and |
---|
1093 | GetInsertSQL( ). This allow you to perform a "SELECT * FROM table query WHERE...", |
---|
1094 | make a copy of the $rs->fields, modify the fields, and then generate the SQL to |
---|
1095 | update or insert into the table automatically. |
---|
1096 | <p> We show how the functions can be used when accessing a table with the following |
---|
1097 | fields: (ID, FirstName, LastName, Created). |
---|
1098 | </p><p> Before these functions can be called, you need to initialize the recordset |
---|
1099 | by performing a select on the table. Idea and code by Jonathan Younger jyounger#unilab.com. |
---|
1100 | Since ADOdb 2.42, you can pass a table name instead of a recordset into |
---|
1101 | GetInsertSQL (in $rs), and it will generate an insert statement for that table. |
---|
1102 | </p><p> |
---|
1103 | </p><pre><?<br>#==============================================<br># SAMPLE GetUpdateSQL() and GetInsertSQL() code<br>#==============================================<br>include('adodb.inc.php');<br>include('tohtml.inc.php');<br><br>#==========================<br># This code tests an insert<br><br>$sql = "SELECT * FROM ADOXYZ WHERE id = -1"; <br># Select an empty record from the database<br><br>$conn = &ADONewConnection("mysql"); # create a connection<br>$conn->debug=1;<br>$conn->PConnect("localhost", "admin", "", "test"); # connect to MySQL, testdb<br>$rs = $conn->Execute($sql); # Execute the query and get the empty recordset<br><br>$record = array(); # Initialize an array to hold the record data to insert<br><br># Set the values for the fields in the record<br># Note that field names are case-insensitive<br>$record["firstname"] = "Bob";<br>$record["lastNamE"] = "Smith";<br>$record["creaTed"] = time();<br><br># Pass the empty recordset and the array containing the data to insert<br># into the GetInsertSQL function. The function will process the data and return<br># a fully formatted insert sql statement.<br>$insertSQL = $conn->GetInsertSQL($rs, $record);<br><br>$conn->Execute($insertSQL); # Insert the record into the database<br><br>#==========================<br># This code tests an update<br><br>$sql = "SELECT * FROM ADOXYZ WHERE id = 1"; <br># Select a record to update<br><br>$rs = $conn->Execute($sql); # Execute the query and get the existing record to update<br><br>$record = array(); # Initialize an array to hold the record data to update<br><br># Set the values for the fields in the record<br># Note that field names are case-insensitive<br>$record["firstname"] = "Caroline";<br>$record["LasTnAme"] = "Smith"; # Update Caroline's lastname from Miranda to Smith<br><br># Pass the single record recordset and the array containing the data to update<br># into the GetUpdateSQL function. The function will process the data and return<br># a fully formatted update sql statement with the correct WHERE clause.<br># If the data has not changed, no recordset is returned<br>$updateSQL = $conn->GetUpdateSQL($rs, $record);<br><br>$conn->Execute($updateSQL); # Update the record in the database<br>$conn->Close();<br>?><br></pre> |
---|
1104 | <a name="ADODB_FORCE_TYPE"></a> |
---|
1105 | <b>$ADODB_FORCE_TYPE</b><p> |
---|
1106 | The behaviour of AutoExecute(), GetUpdateSQL() and GetInsertSQL() |
---|
1107 | when converting empty or null PHP variables to SQL is controlled by the |
---|
1108 | global $ADODB_FORCE_TYPE variable. Set it to one of the values below. Default |
---|
1109 | is ADODB_FORCE_VALUE (3): |
---|
1110 | </p><pre>0 = ignore empty fields. All empty fields in array are ignored.<br>1 = force null. All empty, php null and string 'null' fields are changed to sql NULL values.<br>2 = force empty. All empty, php null and string 'null' fields are changed to sql empty '' or 0 values.<br>3 = force value. Value is left as it is. Php null and string 'null' are set to sql NULL values and <br> empty fields '' are set to empty '' sql values.<br><br>define('ADODB_FORCE_IGNORE',0);<br>define('ADODB_FORCE_NULL',1);<br>define('ADODB_FORCE_EMPTY',2);<br>define('ADODB_FORCE_VALUE',3);<br></pre> |
---|
1111 | <p> |
---|
1112 | Thanks to Niko (nuko#mbnet.fi) for the $ADODB_FORCE_TYPE code. |
---|
1113 | </p><p> |
---|
1114 | Note: the constant ADODB_FORCE_NULLS is obsolete since 4.52 and is ignored. Set $ADODB_FORCE_TYPE = ADODB_FORCE_NULL |
---|
1115 | for equivalent behaviour. |
---|
1116 | <p>Since 4.62, the table name to be used can be overridden by setting $rs->tableName before AutoExecute(), GetInsertSQL() or GetUpdateSQL() is called. |
---|
1117 | </p><h3>Example 8: Implementing Scrolling with Next and Previous<a name="ex8"></a></h3> |
---|
1118 | <p> The following code creates a very simple recordset pager, where you can scroll |
---|
1119 | from page to page of a recordset.</p> |
---|
1120 | <pre>include_once('../adodb.inc.php');<br>include_once('../adodb-pager.inc.php');<br>session_start();<br><br>$db = NewADOConnection('mysql');<br><br>$db->Connect('localhost','root','','xphplens');<br><br>$sql = "select * from adoxyz ";<br><br>$pager = new ADODB_Pager($db,$sql);<br>$pager->Render($rows_per_page=5);</pre> |
---|
1121 | <p>This will create a basic record pager that looks like this: <a name="scr"></a> |
---|
1122 | </p><p> |
---|
1123 | <table bgcolor="beige" border="1"> |
---|
1124 | <tbody><tr> |
---|
1125 | <td> <a href="#scr"><code>|<</code></a> <a href="#scr"><code><<</code></a> |
---|
1126 | <a href="#scr"><code>>></code></a> <a href="#scr"><code>>|</code></a> |
---|
1127 | </td> |
---|
1128 | </tr> |
---|
1129 | <tr> |
---|
1130 | <td><table bgcolor="white" border="1" cols="4" width="100%"> |
---|
1131 | <tbody><tr><th>ID</th> |
---|
1132 | <th>First Name</th> |
---|
1133 | <th>Last Name</th> |
---|
1134 | <th>Date Created</th> |
---|
1135 | </tr><tr> |
---|
1136 | <td align="right">36 </td> |
---|
1137 | <td>Alan </td> |
---|
1138 | <td>Turing </td> |
---|
1139 | <td>Sat 06, Oct 2001 </td> |
---|
1140 | </tr> |
---|
1141 | <tr> |
---|
1142 | <td align="right">37 </td> |
---|
1143 | <td>Serena </td> |
---|
1144 | <td>Williams </td> |
---|
1145 | <td>Sat 06, Oct 2001 </td> |
---|
1146 | </tr> |
---|
1147 | <tr> |
---|
1148 | <td align="right">38 </td> |
---|
1149 | <td>Yat Sun </td> |
---|
1150 | <td>Sun </td> |
---|
1151 | <td>Sat 06, Oct 2001 </td> |
---|
1152 | </tr> |
---|
1153 | <tr> |
---|
1154 | <td align="right">39 </td> |
---|
1155 | <td>Wai Hun </td> |
---|
1156 | <td>See </td> |
---|
1157 | <td>Sat 06, Oct 2001 </td> |
---|
1158 | </tr> |
---|
1159 | <tr> |
---|
1160 | <td align="right">40 </td> |
---|
1161 | <td>Steven </td> |
---|
1162 | <td>Oey </td> |
---|
1163 | <td>Sat 06, Oct 2001 </td> |
---|
1164 | </tr> |
---|
1165 | </tbody></table></td> |
---|
1166 | </tr> |
---|
1167 | <tr> |
---|
1168 | <td><font size="-1">Page 8/10</font></td> |
---|
1169 | </tr> |
---|
1170 | </tbody></table> |
---|
1171 | </p><p>The number of rows to display at one time is controled by the Render($rows) |
---|
1172 | method. If you do not pass any value to Render(), ADODB_Pager will default to |
---|
1173 | 10 records per page. |
---|
1174 | </p><p>You can control the column titles by modifying your SQL (supported by most |
---|
1175 | databases): |
---|
1176 | </p><pre>$sql = 'select id as "ID", firstname as "First Name", <br> lastname as "Last Name", created as "Date Created" <br> from adoxyz';</pre> |
---|
1177 | <p>The above code can be found in the <i>adodb/tests/testpaging.php</i> example |
---|
1178 | included with this release, and the class ADODB_Pager in <i>adodb/adodb-pager.inc.php</i>. |
---|
1179 | The ADODB_Pager code can be adapted by a programmer so that the text links can |
---|
1180 | be replaced by images, and the dull white background be replaced with more interesting |
---|
1181 | colors. |
---|
1182 | </p><p>You can also allow display of html by setting $pager->htmlSpecialChars = false. |
---|
1183 | </p><p>Some of the code used here was contributed by Iván Oliva and Cornel |
---|
1184 | G. </p> |
---|
1185 | <h3><a name="ex9"></a>Example 9: Exporting in CSV or Tab-Delimited Format</h3> |
---|
1186 | <p>We provide some helper functions to export in comma-separated-value (CSV) and |
---|
1187 | tab-delimited formats:</p> |
---|
1188 | <pre><b>include_once('/path/to/adodb/toexport.inc.php');</b><br>include_once('/path/to/adodb/adodb.inc.php');<br> |
---|
1189 | $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');<br><br>print "<pre>";<br>print <b>rs2csv</b>($rs); # return a string, CSV format<p>print '<hr>';<br><br>$rs->MoveFirst(); # note, some databases do not support MoveFirst<br>print <b>rs2tab</b>($rs,<i>false</i>); # return a string, tab-delimited<br> # 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)<br>print "</pre>";<br><br>$rs->MoveFirst();<br>$fp = fopen($path, "w");<br>if ($fp) {<br> <b>rs2csvfile</b>($rs, $fp); # write to file (there is also an rs2tabfile function)<br> fclose($fp);<br>}<br></pre> |
---|
1190 | <p> Carriage-returns or newlines are converted to spaces. Field names are returned |
---|
1191 | in the first line of text. Strings containing the delimiter character are quoted |
---|
1192 | with double-quotes. Double-quotes are double-quoted again. This conforms to |
---|
1193 | Excel import and export guide-lines. |
---|
1194 | </p><p>All the above functions take as an optional last parameter, $addtitles which |
---|
1195 | defaults to <i>true</i>. When set to <i>false</i> field names in the first line |
---|
1196 | are suppressed. <br> |
---|
1197 | </p><h3>Example 10: Recordset Filters<a name="ex10"></a></h3> |
---|
1198 | <p>Sometimes we want to pre-process all rows in a recordset before we use it. |
---|
1199 | For example, we want to ucwords all text in recordset. |
---|
1200 | </p><pre>include_once('adodb/rsfilter.inc.php');<br>include_once('adodb/adodb.inc.php');<br><br>// ucwords() every element in the recordset<br>function do_ucwords(&$arr,$rs)<br>{<br> foreach($arr as $k => $v) {<br> $arr[$k] = ucwords($v);<br> }<br>}<br><br>$db = NewADOConnection('mysql');<br>$db->PConnect('server','user','pwd','db');<br><br>$rs = $db->Execute('select ... from table');<br>$rs = <b>RSFilter</b>($rs,'do_ucwords');<br></pre> |
---|
1201 | <p>The <i>RSFilter</i> function takes 2 parameters, the recordset, and the name |
---|
1202 | of the <i>filter</i> function. It returns the processed recordset scrolled to |
---|
1203 | the first record. The <i>filter</i> function takes two parameters, the current |
---|
1204 | row as an array, and the recordset object. For future compatibility, you should |
---|
1205 | not use the original recordset object. </p> |
---|
1206 | <h3>Example 11:<a name="ex11"></a> Smart Transactions</h3> |
---|
1207 | The old way of doing transactions required you to use |
---|
1208 | <pre>$conn-><b>BeginTrans</b>();<br>$ok = $conn->Execute($sql);<br>if ($ok) $ok = $conn->Execute($sql2);<br>if (!$ok) $conn-><b>RollbackTrans</b>();<br>else $conn-><b>CommitTrans</b>();<br></pre> |
---|
1209 | This is very complicated for large projects because you have to track the error |
---|
1210 | status. Smart Transactions is much simpler. You start a smart transaction by calling |
---|
1211 | StartTrans(): |
---|
1212 | <pre>$conn-><b>StartTrans</b>();<br>$conn->Execute($sql);<br>$conn->Execute($Sql2);<br>$conn-><b>CompleteTrans</b>();<br></pre> |
---|
1213 | CompleteTrans() detects when an SQL error occurs, and will Rollback/Commit as |
---|
1214 | appropriate. To specificly force a rollback even if no error occured, use FailTrans(). |
---|
1215 | Note that the rollback is done in CompleteTrans(), and not in FailTrans(). |
---|
1216 | <pre>$conn-><b>StartTrans</b>();<br>$conn->Execute($sql);<br>if (!CheckRecords()) $conn-><strong>FailTrans</strong>();<br>$conn->Execute($Sql2);<br>$conn-><b>CompleteTrans</b>();<br></pre> |
---|
1217 | <p>You can also check if a transaction has failed, using HasFailedTrans(), which |
---|
1218 | returns true if FailTrans() was called, or there was an error in the SQL execution. |
---|
1219 | Make sure you call HasFailedTrans() before you call CompleteTrans(), as it is |
---|
1220 | only works between StartTrans/CompleteTrans. |
---|
1221 | </p><p>Lastly, StartTrans/CompleteTrans is nestable, and only the outermost block |
---|
1222 | is executed. In contrast, BeginTrans/CommitTrans/RollbackTrans is NOT nestable. |
---|
1223 | </p><pre>$conn-><strong>StartTrans</strong>();<br>$conn->Execute($sql);<br> $conn-><strong>StartTrans</strong>(); <font color="#006600"># ignored</font> |
---|
1224 | if (!CheckRecords()) $conn->FailTrans(); |
---|
1225 | $conn-><strong>CompleteTrans</strong>(); <font color="#006600"># ignored</font> |
---|
1226 | $conn->Execute($Sql2); |
---|
1227 | $conn-><strong>CompleteTrans</strong>();<br></pre> |
---|
1228 | <p>Note: Savepoints are currently not supported. |
---|
1229 | </p><h2><a name="errorhandling"></a>Using Custom Error Handlers and PEAR_Error</h2> |
---|
1230 | <p>ADOdb supports PHP5 exceptions. Just include <i>adodb-exceptions.inc.php</i> and you can now |
---|
1231 | catch exceptions on errors as they occur. |
---|
1232 | </p><pre> <b>include("../adodb-exceptions.inc.php");</b> <br> include("../adodb.inc.php"); <br> try { <br> $db = NewADOConnection("oci8://scott:bad-password@mytns/"); <br> } catch (exception $e) { <br> var_dump($e); <br> adodb_backtrace($e->gettrace());<br> } <br></pre> |
---|
1233 | <p> ADOdb also provides two custom handlers which you can modify for your needs. The |
---|
1234 | first one is in the <b>adodb-errorhandler.inc.php</b> file. This makes use of |
---|
1235 | the standard PHP functions <a href="http://php.net/error_reporting">error_reporting</a> |
---|
1236 | to control what error messages types to display, and <a href="http://php.net/trigger_error">trigger_error</a> |
---|
1237 | which invokes the default PHP error handler. |
---|
1238 | </p><p> Including the above file will cause <i>trigger_error($errorstring,E_USER_ERROR)</i> |
---|
1239 | to be called when<br> |
---|
1240 | (a) Connect() or PConnect() fails, or <br> |
---|
1241 | (b) a function that executes SQL statements such as Execute() or SelectLimit() |
---|
1242 | has an error.<br> |
---|
1243 | (c) GenID() appears to go into an infinite loop. |
---|
1244 | </p><p> The $errorstring is generated by ADOdb and will contain useful debugging information |
---|
1245 | similar to the error.log data generated below. This file adodb-errorhandler.inc.php |
---|
1246 | should be included before you create any ADOConnection objects. |
---|
1247 | </p><p> If you define error_reporting(0), no errors will be passed to the error handler. |
---|
1248 | If you set error_reporting(E_ALL), all errors will be passed to the error handler. |
---|
1249 | You still need to use <b>ini_set("display_errors", "0" or "1")</b> to control |
---|
1250 | the display of errors. |
---|
1251 | </p><pre><?php<br><b>error_reporting(E_ALL); # pass any error messages triggered to error handler<br>include('adodb-errorhandler.inc.php');</b> |
---|
1252 | include('adodb.inc.php'); |
---|
1253 | include('tohtml.inc.php'); |
---|
1254 | $c = NewADOConnection('mysql'); |
---|
1255 | $c->PConnect('localhost','root','','northwind'); |
---|
1256 | $rs=$c->Execute('select * from productsz'); #invalid table productsz'); |
---|
1257 | if ($rs) rs2html($rs); |
---|
1258 | ?> |
---|
1259 | </pre> |
---|
1260 | <p> If you want to log the error message, you can do so by defining the following |
---|
1261 | optional constants ADODB_ERROR_LOG_TYPE and ADODB_ERROR_LOG_DEST. ADODB_ERROR_LOG_TYPE |
---|
1262 | is the error log message type (see <a href="http://php.net/error_log">error_log</a> |
---|
1263 | in the PHP manual). In this case we set it to 3, which means log to the file |
---|
1264 | defined by the constant ADODB_ERROR_LOG_DEST. |
---|
1265 | </p><pre><?php<br><b>error_reporting(E_ALL); # report all errors<br>ini_set("display_errors", "0"); # but do not echo the errors<br>define('ADODB_ERROR_LOG_TYPE',3);<br>define('ADODB_ERROR_LOG_DEST','C:/errors.log');<br>include('adodb-errorhandler.inc.php');</b> |
---|
1266 | include('adodb.inc.php'); |
---|
1267 | include('tohtml.inc.php'); |
---|
1268 | |
---|
1269 | $c = NewADOConnection('mysql'); |
---|
1270 | $c->PConnect('localhost','root','','northwind'); |
---|
1271 | $rs=$c->Execute('select * from productsz'); ## invalid table productsz |
---|
1272 | if ($rs) rs2html($rs); |
---|
1273 | ?> |
---|
1274 | </pre> |
---|
1275 | The following message will be logged in the error.log file: |
---|
1276 | <pre>(2001-10-28 14:20:38) mysql error: [1146: Table 'northwind.productsz' doesn't exist] in<br> EXECUTE("select * from productsz")<br></pre> |
---|
1277 | <h3>PEAR_ERROR</h3> |
---|
1278 | The second error handler is <b>adodb-errorpear.inc.php</b>. This will create a |
---|
1279 | PEAR_Error derived object whenever an error occurs. The last PEAR_Error object |
---|
1280 | created can be retrieved using ADODB_Pear_Error(). |
---|
1281 | <pre><?php<br><b>include('adodb-errorpear.inc.php');</b> |
---|
1282 | include('adodb.inc.php'); |
---|
1283 | include('tohtml.inc.php'); |
---|
1284 | $c = NewADOConnection('mysql'); |
---|
1285 | $c->PConnect('localhost','root','','northwind'); |
---|
1286 | $rs=$c->Execute('select * from productsz'); #invalid table productsz'); |
---|
1287 | if ($rs) rs2html($rs); |
---|
1288 | else { |
---|
1289 | <b>$e = ADODB_Pear_Error();<br> echo '<p>',$e->message,'</p>';</b> |
---|
1290 | } |
---|
1291 | ?> |
---|
1292 | </pre> |
---|
1293 | <p> You can use a PEAR_Error derived class by defining the constant ADODB_PEAR_ERROR_CLASS |
---|
1294 | before the adodb-errorpear.inc.php file is included. For easy debugging, you |
---|
1295 | can set the default error handler in the beginning of the PHP script to PEAR_ERROR_DIE, |
---|
1296 | which will cause an error message to be printed, then halt script execution: |
---|
1297 | </p><pre>include('PEAR.php');<br>PEAR::setErrorHandling('PEAR_ERROR_DIE');<br></pre> |
---|
1298 | <p> Note that we do not explicitly return a PEAR_Error object to you when an error |
---|
1299 | occurs. We return false instead. You have to call ADODB_Pear_Error() to get |
---|
1300 | the last error or use the PEAR_ERROR_DIE technique. |
---|
1301 | </p> |
---|
1302 | <h3>MetaError and MetaErrMsg</h3> |
---|
1303 | <p>If you need error messages that work across multiple databases, then use <a href="#metaerror">MetaError()</a>, which returns a virtualized error number, based on PEAR DB's error number system, and <a href=<a href="#metaerrmsg">MetaErrMsg()</a>. |
---|
1304 | |
---|
1305 | <h4>Error Messages</h4> |
---|
1306 | <p>Error messages are outputted using the static method ADOConnnection::outp($msg,$newline=true). |
---|
1307 | By default, it sends the messages to the client. You can override this to perform |
---|
1308 | error-logging. |
---|
1309 | </p><h2><a name="dsn"></a> Data Source Names</h2> |
---|
1310 | <p>We now support connecting using PEAR style DSN's. A DSN is a connection string |
---|
1311 | of the form:</p> |
---|
1312 | <p>$dsn = <i>"$driver://$username:$password@$hostname/$databasename"</i>;</p> |
---|
1313 | <p>An example:</p> |
---|
1314 | <pre> $username = 'root';<br> $password = '';<br> $hostname = 'localhost';<br> $databasename = 'xphplens';<br> $driver = 'mysql';<br> $dsn = "$driver://$username:$password@$hostname/$databasename"<br> $db = NewADOConnection(); <br> # DB::Connect($dsn) also works if you include 'adodb/adodb-pear.inc.php' at the top<br> $rs = $db->query('select firstname,lastname from adoxyz');<br> $cnt = 0;<br> while ($arr = $rs->fetchRow()) {<br> print_r($arr); print "<br>";<br> }</pre> |
---|
1315 | <p></p> |
---|
1316 | <p> <a href="#dsnsupport">More info and connection examples</a> on the DSN format. |
---|
1317 | |
---|
1318 | </p><h2><a name="pear"></a>PEAR Compatibility</h2> |
---|
1319 | We support DSN's (see above), and the following functions: |
---|
1320 | <pre><b> DB_Common</b> |
---|
1321 | query - returns PEAR_Error on error |
---|
1322 | limitQuery - return PEAR_Error on error |
---|
1323 | prepare - does not return PEAR_Error on error |
---|
1324 | execute - does not return PEAR_Error on error |
---|
1325 | setFetchMode - supports ASSOC and ORDERED |
---|
1326 | errorNative |
---|
1327 | quote |
---|
1328 | nextID |
---|
1329 | disconnect |
---|
1330 | |
---|
1331 | getOne |
---|
1332 | getAssoc |
---|
1333 | getRow |
---|
1334 | getCol |
---|
1335 | |
---|
1336 | <b> DB_Result</b> |
---|
1337 | numRows - returns -1 if not supported |
---|
1338 | numCols |
---|
1339 | fetchInto - does not support passing of fetchmode |
---|
1340 | fetchRows - does not support passing of fetchmode |
---|
1341 | free |
---|
1342 | </pre> |
---|
1343 | <h2><a name="caching"></a>Caching of Recordsets</h2> |
---|
1344 | <p>ADOdb now supports caching of recordsets using the CacheExecute( ), CachePageExecute( |
---|
1345 | ) and CacheSelectLimit( ) functions. There are similar to the non-cache functions, |
---|
1346 | except that they take a new first parameter, $secs2cache. |
---|
1347 | </p><p> An example: |
---|
1348 | </p><pre><b>include</b>('adodb.inc.php'); # load code common to ADOdb<br>$ADODB_CACHE_DIR = '/usr/ADODB_cache';<br>$<font color="#663300">conn</font> = &ADONewConnection('mysql'); # create a connection<br>$<font color="#663300">conn</font>->PConnect('localhost','userid','','agora');# connect to MySQL, agora db<br><font>$<font color="#663300">sql</font> = 'select CustomerName, CustomerID from customers';<br>$<font color="#663300">rs</font> = $<font color="#663300">conn</font>->CacheExecute(15,$sql);</font></pre> |
---|
1349 | <p><font> The first parameter is the number of seconds to cache |
---|
1350 | the query. Subsequent calls to that query will used the cached version stored |
---|
1351 | in $ADODB_CACHE_DIR. To force a query to execute and flush the cache, call CacheExecute() |
---|
1352 | with the first parameter set to zero. Alternatively, use the CacheFlush($sql) |
---|
1353 | call. </font></p> |
---|
1354 | <p><font>For the sake of security, we recommend you set <i>register_globals=off</i> |
---|
1355 | in php.ini if you are using $ADODB_CACHE_DIR.</font></p> |
---|
1356 | <p>In ADOdb 1.80 onwards, the secs2cache parameter is optional in CacheSelectLimit() |
---|
1357 | and CacheExecute(). If you leave it out, it will use the $connection->cacheSecs |
---|
1358 | parameter, which defaults to 60 minutes. |
---|
1359 | </p><pre> $conn->Connect(...);<br> $conn->cacheSecs = 3600*24; # cache 24 hours<br> $rs = $conn->CacheExecute('select * from table');<br></pre> |
---|
1360 | <p>Please note that magic_quotes_runtime should be turned off. <a href="http://phplens.com/lens/lensforum/msgs.php?LeNs#LensBM_forummsg">More |
---|
1361 | info</a>, and do not change $ADODB_FETCH_MODE (or SetFetchMode) |
---|
1362 | as the cached recordset will use the $ADODB_FETCH_MODE set when the query was executed. <font> |
---|
1363 | <h2><a name="pivot"></a>Pivot Tables</h2> |
---|
1364 | </font> </p><p><font>Since ADOdb 2.30, we support the generation of |
---|
1365 | SQL to create pivot tables, also known as cross-tabulations. For further explanation |
---|
1366 | read this DevShed <a href="http://www.devshed.com/Server_Side/MySQL/MySQLWiz/">Cross-Tabulation |
---|
1367 | tutorial</a>. We assume that your database supports the SQL case-when expression. </font></p> |
---|
1368 | <font> |
---|
1369 | <p>In this example, we will use the Northwind database from Microsoft. In the |
---|
1370 | database, we have a products table, and we want to analyze this table by <i>suppliers |
---|
1371 | versus product categories</i>. We will place the suppliers on each row, and |
---|
1372 | pivot on categories. So from the table on the left, we generate the pivot-table |
---|
1373 | on the right:</p> |
---|
1374 | </font> |
---|
1375 | <table align="center" border="0" cellpadding="2" cellspacing="2"> |
---|
1376 | <tbody><tr> |
---|
1377 | <td> |
---|
1378 | <table align="center" border="1" cellpadding="2" cellspacing="2" width="142"> |
---|
1379 | <tbody><tr> |
---|
1380 | <td><i>Supplier</i></td> |
---|
1381 | <td><i>Category</i></td> |
---|
1382 | </tr> |
---|
1383 | <tr> |
---|
1384 | <td>supplier1</td> |
---|
1385 | <td>category1</td> |
---|
1386 | </tr> |
---|
1387 | <tr> |
---|
1388 | <td>supplier2</td> |
---|
1389 | <td>category1</td> |
---|
1390 | </tr> |
---|
1391 | <tr> |
---|
1392 | <td>supplier2</td> |
---|
1393 | <td>category2</td> |
---|
1394 | </tr> |
---|
1395 | </tbody></table> |
---|
1396 | </td> |
---|
1397 | <td> <font face="Courier New, Courier, mono">--></font></td> |
---|
1398 | <td> |
---|
1399 | <table align="center" border="1" cellpadding="2" cellspacing="2"> |
---|
1400 | <tbody><tr> |
---|
1401 | <td> </td> |
---|
1402 | <td><i>category1</i></td> |
---|
1403 | <td><i>category2</i></td> |
---|
1404 | <td><i>total</i></td> |
---|
1405 | </tr> |
---|
1406 | <tr> |
---|
1407 | <td><i>supplier1</i></td> |
---|
1408 | <td align="right">1</td> |
---|
1409 | <td align="right">0</td> |
---|
1410 | <td align="right">1</td> |
---|
1411 | </tr> |
---|
1412 | <tr> |
---|
1413 | <td><i>supplier2</i></td> |
---|
1414 | <td align="right">1</td> |
---|
1415 | <td align="right">1</td> |
---|
1416 | <td align="right">2</td> |
---|
1417 | </tr> |
---|
1418 | </tbody></table> |
---|
1419 | </td> |
---|
1420 | </tr> |
---|
1421 | </tbody></table> |
---|
1422 | <font> |
---|
1423 | </font><p><font>The following code will generate the SQL for a cross-tabulation: |
---|
1424 | </font></p><pre><font># Query the main "product" table<br># Set the rows to SupplierName<br># and the columns to the values of Categories<br># and define the joins to link to lookup tables <br># "categories" and "suppliers"<br>#<br> include "adodb/pivottable.inc.php";<br> $sql = PivotTableSQL(<br> $gDB, # adodb connection<br> 'products p ,categories c ,suppliers s', # tables<br> 'SupplierName', # rows (multiple fields allowed)<br> 'CategoryName', # column to pivot on <br> 'p.CategoryID = c.CategoryID and s.SupplierID= p.SupplierID' # joins/where<br>);<br></font></pre> |
---|
1425 | |
---|
1426 | <p><font> This will generate the following SQL:</font></p> |
---|
1427 | <p><code><font size="2">SELECT SupplierName, <br> |
---|
1428 | SUM(CASE WHEN CategoryName='Beverages' THEN 1 ELSE 0 END) AS "Beverages", |
---|
1429 | <br> |
---|
1430 | SUM(CASE WHEN CategoryName='Condiments' THEN 1 ELSE 0 END) AS "Condiments", |
---|
1431 | <br> |
---|
1432 | SUM(CASE WHEN CategoryName='Confections' THEN 1 ELSE 0 END) AS "Confections", |
---|
1433 | <br> |
---|
1434 | SUM(CASE WHEN CategoryName='Dairy Products' THEN 1 ELSE 0 END) AS "Dairy |
---|
1435 | Products", <br> |
---|
1436 | SUM(CASE WHEN CategoryName='Grains/Cereals' THEN 1 ELSE 0 END) AS "Grains/Cereals", |
---|
1437 | <br> |
---|
1438 | SUM(CASE WHEN CategoryName='Meat/Poultry' THEN 1 ELSE 0 END) AS "Meat/Poultry", |
---|
1439 | <br> |
---|
1440 | SUM(CASE WHEN CategoryName='Produce' THEN 1 ELSE 0 END) AS "Produce", |
---|
1441 | <br> |
---|
1442 | SUM(CASE WHEN CategoryName='Seafood' THEN 1 ELSE 0 END) AS "Seafood", |
---|
1443 | <br> |
---|
1444 | SUM(1) as Total <br> |
---|
1445 | FROM products p ,categories c ,suppliers s WHERE p.CategoryID = c.CategoryID |
---|
1446 | and s.SupplierID= p.SupplierID <br> |
---|
1447 | GROUP BY SupplierName</font></code></p> |
---|
1448 | <p> You can also pivot on <i>numerical columns</i> and <i>generate totals</i> |
---|
1449 | by using ranges. <font>This code was revised in ADODB 2.41 |
---|
1450 | and is not backward compatible.</font> The second example shows this:</p> |
---|
1451 | <pre> $sql = PivotTableSQL(<br> $gDB, # adodb connection<br> 'products p ,categories c ,suppliers s', # tables<br> 'SupplierName', #<font> rows (multiple fields allowed)</font> |
---|
1452 | array( # column ranges |
---|
1453 | ' 0 ' => 'UnitsInStock <= 0', |
---|
1454 | "1 to 5" => '0 < UnitsInStock and UnitsInStock <= 5', |
---|
1455 | "6 to 10" => '5 < UnitsInStock and UnitsInStock <= 10', |
---|
1456 | "11 to 15" => '10 < UnitsInStock and UnitsInStock <= 15', |
---|
1457 | "16+" => '15 < UnitsInStock' |
---|
1458 | ), |
---|
1459 | ' p.CategoryID = c.CategoryID and s.SupplierID= p.SupplierID', # joins/where |
---|
1460 | 'UnitsInStock', # sum this field |
---|
1461 | 'Sum ' # sum label prefix |
---|
1462 | ); |
---|
1463 | </pre> |
---|
1464 | <p>Which generates: </p> |
---|
1465 | <p> <code> <font size="2">SELECT SupplierName, <br> |
---|
1466 | SUM(CASE WHEN UnitsInStock <= 0 THEN UnitsInStock ELSE 0 END) AS "Sum |
---|
1467 | 0 ", <br> |
---|
1468 | SUM(CASE WHEN 0 < UnitsInStock and UnitsInStock <= 5 THEN UnitsInStock |
---|
1469 | ELSE 0 END) AS "Sum 1 to 5",<br> |
---|
1470 | SUM(CASE WHEN 5 < UnitsInStock and UnitsInStock <= 10 THEN UnitsInStock |
---|
1471 | ELSE 0 END) AS "Sum 6 to 10",<br> |
---|
1472 | SUM(CASE WHEN 10 < UnitsInStock and UnitsInStock <= 15 THEN UnitsInStock |
---|
1473 | ELSE 0 END) AS "Sum 11 to 15", <br> |
---|
1474 | SUM(CASE WHEN 15 < UnitsInStock THEN UnitsInStock ELSE 0 END) AS "Sum |
---|
1475 | 16+", <br> |
---|
1476 | SUM(UnitsInStock) AS "Sum UnitsInStock", <br> |
---|
1477 | SUM(1) as Total,<br> |
---|
1478 | FROM products p ,categories c ,suppliers s WHERE p.CategoryID = c.CategoryID |
---|
1479 | and s.SupplierID= p.SupplierID <br> |
---|
1480 | GROUP BY SupplierName</font></code><font size="2"><br> |
---|
1481 | </font> </p> |
---|
1482 | <font><hr /> |
---|
1483 | <h1>Class Reference<a name="ref"></a></h1> |
---|
1484 | <p>Function parameters with [ ] around them are optional.</p> |
---|
1485 | </font> |
---|
1486 | <h2>Global Variables</h2> |
---|
1487 | <h3><font><a name="adodb_countrecs"></a></font>$ADODB_COUNTRECS</h3> |
---|
1488 | <p>If the database driver API does not support counting the number of records |
---|
1489 | returned in a SELECT statement, the function RecordCount() is emulated when |
---|
1490 | the global variable $ADODB_COUNTRECS is set to true, which is the default. |
---|
1491 | We emulate this by buffering the records, which can take up large amounts |
---|
1492 | of memory for big recordsets. Set this variable to false for the best performance. |
---|
1493 | This variable is checked every time a query is executed, so you can selectively |
---|
1494 | choose which recordsets to count.</p> |
---|
1495 | <h3><font><a name="adodb_cache_dir"></a>$ADODB_CACHE_DIR</font></h3> |
---|
1496 | <font> |
---|
1497 | <p>If you are using recordset caching, this is the directory to save your recordsets |
---|
1498 | in. Define this before you call any caching functions such as CacheExecute( |
---|
1499 | ). We recommend setting <i>register_globals=off</i> in php.ini if you use this |
---|
1500 | feature for security reasons.</p> |
---|
1501 | <p>If you are using Unix and apache, you might need to set your cache directory |
---|
1502 | permissions to something similar to the following:</p> |
---|
1503 | </font> |
---|
1504 | <p>chown -R apache /path/to/adodb/cache<br> |
---|
1505 | chgrp -R apache /path/to/adodb/cache </p> |
---|
1506 | <h3><font><a name="adodb_ansi_padding_off"></a>$ADODB_ANSI_PADDING_OFF</font></h3> |
---|
1507 | <p><font>Determines whether to right trim CHAR fields (and also VARCHAR for ibase/firebird). |
---|
1508 | Set to true to trim. Default is false. Currently works for oci8po, ibase and firebird |
---|
1509 | drivers. Added in ADOdb 4.01. |
---|
1510 | </font></p><h3><font><a name="adodb_lang"></a>$ADODB_LANG</font></h3> |
---|
1511 | <p><font>Determines the language used in MetaErrorMsg(). The default is 'en', for English. |
---|
1512 | To find out what languages are supported, see the files |
---|
1513 | in adodb/lang/adodb-$lang.inc.php, where $lang is the supported langauge. |
---|
1514 | </font></p><h3><font><a name="adodb_fetch_mode"></a>$ADODB_FETCH_MODE</font></h3> |
---|
1515 | <p><font>This is a global variable that determines how arrays are retrieved by recordsets. |
---|
1516 | The recordset saves this value on creation (eg. in Execute( ) or SelectLimit( |
---|
1517 | )), and any subsequent changes to $ADODB_FETCH_MODE have no affect on existing |
---|
1518 | recordsets, only on recordsets created in the future.</font></p> |
---|
1519 | <p><font>The following constants are defined:</font></p> |
---|
1520 | <p><font>define('ADODB_FETCH_DEFAULT',0);<br> |
---|
1521 | define('ADODB_FETCH_NUM',1);<br> |
---|
1522 | define('ADODB_FETCH_ASSOC',2);<br> |
---|
1523 | define('ADODB_FETCH_BOTH',3); </font></p> |
---|
1524 | <font> |
---|
1525 | </font><p><font> An example: |
---|
1526 | </font></p><pre><font> $ADODB_<b>FETCH_MODE</b> = ADODB_FETCH_NUM;<br> $rs1 = $db->Execute('select * from table');<br> $ADODB_<b>FETCH_MODE</b> = ADODB_FETCH_ASSOC;<br> $rs2 = $db->Execute('select * from table');<br> print_r($rs1->fields); # shows <i>array([0]=>'v0',[1] =>'v1')</i> |
---|
1527 | print_r($rs2->fields); # shows <i>array(['col1']=>'v0',['col2'] =>'v1')</i> |
---|
1528 | </font></pre> |
---|
1529 | <p><font> As you can see in the above example, both recordsets store and use different |
---|
1530 | fetch modes based on the $ADODB_FETCH_MODE setting when the recordset was |
---|
1531 | created by Execute().</font></p> |
---|
1532 | <p><font>If no fetch mode is predefined, the fetch mode defaults to ADODB_FETCH_DEFAULT. |
---|
1533 | The behaviour of this default mode varies from driver to driver, so do not |
---|
1534 | rely on ADODB_FETCH_DEFAULT. For portability, we recommend sticking to ADODB_FETCH_NUM |
---|
1535 | or ADODB_FETCH_ASSOC. Many drivers do not support ADODB_FETCH_BOTH.</font></p> |
---|
1536 | <p><font><strong>SetFetchMode Function</strong></font></p> |
---|
1537 | <p><font>If you have multiple connection objects, and want to have different fetch modes for each |
---|
1538 | connection, then use <a href="#setfetchmode">SetFetchMode</a>. |
---|
1539 | Once this function is called for a connection object, that connection object |
---|
1540 | will ignore the global variable $ADODB_FETCH_MODE and will use the internal |
---|
1541 | fetchMode property exclusively.</font></p> |
---|
1542 | <pre><font> $db->SetFetchMode(ADODB_FETCH_NUM);<br> $rs1 = $db->Execute('select * from table');<br> $db->SetFetchMode(ADODB_FETCH_ASSOC);<br> $rs2 = $db->Execute('select * from table');<br> print_r($rs1->fields); # shows <i>array([0]=>'v0',[1] =>'v1')</i> |
---|
1543 | print_r($rs2->fields); # shows <i>array(['col1']=>'v0',['col2'] =>'v1')</i></font></pre> |
---|
1544 | <p><font>To retrieve the previous fetch mode, you can use check the $db->fetchMode |
---|
1545 | property, or use the return value of SetFetchMode( ). |
---|
1546 | </font></p><p><font><strong><a name="adodb_assoc_case"></a>ADODB_ASSOC_CASE</strong></font></p> |
---|
1547 | <p><font>You can control the associative fetch case for certain drivers which behave |
---|
1548 | differently. For the sybase, oci8po, mssql, odbc and ibase drivers and all |
---|
1549 | drivers derived from them, ADODB_ASSOC_CASE will by default generate recordsets |
---|
1550 | where the field name keys are lower-cased. Use the constant ADODB_ASSOC_CASE |
---|
1551 | to change the case of the keys. There are 3 possible values:</font></p> |
---|
1552 | <p><font>0 = assoc lowercase field names. $rs->fields['orderid']<br> |
---|
1553 | 1 = assoc uppercase field names. $rs->fields['ORDERID']<br> |
---|
1554 | 2 = use native-case field names. $rs->fields['OrderID'] -- this is the |
---|
1555 | default since ADOdb 2.90</font></p> |
---|
1556 | <p><font>To use it, declare it before you incldue adodb.inc.php.</font></p> |
---|
1557 | <p><font>define('ADODB_ASSOC_CASE', 2); # use native-case for ADODB_FETCH_ASSOC<br> |
---|
1558 | include('adodb.inc.php'); </font></p> |
---|
1559 | <h3><font><a name="force_type"></a>$ADODB_FORCE_TYPE</font></h3> |
---|
1560 | <p><font>See the <a href="#ADODB_FORCE_TYPE">GetUpdateSQL tutorial</a>. |
---|
1561 | </font></p> |
---|
1562 | <h3><font><a name="adodb_auto_quote"></a>$ADODB_QUOTE_FIELDNAMES</font></h3> |
---|
1563 | <p><font>Auto-quotes field names when using AutoExecute() when set to true. </font> |
---|
1564 | <p> </p> |
---|
1565 | <hr /> |
---|
1566 | <h2><font>ADOConnection<a name="adoconnection"></a></font></h2> |
---|
1567 | <p><font>Object that performs the connection to the database, executes SQL statements |
---|
1568 | and has a set of utility functions for standardising the format of SQL statements |
---|
1569 | for issues such as concatenation and date formats.</font></p> |
---|
1570 | <h3><font>ADOConnection Fields</font></h3> |
---|
1571 | <p><font><b>databaseType</b>: Name of the database system we are connecting to. Eg. |
---|
1572 | <b>odbc</b> or <b>mssql</b> or <b>mysql</b>.</font></p> |
---|
1573 | <p><font><b>dataProvider</b>: The underlying mechanism used to connect to the database. |
---|
1574 | Normally set to <b>native</b>, unless using <b>odbc</b> or <b>ado</b>.</font></p> |
---|
1575 | <p><font><b>host: </b>Name of server or data source name (DSN) to connect to.</font></p> |
---|
1576 | <p><font><b>database</b>: Name of the database or to connect to. If ado is used, it |
---|
1577 | will hold the ado data provider.</font></p> |
---|
1578 | <p><font><b>user</b>: Login id to connect to database. Password is not saved for security |
---|
1579 | reasons.</font></p> |
---|
1580 | <p><font><b>raiseErrorFn</b>: Allows you to define an error handling function. See adodb-errorhandler.inc.php |
---|
1581 | for an example.</font></p> |
---|
1582 | <p><font><b>debug</b>: Set to <i>true</i> to make debug statements to appear.</font></p> |
---|
1583 | <p><font><b>concat_operator</b>: Set to '+' or '||' normally. The operator used to concatenate |
---|
1584 | strings in SQL. Used by the <b><a href="#concat">Concat</a></b> function.</font></p> |
---|
1585 | <p><font><b>fmtDate</b>: The format used by the <b><a href="#dbdate">DBDate</a></b> |
---|
1586 | function to send dates to the database. is '#Y-m-d#' for Microsoft Access, |
---|
1587 | and ''Y-m-d'' for MySQL.</font></p> |
---|
1588 | <p><font><b>fmtTimeStamp: </b>The format used by the <b><a href="#dbtimestamp">DBTimeStamp</a></b> |
---|
1589 | function to send timestamps to the database. </font></p> |
---|
1590 | <p><font><b>true</b>: The value used to represent true.Eg. '.T.'. for Foxpro, '1' for |
---|
1591 | Microsoft SQL.</font></p> |
---|
1592 | <p><font><b>false: </b> The value used to represent false. Eg. '.F.'. for Foxpro, '0' |
---|
1593 | for Microsoft SQL.</font></p> |
---|
1594 | <p><font><b>replaceQuote</b>: The string used to escape quotes. Eg. double single-quotes |
---|
1595 | for Microsoft SQL, and backslash-quote for MySQL. Used by <a href="#qstr">qstr</a>.</font></p> |
---|
1596 | <p><font><b>autoCommit</b>: indicates whether automatic commit is enabled. Default is |
---|
1597 | true.</font></p> |
---|
1598 | <p><font><b>charSet</b>: set the default charset to use. Currently only interbase/firebird supports |
---|
1599 | this.</font></p> |
---|
1600 | <p><font><b>dialect</b>: set the default sql dialect to use. Currently only interbase/firebird |
---|
1601 | supports this.</font></p> |
---|
1602 | <p><font><b>role</b>: set the role. Currently only interbase/firebird |
---|
1603 | supports this.</font></p> |
---|
1604 | <p><font><b>metaTablesSQL</b>: SQL statement to return a list of available tables. Eg. |
---|
1605 | <i>SHOW TABLES</i> in MySQL.</font></p> |
---|
1606 | <p><font><b>genID</b>: The latest id generated by GenID() if supported by the database.</font></p> |
---|
1607 | <p><font><b>cacheSecs</b>: The number of seconds to cache recordsets if CacheExecute() |
---|
1608 | or CacheSelectLimit() omit the $secs2cache parameter. Defaults to 60 minutes.</font></p> |
---|
1609 | <p><font><b>sysDate</b>: String that holds the name of the database function to call |
---|
1610 | to get the current date. Useful for inserts and updates.</font></p> |
---|
1611 | <p><font><b>sysTimeStamp</b>: String that holds the name of the database function to |
---|
1612 | call to get the current timestamp/datetime value.</font></p> |
---|
1613 | <p><font><b>leftOuter</b>: String that holds operator for left outer join, if known. |
---|
1614 | Otherwise set to false.</font></p> |
---|
1615 | <p><font><b>rightOuter</b>: String that holds operator for left outer join, if known. |
---|
1616 | Otherwise set to false.</font></p> |
---|
1617 | <p><font><b>ansiOuter</b>: Boolean that if true indicates that ANSI style outer joins |
---|
1618 | are permitted. Eg. <i>select * from table1 left join table2 on p1=p2.</i></font></p> |
---|
1619 | <p><font><b>connectSID</b>: Boolean that indicates whether to treat the $database parameter |
---|
1620 | in connects as the SID for the oci8 driver. Defaults to false. Useful for |
---|
1621 | Oracle 8.0.5 and earlier.</font></p> |
---|
1622 | <p><font><b>autoRollback</b>: Persistent connections are auto-rollbacked in PConnect( |
---|
1623 | ) if this is set to true. Default is false.</font></p> |
---|
1624 | <hr /> |
---|
1625 | <h3><font>ADOConnection Main Functions</font></h3> |
---|
1626 | <p><font><b>ADOConnection( )</b></font></p> |
---|
1627 | <p><font>Constructor function. Do not call this directly. Use ADONewConnection( ) instead.</font></p> |
---|
1628 | <p><font><b>Connect<a name="connect"></a>($host,[$user],[$password],[$database])</b></font></p> |
---|
1629 | <p><font>Non-persistent connect to data source or server $<b>host</b>, using userid |
---|
1630 | $<b>user </b>and password $<b>password</b>. If the server supports multiple |
---|
1631 | databases, connect to database $<b>database</b>. </font></p> |
---|
1632 | <p><font>Returns true/false depending on connection success. Since 4.23, null is returned if the extension is not loaded.</font></p> |
---|
1633 | <p><font>ADO Note: If you are using a Microsoft ADO and not OLEDB, you can set the $database |
---|
1634 | parameter to the OLEDB data provider you are using.</font></p> |
---|
1635 | <p><font>PostgreSQL: An alternative way of connecting to the database is to pass the |
---|
1636 | standard PostgreSQL connection string in the first parameter $host, and the |
---|
1637 | other parameters will be ignored.</font></p> |
---|
1638 | <p><font>For Oracle and Oci8, there are two ways to connect. First is to use the TNS |
---|
1639 | name defined in your local tnsnames.ora (or ONAMES or HOSTNAMES). Place the |
---|
1640 | name in the $database field, and set the $host field to false. Alternatively, |
---|
1641 | set $host to the server, and $database to the database SID, this bypassed |
---|
1642 | tnsnames.ora. |
---|
1643 | </font></p><p><font>Examples: |
---|
1644 | </font></p><pre><font> # $oraname in tnsnames.ora/ONAMES/HOSTNAMES<br> $conn->Connect(false, 'scott', 'tiger', $oraname); <br> $conn->Connect('server:1521', 'scott', 'tiger', 'ServiceName'); # bypass tnsnames.ora</font></pre> |
---|
1645 | <p><font>There are many examples of connecting to a database. |
---|
1646 | See <a href="#connect_ex">Connection Examples</a> for many examples. |
---|
1647 | |
---|
1648 | </font></p><p><font><b>PConnect<a name="pconnect"></a>($host,[$user],[$password],[$database])</b></font></p> |
---|
1649 | <p><font>Persistent connect to data source or server $<b>host</b>, using userid $<b>user</b> |
---|
1650 | and password $<b>password</b>. If the server supports multiple databases, |
---|
1651 | connect to database $<b>database</b>.</font></p> |
---|
1652 | <p><font>We now perform a rollback on persistent connection for selected databases since |
---|
1653 | 2.21, as advised in the PHP manual. See change log or source code for which |
---|
1654 | databases are affected. |
---|
1655 | </font></p><p><font>Returns true/false depending on connection. Since 4.23, 0 is returned if the extension is not loaded. |
---|
1656 | See Connect( ) above for more info.</font></p> |
---|
1657 | <p><font>Since ADOdb 2.21, we also support autoRollback. If you set:</font></p> |
---|
1658 | |
---|
1659 | <pre> $conn = &NewADOConnection('mysql');<br> $conn->autoRollback = true; # default is false<br> $conn->PConnect(...); # rollback here</pre> |
---|
1660 | <p> Then when doing a persistent connection with PConnect( ), ADOdb will |
---|
1661 | perform a rollback first. This is because it is documented that PHP is |
---|
1662 | not guaranteed to rollback existing failed transactions when |
---|
1663 | persistent connections are used. This is implemented in Oracle, |
---|
1664 | MySQL, PgSQL, MSSQL, ODBC currently. |
---|
1665 | </p><p>Since ADOdb 3.11, you can force non-persistent |
---|
1666 | connections even if PConnect is called by defining the constant |
---|
1667 | ADODB_NEVER_PERSIST before you call PConnect. |
---|
1668 | </p><p> |
---|
1669 | Since 4.23, null is returned if the extension is not loaded. |
---|
1670 | </p><p><b>NConnect<a name="nconnect"></a>($host,[$user],[$password],[$database])</b></p> |
---|
1671 | <p>Always force a new connection. In contrast, PHP sometimes reuses connections |
---|
1672 | when you use Connect() or PConnect(). Currently works only on mysql (PHP 4.3.0 |
---|
1673 | or later), postgresql and oci8-derived drivers. For other drivers, NConnect() works like |
---|
1674 | Connect().</p> |
---|
1675 | <p><font><b>IsConnected( )<a name="isconnected"></a></b></font></p> |
---|
1676 | <p> |
---|
1677 | <font>Returns true if connected to database. Added in 4.53. |
---|
1678 | |
---|
1679 | </font></p><p><font><b>Execute<a name="execute"></a>($sql,$inputarr=false)</b></font></p> |
---|
1680 | <p><font>Execute SQL statement $<b>sql</b> and return derived class of ADORecordSet |
---|
1681 | if successful. Note that a record set is always returned on success, even |
---|
1682 | if we are executing an insert or update statement. You can also pass in $sql a statement prepared |
---|
1683 | in <a href="#prepare">Prepare()</a>.</font></p> |
---|
1684 | <p><font>Returns derived class of ADORecordSet. Eg. if connecting via mysql, then ADORecordSet_mysql |
---|
1685 | would be returned. False is returned if there was an error in executing the |
---|
1686 | sql.</font></p> |
---|
1687 | <p><font>The $inputarr parameter can be used for binding variables to parameters. Below |
---|
1688 | is an Oracle example:</font></p> |
---|
1689 | <pre><font> $conn->Execute("SELECT * FROM TABLE WHERE COND=:val", array('val'=> $val));<br> </font></pre> |
---|
1690 | <p><font>Another example, using ODBC,which uses the ? convention:</font></p> |
---|
1691 | <pre><font> $conn->Execute("SELECT * FROM TABLE WHERE COND=?", array($val));<br></font></pre> |
---|
1692 | <font><a name="binding"></a> |
---|
1693 | <i>Binding variables</i></font><p> |
---|
1694 | <font>Variable binding speeds the compilation and caching of SQL statements, leading |
---|
1695 | to higher performance. Currently Oracle, Interbase and ODBC supports variable binding. |
---|
1696 | Interbase/ODBC style ? binding is emulated in databases that do not support binding. |
---|
1697 | Note that you do not have to quote strings if you use binding. |
---|
1698 | </font></p><p><font> Variable binding in the odbc, interbase and oci8po drivers. |
---|
1699 | </font></p><pre><font>$rs = $db->Execute('select * from table where val=?', array('10'));<br></font></pre> |
---|
1700 | <font>Variable binding in the oci8 driver: |
---|
1701 | </font><pre><font>$rs = $db->Execute('select name from table where val=:key', <br> array('key' => 10));<br></font></pre> |
---|
1702 | <font><a name="bulkbind"></a> |
---|
1703 | <i>Bulk binding</i> |
---|
1704 | </font><p><font>Since ADOdb 3.80, we support bulk binding in Execute(), in which you pass in a 2-dimensional array to |
---|
1705 | be bound to an INSERT/UPDATE or DELETE statement. |
---|
1706 | </font></p><pre><font>$arr = array(<br> array('Ahmad',32),<br> array('Zulkifli', 24),<br> array('Rosnah', 21)<br> );<br>$ok = $db->Execute('insert into table (name,age) values (?,?)',$arr);<br></font></pre> |
---|
1707 | <p><font>This provides very high performance as the SQL statement is prepared first. |
---|
1708 | The prepared statement is executed repeatedly for each array row until all rows are completed, |
---|
1709 | or until the first error. Very useful for importing data. |
---|
1710 | |
---|
1711 | </font></p><p><font><b>CacheExecute<a name="cacheexecute"></a>([$secs2cache,]$sql,$inputarr=false)</b></font></p> |
---|
1712 | <p><font>Similar to Execute, except that the recordset is cached for $secs2cache seconds |
---|
1713 | in the $ADODB_CACHE_DIR directory, and $inputarr only accepts 1-dimensional arrays. |
---|
1714 | If CacheExecute() is called again with the same $sql, $inputarr, |
---|
1715 | and also the same database, same userid, and the cached recordset |
---|
1716 | has not expired, the cached recordset is returned. |
---|
1717 | </font></p><pre><font> include('adodb.inc.php'); <br> include('tohtml.inc.php');<br> $ADODB_<b>CACHE_DIR</b> = '/usr/local/ADOdbcache';<br> $conn = &ADONewConnection('mysql'); <br> $conn->PConnect('localhost','userid','password','database');<br> $rs = $conn-><b>CacheExecute</b>(15, 'select * from table'); # cache 15 secs<br> rs2html($rs); /* recordset to html table */ <br></font></pre> |
---|
1718 | <p><font> Alternatively, since ADOdb 1.80, the $secs2cache parameter is optional:</font></p> |
---|
1719 | <pre><font> $conn->Connect(...);<br> $conn->cacheSecs = 3600*24; // cache 24 hours<br> $rs = $conn->CacheExecute('select * from table');<br></font></pre> |
---|
1720 | <font>If $secs2cache is omitted, we use the value |
---|
1721 | in $connection->cacheSecs (default is 3600 seconds, or 1 hour). Use CacheExecute() |
---|
1722 | only with SELECT statements. |
---|
1723 | </font><p><font>Performance note: I have done some benchmarks and found that they vary so greatly |
---|
1724 | that it's better to talk about when caching is of benefit. When your database |
---|
1725 | server is <i>much slower </i>than your Web server or the database is <i>very |
---|
1726 | overloaded </i>then ADOdb's caching is good because it reduces the load on |
---|
1727 | your database server. If your database server is lightly loaded or much faster |
---|
1728 | than your Web server, then caching could actually reduce performance. </font></p> |
---|
1729 | <p><font><b>ExecuteCursor<a name="executecursor"></a>($sql,$cursorName='rs',$parameters=false)</b></font></p> |
---|
1730 | <p><font>Execute an Oracle stored procedure, and returns an Oracle REF cursor variable as |
---|
1731 | a regular ADOdb recordset. Does not work with any other database except oci8. |
---|
1732 | Thanks to Robert Tuttle for the design. |
---|
1733 | </font></p><pre><font> $db = ADONewConnection("oci8"); <br> $db->Connect("foo.com:1521", "uid", "pwd", "FOO"); <br> $rs = $db->ExecuteCursor("begin :cursorvar := getdata(:param1); end;", <br> 'cursorvar',<br> array('param1'=>10)); <br> # $rs is now just like any other ADOdb recordset object<br> rs2html($rs);</font></pre> |
---|
1734 | <p><font>ExecuteCursor() is a helper function that does the following internally: |
---|
1735 | </font></p><pre><font> $stmt = $db->Prepare("begin :cursorvar := getdata(:param1); end;", true); <br> $db->Parameter($stmt, $cur, 'cursorvar', false, -1, OCI_B_CURSOR);<br> $rs = $db->Execute($stmt,$bindarr);<br></font></pre> |
---|
1736 | <p><font>ExecuteCursor only accepts 1 out parameter. So if you have 2 out parameters, use: |
---|
1737 | </font></p><pre><font> $vv = 'A%';<br> $stmt = $db->PrepareSP("BEGIN list_tabs(:crsr,:tt); END;");<br> $db->OutParameter($stmt, $cur, 'crsr', -1, OCI_B_CURSOR);<br> $db->OutParameter($stmt, $vv, 'tt', 32); # return varchar(32)<br> $arr = $db->GetArray($stmt);<br> print_r($arr);<br> echo " val = $vv"; ## outputs 'TEST'<br></font></pre> |
---|
1738 | <font>for the following PL/SQL: |
---|
1739 | </font><pre><font> TYPE TabType IS REF CURSOR RETURN TAB%ROWTYPE;<br><br> PROCEDURE list_tabs(tabcursor IN OUT TabType,tablenames IN OUT VARCHAR) IS<br> BEGIN<br> OPEN tabcursor FOR SELECT * FROM TAB WHERE tname LIKE tablenames;<br> tablenames := 'TEST';<br> END list_tabs;<br></font></pre> |
---|
1740 | <p><font><b>SelectLimit<a name="selectlimit"></a>($sql,$numrows=-1,$offset=-1,$inputarr=false)</b></font></p> |
---|
1741 | <p><font>Returns a recordset if successful. Returns false otherwise. Performs a select |
---|
1742 | statement, simulating PostgreSQL's SELECT statement, LIMIT $numrows OFFSET |
---|
1743 | $offset clause.</font></p> |
---|
1744 | <p><font>In PostgreSQL, SELECT * FROM TABLE LIMIT 3 will return the first 3 records |
---|
1745 | only. The equivalent is <code>$connection->SelectLimit('SELECT * FROM TABLE',3)</code>. |
---|
1746 | This functionality is simulated for databases that do not possess this feature.</font></p> |
---|
1747 | <p><font>And SELECT * FROM TABLE LIMIT 3 OFFSET 2 will return records 3, 4 and 5 (eg. |
---|
1748 | after record 2, return 3 rows). The equivalent in ADOdb is <code>$connection->SelectLimit('SELECT |
---|
1749 | * FROM TABLE',3,2)</code>.</font></p> |
---|
1750 | <p><font>Note that this is the <i>opposite</i> of MySQL's LIMIT clause. You can also |
---|
1751 | set <code>$connection->SelectLimit('SELECT * FROM TABLE',-1,10)</code> to |
---|
1752 | get rows 11 to the last row.</font></p> |
---|
1753 | <p><font>The last parameter $inputarr is for databases that support variable binding |
---|
1754 | such as Oracle oci8. This substantially reduces SQL compilation overhead. |
---|
1755 | Below is an Oracle example:</font></p> |
---|
1756 | <pre><font> $conn->SelectLimit("SELECT * FROM TABLE WHERE COND=:val", 100,-1,array('val'=> $val));<br> </font></pre> |
---|
1757 | <p><font>The oci8po driver (oracle portable driver) uses the more standard bind variable |
---|
1758 | of ?: |
---|
1759 | </font></p><pre><font> $conn->SelectLimit("SELECT * FROM TABLE WHERE COND=?", 100,-1,array('val'=> $val));<br></font></pre> |
---|
1760 | <p><font> |
---|
1761 | </font></p><p><font>Ron Wilson reports that SelectLimit does not work with UNIONs. |
---|
1762 | </font></p><p><font><b>CacheSelectLimit<a name="cacheselectlimit"></a>([$secs2cache,] $sql, $numrows=-1,$offset=-1,$inputarr=false)</b></font></p> |
---|
1763 | <p><font>Similar to SelectLimit, except that the recordset returned is cached for $secs2cache |
---|
1764 | seconds in the $ADODB_CACHE_DIR directory. </font></p> |
---|
1765 | <p><font>Since 1.80, $secs2cache has been optional, and you can define the caching time |
---|
1766 | in $connection->cacheSecs.</font></p> |
---|
1767 | |
---|
1768 | <pre><font> $conn->Connect(...);<br> $conn->cacheSecs = 3600*24; // cache 24 hours<br> $rs = $conn->CacheSelectLimit('select * from table',10);</font></pre> |
---|
1769 | <font> |
---|
1770 | </font><p><font><b>CacheFlush<a name="cacheflush"></a>($sql=false,$inputarr=false)</b></font></p> |
---|
1771 | <p><font>Flush (delete) any cached recordsets for the SQL statement $sql in $ADODB_CACHE_DIR. |
---|
1772 | </font></p><p><font>If no parameter is passed in, then all adodb_*.cache files are deleted. |
---|
1773 | </font></p> |
---|
1774 | <p>CacheSelectLimit() rewrites the SQL query, so you won't be able to pass the SQL to CacheFlush. In this case, |
---|
1775 | to flush the cached SQL recordset returned by CacheSelectLimit(), set $secs2cache to -1: |
---|
1776 | <pre> |
---|
1777 | $db->CacheSelectLimit(-1, $sql, $nrows); |
---|
1778 | </pre> |
---|
1779 | <p><font> If you want to flush all cached recordsets manually, execute the following |
---|
1780 | PHP code (works only under Unix): <br> |
---|
1781 | <code> system("rm -f `find ".$ADODB_CACHE_DIR." -name |
---|
1782 | adodb_*.cache`");</code></font></p> |
---|
1783 | <p><font>For general cleanup of all expired files, you should use <a href="http://www.superscripts.com/tutorial/crontab.html">crontab</a> |
---|
1784 | on Unix, or at.exe on Windows, and a shell script similar to the following:<font face="Courier New, Courier, mono"><br> |
---|
1785 | #------------------------------------------------------ <br> |
---|
1786 | # This particular example deletes files in the TMPPATH <br> |
---|
1787 | # directory with the string ".cache" in their name that <br> |
---|
1788 | # are more than 7 days old. <br> |
---|
1789 | #------------------------------------------------------ <br> |
---|
1790 | AGED=7 <br> |
---|
1791 | find ${TMPPATH} -mtime +$AGED | grep "\.cache" | xargs rm -f <br> |
---|
1792 | </font> </font></p> |
---|
1793 | <p><font><b>MetaError<a name="metaerror"></a>($errno=false)</b></font></p> |
---|
1794 | <p><font>Returns a virtualized error number, based on PEAR DB's error number system. You might |
---|
1795 | need to include adodb-error.inc.php before you call this function. The parameter $errno |
---|
1796 | is the native error number you want to convert. If you do not pass any parameter, MetaError |
---|
1797 | will call ErrorNo() for you and convert it. If the error number cannot be virtualized, MetaError |
---|
1798 | will return -1 (DB_ERROR).</font></p> |
---|
1799 | |
---|
1800 | <p><font><b>MetaErrorMsg<a name="metaerrormsg"></a>($errno)</b></font></p> |
---|
1801 | <p><font>Pass the error number returned by MetaError() for the equivalent textual error message.</font></p> |
---|
1802 | <p><font><b>ErrorMsg<a name="errormsg"></a>()</b></font></p> |
---|
1803 | <p><font>Returns the last status or error message. The error message is reset after every |
---|
1804 | call to Execute(). |
---|
1805 | </font></p><p> |
---|
1806 | <font>This can return a string even if |
---|
1807 | no error occurs. In general you do not need to call this function unless an |
---|
1808 | ADOdb function returns false on an error. </font></p> |
---|
1809 | <p><font>Note: If <b>debug</b> is enabled, the SQL error message is always displayed |
---|
1810 | when the <b>Execute</b> function is called.</font></p> |
---|
1811 | <p><font><b>ErrorNo<a name="errorno"></a>()</b></font></p> |
---|
1812 | <p><font>Returns the last error number. The error number is reset after every call to Execute(). |
---|
1813 | If 0 is returned, no error occurred. |
---|
1814 | </font></p><p> |
---|
1815 | <font>Note that old versions of PHP (pre 4.0.6) do |
---|
1816 | not support error number for ODBC. In general you do not need to call this |
---|
1817 | function unless an ADOdb function returns false on an error.</font></p> |
---|
1818 | <p><font><b>IgnoreErrors<a name="ignoreerrors"></a>($saveErrHandlers)</b></font></p> |
---|
1819 | <p>Allows you to ignore errors so that StartTrans()/CompleteTrans() is not affected, nor is the default error handler called if an error occurs. |
---|
1820 | Useful when you want to check if a field or table exists in a database without invoking an error if it does not exist. |
---|
1821 | <p>Usage: |
---|
1822 | <pre> |
---|
1823 | $saveErrHandlers = $conn->IgnoreErrors(); |
---|
1824 | $rs = $conn->Execute("select field from some_table_that_might_not_exist"); |
---|
1825 | $conn->IgnoreErrors($saveErrHandlers); |
---|
1826 | </pre> |
---|
1827 | <p>Warning: do not call StartTrans()/CompleteTrans() inside a code block that is using IgnoreErrors(). |
---|
1828 | <p><font><b>SetFetchMode<a name="setfetchmode"></a>($mode)</b></font></p> |
---|
1829 | <p><font>Sets the current fetch mode for the connection and stores |
---|
1830 | it in $db->fetchMode. Legal modes are ADODB_FETCH_ASSOC and ADODB_FETCH_NUM. |
---|
1831 | For more info, see <a href="#adodb_fetch_mode">$ADODB_FETCH_MODE</a>.</font></p> |
---|
1832 | <p><font>Returns the previous fetch mode, which could be false |
---|
1833 | if SetFetchMode( ) has not been called before.</font></p> |
---|
1834 | <font> |
---|
1835 | </font><p><font><b>CreateSequence<a name="createseq"></a>($seqName = 'adodbseq',$startID=1)</b></font></p> |
---|
1836 | <p><font>Create a sequence. The next time GenID( ) is called, the value returned will |
---|
1837 | be $startID. Added in 2.60. |
---|
1838 | </font></p><p><font><b>DropSequence<a name="dropseq"></a>($seqName = 'adodbseq')</b></font></p> |
---|
1839 | <p><font>Delete a sequence. Added in 2.60. |
---|
1840 | </font></p><p><font><b>GenID<a name="genid"></a>($seqName = 'adodbseq',$startID=1)</b></font></p> |
---|
1841 | <p><font>Generate a sequence number . Works for interbase, |
---|
1842 | mysql, postgresql, oci8, oci8po, mssql, ODBC based (access,vfp,db2,etc) drivers |
---|
1843 | currently. Uses $seqName as the name of the sequence. GenID() will automatically |
---|
1844 | create the sequence for you if it does not exist (provided the userid has |
---|
1845 | permission to do so). Otherwise you will have to create the sequence yourself. |
---|
1846 | </font></p><p><font> If your database driver emulates sequences, the name of the table is the sequence |
---|
1847 | name. The table has one column, "id" which should be of type integer, or if |
---|
1848 | you need something larger - numeric(16). |
---|
1849 | </font></p><p><font> For ODBC and databases that do not support sequences natively (eg mssql, mysql), |
---|
1850 | we create a table for each sequence. If the sequence has not been defined |
---|
1851 | earlier, it is created with the starting value set in $startID.</font></p> |
---|
1852 | <p><font>Note that the mssql driver's GenID() before 1.90 used to generate 16 byte GUID's.</font></p> |
---|
1853 | <p><font><b>UpdateBlob<a name="updateblob"></a>($table,$column,$val,$where)</b></font></p> |
---|
1854 | <font>Allows you to store a blob (in $val) into $table into $column in a row at $where. |
---|
1855 | </font><p><font> Usage: |
---|
1856 | </font></p><p><font> |
---|
1857 | </font></p><pre><font> # for oracle<br> $conn->Execute('INSERT INTO blobtable (id, blobcol) VALUES (1, empty_blob())');<br> $conn->UpdateBlob('blobtable','blobcol',$blobvalue,'id=1');<br> <br> # non oracle databases<br> $conn->Execute('INSERT INTO blobtable (id, blobcol) VALUES (1, null)');<br> $conn->UpdateBlob('blobtable','blobcol',$blobvalue,'id=1');<br></font></pre> |
---|
1858 | <p><font> Returns true if succesful, false otherwise. Supported by MySQL, PostgreSQL, |
---|
1859 | Oci8, Oci8po and Interbase drivers. Other drivers might work, depending on |
---|
1860 | the state of development.</font></p> |
---|
1861 | <p><font>Note that when an Interbase blob is retrieved using SELECT, it still needs |
---|
1862 | to be decoded using $connection->DecodeBlob($blob); to derive the original |
---|
1863 | value in versions of PHP before 4.1.0. |
---|
1864 | </font></p><p><font>For PostgreSQL, you can store your blob using blob oid's or as a bytea field. |
---|
1865 | You can use bytea fields but not blob oid's currently with UpdateBlob( ). |
---|
1866 | Conversely UpdateBlobFile( ) supports oid's, but not bytea data.<br> |
---|
1867 | <br> |
---|
1868 | If you do not pass in an oid, then UpdateBlob() assumes that you are storing |
---|
1869 | in bytea fields. |
---|
1870 | <p>If you do not have any blob fields, you can improve you can improve general SQL query performance by disabling blob handling with $connection->disableBlobs = true. |
---|
1871 | </p></font><p><font><b>UpdateClob<a name="updateclob"></a>($table,$column,$val,$where)</b></font></p> |
---|
1872 | <font>Allows you to store a clob (in $val) into $table into $column in a row at $where. |
---|
1873 | Similar to UpdateBlob (see above), but for Character Large OBjects. |
---|
1874 | </font><p><font> Usage: |
---|
1875 | </font></p><pre><font> # for oracle<br> $conn->Execute('INSERT INTO clobtable (id, clobcol) VALUES (1, empty_clob())');<br> $conn->UpdateBlob('clobtable','clobcol',$clobvalue,'id=1');<br> <br> # non oracle databases<br> $conn->Execute('INSERT INTO clobtable (id, clobcol) VALUES (1, null)');<br> $conn->UpdateBlob('clobtable','clobcol',$clobvalue,'id=1');<br></font></pre> |
---|
1876 | <p><font><b>UpdateBlobFile<a name="updateblobfile"></a>($table,$column,$path,$where,$blobtype='BLOB')</b></font></p> |
---|
1877 | <p><font>Similar to UpdateBlob, except that we pass in a file path to where the blob |
---|
1878 | resides. |
---|
1879 | </font></p><p><font>For PostgreSQL, if you are using blob oid's, use this interface. This interface |
---|
1880 | does not support bytea fields. |
---|
1881 | </font></p><p><font>Returns true if successful, false otherwise. |
---|
1882 | </font></p><p><font><b>BlobEncode<a name="blobencode" id="blobencode"></a>($blob)</b> |
---|
1883 | </font></p><p><font>Some databases require blob's to be encoded manually before upload. Note if |
---|
1884 | you use UpdateBlob( ) or UpdateBlobFile( ) the conversion is done automatically |
---|
1885 | for you and you do not have to call this function. For PostgreSQL, currently, |
---|
1886 | BlobEncode() can only be used for bytea fields. |
---|
1887 | </font></p><p><font>Returns the encoded blob value. |
---|
1888 | </font></p><p><font>Note that there is a connection property called <em>blobEncodeType</em> which |
---|
1889 | has 3 legal values: |
---|
1890 | </font></p><p><font>false - no need to perform encoding or decoding.<br> |
---|
1891 | 'I' - blob encoding required, and returned encoded blob is a numeric value |
---|
1892 | (no need to quote).<br> |
---|
1893 | 'C' - blob encoding required, and returned encoded blob is a character value |
---|
1894 | (requires quoting). |
---|
1895 | </font></p><p><font>This is purely for documentation purposes, so that programs that accept multiple |
---|
1896 | database drivers know what is the right thing to do when processing blobs. |
---|
1897 | </font></p><p><font><strong>BlobDecode<a name="blobdecode"></a>($blob, $maxblobsize = false)</strong> |
---|
1898 | </font></p><p><font>Some databases require blob's to be decoded manually after doing a select statement. |
---|
1899 | If the database does not require decoding, then this function will return |
---|
1900 | the blob unchanged. Currently BlobDecode is only required for one database, |
---|
1901 | PostgreSQL, and only if you are using blob oid's (if you are using bytea fields, |
---|
1902 | we auto-decode for you).</font> The default maxblobsize is set in $connection->maxblobsize, which |
---|
1903 | is set to 256K in adodb 4.54. </p><p> |
---|
1904 | In ADOdb 4.54 and later, the blob is the return value. In earlier versions, the blob data is sent to stdout.</p><font> |
---|
1905 | </font><p></p><pre><font>$rs = $db->Execute("select bloboid from postgres_table where id=$key");<br>$blob = $db->BlobDecode( reset($rs->fields) );</font></pre> |
---|
1906 | <p><font><b>Replace<a name="replace"></a>($table, $arrFields, $keyCols,$autoQuote=false)</b></font></p> |
---|
1907 | <p><font>Try to update a record, and if the record is not found, an insert statement |
---|
1908 | is generated and executed. Returns 0 on failure, 1 if update statement worked, |
---|
1909 | 2 if no record was found and the insert was executed successfully. This differs |
---|
1910 | from MySQL's replace which deletes the record and inserts a new record. This |
---|
1911 | also means you cannot update the primary key. The only exception to this is |
---|
1912 | Interbase and its derivitives, which uses delete and insert because of some |
---|
1913 | Interbase API limitations. |
---|
1914 | </font></p><p><font>The parameters are $table which is the table name, the $arrFields which is an |
---|
1915 | associative array where the keys are the field names, and $keyCols is the name |
---|
1916 | of the primary key, or an array of field names if it is a compound key. If |
---|
1917 | $autoQuote is set to true, then Replace() will quote all values that are non-numeric; |
---|
1918 | auto-quoting will not quote nulls. Note that auto-quoting will not work if |
---|
1919 | you use SQL functions or operators. |
---|
1920 | </font></p><p><font>Examples: |
---|
1921 | </font></p><pre><font># single field primary key<br>$ret = $db->Replace('atable', <br> array('id'=>1000,'firstname'=>'Harun','lastname'=>'Al-Rashid'),<br> 'id',$autoquote = true); <br># generates UPDATE atable SET firstname='Harun',lastname='Al-Rashid' WHERE id=1000<br># or INSERT INTO atable (id,firstname,lastname) VALUES (1000,'Harun','Al-Rashid')<br><br># compound key<br>$ret = $db->Replace('atable2', <br> array('firstname'=>'Harun','lastname'=>'Al-Rashid', 'age' => 33, 'birthday' => 'null'),<br> array('lastname','firstname'),<br> $autoquote = true);<br><br># no auto-quoting<br>$ret = $db->Replace('atable2', <br> array('firstname'=>"'Harun'",'lastname'=>"'Al-Rashid'", 'age' => 'null'),<br> array('lastname','firstname')); <br></font></pre> |
---|
1922 | <p><font><b>AutoExecute<a name="autoexecute"></a>($table, $arrFields, $mode, $where=false, $forceUpdate=true,$magicq=false)</b></font></p> |
---|
1923 | <p>Since ADOdb 4.56, you can automatically generate and execute INSERTs and UPDATEs on a given table with this |
---|
1924 | function, which is a wrapper for GetInsertSQL() and GetUpdateSQL(). |
---|
1925 | <p>AutoExecute() inserts or updates $table given an array of $arrFields, where the keys are the field names and the array values are the |
---|
1926 | field values to store. Note that there is some overhead because the table is first queried to extract key information |
---|
1927 | before the SQL is generated. We generate an INSERT or UPDATE based on $mode (see below). |
---|
1928 | <p> |
---|
1929 | Legal values for $mode are |
---|
1930 | <ul> |
---|
1931 | <li>'INSERT' or 1 or DB_AUTOQUERY_INSERT |
---|
1932 | <li>'UPDATE' or 2 or DB_AUTOQUERY_UPDATE |
---|
1933 | </ul> |
---|
1934 | <p>You have to define the constants DB_AUTOQUERY_UPDATE and DB_AUTOQUERY_INSERT yourself or include adodb-pear.inc.php. |
---|
1935 | <p>The $where clause is required if $mode == 'UPDATE'. If $forceUpdate=false then we will query the |
---|
1936 | database first and check if the field value returned by the query matches the current field value; only if they differ do we update that field. |
---|
1937 | <p>Returns true on success, false on error. |
---|
1938 | <p>An example of its use is: |
---|
1939 | <pre> |
---|
1940 | $record["firstName"] = "Carol"; |
---|
1941 | $record["lasTname"] = "Smith"; |
---|
1942 | $conn->AutoExecute($table,$record,'INSERT'); |
---|
1943 | # executes <i>"INSERT INTO $table (firstName,lasTname) values ('Carol',Smith')"</i>; |
---|
1944 | |
---|
1945 | $record["firstName"] = "Carol"; |
---|
1946 | $record["lasTname"] = "Jones"; |
---|
1947 | $conn->AutoExecute($table,$record,'UPDATE', "lastname like 'Sm%'"); |
---|
1948 | # executes <i>"UPDATE $table SET firstName='Carol',lasTname='Jones' WHERE lastname like 'Sm%'"</i>; |
---|
1949 | </pre> |
---|
1950 | <p>Note: One of the strengths of ADOdb's AutoExecute() is that only valid field names for $table are updated. If $arrFields |
---|
1951 | contains keys that are invalid field names for $table, they are ignored. There is some overhead in doing this as we have to |
---|
1952 | query the database to get the field names, but given that you are not directly coding the SQL yourself, you probably aren't interested in |
---|
1953 | speed at all, but convenience. |
---|
1954 | <p>Since 4.62, the table name to be used can be overridden by setting $rs->tableName before AutoExecute(), GetInsertSQL() or GetUpdateSQL() is called. |
---|
1955 | <p>Since 4.94, setting the global variable $ADODB_QUOTE_FIELDNAMES to true will force field names to be auto-quoted in AutoExecute(), GetInsertSQL() and GetUpdateSQL(). </p> |
---|
1956 | <p><font><b>GetUpdateSQL<a name="getupdatesql"></a>(&$rs, $arrFields, $forceUpdate=false,$magicq=false, $force=null)</b></font></p> |
---|
1957 | <p><font>Generate SQL to update a table given a recordset $rs, and the modified fields |
---|
1958 | of the array $arrFields (which must be an associative array holding the column |
---|
1959 | names and the new values) are compared with the current recordset. If $forceUpdate |
---|
1960 | is true, then we also generate the SQL even if $arrFields is identical to |
---|
1961 | $rs->fields. Requires the recordset to be associative. $magicq is used |
---|
1962 | to indicate whether magic quotes are enabled (see qstr()). The field names in the array |
---|
1963 | are case-insensitive.</font></p> |
---|
1964 | <font> </font><p><font>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> |
---|
1965 | global variable. |
---|
1966 | <p>Since 4.62, the table name to be used can be overridden by setting $rs->tableName before AutoExecute(), GetInsertSQL() or GetUpdateSQL() is called. |
---|
1967 | </p></font><p><font><b>GetInsertSQL<a name="getinsertsql"></a>(&$rs, $arrFields,$magicq=false,$force_type=false)</b></font></p> |
---|
1968 | <p><font>Generate SQL to insert into a table given a recordset $rs. Requires the query |
---|
1969 | to be associative. $magicq is used to indicate whether magic quotes are enabled |
---|
1970 | (for qstr()). The field names in the array are case-insensitive.</font></p> |
---|
1971 | <p> |
---|
1972 | <font> Since 2.42, you can pass a table name instead of a recordset into |
---|
1973 | GetInsertSQL (in $rs), and it will generate an insert statement for that table. |
---|
1974 | </font></p><p><font>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> |
---|
1975 | global variable. |
---|
1976 | <p>Since 4.62, the table name to be used can be overridden by setting $rs->tableName before AutoExecute(), GetInsertSQL() or GetUpdateSQL() is called. |
---|
1977 | </p></font><p><font><b>PageExecute<a name="pageexecute"></a>($sql, $nrows, $page, $inputarr=false)</b> |
---|
1978 | </font></p><p><font>Used for pagination of recordset. $page is 1-based. See <a href="#ex8">Example |
---|
1979 | 8</a>.</font></p> |
---|
1980 | |
---|
1981 | <p><font><b>CachePageExecute<a name="cachepageexecute"></a>($secs2cache, |
---|
1982 | $sql, $nrows, $page, $inputarr=false)</b> </font></p> |
---|
1983 | <p><font>Used for pagination of recordset. $page is 1-based. See |
---|
1984 | <a href="#ex8">Example 8</a>. Caching version of PageExecute.</font></p> |
---|
1985 | <font> |
---|
1986 | </font><p></p> |
---|
1987 | <p><font><b>Close<a name="close"></a>( )</b></font></p> |
---|
1988 | <p><font>Close the database connection. PHP4 proudly states that we no longer have to |
---|
1989 | clean up at the end of the connection because the reference counting mechanism |
---|
1990 | of PHP4 will automatically clean up for us.</font></p> |
---|
1991 | <font> </font><p><font><b>StartTrans<a name="starttrans"></a>( )</b></font></p> |
---|
1992 | <font> </font><p><font>Start a monitored transaction. As SQL statements are executed, ADOdb will monitor |
---|
1993 | for SQL errors, and if any are detected, when CompleteTrans() is called, we auto-rollback. |
---|
1994 | </font></p><p> |
---|
1995 | <font> </font></p><p><font> To understand why StartTrans() is superior to BeginTrans(), |
---|
1996 | let us examine a few ways of using BeginTrans(). |
---|
1997 | The following is the wrong way to use transactions: |
---|
1998 | </font></p><pre><font>$DB->BeginTrans();<br>$DB->Execute("update table1 set val=$val1 where id=$id");<br>$DB->Execute("update table2 set val=$val2 where id=$id");<br>$DB->CommitTrans();<br></font></pre> |
---|
1999 | <p><font>because you perform no error checking. It is possible to update table1 and |
---|
2000 | for the update on table2 to fail. Here is a better way: |
---|
2001 | </font></p><pre><font>$DB->BeginTrans();<br>$ok = $DB->Execute("update table1 set val=$val1 where id=$id");<br>if ($ok) $ok = $DB->Execute("update table2 set val=$val2 where id=$id");<br>if ($ok) $DB->CommitTrans();<br>else $DB->RollbackTrans();<br></font></pre> |
---|
2002 | <p><font>Another way is (since ADOdb 2.0): |
---|
2003 | </font></p><pre><font>$DB->BeginTrans();<br>$ok = $DB->Execute("update table1 set val=$val1 where id=$id");<br>if ($ok) $ok = $DB->Execute("update table2 set val=$val2 where id=$id");<br>$DB->CommitTrans($ok);<br></font></pre> |
---|
2004 | <p><font> Now it is a headache monitoring $ok all over the place. StartTrans() is an |
---|
2005 | improvement because it monitors all SQL errors for you. This is particularly |
---|
2006 | useful if you are calling black-box functions in which SQL queries might be executed. |
---|
2007 | Also all BeginTrans, CommitTrans and RollbackTrans calls inside a StartTrans block |
---|
2008 | will be disabled, so even if the black box function does a commit, it will be ignored. |
---|
2009 | </font></p><pre><font>$DB->StartTrans();<br>CallBlackBox();<br>$DB->Execute("update table1 set val=$val1 where id=$id");<br>$DB->Execute("update table2 set val=$val2 where id=$id");<br>$DB->CompleteTrans();<br></font></pre> |
---|
2010 | <p><font>Note that a StartTrans blocks are nestable, the inner blocks are ignored. |
---|
2011 | </font></p><p><font><b>CompleteTrans<a name="completetrans"></a>($autoComplete=true)</b></font></p> |
---|
2012 | <font> </font><p><font>Complete a transaction called with StartTrans(). This function monitors |
---|
2013 | for SQL errors, and will commit if no errors have occured, otherwise it will rollback. |
---|
2014 | Returns true on commit, false on rollback. If the parameter $autoComplete is true |
---|
2015 | monitor sql errors and commit and rollback as appropriate. Set $autoComplete to false |
---|
2016 | to force rollback even if no SQL error detected. |
---|
2017 | </font></p><p><font><b>FailTrans<a name="failtrans"></a>( )</b></font></p> |
---|
2018 | <font> </font><p><font>Fail a transaction started with StartTrans(). The rollback will only occur when |
---|
2019 | CompleteTrans() is called. |
---|
2020 | </font></p><p><font><b>HasFailedTrans<a name="hasfailedtrans"></a>( )</b></font></p> |
---|
2021 | <font> </font><p><font>Check whether smart transaction has failed, |
---|
2022 | eg. returns true if there was an error in SQL execution or FailTrans() was called. |
---|
2023 | If not within smart transaction, returns false. |
---|
2024 | </font></p><p><font><b>BeginTrans<a name="begintrans"></a>( )</b></font></p> |
---|
2025 | <p><font>Begin a transaction. Turns off autoCommit. Returns true if successful. Some |
---|
2026 | databases will always return false if transaction support is not available. |
---|
2027 | Any open transactions will be rolled back when the connection is closed. Among the |
---|
2028 | databases that support transactions are Oracle, PostgreSQL, Interbase, MSSQL, certain |
---|
2029 | versions of MySQL, DB2, Informix, Sybase, etc.</font></p> |
---|
2030 | <font> </font><p><font>Note that <a href="#starttrans">StartTrans()</a> and CompleteTrans() is a superior method of |
---|
2031 | handling transactions, available since ADOdb 3.40. For a explanation, see the <a href="#starttrans">StartTrans()</a> documentation. |
---|
2032 | |
---|
2033 | </font></p><p><font>You can also use the ADOdb <a href="#errorhandling">error handler</a> to die |
---|
2034 | and rollback your transactions for you transparently. Some buggy database extensions |
---|
2035 | are known to commit all outstanding tranasactions, so you might want to explicitly |
---|
2036 | do a $DB->RollbackTrans() in your error handler for safety. |
---|
2037 | </font></p><h4><font>Detecting Transactions</font></h4> |
---|
2038 | <font> </font><p><font>Since ADOdb 2.50, you are able to detect when you are inside a transaction. Check |
---|
2039 | that $connection->transCnt > 0. This variable is incremented whenever BeginTrans() is called, |
---|
2040 | and decremented whenever RollbackTrans() or CommitTrans() is called. |
---|
2041 | </font></p><p><font><b>CommitTrans<a name="committrans"></a>($ok=true)</b></font></p> |
---|
2042 | <p><font>End a transaction successfully. Returns true if successful. If the database |
---|
2043 | does not support transactions, will return true also as data is always committed. |
---|
2044 | </font></p> |
---|
2045 | <p><font>If you pass the parameter $ok=false, the data is rolled back. See example in |
---|
2046 | BeginTrans().</font></p> |
---|
2047 | <p><font><b>RollbackTrans<a name="rollbacktrans"></a>( )</b></font></p> |
---|
2048 | <p><font>End a transaction, rollback all changes. Returns true if successful. If the |
---|
2049 | database does not support transactions, will return false as data is never rollbacked. |
---|
2050 | </font></p> |
---|
2051 | |
---|
2052 | <p><font><b>SetTransactionMode<a name="SetTransactionMode"></a>($mode )</b></font></p> |
---|
2053 | <p>SetTransactionMode allows you to pass in the transaction mode to use for all subsequent transactions. |
---|
2054 | Note: if you have persistent connections and using mssql or mysql, you might have to explicitly reset your transaction mode at the beginning of each page request. |
---|
2055 | This is only supported in postgresql, mssql, mysql with InnoDB and oci8 currently. For example: |
---|
2056 | <pre> |
---|
2057 | $db->SetTransactionMode("SERIALIZABLE"); |
---|
2058 | $db->BeginTrans(); |
---|
2059 | $db->Execute(...); $db->Execute(...); |
---|
2060 | $db->CommiTrans(); |
---|
2061 | |
---|
2062 | $db->SetTransactionMode(""); // restore to default |
---|
2063 | $db->StartTrans(); |
---|
2064 | $db->Execute(...); $db->Execute(...); |
---|
2065 | $db->CompleteTrans(); |
---|
2066 | </pre> |
---|
2067 | |
---|
2068 | <p>Supported values to pass in: |
---|
2069 | <ul> |
---|
2070 | <li>READ UNCOMMITTED (allows dirty reads, but fastest) |
---|
2071 | <li>READ COMMITTED (default postgres, mssql and oci8) |
---|
2072 | <li>REPEATABLE READ (default mysql) |
---|
2073 | <li>SERIALIZABLE (slowest and most restrictive) |
---|
2074 | </ul> |
---|
2075 | <p>You can also pass in database specific values such as 'SNAPSHOT' for mssql or 'READ ONLY' for oci8/postgres. |
---|
2076 | <p>See transaction levels for <a href=http://www.postgresql.org/docs/8.1/interactive/sql-set-transaction.html>PostgreSQL</a>, |
---|
2077 | <a href=http://www.stanford.edu/dept/itss/docs/oracle/10g/server.101/b10759/statements_10005.htm>Oracle</a>, |
---|
2078 | <a href=http://dev.mysql.com/doc/refman/5.0/en/set-transaction.html>MySQL</a>, and |
---|
2079 | <a href=http://msdn2.microsoft.com/en-US/ms173763.aspx>MS SQL Server</a>. |
---|
2080 | <p><font><b>GetAssoc<a name="getassoc1"></a>($sql,$inputarr=false,$force_array=false,$first2cols=false)</b></font></p> |
---|
2081 | <p><font>Returns an associative array for the given query $sql with optional bind parameters |
---|
2082 | in $inputarr. If the number of columns returned is greater to two, a 2-dimensional |
---|
2083 | array is returned, with the first column of the recordset becomes the keys |
---|
2084 | to the rest of the rows. If the columns is equal to two, a 1-dimensional array |
---|
2085 | is created, where the the keys directly map to the values (unless $force_array |
---|
2086 | is set to true, when an array is created for each value). |
---|
2087 | </font></p><p><font> Examples:<a name="getassocex"></a></font></p> |
---|
2088 | |
---|
2089 | <p><font>We have the following data in a recordset:</font></p> |
---|
2090 | <p><font>row1: Apple, Fruit, Edible<br> |
---|
2091 | row2: Cactus, Plant, Inedible<br> |
---|
2092 | row3: Rose, Flower, Edible</font></p> |
---|
2093 | <p><font>GetAssoc will generate the following 2-dimensional associative |
---|
2094 | array:</font></p> |
---|
2095 | <p><font>Apple => array[Fruit, Edible]<br> |
---|
2096 | Cactus => array[Plant, Inedible]<br> |
---|
2097 | Rose => array[Flower,Edible]</font></p> |
---|
2098 | <p><font>If the dataset is:</font></p> |
---|
2099 | <p><font>row1: Apple, Fruit<br> |
---|
2100 | row2: Cactus, Plant<br> |
---|
2101 | row3: Rose, Flower </font></p> |
---|
2102 | <p><font>GetAssoc will generate the following 1-dimensional associative |
---|
2103 | array (with $force_array==false):</font></p> |
---|
2104 | <p><font>Apple => Fruit</font><br> |
---|
2105 | Cactus=>Plant<br> |
---|
2106 | Rose=>Flower </p> |
---|
2107 | <p><font>The function returns:</font></p> |
---|
2108 | <p><font>The associative array, or false if an error occurs.</font></p> |
---|
2109 | <font> |
---|
2110 | <p><b>CacheGetAssoc<a name="cachegetassoc"></a>([$secs2cache,] $sql,$inputarr=false,$force_array=false,$first2cols=false)</b></p> |
---|
2111 | </font> |
---|
2112 | <p><font>Caching version of <a href="#getassoc1">GetAssoc</a> function above. |
---|
2113 | </font></p><p><font><b>GetOne<a name="getone"></a>($sql,$inputarr=false)</b></font></p> |
---|
2114 | <p><font>Executes the SQL and returns the first field of the first row. The recordset |
---|
2115 | and remaining rows are discarded for you automatically. If an error occur, false |
---|
2116 | is returned.</font></p> |
---|
2117 | <p><font><b>GetRow<a name="getrow"></a>($sql,$inputarr=false)</b></font></p> |
---|
2118 | <p><font>Executes the SQL and returns the first row as an array. The recordset and remaining |
---|
2119 | rows are discarded for you automatically. If an error occurs, false is returned.</font></p> |
---|
2120 | <p><font><b>GetAll<a name="getall"></a>($sql,$inputarr=false)</b></font></p> |
---|
2121 | |
---|
2122 | <p>Executes the SQL and returns the all the rows as a 2-dimensional |
---|
2123 | array. The recordset is discarded for you automatically. If an error occurs, |
---|
2124 | false is returned. <i>GetArray</i> is a synonym for <i>GetAll</i>.</p> |
---|
2125 | <p><b>GetCol<a name="getcol"></a>($sql,$inputarr=false,$trim=false)</b></p> |
---|
2126 | |
---|
2127 | <p><font>Executes the SQL and returns all elements of the first column as a |
---|
2128 | 1-dimensional array. The recordset is discarded for you automatically. If an error occurs, |
---|
2129 | false is returned.</font></p> |
---|
2130 | <p><font><b>CacheGetOne<a name="cachegetone"></a>([$secs2cache,] |
---|
2131 | $sql,$inputarr=false), CacheGetRow<a name="cachegetrow"></a>([$secs2cache,] $sql,$inputarr=false), CacheGetAll<a name="cachegetall"></a>([$secs2cache,] |
---|
2132 | $sql,$inputarr=false), CacheGetCol<a name="cachegetcol"></a>([$secs2cache,] |
---|
2133 | $sql,$inputarr=false,$trim=false)</b></font></p> |
---|
2134 | <font> |
---|
2135 | </font><p><font>Similar to above Get* functions, except that the recordset is serialized and |
---|
2136 | cached in the $ADODB_CACHE_DIR directory for $secs2cache seconds. Good for speeding |
---|
2137 | up queries on rarely changing data. Note that the $secs2cache parameter is optional. |
---|
2138 | If omitted, we use the value in $connection->cacheSecs (default is 3600 seconds, |
---|
2139 | or 1 hour).</font></p> |
---|
2140 | <p><font><b>Prepare<a name="prepare"></a>($sql )</b></font></p> |
---|
2141 | |
---|
2142 | <p><font>Prepares (compiles) an SQL query for repeated execution. Bind parameters |
---|
2143 | are denoted by ?, except for the oci8 driver, which uses the traditional Oracle :varname |
---|
2144 | convention. |
---|
2145 | </font></p> |
---|
2146 | <p><font>Returns an array containing the original sql statement |
---|
2147 | in the first array element; the remaining elements of the array are driver dependent. |
---|
2148 | If there is an error, or we are emulating Prepare( ), we return the original |
---|
2149 | $sql string. This is because all error-handling has been centralized in Execute( |
---|
2150 | ).</font></p> |
---|
2151 | <p><font>Prepare( ) cannot be used with functions that use SQL |
---|
2152 | query rewriting techniques, e.g. PageExecute( ) and SelectLimit( ).</font></p> |
---|
2153 | <p>Example:</p> |
---|
2154 | <pre><font>$stmt = $DB->Prepare('insert into table (col1,col2) values (?,?)');<br>for ($i=0; $i < $max; $i++)<br></font> $DB-><font>Execute($stmt,array((string) rand(), $i));<br></font></pre> |
---|
2155 | <font> |
---|
2156 | </font><p><font>Also see InParameter(), OutParameter() and PrepareSP() below. Only supported internally by interbase, |
---|
2157 | oci8 and selected ODBC-based drivers, otherwise it is emulated. There is no |
---|
2158 | performance advantage to using Prepare() with emulation. |
---|
2159 | </font></p><p><font> Important: Due to limitations or bugs in PHP, if you are getting errors when |
---|
2160 | you using prepared queries, try setting $ADODB_COUNTRECS = false before preparing. |
---|
2161 | This behaviour has been observed with ODBC. |
---|
2162 | </font></p><p><font><b>IfNull<a name="ifnull"></a>($field, $nullReplacementValue)</b></font></p> |
---|
2163 | <p><font>Portable IFNULL function (NVL in Oracle). Returns a string that represents |
---|
2164 | the function that checks whether a $field is null for the given database, and |
---|
2165 | if null, change the value returned to $nullReplacementValue. Eg.</font></p> |
---|
2166 | <pre><font>$sql = <font color="#993300">'SELECT '</font>.$db->IfNull('name', <font color="#993300">"'- unknown -'"</font>).<font color="#993300"> ' FROM table'</font>;</font></pre> |
---|
2167 | |
---|
2168 | <p><font><b>length<a name="length"></a></b></font></p> |
---|
2169 | <p><font>This is not a function, but a property. Some databases have "length" and others "len" |
---|
2170 | as the function to measure the length of a string. To use this property: |
---|
2171 | </font></p><pre><font> $sql = <font color="#993300">"SELECT "</font>.$db->length.<font color="#993300">"(field) from table"</font>;<br> $rs = $db->Execute($sql);<br></font></pre> |
---|
2172 | |
---|
2173 | <p><font><b>random<a name="random"></a></b></font></p> |
---|
2174 | <p><font>This is not a function, but a property. This is a string that holds the sql to |
---|
2175 | generate a random number between 0.0 and 1.0 inclusive. |
---|
2176 | |
---|
2177 | </font></p><p><font><b>substr<a name="substr"></a></b></font></p> |
---|
2178 | <p><font>This is not a function, but a property. Some databases have "substr" and others "substring" |
---|
2179 | as the function to retrieve a sub-string. To use this property: |
---|
2180 | </font></p><pre><font> $sql = <font color="#993300">"SELECT "</font>.$db->substr.<font color="#993300">"(field, $offset, $length) from table"</font>;<br> $rs = $db->Execute($sql);<br></font></pre> |
---|
2181 | <p><font>For all databases, the 1st parameter of <i>substr</i> is the field, the 2nd is the |
---|
2182 | offset (1-based) to the beginning of the sub-string, and the 3rd is the length of the sub-string. |
---|
2183 | |
---|
2184 | |
---|
2185 | </font></p><p><font><b>Param<a name="param"></a>($name)</b></font></p> |
---|
2186 | <p><font>Generates a bind placeholder portably. For most databases, the bind placeholder |
---|
2187 | is "?". However some databases use named bind parameters such as Oracle, eg |
---|
2188 | ":somevar". This allows us to portably define an SQL statement with bind parameters: |
---|
2189 | </font></p><pre><font>$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>;<br><font color="#006600"># generates 'insert into table (col1,col2) values (?,?)'<br># or 'insert into table (col1,col2) values (:a,:b)</font>'<br>$stmt = $DB->Prepare($sql);<br>$stmt = $DB->Execute($stmt,array('one','two'));<br></font></pre> |
---|
2190 | <font> </font> |
---|
2191 | <p></p> |
---|
2192 | <p><font><b>PrepareSP</b><b><a name="preparesp"></a></b><b>($sql, |
---|
2193 | $cursor=false )</b></font></p> |
---|
2194 | <p><font>When calling stored procedures in mssql and oci8 (oracle), |
---|
2195 | and you might want to directly bind to parameters that return values, or |
---|
2196 | for special LOB handling. PrepareSP() allows you to do so. </font></p> |
---|
2197 | <p><font>Returns the same array or $sql string as Prepare( ) |
---|
2198 | above. If you do not need to bind to return values, you should use Prepare( |
---|
2199 | ) instead.</font></p> |
---|
2200 | <p><font>The 2nd parameter, $cursor is not used except with oci8. |
---|
2201 | Setting it to true will force OCINewCursor to be called; this is to support |
---|
2202 | output REF CURSORs. </font></p> |
---|
2203 | <p><font>For examples of usage of PrepareSP( ), see InParameter( |
---|
2204 | ) below. </font></p> |
---|
2205 | <p><font>Note: in the mssql driver, preparing stored procedures |
---|
2206 | requires a special function call, mssql_init( ), which is called by this |
---|
2207 | function. PrepareSP( ) is available in all other drivers, and is emulated |
---|
2208 | by calling Prepare( ). </font></p> |
---|
2209 | <p><font><b> InParameter<a name="inparameter"></a>($stmt, $var, |
---|
2210 | $name, $maxLen = 4000, $type = false )</b></font></p> |
---|
2211 | <font>Binds a PHP variable as input to a stored procedure variable. |
---|
2212 | The parameter <i>$stmt</i> is the value returned by PrepareSP(), <i>$var</i> is |
---|
2213 | the PHP variable you want to bind, $name is the name of the stored procedure |
---|
2214 | variable. Optional is <i>$maxLen</i>, the maximum length of the data to bind, |
---|
2215 | 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 |
---|
2216 | at php.net for more info on legal values for $type. </font> |
---|
2217 | <p> |
---|
2218 | <font>InParameter() is a wrapper function that calls Parameter() |
---|
2219 | with $isOutput=false. The advantage of this function is that it is self-documenting, |
---|
2220 | because the $isOutput parameter is no longer needed. Only for mssql and oci8 |
---|
2221 | currently. </font></p> |
---|
2222 | <p><font>Here is an example using oci8: </font></p> |
---|
2223 | <pre><font><font color="green"># For oracle, Prepare and PrepareSP are identical</font> |
---|
2224 | $stmt = $db->PrepareSP( |
---|
2225 | <font color="#993300">"declare RETVAL integer; <br> begin<br> :RETVAL := </font><font color="#993300">SP_RUNSOMETHING</font><font color="#993300">(:myid,:group);<br> end;"</font>);<br>$db->InParameter($stmt,$id,'myid');<br>$db->InParameter($stmt,$group,'group',64);<br>$db->OutParameter($stmt,$ret,'RETVAL');<br>$db->Execute($stmt);<br></font></pre> |
---|
2226 | <p><font> The same example using mssql:</font></p> |
---|
2227 | <font> |
---|
2228 | </font><pre><font><font color="green"># @RETVAL = SP_RUNSOMETHING @myid,@group</font> |
---|
2229 | $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> |
---|
2230 | $db->InParameter($stmt,$id,'myid'); |
---|
2231 | $db->InParameter($stmt,$group,'group',64); |
---|
2232 | <font color="green"># return value in mssql - RETVAL is hard-coded name</font> <br>$db->OutParameter($stmt,$ret,'RETVAL');<br>$db->Execute($stmt); </font></pre> |
---|
2233 | |
---|
2234 | <p><font>Note that the only difference between the oci8 and mssql implementations is $sql.</font></p> |
---|
2235 | <p> |
---|
2236 | <font> If $type parameter is set to false, in mssql, $type will be dynamicly determined |
---|
2237 | based on the type of the PHP variable passed <font face="Courier New, Courier, mono">(string |
---|
2238 | => SQLCHAR, boolean =>SQLINT1, integer =>SQLINT4 or float/double=>SQLFLT8)</font>. |
---|
2239 | </font></p><p><font> |
---|
2240 | In oci8, $type can be set to OCI_B_FILE (Binary-File), OCI_B_CFILE (Character-File), |
---|
2241 | OCI_B_CLOB (Character-LOB), OCI_B_BLOB (Binary-LOB) and OCI_B_ROWID (ROWID). To |
---|
2242 | pass in a null, use<font face="Courier New, Courier, mono"> $db->Parameter($stmt, |
---|
2243 | $null=null, 'param')</font>. |
---|
2244 | </font></p><p><font><b> OutParameter<a name="outparameter"></a>($stmt, $var, $name, |
---|
2245 | $maxLen = 4000, $type = false )</b></font></p> |
---|
2246 | <font> Binds a PHP variable as output from a stored procedure variable. The parameter <i>$stmt</i> |
---|
2247 | is the value returned by PrepareSP(), <i>$var</i> is the PHP variable you want to bind, <i>$name</i> |
---|
2248 | is the name of the stored procedure variable. Optional is <i>$maxLen</i>, the maximum length of the |
---|
2249 | data to bind, and <i>$type</i> which is database dependant. |
---|
2250 | </font><p> |
---|
2251 | <font> OutParameter() is a wrapper function that calls Parameter() with $isOutput=true. |
---|
2252 | The advantage of this function is that it is self-documenting, because |
---|
2253 | the $isOutput parameter is no longer needed. Only for mssql |
---|
2254 | and oci8 currently. |
---|
2255 | </font></p><p> |
---|
2256 | <font>For an example, see <a href="#inparameter">InParameter</a>. |
---|
2257 | |
---|
2258 | </font></p><p><font><b> Parameter<a name="parameter"></a>($stmt, $var, $name, $isOutput=false, |
---|
2259 | $maxLen = 4000, $type = false )</b></font></p> |
---|
2260 | <p><font>Note: This function is deprecated, because of the new InParameter() and OutParameter() functions. |
---|
2261 | These are superior because they are self-documenting, unlike Parameter(). |
---|
2262 | </font></p><p><font>Adds a bind parameter suitable for return values or special data handling (eg. |
---|
2263 | LOBs) after a statement has been prepared using PrepareSP(). Only for mssql |
---|
2264 | and oci8 currently. The parameters are:<br> |
---|
2265 | <br> |
---|
2266 | $<i><b>stmt</b></i> Statement returned by Prepare() or PrepareSP().<br> |
---|
2267 | $<i><b>var</b></i> PHP variable to bind to. Make sure you pre-initialize it!<br> |
---|
2268 | $<i><b>name</b></i> Name of stored procedure variable name to bind to.<br> |
---|
2269 | [$<i><b>isOutput</b></i>] Indicates direction of parameter 0/false=IN 1=OUT |
---|
2270 | 2= IN/OUT. This is ignored in oci8 as this driver auto-detects the direction.<br> |
---|
2271 | [$<b>maxLen</b>] Maximum length of the parameter variable.<br> |
---|
2272 | [$<b>type</b>] Consult <a href="http://php.net/mssql_bind">mssql_bind</a> and |
---|
2273 | <a href="http://php.net/ocibindbyname">ocibindbyname</a> docs at php.net for |
---|
2274 | more info on legal values for type.</font></p> |
---|
2275 | <p><font>Lastly, in oci8, bind parameters can be reused without calling PrepareSP( ) |
---|
2276 | or Parameters again. This is not possible with mssql. An oci8 example:</font></p> |
---|
2277 | <pre><font>$id = 0; $i = 0;<br>$stmt = $db->PrepareSP( <font color="#993300">"update table set val=:i where id=:id"</font>);<br>$db->Parameter($stmt,$id,'id');<br>$db->Parameter($stmt,$i, 'i');<br>for ($cnt=0; $cnt < 1000; $cnt++) {<br> $id = $cnt; <br> $i = $cnt * $cnt; <font color="green"># works with oci8!</font> |
---|
2278 | $db->Execute($stmt); <br>}</font></pre> |
---|
2279 | <p><font><b>Bind<a name="bind"></a>($stmt, $var, $size=4001, $type=false, $name=false)</b></font></p> |
---|
2280 | |
---|
2281 | <p><font>This is a low-level function supported only by the oci8 |
---|
2282 | driver. <b>Avoid using</b> unless you only want to support Oracle. The Parameter( |
---|
2283 | ) function is the recommended way to go with bind variables.</font></p> |
---|
2284 | <p><font>Bind( ) allows you to use bind variables in your sql |
---|
2285 | statement. This binds a PHP variable to a name defined in an Oracle sql statement |
---|
2286 | that was previously prepared using Prepare(). Oracle named variables begin with |
---|
2287 | a colon, and ADOdb requires the named variables be called :0, :1, :2, :3, etc. |
---|
2288 | The first invocation of Bind() will match :0, the second invocation will match |
---|
2289 | :1, etc. Binding can provide 100% speedups for insert, select and update statements. |
---|
2290 | </font></p> |
---|
2291 | <p>The other variables, $size sets the buffer size for data storage, $type is |
---|
2292 | the optional descriptor type OCI_B_FILE (Binary-File), OCI_B_CFILE (Character-File), |
---|
2293 | OCI_B_CLOB (Character-LOB), OCI_B_BLOB (Binary-LOB) and OCI_B_ROWID (ROWID). |
---|
2294 | Lastly, instead of using the default :0, :1, etc names, you can define your |
---|
2295 | own bind-name using $name. |
---|
2296 | </p><p><font>The following example shows 3 bind variables being used: |
---|
2297 | p1, p2 and p3. These variables are bound to :0, :1 and :2.</font></p> |
---|
2298 | <pre>$stmt = $DB->Prepare("insert into table (col0, col1, col2) values (:0, :1, :2)");<br>$DB->Bind($stmt, $p1);<br>$DB->Bind($stmt, $p2);<br>$DB->Bind($stmt, $p3);<br>for ($i = 0; $i < $max; $i++) { <br> $p1 = ?; $p2 = ?; $p3 = ?;<br> $DB->Execute($stmt);<br>}</pre> |
---|
2299 | <p>You can also use named variables:</p> |
---|
2300 | <pre>$stmt = $DB->Prepare("insert into table (col0, col1, col2) values (:name0, :name1, :name2)");<br>$DB->Bind($stmt, $p1, "name0");<br>$DB->Bind($stmt, $p2, "name1");<br>$DB->Bind($stmt, $p3, "name2");<br>for ($i = 0; $i < $max; $i++) { <br> $p1 = ?; $p2 = ?; $p3 = ?;<br> $DB->Execute($stmt);<br>}</pre> |
---|
2301 | <p><b>LogSQL($enable=true)<a name="logsql"></a></b></p> |
---|
2302 | Call this method to install a SQL logging and timing function (using fnExecute). |
---|
2303 | Then all SQL statements are logged into an adodb_logsql table in a database. If |
---|
2304 | the adodb_logsql table does not exist, ADOdb will create the table if you have |
---|
2305 | the appropriate permissions. Returns the previous logging value (true for enabled, |
---|
2306 | false for disabled). Here are samples of the DDL for selected databases: |
---|
2307 | <p> |
---|
2308 | </p><pre> <b>mysql:</b> |
---|
2309 | CREATE TABLE adodb_logsql ( |
---|
2310 | created datetime NOT NULL, |
---|
2311 | sql0 varchar(250) NOT NULL, |
---|
2312 | sql1 text NOT NULL, |
---|
2313 | params text NOT NULL, |
---|
2314 | tracer text NOT NULL, |
---|
2315 | timer decimal(16,6) NOT NULL |
---|
2316 | ) |
---|
2317 | |
---|
2318 | <b>postgres:</b> |
---|
2319 | CREATE TABLE adodb_logsql ( |
---|
2320 | created timestamp NOT NULL, |
---|
2321 | sql0 varchar(250) NOT NULL, |
---|
2322 | sql1 text NOT NULL, |
---|
2323 | params text NOT NULL, |
---|
2324 | tracer text NOT NULL, |
---|
2325 | timer decimal(16,6) NOT NULL |
---|
2326 | ) |
---|
2327 | |
---|
2328 | <b>mssql:</b> |
---|
2329 | CREATE TABLE adodb_logsql ( |
---|
2330 | created datetime NOT NULL, |
---|
2331 | sql0 varchar(250) NOT NULL, |
---|
2332 | sql1 varchar(4000) NOT NULL, |
---|
2333 | params varchar(3000) NOT NULL, |
---|
2334 | tracer varchar(500) NOT NULL, |
---|
2335 | timer decimal(16,6) NOT NULL |
---|
2336 | ) |
---|
2337 | |
---|
2338 | <b>oci8:</b> |
---|
2339 | CREATE TABLE adodb_logsql ( |
---|
2340 | created date NOT NULL, |
---|
2341 | sql0 varchar(250) NOT NULL, |
---|
2342 | sql1 varchar(4000) NOT NULL, |
---|
2343 | params varchar(4000), |
---|
2344 | tracer varchar(4000), |
---|
2345 | timer decimal(16,6) NOT NULL |
---|
2346 | ) |
---|
2347 | </pre> |
---|
2348 | Usage: |
---|
2349 | <pre> $conn->LogSQL(); // turn on logging<br> :<br> $conn->Execute(...);<br> :<br> $conn->LogSQL(false); // turn off logging<br> <br> # output summary of SQL logging results<br> $perf = NewPerfMonitor($conn);<br> echo $perf->SuspiciousSQL();<br> echo $perf->ExpensiveSQL();<br></pre> |
---|
2350 | <p>One limitation of logging is that rollback also prevents SQL from being logged. |
---|
2351 | </p><p> |
---|
2352 | If you prefer to use another name for the table used to store the SQL, you can override it by calling |
---|
2353 | adodb_perf::table($tablename), where $tablename is the new table name (you will still need to manually |
---|
2354 | create the table yourself). An example: |
---|
2355 | </p><pre> include('adodb.inc.php');<br> include('adodb-perf.inc.php');<br> adodb_perf::table('my_logsql_table');<br></pre> |
---|
2356 | Also see <a href="docs-perf.htm">Performance Monitor</a>. |
---|
2357 | <p><font><b>fnExecute and fnCacheExecute properties<a name="fnexecute" id="fnexecute"></a></b></font></p> |
---|
2358 | <p>These two properties allow you to define bottleneck functions for all sql statements |
---|
2359 | processed by ADOdb. This allows you to perform statistical analysis and query-rewriting |
---|
2360 | of your sql. |
---|
2361 | </p><p><b>Examples of fnExecute</b></p> |
---|
2362 | <p>Here is an example of using fnExecute, to count all cached queries and non-cached |
---|
2363 | queries, you can do this:</p> |
---|
2364 | <pre><font color="#006600"># $db is the connection object</font> |
---|
2365 | function &CountExecs($db, $sql, $inputarray) |
---|
2366 | { |
---|
2367 | global $EXECS; |
---|
2368 | |
---|
2369 | if (!is_array(inputarray)) $EXECS++; |
---|
2370 | <font color="#006600"># handle 2-dimensional input arrays</font> |
---|
2371 | else if (is_array(reset($inputarray))) $EXECS += sizeof($inputarray); |
---|
2372 | else $EXECS++; |
---|
2373 | |
---|
2374 | <font color="#006600"># in PHP4.4 and PHP5, we need to return a value by reference</font> |
---|
2375 | $null = null; |
---|
2376 | return $null; |
---|
2377 | } |
---|
2378 | |
---|
2379 | <font color="#006600"># $db is the connection object</font> |
---|
2380 | function CountCachedExecs($db, $secs2cache, $sql, $inputarray) |
---|
2381 | {<br>global $CACHED; $CACHED++;<br>}<br><br>$db = NewADOConnection('mysql');<br>$db->Connect(...);<br>$db-><strong>fnExecute</strong> = 'CountExecs';<br>$db-><strong>fnCacheExecute</strong> = 'CountCachedExecs';<br> :<br> :<br><font color="#006600"># After many sql statements:</font>`<br>printf("<p>Total queries=%d; total cached=%d</p>",$EXECS+$CACHED, $CACHED);<br></pre> |
---|
2382 | <p>The fnExecute function is called before the sql is parsed and executed, so |
---|
2383 | you can perform a query rewrite. If you are passing in a prepared statement, |
---|
2384 | then $sql is an array (see <a href="#prepare">Prepare</a>). The fnCacheExecute |
---|
2385 | function is only called if the recordset returned was cached.<font> |
---|
2386 | The function parameters match the Execute and CacheExecute functions respectively, |
---|
2387 | except that $this (the connection object) is passed as the first parameter.</font></p> |
---|
2388 | <p>Since ADOdb 3.91, the behaviour of fnExecute varies depending on whether the |
---|
2389 | defined function returns a value. If it does not return a value, then the $sql |
---|
2390 | is executed as before. This is useful for query rewriting or counting sql queries. |
---|
2391 | </p><p> On the other hand, you might want to replace the Execute function with one |
---|
2392 | of your own design. If this is the case, then have your function return a value. |
---|
2393 | If a value is returned, that value is returned immediately, without any further |
---|
2394 | processing. This is used internally by ADOdb to implement LogSQL() functionality. |
---|
2395 | </p> |
---|
2396 | <p> |
---|
2397 | </p><hr /> |
---|
2398 | <h3><font>ADOConnection Utility Functions</font></h3> |
---|
2399 | <p><font><b>BlankRecordSet<a name="blankrecordset"></a>([$queryid])</b></font></p> |
---|
2400 | <p><font>No longer available - removed since 1.99.</font></p> |
---|
2401 | <p><font><b>Concat<a name="concat"></a>($s1,$s2,....)</b></font></p> |
---|
2402 | <p><font>Generates the sql string used to concatenate $s1, $s2, etc together. Uses the |
---|
2403 | string in the concat_operator field to generate the concatenation. Override |
---|
2404 | this function if a concatenation operator is not used, eg. MySQL.</font></p> |
---|
2405 | <p><font>Returns the concatenated string.</font></p> |
---|
2406 | <p><font><b>DBDate<a name="dbdate"></a>($date)</b></font></p> |
---|
2407 | <p><font>Format the $<b>date</b> in the format the database accepts - the return string is also quoted. This is used |
---|
2408 | when you are sending dates to the database (eg INSERT, UPDATE or where clause of SELECT statement). |
---|
2409 | The $<b>date</b> parameter can be a Unix integer timestamp or an ISO format |
---|
2410 | Y-m-d. Uses the fmtDate field, which holds the format to use. If null or false |
---|
2411 | or '' is passed in, it will be converted to an SQL null.</font></p> |
---|
2412 | <p><font>Returns the date as a quoted string.</font></p> |
---|
2413 | <pre> |
---|
2414 | $sql = "select * from atable where created > ".$db->DBDate("$year-$month-$day"); |
---|
2415 | $db->Execute($sql); |
---|
2416 | </pre> |
---|
2417 | <p>Note to retrieve a date column in a specific format, use <a href="#sqldate">SQLDate</a>. </p> |
---|
2418 | <p><font><b>BindDate<a name="binddate"></a>($date)</b></font></p> |
---|
2419 | <p><font>Format the $<b>date</b> in the bind format the database accepts. Normally |
---|
2420 | this means that the date string is not quoted, unlike DBDate, which quotes the string. |
---|
2421 | <pre> |
---|
2422 | $sql = "select * from atable where created > ".$db->Param('0'); |
---|
2423 | // or |
---|
2424 | $sql = "select * from atable where created > ?"; |
---|
2425 | $db->Execute($sql,array($db->BindDate("$year-$month-$day")); |
---|
2426 | </pre> |
---|
2427 | <p><font><b>DBTimeStamp<a name="dbtimestamp"></a>($ts)</b></font></p> |
---|
2428 | <p><font>Format the timestamp $<b>ts</b> in the format the database accepts; this can |
---|
2429 | be a Unix integer timestamp or an ISO format Y-m-d H:i:s. Uses the fmtTimeStamp |
---|
2430 | field, which holds the format to use. If null or false or '' is passed in, it |
---|
2431 | will be converted to an SQL null.</font></p> |
---|
2432 | <p><font>Returns the timestamp as a quoted string.</font></p> |
---|
2433 | <pre> |
---|
2434 | $sql = "select * from atable where created > ".$db->DBTimeStamp("$year-$month-$day $hr:$min:$secs"); |
---|
2435 | $db->Execute($sql); |
---|
2436 | </pre> |
---|
2437 | <p><font><b>BindTimeStamp<a name="bindtimestamp"></a>($ts)</b></font></p> |
---|
2438 | <p><font>Format the timestamp $<b>ts</b> in the bind format the database accepts. Normally |
---|
2439 | this means that the timestamp string is not quoted, unlike DBTimeStamp, which quotes the string. |
---|
2440 | <pre> |
---|
2441 | $sql = "select * from atable where created > ".$db->Param('0'); |
---|
2442 | // or |
---|
2443 | $sql = "select * from atable where created > ?"; |
---|
2444 | $db->Execute($sql,array($db->BindTimeStamp("$year-$month-$day $hr:$min:$secs")); |
---|
2445 | </pre> |
---|
2446 | <p><font><b>qstr<a name="qstr"></a>($s,[$magic_quotes_enabled</b>=false]<b>)</b></font></p> |
---|
2447 | <p><font>Quotes a string to be sent to the database. The $<b>magic_quotes_enabled</b> |
---|
2448 | parameter may look funny, but the idea is if you are quoting a string extracted |
---|
2449 | from a POST/GET variable, then pass get_magic_quotes_gpc() as the second parameter. |
---|
2450 | This will ensure that the variable is not quoted twice, once by <i>qstr</i> |
---|
2451 | and once by the <i>magic_quotes_gpc</i>.</font></p> |
---|
2452 | <p><font>Eg.<font face="Courier New, Courier, mono"> $s = $db->qstr(HTTP_GET_VARS['name'],get_magic_quotes_gpc());</font></font></p> |
---|
2453 | <p><font>Returns the quoted string.</font></p> |
---|
2454 | <p><font><b>Quote<a name="quote"></a>($s)</b></font></p> |
---|
2455 | <p><font>Quotes the string $s, escaping the database specific quote character as appropriate. |
---|
2456 | Formerly checked magic quotes setting, but this was disabled since 3.31 for |
---|
2457 | compatibility with PEAR DB. |
---|
2458 | </font></p><p><font><b>Affected_Rows<a name="affected_rows"></a>( )</b></font></p> |
---|
2459 | <p><font>Returns the number of rows affected by a update or delete statement. Returns |
---|
2460 | false if function not supported.</font></p> |
---|
2461 | <p><font>Not supported by interbase/firebird currently. </font></p> |
---|
2462 | <p><font><b>Insert_ID<a name="inserted_id"></a>( )</b></font></p> |
---|
2463 | <p><font>Returns the last autonumbering ID inserted. Returns false if function not supported. |
---|
2464 | </font></p> |
---|
2465 | <p><font>Only supported by databases that support auto-increment or object id's, such |
---|
2466 | as PostgreSQL, MySQL and MS SQL Server currently. PostgreSQL returns the OID, which |
---|
2467 | can change on a database reload.</font></p> |
---|
2468 | <p><font><b>RowLock<a name="rowlock"></a>($table,$where)</b></font></p> |
---|
2469 | <p><font>Lock a table row for the duration of a transaction. For example to lock record $id in table1: |
---|
2470 | </font></p><pre><font> $DB->StartTrans();<br> $DB->RowLock("table1","rowid=$id");<br> $DB->Execute($sql1);<br> $DB->Execute($sql2);<br> $DB->CompleteTrans();<br></font></pre> |
---|
2471 | <p><font>Supported in db2, interbase, informix, mssql, oci8, postgres, sybase. |
---|
2472 | </font></p><p><font><b>MetaDatabases<a name="metadatabases"></a>()</b></font></p> |
---|
2473 | <p><font>Returns a list of databases available on the server as an array. You have to |
---|
2474 | connect to the server first. Only available for ODBC, MySQL and ADO.</font></p> |
---|
2475 | <p><font><b>MetaTables<a name="metatables"></a>($ttype = false, $showSchema = false, |
---|
2476 | $mask=false)</b></font></p> |
---|
2477 | <p><font>Returns an array of tables and views for the current database as an array. |
---|
2478 | The array should exclude system catalog tables if possible. To only show tables, |
---|
2479 | use $db->MetaTables('TABLES'). To show only views, use $db->MetaTables('VIEWS'). |
---|
2480 | The $showSchema parameter currently works only for DB2, and when set to true, |
---|
2481 | will add the schema name to the table, eg. "SCHEMA.TABLE". </font></p> |
---|
2482 | <p><font>You can define a mask for matching. For example, setting $mask = 'TMP%' will |
---|
2483 | match all tables that begin with 'TMP'. Currently only mssql, oci8, odbc_mssql |
---|
2484 | and postgres* support $mask. |
---|
2485 | </font></p><p><font><b>MetaColumns<a name="metacolumns"></a>($table,$notcasesensitive=true)</b></font></p> |
---|
2486 | <p><font>Returns an array of ADOFieldObject's, one field object for every column of |
---|
2487 | $table. A field object is a class instance with (name, type, max_length) defined. |
---|
2488 | Currently Sybase does not recognise date types, and ADO cannot identify |
---|
2489 | the correct data type (so we default to varchar). |
---|
2490 | </font></p><p><font> The $notcasesensitive parameter determines whether we uppercase or lowercase the table name to normalize it |
---|
2491 | (required for some databases). Does not work with MySQL ISAM tables. |
---|
2492 | </font></p><p><font>For schema support, pass in the $table parameter, "$schema.$tablename". This is only |
---|
2493 | supported for selected databases. |
---|
2494 | </font></p><p><font><b>MetaColumnNames<a name="metacolumnames"></a>($table,$numericIndex=false)</b></font></p> |
---|
2495 | <p><font>Returns an array of column names for $table. Since ADOdb 4.22, this is an associative array, with the |
---|
2496 | keys in uppercase. Set $numericIndex=true if you want the old behaviour of numeric indexes (since 4.23). |
---|
2497 | </font></p><p> |
---|
2498 | <font>e.g. array('FIELD1' => 'Field1', 'FIELD2'=>'Field2') |
---|
2499 | </font></p><p> |
---|
2500 | </p><p><font><b>MetaPrimaryKeys<a name="metaprimarykeys"></a>($table, |
---|
2501 | $owner=false)</b></font> |
---|
2502 | </p> |
---|
2503 | <p><font>Returns an array containing column names that are the |
---|
2504 | primary keys of $table. Supported by mysql, odbc (including db2, odbc_mssql, |
---|
2505 | etc), mssql, postgres, interbase/firebird, oci8 currently. </font></p> |
---|
2506 | <p><font>Views (and some tables) have primary keys, but sometimes this information is not available from the |
---|
2507 | database. You can define a function ADODB_View_PrimaryKeys($databaseType, $database, $view, $owner) that |
---|
2508 | should return an array containing the fields that make up the primary key. If that function exists, |
---|
2509 | it will be called when MetaPrimaryKeys() cannot find a primary key for a table or view. |
---|
2510 | </font></p><pre><font>// In this example: dbtype = 'oci8', $db = 'mydb', $view = 'dataView', $owner = false <br>function ADODB_View_PrimaryKeys($dbtype,$db,$view,$owner)<br>{<br> switch(strtoupper($view)) {<br> case 'DATAVIEW': return array('DATAID');<br> default: return false;<br> }<br>}<br><br>$db = NewADOConnection('oci8');<br>$db->Connect('localhost','root','','mydb'); <br>$db->MetaPrimaryKeys('dataView');<br></font></pre> |
---|
2511 | <p><font><b>ServerInfo<a name="serverinfo" id="serverinfo"></a>()</b></font> |
---|
2512 | </p> |
---|
2513 | <p><font>Returns an array of containing two elements 'description' |
---|
2514 | and 'version'. The 'description' element contains the string description of |
---|
2515 | the database. The 'version' naturally holds the version number (which is also |
---|
2516 | a string).</font></p> |
---|
2517 | <p><font><b>MetaForeignKeys<a name="metaforeignkeys"></a>($table, $owner=false, $upper=false)</b> |
---|
2518 | </font></p><p><font>Returns an associate array of foreign keys, or false if not supported. For |
---|
2519 | example, if table employee has a foreign key where employee.deptkey points to |
---|
2520 | dept_table.deptid, and employee.posn=posn_table.postionid and employee.poscategory=posn_table.category, |
---|
2521 | then $conn->MetaForeignKeys('employee') will return |
---|
2522 | </font></p><pre><font> array(<br> 'dept_table' => array('deptkey=deptid'),<br> 'posn_table' => array('posn=positionid','poscategory=category')<br> )<br></font></pre> |
---|
2523 | <p><font>The optional schema or owner can be defined in $owner. If $upper is true, then |
---|
2524 | the table names (array keys) are upper-cased. |
---|
2525 | </font></p><hr /> |
---|
2526 | <h2><font>ADORecordSet<a name="adorecordset"></a></font></h2> |
---|
2527 | <p><font>When an SQL statement successfully is executed by <font face="Courier New, Courier, mono">ADOConnection->Execute($sql),</font>an |
---|
2528 | ADORecordSet object is returned. This object contains a virtual cursor so we |
---|
2529 | can move from row to row, functions to obtain information about the columns |
---|
2530 | and column types, and helper functions to deal with formating the results to |
---|
2531 | show to the user.</font></p> |
---|
2532 | <h3><font>ADORecordSet Fields</font></h3> |
---|
2533 | <p><font><b>fields: </b>Array containing the current row. This is not associative, but |
---|
2534 | is an indexed array from 0 to columns-1. See also the function <b><a href="#fields">Fields</a></b>, |
---|
2535 | which behaves like an associative array.</font></p> |
---|
2536 | <p><font><b>dataProvider</b>: The underlying mechanism used to connect to the database. |
---|
2537 | Normally set to <b>native</b>, unless using <b>odbc</b> or <b>ado</b>.</font></p> |
---|
2538 | <p><font><b>blobSize</b>: Maximum size of a char, string or varchar object before it |
---|
2539 | is treated as a Blob (Blob's should be shown with textarea's). See the <a href="#metatype">MetaType</a> |
---|
2540 | function.</font></p> |
---|
2541 | <p><font><b>sql</b>: Holds the sql statement used to generate this record set.</font></p> |
---|
2542 | <p><font><b>canSeek</b>: Set to true if Move( ) function works.</font></p> |
---|
2543 | <p><font><b>EOF</b>: True if we have scrolled the cursor past the last record.</font></p> |
---|
2544 | <h3><font>ADORecordSet Functions</font></h3> |
---|
2545 | <p><font><b>ADORecordSet( )</b></font></p> |
---|
2546 | <p><font>Constructer. Normally you never call this function yourself.</font></p> |
---|
2547 | <p><font><b>GetAssoc<a name="getassoc"></a>([$force_array])</b></font></p> |
---|
2548 | <p><font>Generates an associative array from the recordset. Note that is this function |
---|
2549 | is also <a href="#getassoc1">available</a> in the connection object. More details |
---|
2550 | can be found there.</font></p> |
---|
2551 | <font> </font> |
---|
2552 | <p><font><b>GetArray<a name="getarray"></a>([$number_of_rows])</b></font></p> |
---|
2553 | <p><font>Generate a 2-dimensional array of records from the current |
---|
2554 | cursor position, indexed from 0 to $number_of_rows - 1. If $number_of_rows |
---|
2555 | is undefined, till EOF.</font></p> |
---|
2556 | <p><font><b>GetRows<a name="getrows"></a>([$number_of_rows])</b></font></p> |
---|
2557 | <font>Generate a 2-dimensional array of records from the current |
---|
2558 | cursor position. Synonym for GetArray() for compatibility with Microsoft ADO. </font> |
---|
2559 | <p><font> <b>GetMenu<a name="getmenu"></a>($name, [$default_str=''], |
---|
2560 | [$blank1stItem=true], [$multiple_select=false], [$size=0], [$moreAttr=''])</b></font></p> |
---|
2561 | <p><font>Generate a HTML menu (<select><option><option></select>). |
---|
2562 | The first column of the recordset (fields[0]) will hold the string to display |
---|
2563 | in the option tags. If the recordset has more than 1 column, the second column |
---|
2564 | (fields[1]) is the value to send back to the web server.. The menu will be |
---|
2565 | given the name $<i>name</i>. </font></p> |
---|
2566 | <p><font> If $<i>default_str</i> is defined, then if $<i>default_str</i> == |
---|
2567 | fields[0], that field is selected. If $<i>blank1stItem</i> is true, the first |
---|
2568 | option is empty. You can also set the first option strings by setting $blank1stItem |
---|
2569 | = "$value:$text".</font></p> |
---|
2570 | <p><font>$<i>Default_str</i> can be array for a multiple select |
---|
2571 | listbox.</font></p> |
---|
2572 | <p><font>To get a listbox, set the $<i>size</i> to a non-zero |
---|
2573 | value (or pass $default_str as an array). If $<i>multiple_select</i> is true |
---|
2574 | then a listbox will be generated with $<i>size</i> items (or if $size==0, |
---|
2575 | then 5 items) visible, and we will return an array to a server. Lastly use |
---|
2576 | $<i>moreAttr </i> to add additional attributes such as javascript or styles. </font></p> |
---|
2577 | <p><font>Menu Example 1: <code>GetMenu('menu1','A',true)</code> will |
---|
2578 | generate a menu: |
---|
2579 | <select name="menu1"><option> </option><option value="1" selected="selected">A </option><option value="2">B </option><option value="3">C </option></select> |
---|
2580 | for the data (A,1), (B,2), (C,3). Also see <a href="#ex5">example 5</a>.</font></p> |
---|
2581 | <p><font>Menu Example 2: For the same data, <code>GetMenu('menu1',array('A','B'),false)</code> will |
---|
2582 | generate a menu with both A and B selected: <br> |
---|
2583 | <select name="menu1" multiple="multiple" size="3"><option value="1" selected="selected">A </option><option value="2" selected="selected">B </option><option value="3">C </option></select> |
---|
2584 | </font></p> |
---|
2585 | <p><font> <b>GetMenu2<a name="getmenu2"></a>($name, [$default_str=''], |
---|
2586 | [$blank1stItem=true], [$multiple_select=false], [$size=0], [$moreAttr=''])</b></font></p> |
---|
2587 | <p><font>This is nearly identical to GetMenu, except that the |
---|
2588 | $<i>default_str</i> is matched to fields[1] (the option values).</font></p> |
---|
2589 | <p><font>Menu Example 3: Given the data in menu example 2, <code>GetMenu2('menu1',array('1','2'),false)</code> will |
---|
2590 | generate a menu with both A and B selected in menu example 2, but this time |
---|
2591 | the selection is based on the 2nd column, which holds the values to return |
---|
2592 | to the Web server. </font></p> |
---|
2593 | <p><font><b>UserDate<a name="userdate"></a>($str, [$fmt])</b></font></p> |
---|
2594 | <p><font>Converts the date string $<i>str</i> to another format. |
---|
2595 | The date format is Y-m-d, or Unix timestamp format. The default $<i>fmt</i> is |
---|
2596 | Y-m-d.</font></p> |
---|
2597 | <p><font><b>UserTimeStamp<a name="usertimestamp"></a>($str, [$fmt])</b></font></p> |
---|
2598 | <p><font>Converts the timestamp string $<b>str</b> to another |
---|
2599 | format. The timestamp format is Y-m-d H:i:s, as in '2002-02-28 23:00:12', |
---|
2600 | or Unix timestamp format. UserTimeStamp calls UnixTimeStamp to parse $<i>str</i>, |
---|
2601 | and $<i>fmt</i> defaults to Y-m-d H:i:s if not defined. </font></p> |
---|
2602 | <p><font><b>UnixDate<a name="unixdate"></a>($str)</b></font></p> |
---|
2603 | <p><font>Parses the date string $<b>str</b> and returns it in |
---|
2604 | unix mktime format (eg. a number indicating the seconds after January 1st, |
---|
2605 | 1970). Expects the date to be in Y-m-d H:i:s format, except for Sybase and |
---|
2606 | Microsoft SQL Server, where M d Y is also accepted (the 3 letter month strings |
---|
2607 | are controlled by a global array, which might need localisation).</font></p> |
---|
2608 | <p><font>This function is available in both ADORecordSet and |
---|
2609 | ADOConnection since 1.91.</font></p> |
---|
2610 | <p><font><b>UnixTimeStamp<a name="unixtimestamp"></a>($str)</b></font></p> |
---|
2611 | <p><font>Parses the timestamp string $<b>str</b> and returns |
---|
2612 | it in unix mktime format (eg. a number indicating the seconds after January |
---|
2613 | 1st, 1970). Expects the date to be in "Y-m-d, H:i:s" (1970-12-24, 00:00:00) |
---|
2614 | or "Y-m-d H:i:s" (1970-12-24 00:00:00) or "YmdHis" (19701225000000) format, |
---|
2615 | except for Sybase and Microsoft SQL Server, where "M d Y h:i:sA" (Dec 25 |
---|
2616 | 1970 00:00:00AM) is also accepted (the 3 letter month strings are controlled |
---|
2617 | by a global array, which might need localisation).</font></p> |
---|
2618 | <font> |
---|
2619 | </font><p><font>This function is available in both ADORecordSet |
---|
2620 | and ADOConnection since 1.91. </font></p> |
---|
2621 | <p><font><b>OffsetDate<a name="OffsetDate"></a>($dayFraction, |
---|
2622 | $basedate=false)</b></font></p> |
---|
2623 | <p><font>Returns a string with the native SQL functions to calculate |
---|
2624 | future and past dates based on $basedate in a portable fashion. If $basedate |
---|
2625 | is not defined, then the current date (at 12 midnight) is used. Returns the |
---|
2626 | SQL string that performs the calculation when passed to Execute(). </font></p> |
---|
2627 | <p><font>For example, in Oracle, to find the date and time that |
---|
2628 | is 2.5 days from today, you can use:</font></p> |
---|
2629 | <pre><font># get date one week from now<br>$fld = $conn->OffsetDate(7); // returns "(trunc(sysdate)+7")</font></pre> |
---|
2630 | <pre><font># get date and time that is 60 hours from current date and time<br>$fld = $conn->OffsetDate(2.5, $conn->sysTimeStamp); // returns "(sysdate+2.5)"<br><br>$conn->Execute("UPDATE TABLE SET dodate=$fld WHERE ID=$id");</font></pre> |
---|
2631 | <p><font> This function is available for mysql, mssql, oracle, oci8 and postgresql drivers |
---|
2632 | since 2.13. It might work with other drivers provided they allow performing |
---|
2633 | numeric day arithmetic on dates.</font></p> |
---|
2634 | <font> </font> |
---|
2635 | <p><font><b>SQLDate<a name="sqldate"></a>($dateFormat, $basedate=false)</b></font></p> |
---|
2636 | <font>Returns a string which contains the native SQL functions |
---|
2637 | to format a date or date column $basedate. This is used when retrieving date columns in SELECT statements. |
---|
2638 | For sending dates to the database (eg. in UPDATE, INSERT or the where clause of SELECT statements) |
---|
2639 | use <a href="#dbdate">DBDate</a>. It uses a case-sensitive |
---|
2640 | $dateFormat, which supports: </font> |
---|
2641 | <pre><font> |
---|
2642 | Y: 4-digit Year |
---|
2643 | Q: Quarter (1-4) |
---|
2644 | M: Month (Jan-Dec) |
---|
2645 | m: Month (01-12) |
---|
2646 | d: Day (01-31) |
---|
2647 | H: Hour (00-23) |
---|
2648 | h: Hour (1-12) |
---|
2649 | i: Minute (00-59) |
---|
2650 | s: Second (00-60) |
---|
2651 | A: AM/PM indicator |
---|
2652 | w: day of week (0-6 or 1-7 depending on DB) |
---|
2653 | l: day of week (as string - lowercase L) |
---|
2654 | W: week in year (0..53 for MySQL, 1..53 for PostgreSQL and Oracle) |
---|
2655 | </font></pre> |
---|
2656 | <p><font>All other characters are treated as strings. You can |
---|
2657 | also use \ to escape characters. Available on selected databases, including |
---|
2658 | mysql, postgresql, mssql, oci8 and DB2. </font></p> |
---|
2659 | <p><font>This is useful in writing portable sql statements that |
---|
2660 | GROUP BY on dates. For example to display total cost of goods sold broken |
---|
2661 | by quarter (dates are stored in a field called postdate): </font></p> |
---|
2662 | <pre><font> $sqlfn = $db->SQLDate('Y-\QQ','postdate'); # get sql that formats postdate to output 2002-Q1<br> $sql = "SELECT $sqlfn,SUM(cogs) FROM table GROUP BY $sqlfn ORDER BY 1 desc";<br> </font></pre> |
---|
2663 | <p><font><b>MoveNext<a name="movenext"></a>( )</b></font></p> |
---|
2664 | <p><font>Move the internal cursor to the next row. The <i>$this->fields</i> array |
---|
2665 | is automatically updated. Returns false if unable to do so (normally because |
---|
2666 | EOF has been reached), otherwise true. </font></p> |
---|
2667 | <p><font> If EOF is reached, then the $this->fields array |
---|
2668 | is set to false (this was only implemented consistently in ADOdb 3.30). For |
---|
2669 | the pre-3.30 behaviour of $this->fields (at EOF), set the global variable |
---|
2670 | $ADODB_COMPAT_FETCH = true.</font></p> |
---|
2671 | <p><font>Example:</font></p> |
---|
2672 | <pre><font>$rs = $db->Execute($sql);<br>if ($rs) <br> while (!$rs->EOF) {<br> ProcessArray($rs->fields); <br> $rs->MoveNext();<br> } </font></pre> |
---|
2673 | <p><font><b>Move<a name="move"></a>($to)</b></font></p> |
---|
2674 | <p><font>Moves the internal cursor to a specific row $<b>to</b>. |
---|
2675 | Rows are zero-based eg. 0 is the first row. The <b>fields</b> array is automatically |
---|
2676 | updated. For databases that do not support scrolling internally, ADOdb will |
---|
2677 | simulate forward scrolling. Some databases do not support backward scrolling. |
---|
2678 | If the $<b>to</b> position is after the EOF, $<b>to</b> will move to the |
---|
2679 | end of the RecordSet for most databases. Some obscure databases using odbc |
---|
2680 | might not behave this way.</font></p> |
---|
2681 | <p><font>Note: This function uses <i>absolute positioning</i>, |
---|
2682 | unlike Microsoft's ADO.</font></p> |
---|
2683 | <p><font>Returns true or false. If false, the internal cursor |
---|
2684 | is not moved in most implementations, so AbsolutePosition( ) will return |
---|
2685 | the last cursor position before the Move( ). </font></p> |
---|
2686 | <p><font><b>MoveFirst<a name="movefirst"></a>()</b></font></p> |
---|
2687 | <p><font>Internally calls Move(0). Note that some databases do |
---|
2688 | not support this function.</font></p> |
---|
2689 | <p><font><b>MoveLast<a name="movelast"></a>()</b></font></p> |
---|
2690 | <p><font>Internally calls Move(RecordCount()-1). Note that some |
---|
2691 | databases do not support this function.</font></p> |
---|
2692 | <p><font><b>GetRowAssoc</b><a name="getrowassoc"></a>($toUpper=true)</font></p> |
---|
2693 | <p><font>Returns an associative array containing the current |
---|
2694 | row. The keys to the array are the column names. The column names are upper-cased |
---|
2695 | for easy access. To get the next row, you will still need to call MoveNext(). </font></p> |
---|
2696 | <p><font>For example:<br> |
---|
2697 | Array ( [ID] => 1 [FIRSTNAME] => Caroline [LASTNAME] => Miranda [CREATED] |
---|
2698 | => 2001-07-05 ) </font></p> |
---|
2699 | <p><font>Note: do not use GetRowAssoc() with $ADODB_FETCH_MODE |
---|
2700 | = ADODB_FETCH_ASSOC. Because they have the same functionality, they will |
---|
2701 | interfere with each other.</font></p> |
---|
2702 | <font> |
---|
2703 | </font><p><font><b>AbsolutePage<a name="absolutepage"></a>($page=-1) </b></font></p> |
---|
2704 | <p><font>Returns the current page. Requires PageExecute()/CachePageExecute() to be called. |
---|
2705 | See <a href="#ex8">Example 8</a>.</font></p> |
---|
2706 | <font> |
---|
2707 | <p><b>AtFirstPage<a name="atfirstpage">($status='')</a></b></p> |
---|
2708 | <p>Returns true if at first page (1-based). Requires PageExecute()/CachePageExecute() |
---|
2709 | to be called. See <a href="#ex8">Example 8</a>.</p> |
---|
2710 | <p><b>AtLastPage<a name="atlastpage">($status='')</a></b></p> |
---|
2711 | <p>Returns true if at last page (1-based). Requires PageExecute()/CachePageExecute() |
---|
2712 | to be called. See <a href="#ex8">Example 8</a>.</p> |
---|
2713 | <p><b>Fields</b><a name="fields"></a>(<b>$colname</b>)</p> |
---|
2714 | <p>Returns the value of the associated column $<b>colname</b> for the current |
---|
2715 | row. The column name is case-insensitive.</p> |
---|
2716 | <p>This is a convenience function. For higher performance, use <a href="#adodb_fetch_mode">$ADODB_FETCH_MODE</a>. </p> |
---|
2717 | <p><b>FetchRow</b><a name="fetchrow"></a>()</p> |
---|
2718 | </font><p><font>Returns array containing current row, or false |
---|
2719 | if EOF. FetchRow( ) internally moves to the next record after returning the |
---|
2720 | current row. </font></p> |
---|
2721 | <p><font>Warning: Do not mix using FetchRow() with MoveNext().</font></p> |
---|
2722 | <p><font>Usage:</font></p> |
---|
2723 | <pre><font>$rs = $db->Execute($sql);<br>if ($rs)<br> while ($arr = $rs->FetchRow()) {<br> # process $arr <br> }</font></pre> |
---|
2724 | <p><font><b>FetchInto</b><a name="fetchinto"></a>(<b>&$array</b>)</font></p> |
---|
2725 | <p><font> Sets $array to the current row. Returns PEAR_Error |
---|
2726 | object if EOF, 1 if ok (DB_OK constant). If PEAR is undefined, false is returned |
---|
2727 | when EOF. FetchInto( ) internally moves to the next record after returning |
---|
2728 | the current row. </font></p> |
---|
2729 | <p><font> FetchRow() is easier to use. See above.</font></p> |
---|
2730 | <font> </font> |
---|
2731 | <p><font><b>FetchField<a name="fetchfield"></a>($column_number)</b></font></p> |
---|
2732 | <p><font>Returns an object containing the <b>name</b>, <b>type</b> and <b>max_length</b> of |
---|
2733 | the associated field. If the max_length cannot be determined reliably, it |
---|
2734 | will be set to -1. The column numbers are zero-based. See <a href="#ex2">example |
---|
2735 | 2.</a></font></p> |
---|
2736 | <p><font><b>FieldCount<a name="fieldcount"></a>( )</b></font></p> |
---|
2737 | <p><font>Returns the number of fields (columns) in the record |
---|
2738 | set.</font></p> |
---|
2739 | <p><font><b>RecordCount<a name="recordcount"></a>( )</b></font></p> |
---|
2740 | <p><font>Returns the number of rows in the record set. If the |
---|
2741 | number of records returned cannot be determined from the database driver |
---|
2742 | API, we will buffer all rows and return a count of the rows after all the |
---|
2743 | records have been retrieved. This buffering can be disabled (for performance |
---|
2744 | reasons) by setting the global variable $ADODB_COUNTRECS = false. When disabled, |
---|
2745 | RecordCount( ) will return -1 for certain databases. See the supported databases |
---|
2746 | list above for more details. </font></p> |
---|
2747 | <p><font> RowCount is a synonym for RecordCount.</font></p> |
---|
2748 | <p><font><b>PO_RecordCount<a name="po_recordcount"></a>($table, |
---|
2749 | $where)</b></font></p> |
---|
2750 | <p><font>Returns the number of rows in the record set. If the |
---|
2751 | database does not support this, it will perform a SELECT COUNT(*) on the |
---|
2752 | table $table, with the given $where condition to return an estimate of the |
---|
2753 | recordset size.</font></p> |
---|
2754 | <p><font>$numrows = $rs->PO_RecordCount("articles_table", "group=$group");</font></p> |
---|
2755 | <font><b> NextRecordSet<a name="nextrecordset" id="nextrecordset"></a>()</b> </font> |
---|
2756 | <p><font>For databases that allow multiple recordsets to be returned |
---|
2757 | in one query, this function allows you to switch to the next recordset. Currently |
---|
2758 | only supported by mssql driver.</font></p> |
---|
2759 | <pre><font>$rs = $db->Execute('execute return_multiple_rs');<br>$arr1 = $rs->GetArray();<br>$rs->NextRecordSet();<br>$arr2 = $rs->GetArray();</font></pre> |
---|
2760 | <p><font><b>FetchObject<a name="fetchobject"></a>($toupper=true)</b></font></p> |
---|
2761 | <p><font>Returns the current row as an object. If you set $toupper |
---|
2762 | to true, then the object fields are set to upper-case. Note: The newer FetchNextObject() |
---|
2763 | is the recommended way of accessing rows as objects. See below.</font></p> |
---|
2764 | <p><font><b>FetchNextObject<a name="fetchnextobject"></a>($toupper=true)</b></font></p> |
---|
2765 | <p><font>Gets the current row as an object and moves to the next |
---|
2766 | row automatically. Returns false if at end-of-file. If you set $toupper to |
---|
2767 | true, then the object fields are set to upper-case. Note that for some drivers such as mssql, you need to SetFetchMode(ADODB_FETCH_ASSOC) or SetFetchMode(ADODB_FETCH_BOTH).</font></p> |
---|
2768 | <pre><font>$rs = $db->Execute('select firstname,lastname from table');<br>if ($rs) {<br> while ($o = $rs->FetchNextObject()) {<br> print "$o->FIRSTNAME, $o->LASTNAME<BR>";<br> }<br>}<br></font></pre> |
---|
2769 | <p><font>There is some trade-off in speed in using FetchNextObject(). |
---|
2770 | If performance is important, you should access rows with the <code>fields[]</code> array. <b>FetchObj<a name="fetchobj" id="fetchobj"></a>()</b> </font></p> |
---|
2771 | <p><font>Returns the current record as an object. Fields are |
---|
2772 | not upper-cased, unlike FetchObject. |
---|
2773 | </font></p> |
---|
2774 | <p><font><b>FetchNextObj<a name="fetchnextobj" id="fetchnextobj"></a>()</b> </font></p> |
---|
2775 | <p><font>Returns the current record as an object and moves to |
---|
2776 | the next record. If EOF, false is returned. Fields are not upper-cased, unlike |
---|
2777 | FetctNextObject. </font></p> |
---|
2778 | <font> |
---|
2779 | <p><b>CurrentRow<a name="currentrow"></a>( )</b></p> |
---|
2780 | <p>Returns the current row of the record set. 0 is the first row.</p> |
---|
2781 | <p><b>AbsolutePosition<a name="abspos"></a>( )</b></p> |
---|
2782 | <p>Synonym for <b>CurrentRow</b> for compatibility with ADO. Returns the current |
---|
2783 | row of the record set. 0 is the first row.</p> |
---|
2784 | <p><b>MetaType<a name="metatype"></a>($nativeDBType[,$field_max_length],[$fieldobj])</b></p> |
---|
2785 | <p>Determine what <i>generic</i> meta type a database field type is given its |
---|
2786 | native type $<b>nativeDBType</b> as a string and the length of the field $<b>field_max_length</b>. |
---|
2787 | Note that field_max_length can be -1 if it is not known. The field object returned |
---|
2788 | by FetchField() can be passed in $<b>fieldobj</b> or as the 1st parameter <b>$nativeDBType</b>. |
---|
2789 | This is useful for databases such as <i>mysql</i> which has additional properties |
---|
2790 | in the field object such as <i>primary_key</i>. </p> |
---|
2791 | <p>Uses the field <b>blobSize</b> and compares it with $<b>field_max_length</b> to |
---|
2792 | determine whether the character field is actually a blob.</p> |
---|
2793 | For example, $db->MetaType('char') will return 'C'. |
---|
2794 | <p>Returns:</p> |
---|
2795 | <ul> |
---|
2796 | <li><b>C</b>: Character fields that should be shown in a <input type="text"> tag. </li> |
---|
2797 | <li><b>X</b>: Clob (character large objects), or large text fields that should |
---|
2798 | be shown in a <textarea></li> |
---|
2799 | <li><b>D</b>: Date field</li> |
---|
2800 | <li><b>T</b>: Timestamp field</li> |
---|
2801 | <li><b>L</b>: Logical field (boolean or bit-field)</li> |
---|
2802 | <li><b>N</b>: Numeric field. Includes decimal, numeric, floating point, and |
---|
2803 | real. </li> |
---|
2804 | <li><b>I</b>: Integer field. </li> |
---|
2805 | <li><b>R</b>: Counter or Autoincrement field. Must be numeric.</li> |
---|
2806 | <li><b>B</b>: Blob, or binary large objects. </li> |
---|
2807 | </ul> |
---|
2808 | </font><p><font> Since ADOdb 3.0, MetaType accepts $fieldobj |
---|
2809 | as the first parameter, instead of $nativeDBType. </font></p> |
---|
2810 | <font> </font> |
---|
2811 | <p><font><b>Close( )<a name="rsclose"></a></b></font></p> |
---|
2812 | <p><font>Closes the recordset, cleaning all memory and resources |
---|
2813 | associated with the recordset. </font></p> |
---|
2814 | <p> |
---|
2815 | <font>If memory management is not an issue, you do not need to |
---|
2816 | call this function as recordsets are closed for you by PHP at the end of the |
---|
2817 | script. SQL statements such as INSERT/UPDATE/DELETE do not really return a recordset, |
---|
2818 | so you do not have to call Close() for such SQL statements.</font></p> |
---|
2819 | <hr /> |
---|
2820 | <h3><font>function rs2html<a name="rs2html"></a>($adorecordset,[$tableheader_attributes], |
---|
2821 | [$col_titles])</font></h3> |
---|
2822 | <p><font>This is a standalone function (rs2html = recordset to |
---|
2823 | html) that is similar to PHP's <i>odbc_result_all</i> function, it prints |
---|
2824 | a ADORecordSet, $<b>adorecordset</b> as a HTML table. $<b>tableheader_attributes</b> allow |
---|
2825 | you to control the table <i>cellpadding</i>, <i>cellspacing</i> and <i>border</i> attributes. |
---|
2826 | Lastly you can replace the database column names with your own column titles |
---|
2827 | with the array $<b>col_titles</b>. This is designed more as a quick debugging |
---|
2828 | mechanism, not a production table recordset viewer.</font></p> |
---|
2829 | <p><font>You will need to include the file <i>tohtml.inc.php</i>.</font></p> |
---|
2830 | <p><font>Example of rs2html:<b><font color="#336600"><a name="exrs2html"></a></font></b></font></p> |
---|
2831 | <pre><font><b><font color="#336600"><?<br>include('tohtml.inc.php')</font></b>; # load code common to ADOdb <br><b>include</b>('adodb.inc.php'); # load code common to ADOdb <br>$<font color="#663300">conn</font> = &ADONewConnection('mysql'); # create a connection <br>$<font color="#663300">conn</font>->PConnect('localhost','userid','','agora');# connect to MySQL, agora db<br>$<font color="#663300">sql</font> = 'select CustomerName, CustomerID from customers'; <br>$<font color="#663300">rs</font> = $<font color="#663300">conn</font>->Execute($sql); <br><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>'));<br>?></b></font></pre> |
---|
2832 | <hr /> |
---|
2833 | <h3><font>Differences between this ADOdb library and Microsoft |
---|
2834 | ADO<a name="adodiff"></a></font></h3> |
---|
2835 | <ol> |
---|
2836 | <font> |
---|
2837 | <li>ADOdb only supports recordsets created by a connection object. Recordsets |
---|
2838 | cannot be created independently.</li> |
---|
2839 | <li>ADO properties are implemented as functions in ADOdb. This makes it easier |
---|
2840 | to implement any enhanced ADO functionality in the future.</li> |
---|
2841 | <li>ADOdb's <font face="Courier New, Courier, mono">ADORecordSet->Move()</font> uses |
---|
2842 | absolute positioning, not relative. Bookmarks are not supported.</li> |
---|
2843 | <li><font face="Courier New, Courier, mono">ADORecordSet->AbsolutePosition() </font>cannot |
---|
2844 | be used to move the record cursor.</li> |
---|
2845 | <li>ADO Parameter objects are not supported. Instead we have the ADOConnection::<a href="#parameter">Parameter</a>( |
---|
2846 | ) function, which provides a simpler interface for calling preparing parameters |
---|
2847 | and calling stored procedures.</li> |
---|
2848 | <li>Recordset properties for paging records are available, but implemented as |
---|
2849 | in <a href="#ex8">Example 8</a>.</li> |
---|
2850 | </font></ol> |
---|
2851 | <hr /> |
---|
2852 | <h1><font>Database Driver Guide<a name="driverguide"></a></font></h1> |
---|
2853 | <p><font>This describes how to create a class to connect to a |
---|
2854 | new database. To ensure there is no duplication of work, kindly email me |
---|
2855 | at jlim#natsoft.com.my if you decide to create such a class.</font></p> |
---|
2856 | <p><font>First decide on a name in lower case to call the database |
---|
2857 | type. Let's say we call it xbase. </font></p> |
---|
2858 | <p><font>Then we need to create two classes ADODB_xbase and ADORecordSet_xbase |
---|
2859 | in the file adodb-xbase.inc.php.</font></p> |
---|
2860 | <p><font>The simplest form of database driver is an adaptation |
---|
2861 | of an existing ODBC driver. Then we just need to create the class <i>ADODB_xbase |
---|
2862 | extends ADODB_odbc</i> to support the new <b>date</b> and <b>timestamp</b> formats, |
---|
2863 | the <b>concatenation</b> operator used, <b>true</b> and <b>false</b>. For |
---|
2864 | the<i> ADORecordSet_xbase extends ADORecordSet_odbc </i>we need to change |
---|
2865 | the <b>MetaType</b> function. See<b> adodb-vfp.inc.php</b> as an example.</font></p> |
---|
2866 | <p><font>More complicated is a totally new database driver that |
---|
2867 | connects to a new PHP extension. Then you will need to implement several |
---|
2868 | functions. Fortunately, you do not have to modify most of the complex code. |
---|
2869 | You only need to override a few stub functions. See <b>adodb-mysql.inc.php</b> for |
---|
2870 | example.</font></p> |
---|
2871 | <p><font>The default date format of ADOdb internally is YYYY-MM-DD |
---|
2872 | (Ansi-92). All dates should be converted to that format when passing to an |
---|
2873 | ADOdb date function. See Oracle for an example how we use ALTER SESSION to |
---|
2874 | change the default date format in _pconnect _connect.</font></p> |
---|
2875 | <p><font><b>ADOConnection Functions to Override</b></font></p> |
---|
2876 | <p><font>Defining a constructor for your ADOConnection derived |
---|
2877 | function is optional. There is no need to call the base class constructor.</font></p> |
---|
2878 | <p><font>_<b>connect</b>: Low level implementation of Connect. |
---|
2879 | Returns true or false. Should set the _<b>connectionID</b>.</font></p> |
---|
2880 | <p><font>_<b>pconnect:</b> Low level implemention of PConnect. |
---|
2881 | Returns true or false. Should set the _<b>connectionID</b>.</font></p> |
---|
2882 | <p><font>_<b>query</b>: Execute a query. Returns the queryID, |
---|
2883 | or false.</font></p> |
---|
2884 | <p><font>_<b>close: </b>Close the connection -- PHP should clean |
---|
2885 | up all recordsets. </font></p> |
---|
2886 | <p><font><b>ErrorMsg</b>: Stores the error message in the private |
---|
2887 | variable _errorMsg. </font></p> |
---|
2888 | <p><font><b>ADOConnection Fields to Set</b></font></p> |
---|
2889 | <p><font>_<b>bindInputArray</b>: Set to true if binding of parameters |
---|
2890 | for SQL inserts and updates is allowed using ?, eg. as with ODBC.</font></p> |
---|
2891 | <p><font><b>fmtDate</b></font></p> |
---|
2892 | <p><font><b>fmtTimeStamp</b></font></p> |
---|
2893 | <p><font><b>true</b></font></p> |
---|
2894 | <p><font><b>false</b></font></p> |
---|
2895 | <p><font><b>concat_operator</b></font></p> |
---|
2896 | <p><font><b>replaceQuote</b></font></p> |
---|
2897 | <p><font><b>hasLimit</b> support SELECT * FROM TABLE LIMIT 10 |
---|
2898 | of MySQL.</font></p> |
---|
2899 | <p><font><b>hasTop</b> support Microsoft style SELECT TOP 10 |
---|
2900 | * FROM TABLE.</font></p> |
---|
2901 | <p><font><b>ADORecordSet Functions to Override</b></font></p> |
---|
2902 | <p><font>You will need to define a constructor for your ADORecordSet |
---|
2903 | derived class that calls the parent class constructor.</font></p> |
---|
2904 | <p><font><b>FetchField: </b> as documented above in ADORecordSet</font></p> |
---|
2905 | <p><font>_<b>initrs</b>: low level initialization of the recordset: |
---|
2906 | setup the _<b>numOfRows</b> and _<b>numOfFields</b> fields -- called by the |
---|
2907 | constructor.</font></p> |
---|
2908 | <p><font>_<b>seek</b>: seek to a particular row. Do not load |
---|
2909 | the data into the fields array. This is done by _fetch. Returns true or false. |
---|
2910 | Note that some implementations such as Interbase do not support seek. Set |
---|
2911 | canSeek to false.</font></p> |
---|
2912 | <p><font>_<b>fetch</b>: fetch a row using the database extension |
---|
2913 | function and then move to the next row. Sets the <b>fields</b> array. If |
---|
2914 | the parameter $ignore_fields is true then there is no need to populate the <b>fields</b> array, |
---|
2915 | just move to the next row. then Returns true or false.</font></p> |
---|
2916 | <p><font>_<b>close</b>: close the recordset</font></p> |
---|
2917 | <p><font><b>Fields</b>: If the array row returned by the PHP |
---|
2918 | extension is not an associative one, you will have to override this. See |
---|
2919 | adodb-odbc.inc.php for an example. For databases such as MySQL and MSSQL |
---|
2920 | where an associative array is returned, there is no need to override this |
---|
2921 | function.</font></p> |
---|
2922 | <p><font><b>ADOConnection Fields to Set</b></font></p> |
---|
2923 | <p><font>canSeek: Set to true if the _seek function works.</font></p> |
---|
2924 | <h2><font>Optimizing PHP</font></h2> |
---|
2925 | For info on tuning PHP, read this article on <a href="http://phplens.com/lens/php-book/optimizing-debugging-php.php">Optimizing |
---|
2926 | PHP</a>. </font></p> |
---|
2927 | |
---|
2928 | <h2><font>Change Log<a name="Changes"></a><a name="changes"></a><a name="changelog"></a></font></h2> |
---|
2929 | |
---|
2930 | <p><a name="4.95"></a><b>4.95/5.01 17 May 2007</b> |
---|
2931 | <p>CacheFlush debug outp() passed in invalid parameters. Fixed. |
---|
2932 | <p>Added Thai language file for adodb. Thx Trirat Petchsingh rosskouk#gmail.com and Marcos Pont</p> |
---|
2933 | <p>Added zerofill checking support to MetaColumns for mysql and mysqli. |
---|
2934 | <p>CacheFlush no longer deletes all files/directories. Only *.cache files deleted.</p> |
---|
2935 | <p>DB2 timestamp format changed to var $fmtTimeStamp = "'Y-m-d-H:i:s'";</p> |
---|
2936 | <p>Added some code sanitization to AutoExecute in adodb-lib.inc.php.</p> |
---|
2937 | <p>Due to typo, all connections in adodb-oracle.inc.php would become persistent, even non-persistent ones. Fixed.</p> |
---|
2938 | <P>Oci8 DBTimeStamp uses 24 hour time for input now, so you can perform string comparisons between 2 DBTimeStamp values.</P> |
---|
2939 | <p>Some PHP4.4 compat issues fixed in adodb-session2.inc.php</p> |
---|
2940 | <p>For ADOdb 5.01, fixed some adodb-datadict.inc.php MetaType compat issues with PHP5. |
---|
2941 | <p>The $argHostname was wiped out in adodb-ado5.inc.php. Fixed. |
---|
2942 | <p>Adodb5 version, added iterator support for adodb_recordset_empty. |
---|
2943 | |
---|
2944 | <p><a name="4.94"></a><b>4.94 23 Jan 2007</b> |
---|
2945 | <p>Active Record: $ADODB_ASSOC_CASE=2 did not work properly. Fixed. Thx gmane#auxbuss.com. |
---|
2946 | <p>mysqli had bugs in BeginTrans() and EndTrans(). Fixed.</p> |
---|
2947 | <p>Improved error handling when no database is connected for oci8. Thx Andy Hassall.</p> |
---|
2948 | <p>Names longer than 30 chars in oci8 datadict will be changed to random name. Thx Eugenio. http://phplens.com/lens/lensforum/msgs.php?id=16182 |
---|
2949 | <p>Added var $upperCase = 'ucase' to access and ado_access drivers. Thx Renato De Giovanni renato#cria.org.br</p> |
---|
2950 | <p>Postgres64 driver, if preparing plan failed in _query, did not handle error properly. Fixed. See http://phplens.com/lens/lensforum/msgs.php?id=16131. |
---|
2951 | <p>Fixed GetActiveRecordsClass() reference bug. See http://phplens.com/lens/lensforum/msgs.php?id=16120 |
---|
2952 | <p> |
---|
2953 | |
---|
2954 | Added handling of nulls in adodb-ado_mssql.inc.php for qstr(). Thx to Felix Rabinovich. |
---|
2955 | <p> |
---|
2956 | |
---|
2957 | Adodb-dict contributions by Gaetano: |
---|
2958 | <br> |
---|
2959 | + Support for INDEX in data-dict. Example: |
---|
2960 | idx_ev1. The ability to define indexes using the INDEX keyword was added in ADOdb 4.94. The following example features mutiple indexes, including a compound index idx_ev1. |
---|
2961 | <pre> |
---|
2962 | event_id I(11) NOTNULL AUTOINCREMENT PRIMARY, |
---|
2963 | event_type I(4) NOTNULL <b>INDEX idx_evt</b>, |
---|
2964 | event_start_date T DEFAULT NULL <b>INDEX id_esd</b>, |
---|
2965 | event_end_date T DEFAULT '0000-00-00 00:00:00' <b>INDEX id_eted</b>, |
---|
2966 | event_parent I(11) UNSIGNED NOTNULL DEFAULT 0 <b>INDEX id_evp</b>, |
---|
2967 | event_owner I(11) DEFAULT 0 <b>INDEX idx_ev1</b>, |
---|
2968 | event_project I(11) DEFAULT 0 <b>INDEX idx_ev1</b>, |
---|
2969 | event_times_recuring I(11) UNSIGNED NOTNULL DEFAULT 0, |
---|
2970 | event_icon C(20) DEFAULT 'obj/event', |
---|
2971 | event_description X |
---|
2972 | </pre> |
---|
2973 | <br> |
---|
2974 | + Prevents the generated SQL from including double drop-sequence statements for REPLACE case of tables with autoincrement columns (on those dbs that emulate it via sequences) |
---|
2975 | <br> |
---|
2976 | + makes any date defined as DEFAULT value for D and T columns work cross-database, not just the "sysdate" value (as long as it is specified using adodb standard format). See above example. |
---|
2977 | <p>Fixed pdo's GetInsertID() support. Thx Ricky Su. |
---|
2978 | <p>oci8 Prepare() now sets error messages if an error occurs. |
---|
2979 | <p>Added 'PT_BR' to SetDateLocale() -- brazilian portugese. |
---|
2980 | <p>charset in oci8 was not set correctly on *Connect() |
---|
2981 | <p>ADOConnection::Transpose() now appends as first column the field names. |
---|
2982 | <p>Added $ADODB_QUOTE_FIELDNAMES. If set to true, will autoquote field names in AutoExecute(),GetInsertSQL(), GetUpdateSQL(). |
---|
2983 | <p>Transpose now adds the field names as the first column after transposition. |
---|
2984 | <p>Added === check in ADODB_SetDatabaseAdapter for $db, adodb-active-record.inc.php. Thx Christian Affolter. |
---|
2985 | <p>Added ErrorNo() to adodb-active-record.inc.php. Thx ante#novisplet.com. |
---|
2986 | |
---|
2987 | |
---|
2988 | |
---|
2989 | <p><a name="4.93"></a><b>4.93 10 Oct 2006</b> |
---|
2990 | <p>Added support for multiple database connections in performance monitoring code (adodb-perf.inc.php). Now all sql in multiple database connections can be saved into one database ($ADODB_LOG_CONN). |
---|
2991 | <p>Added MetaIndexes() to odbc_mssql. |
---|
2992 | <p>Added connection property $db->null2null = 'null'. In autoexecute/getinsertsql/getupdatesql, this value will be converted to a null. Set this to a funny invalid value if you do not want null conversion. See http://phplens.com/lens/lensforum/msgs.php?id=15902. |
---|
2993 | <p>Path disclosure problem in mysqli fixed. Thx Andy. |
---|
2994 | <p>Fixed typo in session_schema2.xml. |
---|
2995 | <p>Changed INT in oci8 to return correct precision in $fld->max_length, MetaColumns(). Thx Eloy Lafuente Plaza. |
---|
2996 | <p>Patched postgres64 _connect to handle serverinfo(). see http://phplens.com/lens/lensforum/msgs.php?id=15887. |
---|
2997 | <p>Added pdo fix for null columns. See http://phplens.com/lens/lensforum/msgs.php?id=15889 |
---|
2998 | <p>For stored procedures, missing connection id now passed into mssql_query(). Thx Ecsy (ecsy#freemail.hu). |
---|
2999 | |
---|
3000 | <p><a name="4.92a"></a><b>4.92a 30 Aug 2006</b> |
---|
3001 | <p>Syntax error in postgres7 driver. Thx Eloy Lafuente Plaza. |
---|
3002 | <p>Minor bug fixes - adodb informix 10 types added to adodb.inc.php. Thx Fernando Ortiz. |
---|
3003 | |
---|
3004 | <p><a name="4.92"></a><b>4.92 29 Aug 2006</b> |
---|
3005 | |
---|
3006 | <p>Better odbtp date support. |
---|
3007 | <P>Added IgnoreErrors() to bypass default error handling. |
---|
3008 | <p>The _adodb_getcount() function in adodb-lib.inc.php, some ORDER BY bug fixes. |
---|
3009 | <p>For ibase and firebird, set $sysTimeStamp = "CURRENT_TIMESTAMP". |
---|
3010 | <p>Fixed postgres connection bug: http://phplens.com/lens/lensforum/msgs.php?id=11057. |
---|
3011 | <p>Changed CacheSelectLimit() to flush cache when $secs2cache==-1 due to complaints from other users. |
---|
3012 | <p>Added support for using memcached with CacheExecute/CacheSelectLimit. Requires memcache module PECL extension. Usage: |
---|
3013 | <pre> |
---|
3014 | $db = NewADOConnection($driver); |
---|
3015 | $db->memCache = true; /// should we use memCache instead of caching in files |
---|
3016 | $db->memCacheHost = 126.0.1.1; /// memCache host |
---|
3017 | $db->memCachePort = 11211; /// this is default memCache port |
---|
3018 | $db->memCacheCompress = false; /// Use 'true' to store the item compressed (uses zlib) |
---|
3019 | |
---|
3020 | $db->Connect(...); |
---|
3021 | $db->CacheExecute($sql); |
---|
3022 | </pre> |
---|
3023 | <p>Implemented Transpose() for recordsets. Recordset must be retrieved using ADODB_FETCH_NUM. First column becomes the |
---|
3024 | column name. |
---|
3025 | <pre> |
---|
3026 | $DB = NewADOConnection('mysql'); |
---|
3027 | $DB->Connect(...); |
---|
3028 | $DB->SetFetchMode(ADODB_FETCH_NUM); |
---|
3029 | $rs = $DB->Execute('select productname,productid,unitprice from products limit 10'); |
---|
3030 | $rs2 = $DB->Transpose($rs); |
---|
3031 | rs2html($rs2); |
---|
3032 | </pre> |
---|
3033 | <p><a name="4.91"></a><b>4.91 2 Aug 2006</b> |
---|
3034 | <p>Major session code rewrite .... See session docs. |
---|
3035 | <p>PDO bindinputarray was not set properly for MySQL (changed from true to false). |
---|
3036 | <p>Changed CacheSelectLimit() to re-cache when $secs2cache==0. This is one way to flush the cache when SelectLimit is called. |
---|
3037 | <p>Added to quotes to mysql and mysqli: "SHOW COLUMNS FROM `%s`"; |
---|
3038 | <p>Removed accidental optgroup handling in GetMenu(). |
---|
3039 | <a>Fixed ibase _BlobDecode for php5 compat, and also mem alloc issues for small blobs, thx salvatori#interia.pl |
---|
3040 | <p>Mysql driver OffsetDate() speedup, useful for adodb-sessions. |
---|
3041 | <p>Fix for GetAssoc() PHP5 compat. See http://phplens.com/lens/lensforum/msgs.php?id=15425 |
---|
3042 | <p>Active Record - If inserting a record and the value of a primary key field is null, then we do not insert that field in as we assume it is an auto-increment field. Needed by mssql. |
---|
3043 | <p>Changed postgres7 MetaForeignKeys() see http://phplens.com/lens/lensforum/msgs.php?id=15531 |
---|
3044 | <p>DB2 will now return db2_conn_errormsg() when it is a connection error. |
---|
3045 | <p><a name="4.90"></a><b>4.90 8 June 2006</b> |
---|
3046 | <p>Changed adodb_countrec() in adodb-lib.inc.php to allow LIMIT to be used as a speedup to reduce no of records counted. |
---|
3047 | <p>Added support for transaction modes for postgres and oci8 with SetTransactionMode(). |
---|
3048 | These transaction modes affect all subsequent transactions of that connection. |
---|
3049 | <p>Thanks to Halmai Csongor for suggestion. |
---|
3050 | <p>Removed $off = $fieldOffset - 1 line in db2 driver, FetchField(). Tx Larry Menard. |
---|
3051 | <p>Added support for PHP5 objects as Execute() bind parameters using __toString (eg. Simple-XML). Thx Carl-Christian Salvesen. |
---|
3052 | <p>Rounding in tohtml.inc.php did not work properly. Fixed. |
---|
3053 | <p>MetaIndexes in postgres fails when fields are deleted then added in again because the attnum has gaps in it. |
---|
3054 | See http://sourceforge.net/tracker/index.php?func=detail&aid=1451245&group_id=42718&atid=433976. Fixed. |
---|
3055 | <p>MetaForeignkeys in mysql and mysqli did not work when fetchMode==ADODB_FETCH_ASSOC used. Fixed. |
---|
3056 | <p>Reference error in AutoExecute() fixed. |
---|
3057 | <p>Added macaddr postgres type to MetaType. Maps to 'C'. |
---|
3058 | <p>Added to _connect() in adodb-ado5.inc.php support for $database and $dataProvider parameters. Thx Larry Menard. |
---|
3059 | <p>Added support for sequences in adodb-ado_mssql.inc.php. Thx Larry Menard. |
---|
3060 | <p>Added ADODB_SESSION_READONLY. |
---|
3061 | <p>Added session expiryref support to crc32 mode, and in LOB code. |
---|
3062 | <p>Clear _errorMsg in postgres7 driver, so that ErrorMsg() displays properly when no error occurs. |
---|
3063 | <p>Added BindDate and BindTimeStamp |
---|
3064 | <p><a name="4.81"></a><b>4.81 3 May 2006</b> |
---|
3065 | <p>Fixed variable ref errors in adodb-ado5.inc.php in _query(). |
---|
3066 | <p>Mysqli setcharset fix using method_exists(). |
---|
3067 | <p>The adodb-perf.inc.php CreateLogTable() code now works for user-defined table names. |
---|
3068 | <p>Error in ibase_blob_open() fixed. See http://phplens.com/lens/lensforum/msgs.php?id=14997 |
---|
3069 | <p><a name="4.80"></a><b>4.80 8 Mar 2006</b> |
---|
3070 | <p>Added activerecord support. |
---|
3071 | <p>Added mysql $conn->compat323 = true if you want MySQL 3.23 compat enabled. Fixes GetOne() Select-Limit problems. |
---|
3072 | <p>Added adodb-xmlschema03.inc.php to support XML Schema version 3 and updated adodb-datadict.htm docs. |
---|
3073 | <p>Better memory management in Execute. Thx Mike Fedyk. |
---|
3074 | <p><a name="4.72"></a><b>4.72 21 Feb 2006</b> |
---|
3075 | <p>Added 'new' DSN parameter for NConnect(). |
---|
3076 | <p>Pager now sanitizes $PHP_SELF to protect against XSS. Thx to James Bercegay and others. |
---|
3077 | <p>ADOConnection::MetaType changed to setup $rs->connection correctly. |
---|
3078 | <p>New native DB2 driver contributed by Larry Menard, Dan Scott, Andy Staudacher, Bharat Mediratta. |
---|
3079 | <p>The mssql CreateSequence() did not BEGIN TRANSACTION correctly. Fixed. Thx Sean Lee. |
---|
3080 | <p>The _adodb_countrecs() function in adodb-lib.inc.php has been revised to handle more ORDER BY variations. |
---|
3081 | <p><a name="4.71"></a><b>4.71 24 Jan 2006</b> |
---|
3082 | <p>Fixes postgresql security issue related to binary strings. Thx to Andy Staudacher. |
---|
3083 | <p>Several DSN bugs found: |
---|
3084 | <p>1. Fix bugs in DSN connections introduced in 4.70 when underscores are found in the DSN. |
---|
3085 | <p>2. DSN with _ did not work properly in PHP5 (fine in PHP4). Fixed. |
---|
3086 | <p>3. Added support for PDO DSN connections in NewADOConnection(), and database parameter in PDO::Connect(). |
---|
3087 | <p>The oci8 datetime flag not correctly implemented in ADORecordSet_array. Fixed. |
---|
3088 | <p>Added BlobDelete() to postgres, as a counterpoint to UpdateBlobFile(). |
---|
3089 | <p>Fixed GetInsertSQL() to support oci8po. |
---|
3090 | <p>Fixed qstr() issue with postgresql with \0 in strings. |
---|
3091 | <p>Fixed some datadict driver loading issues in _adodb_getdriver(). |
---|
3092 | <p>Added register shutdown function session_write_close in adodb-session.inc.php for PHP 5 compat. See http://phplens.com/lens/lensforum/msgs.php?id=14200. |
---|
3093 | <p><a name="4.70"></a><b>4.70 6 Jan 2006</b> |
---|
3094 | <p>Many fixes from Danila Ulyanov to ibase, oci8, postgres, mssql, odbc_oracle, odbtp, etc drivers. |
---|
3095 | <p>Changed usage of binary hint in adodb-session.inc.php for mysql. See |
---|
3096 | http://phplens.com/lens/lensforum/msgs.php?id=14160 |
---|
3097 | <p>Fixed invalid variable reference problem in undomq(), adodb-perf.inc.php. |
---|
3098 | <p>Fixed http://phplens.com/lens/lensforum/msgs.php?id=14254 in adodb-perf.inc.php, _DBParameter() settings of fetchmode was wrong. |
---|
3099 | <p>Fixed security issues in server.php and tmssql.php discussed by Andreas Sandblad in a Secunia security advisory. Added $ACCEPTIP = 127.0.0.1 |
---|
3100 | and changed suggested root password to something more secure. |
---|
3101 | <p>Changed pager to close recordset after RenderLayout(). |
---|
3102 | <p><a name="4.68"></a><b>4.68 25 Nov 2005</b> |
---|
3103 | <p>PHP 5 compat for mysqli. MetaForeignKeys repeated twice and MYSQLI_BINARY_FLAG missing. |
---|
3104 | <p>PHP 5.1 support for postgresql bind parameters using ? did not work if >= 10 parameters. Fixed. Thx to Stanislav Shramko. |
---|
3105 | <p>Lots of PDO improvements. |
---|
3106 | <p>Spelling error fixed in mysql MetaForeignKeys, $associative parameter. |
---|
3107 | <p><a name="4.67"></a><b>4.67 16 Nov 2005</b> |
---|
3108 | <p>Postgresql not_null flag not set to false correctly. Thx Cristian MARIN. |
---|
3109 | <p>We now check in Replace() if key is in fieldArray. Thx Sébastien Vanvelthem. |
---|
3110 | <p>_file_get_contents() function was missing in xmlschema. fixed. |
---|
3111 | <p>Added week in year support to SQLDate(), using 'W' flag. Thx Spider. |
---|
3112 | <p>In sqlite metacolumns was repeated twice, causing PHP 5 problems. Fixed. |
---|
3113 | <p>Made debug output XHTML compliant. |
---|
3114 | <p><a name="4.66"></a><b>4.66 28 Sept 2005</b> |
---|
3115 | <p>ExecuteCursor() in oci8 did not clean up properly on failure. Fixed. |
---|
3116 | <p>Updated xmlschema.dtd, by "Alec Smecher" asmecher#smecher.bc.ca |
---|
3117 | <p>Hardened SelectLimit, typecasting nrows and offset to integer. |
---|
3118 | <p>Fixed misc bugs in AutoExecute() and GetInsertSQL(). |
---|
3119 | <p>Added $conn->database as the property holding the database name. The older $conn->databaseName is retained for backward |
---|
3120 | compat. |
---|
3121 | <p>Changed _adodb_backtrace() compat check to use function_exists(). |
---|
3122 | <p>Bug in postgresql MetaIndexes fixed. Thx Kevin Jamieson. |
---|
3123 | <p>Improved OffsetDate for MySQL, reducing rounding error. |
---|
3124 | <p>Metacolumns added to sqlite. Thx Mark Newnham. |
---|
3125 | <p>PHP 4.4 compat fixes for GetAssoc(). |
---|
3126 | <p>Added postgresql bind support for php 5.1. Thx Cristiano da Cunha Duarte |
---|
3127 | <p>OffsetDate() fixes for postgresql, typecasting strings to date or timestamp. |
---|
3128 | <p>DBTimeStamp formats for mssql, odbc_mssql and postgresql made to conform with other db's. |
---|
3129 | <p>Changed PDO constants from PDO_ to PDO:: to support latest spec. |
---|
3130 | <p><a name="4.65"></a><b>4.65 22 July 2005</b> |
---|
3131 | <p>Reverted 'X' in mssql datadict to 'TEXT' to be compat with mssql driver. However now you can |
---|
3132 | set $datadict->typeX = 'varchar(4000)' or 'TEXT' or 'CLOB' for mssql and oci8 drivers. |
---|
3133 | <p>Added charset support when using DSN for Oracle. |
---|
3134 | <p>_adodb_getmenu did not use fieldcount() to get number of fields. Fixed. |
---|
3135 | <p>MetaForeignKeys() for mysql/mysqli contributed by Juan Carlos Gonzalez. |
---|
3136 | <p>MetaDatabases() now correctly returns an array for mysqli driver. Thx Cristian MARIN. |
---|
3137 | <p>CompleteTrans(false) did not return false. Fixed. Thx to JMF. |
---|
3138 | <p>AutoExecute() did not work with Oracle. Fixed. Thx José Moreira. |
---|
3139 | <p>MetaType() added to connection object. |
---|
3140 | <p>More PHP 4.4 reference return fixes. Thx Ryan C Bonham and others. |
---|
3141 | |
---|
3142 | <p><a name="4.64"></a><b>4.64 20 June 2005</b> |
---|
3143 | <p>In datadict, if the default field value is set to '', then it is not applied when the field is created. Fixed by Eugenio. |
---|
3144 | <p>MetaPrimaryKeys for postgres did not work because of true/false change in 4.63. Fixed. |
---|
3145 | <p>Tested ocifetchstatement in oci8. Rejected at the end. |
---|
3146 | <p>Added port to dsn handling. Supported in postgres, mysql, mysqli,ldap. |
---|
3147 | <p>Added 'w' and 'l' to mysqli SQLDate(). |
---|
3148 | <p>Fixed error handling in ldap _connect() to be more consistent. Also added ErrorMsg() handling to ldap. |
---|
3149 | <p>Added support for union in _adodb_getcount, adodb-lib.inc.php for postgres and oci8. |
---|
3150 | <p>rs2html() did not work with null dates properly. |
---|
3151 | <p>PHP 4.4 reference return fixes. |
---|
3152 | |
---|
3153 | <p><a name="4.63"></a><b>4.63 18 May 2005</b> |
---|
3154 | <p>Added $nrows<0 check to mysqli's SelectLimit(). |
---|
3155 | <p>Added OptimizeTable() and OptimizeTables() in adodb-perf.inc.php. By Markus Staab. |
---|
3156 | <p>PostgreSQL inconsistencies fixed. true and false set to TRUE and FALSE, and boolean type in datadict-postgres.inc.php set |
---|
3157 | to 'L' => 'BOOLEAN'. Thx Kevin Jamieson. |
---|
3158 | <p>New adodb_session_create_table() function in adodb-session.inc.php. By Markus Staab. |
---|
3159 | <p>Added null check to UserTimeStamp(). |
---|
3160 | <p>Fixed typo in mysqlt driver in adorecordset. Thx to Andy Staudacher. |
---|
3161 | <p>GenID() had a bug in the raiseErrorFn handling. Fixed. Thx Marcos Pont. |
---|
3162 | <p>Datadict name quoting now handles ( ) in index fields correctly - they aren't part of the index field. |
---|
3163 | <p>Performance monitoring: (1) oci8 Ixora checks moved down; (2) expensive sql changed so that only those sql with |
---|
3164 | count(*)>1 are shown; (3) changed sql1 field to a length+crc32 checksum - this breaks backward compat. |
---|
3165 | <p>We remap firebird15 to firebird in data dictionary. |
---|
3166 | |
---|
3167 | <p><a name="4.62"></a><b>4.62 2 Apr 2005</b> |
---|
3168 | <p>Added 'w' (dow as 0-6 or 1-7) and 'l' (dow as string) for SQLDate for oci8, postgres and mysql. |
---|
3169 | <p>Rolled back MetaType() changes for mysqli done in prev version. |
---|
3170 | <p>Datadict change by chris, cblin#tennaxia.com data mappings from: |
---|
3171 | <pre> |
---|
3172 | oci8: X->varchar(4000) XL->CLOB |
---|
3173 | mssql: X->XL->TEXT |
---|
3174 | mysql: X->XL->LONGTEXT |
---|
3175 | fbird: X->XL->varchar(4000) |
---|
3176 | </pre> |
---|
3177 | <p>to: |
---|
3178 | <pre> |
---|
3179 | oci8: X->varchar(4000) XL->CLOB |
---|
3180 | mssql: X->VARCHAR(4000) XL->TEXT |
---|
3181 | mysql: X->TEXT XL->LONGTEXT |
---|
3182 | fbird: X->VARCHAR(4000) XL->VARCHAR(32000) |
---|
3183 | </pre> |
---|
3184 | <p>Added $connection->disableBlobs to postgresql to improve performance when no bytea is used (2-5% improvement). |
---|
3185 | <p>Removed all HTTP_* vars. |
---|
3186 | <p>Added $rs->tableName to be set before calling AutoExecute(). |
---|
3187 | <p>Alex Rootoff rootoff#pisem.net contributed ukrainian language file. |
---|
3188 | <p>Added new mysql_option() support using $conn->optionFlags array. |
---|
3189 | <p>Added support for ldap_set_option() using the $LDAP_CONNECT_OPTIONS global variable. Contributed by Josh Eldridge. |
---|
3190 | <p>Added LDAP_* constant definitions to ldap. |
---|
3191 | <p>Added support for boolean bind variables. We use $conn->false and $conn->true to hold values to set false/true to. |
---|
3192 | <p>We now do not close the session connection in adodb-session.inc.php as other objects could be using this connection. |
---|
3193 | <p>We now strip off \0 at end of Ixora SQL strings in $perf->tohtml() for oci8. |
---|
3194 | <p><a name="4.61"></a><b>4.61 23 Feb 2005</b> |
---|
3195 | <p>MySQLi added support for mysqli_connect_errno() and mysqli_connect_error(). |
---|
3196 | <p>Massive improvements to alpha PDO driver. |
---|
3197 | <p>Quote string bind parameters logged by performance monitor for easy type checking. Thx Jason Judge. |
---|
3198 | <p>Added support for $role when connecting with Interbase/firebird. |
---|
3199 | <p>Added support for enum recognition in MetaColumns() mysql and mysqli. Thx Amedeo Petrella. |
---|
3200 | <p>The sybase_ase driver contributed by Interakt Online. Thx Cristian Marin cristic#interaktonline.com. |
---|
3201 | <p>Removed not_null, has_default, and default_value from ADOFieldObject. |
---|
3202 | <p>Sessions code, fixed quoting of keys when handling LOBs in session write() function. |
---|
3203 | <p>Sessions code, added adodb_session_regenerate_id(), to reduce risk of session hijacking by changing session cookie dynamically. Thx Joe Li. |
---|
3204 | <p>Perf monitor, polling for CPU did not work for PHP 4.3.10 and 5.0.0-5.0.3 due to PHP bugs, so we special case these versions. |
---|
3205 | <p>Postgresql, UpdateBlob() added code to handle type==CLOB. |
---|
3206 | <p><a name="4.60"></a><b>4.60 24 Jan 2005</b> |
---|
3207 | <p>Implemented PEAR DB's autoExecute(). Simplified design because I don't like using constants when |
---|
3208 | strings work fine. |
---|
3209 | <p>_rs2serialize will now update $rs->sql and $rs->oldProvider. |
---|
3210 | <p>Added autoExecute(). |
---|
3211 | <p>Added support for postgres8 driver. Currently just remapped to postgres7 driver. |
---|
3212 | <p>Changed oci8 _query(), so that OCIBindByName() sets the length to -1 if element size is > 4000. This provides better support |
---|
3213 | for LONGs. |
---|
3214 | <p>Added SetDateLocale() support for netherlands (Nl). |
---|
3215 | <p>Spelling error in pivot code ($iff should be $iif). |
---|
3216 | </p><p>mysql insert_id() did not work with mysql 3.x. Fixed. |
---|
3217 | </p><p>"\r\n" not converted to spaces correctly in exporting data. Fixed. |
---|
3218 | </p><p>_nconnect() in mysqli did not return value correctly. Fixed. |
---|
3219 | </p><p>Arne Eckmann contributed danish language file. |
---|
3220 | </p><p>Added clone() support to FetchObject() for PHP5.<br> |
---|
3221 | </p> |
---|
3222 | <p>Removed SQL_CUR_USE_ODBC from odbc_mssql.<br> |
---|
3223 | </p> |
---|
3224 | <p><a name="4.55"></a><b>4.55 5 Jan 2005</b> |
---|
3225 | </p><p>Found bug in Execute() with bind params for db's that do not support binding natively. |
---|
3226 | </p><p>DropSequence() now correctly uses default parameter. |
---|
3227 | </p><p>Now Execute() ignores locale for floats, so 1.23 is NEVER converted to 1,23. |
---|
3228 | </p><p>SetFetchMode() not properly saved in adodb-perf, suspicious sql and expensive sql. Fixed. |
---|
3229 | </p><p>Added INET to postgresql metatypes. Thx motzel. |
---|
3230 | </p><p>Allow oracle hints to work when counting with _adodb_getcount in adodb-lib.inc.php. Thx Chris Wrye. |
---|
3231 | </p><p>Changed mysql insert_id() to use SELECT LAST_INSERT_ID(). |
---|
3232 | </p><p>If alter col in datadict does not modify col type/size of actual |
---|
3233 | col, then it is removed from alter col code. By Mark Newham. Not |
---|
3234 | perfect as MetaType() !== ActualType(). |
---|
3235 | </p><p>Added handling of view fields in metacolumns() for postgresql. Thx Renato De Giovanni. |
---|
3236 | </p><p>Added to informix MetaPrimaryKeys and MetaColumns fixes for null bit. Thx to Cecilio Albero. |
---|
3237 | </p><p>Removed obsolete connection_timeout() from perf code. |
---|
3238 | </p><p>Added support for arrayClass in adodb-csv.inc.php. |
---|
3239 | </p><p>RSFilter now accepts methods of the form $array($obj, 'methodname'). Thx to blake#near-time.com. |
---|
3240 | </p><p>Changed CacheFlush to $cmd = 'rm -rf '.$ADODB_CACHE_DIR.'/[0-9a-f][0-9a-f]/'; |
---|
3241 | </p><p>For better cursor concurrency, added code to free ref cursors in |
---|
3242 | oci8 when $rs->Close() is called. Note that CLose() is called |
---|
3243 | internally by the Get* functions too. |
---|
3244 | </p><p>Added IIF support for access when pivoting. Thx Volodia Krupach. |
---|
3245 | </p><p>Added mssql datadict support for timestamp. Thx Alexios. |
---|
3246 | </p><p>Informix pager fix. By Mario Ramirez. |
---|
3247 | </p><p>ADODB_TABLE_REGEX now includes ':'. By Mario Ramirez. |
---|
3248 | </p><p>Mark Newnham contributed MetaIndexes for oci8 and db2. |
---|
3249 | </p><p><a name="4.54"></a><b>4.54 5 Nov 2004</b> |
---|
3250 | </p><p> |
---|
3251 | Now you can set $db->charSet = ?? before doing a Connect() in oci8. |
---|
3252 | </p><p> |
---|
3253 | Added adodbFetchMode to sqlite. |
---|
3254 | </p><p> |
---|
3255 | Perf code, added a string typecast to substr in adodb_log_sql(). |
---|
3256 | </p><p> |
---|
3257 | Postgres: Changed BlobDecode() to use po_loread, added new $maxblobsize parameter, and now it returns the blob instead |
---|
3258 | of sending it to stdout - make sure to mention that as a compat warning. |
---|
3259 | Also added $db->IsOID($oid) function; uses a heuristic, not guaranteed to work 100%. |
---|
3260 | </p><p> |
---|
3261 | Contributed arabic language file by "El-Shamaa, Khaled" k.el-shamaa#cgiar.org |
---|
3262 | </p><p> |
---|
3263 | PHP5 exceptions did not handle @ protocol properly. Fixed. |
---|
3264 | </p><p> |
---|
3265 | Added ifnull handling for postgresql (using coalesce). |
---|
3266 | </p><p> |
---|
3267 | Added metatables() support for Postgresql 8.0 (no longer uses pg_% dictionary tables). |
---|
3268 | </p><p> |
---|
3269 | Improved Sybase ErrorMsg() function. By Gaetano Giunta. |
---|
3270 | </p><p> |
---|
3271 | Improved oci8 SelectLimit() to use Prepare(). By Cristiano Duarte. |
---|
3272 | </p><p> |
---|
3273 | Type-cast $row parameter in ifx_fetch_row() to int. Thx stefan bodgan. |
---|
3274 | </p><p>Ralf becker contributed improvements in postgresql, sapdb, mysql data dictionary handling:<br> |
---|
3275 | - MySql and Postgres MetaType was reporting every int column which was |
---|
3276 | part of a primary key and unique as serial<br> |
---|
3277 | - Postgres was not reporting the scale of decimal types<br> |
---|
3278 | - MaxDB was padding the defaults of none-string types with spaces<br> |
---|
3279 | - MySql now correctly converts enum columns to varchar |
---|
3280 | </p><p> |
---|
3281 | Ralf also changed Postgresql datadict:<br> |
---|
3282 | - you cant add NOT NULL columns in postgres in one go, they need to be |
---|
3283 | added as NULL and then altered to NOT NULL<br> |
---|
3284 | - AlterColumnSQL could not change a varchar column with numbers into an |
---|
3285 | integer column, postgres need an explicit conversation<br> |
---|
3286 | - a re-created sequence was not set to the correct value, if the name |
---|
3287 | was the old name (no implicit sequence), now always the new name of the |
---|
3288 | implicit sequence is used<br> |
---|
3289 | </p><p>Sergio Strampelli added extra $intoken check to Lens_ParseArgs() in datadict code. |
---|
3290 | </p><p><a name="4.53"></a><b>4.53 28 Sept 2004</b> |
---|
3291 | </p><p>FetchMode cached in recordset is sometimes mapped to native db fetchMode. Normally this does not matter, |
---|
3292 | but when using cached recordsets, we need to switch back to using adodb fetchmode. So we cache this |
---|
3293 | in $rs->adodbFetchMode if it differs from the db's fetchMode. |
---|
3294 | </p><p>For informix we now set canSeek = false driver because stefan bodgan tells me that seeking doesn't work. |
---|
3295 | </p><p>SetDateLocale() never worked till now ;-) Thx david#tomato.it |
---|
3296 | </p><p>Set $_bindInputArray = true in sapdb driver. Required for clob support. |
---|
3297 | </p><p>Fixed some PEAR::DB emulation issues with isError() and isWarning. Thx to Gert-Rainer Bitterlich. |
---|
3298 | </p><p>Empty() used in getupdatesql without strlen() check. Fixed.</p> |
---|
3299 | <p>Added unsigned detection to mysql and mysqli drivers. Thx to dan cech. |
---|
3300 | </p><p>Added hungarian language file. Thx to Halászvári Gábor. |
---|
3301 | </p><p>Improved fieldname-type formatting of datadict SQL generated (adding $widespacing parameter to _GenField). |
---|
3302 | </p><p>Datadict oci8 DROP CONSTRAINTS misspelt. Fixed. Thx Mark Newnham. |
---|
3303 | </p><p>Changed odbtp to dynamically change databaseType based on connection, eg. from 'odbtp' to 'odbtp_mssql' when connecting |
---|
3304 | to mssql database. |
---|
3305 | </p><p>In datadict, MySQL I4 was wrongly mapped to MEDIUMINT, which is actually I3. Fixed. |
---|
3306 | </p><p>Fixed mysqli MetaType() recognition. Mysqli returns numeric types unlike mysql extension. Thx Francesco Riosa. |
---|
3307 | </p><p>VFP odbc driver curmode set wrongly, causing problems with memo fields. Fixed. |
---|
3308 | </p><p>Odbc driver did not recognize odbc version 2 driver date types properly. Fixed. Thx Bostjan. |
---|
3309 | </p><p>ChangeTableSQL() fixes to datadict-db2.inc.php by Mark Newnham. |
---|
3310 | </p><p>Perf monitoring with odbc improved. Now we try in perf code to manually set the sysTimeStamp using date() if sysTimeStamp |
---|
3311 | is empty. |
---|
3312 | </p><p>All ADO errors are thrown as exceptions in PHP5. |
---|
3313 | So we added exception handling to ado in PHP5 by creating new adodb-ado5.inc.php driver. |
---|
3314 | </p><p>Added IsConnected(). Returns true if connection object connected. By Luca.Gioppo. |
---|
3315 | </p><p>"Ralf Becker" |
---|
3316 | RalfBecker#digitalROCK.de contributed new sapdb data-dictionary driver |
---|
3317 | and a large patch that implements field and table renaming for oracle, |
---|
3318 | mssql, postgresql, mysql and sapdb. See the new RenameTableSQL() and |
---|
3319 | RenameColumnSQL() functions. |
---|
3320 | </p><p>We now check ExecuteCursor to see if PrepareSP was initially called. |
---|
3321 | </p><p>Changed oci8 datadict to use MODIFY for $dd->alterCol. Thx Mark Newnham. |
---|
3322 | </p><p><a name="4.52"></a><b>4.52 10 Aug 2004</b> |
---|
3323 | </p><p>Bug found in Replace() when performance logging enabled, introduced in ADOdb 4.50. Fixed. |
---|
3324 | </p><p>Replace() checks update stmt. If update stmt fails, we now return immediately. Thx to alex. |
---|
3325 | </p><p>Added support for $ADODB_FORCE_TYPE in GetUpdateSQL/GetInsertSQL. Thx to niko. |
---|
3326 | </p><p>Added ADODB_ASSOC_CASE support to postgres/postgres7 driver. |
---|
3327 | </p><p>Support for DECLARE stmt in oci8. Thx Lochbrunner. |
---|
3328 | </p><p><a name="4.51"></a><b>4.51 29 July 2004</b> |
---|
3329 | </p><p>Added adodb-xmlschema 1.0.2. Thx dan and richard. |
---|
3330 | </p><p>Added new adorecordset_ext_* classes. If ADOdb extension installed for mysql, mysqlt and oci8 |
---|
3331 | (but not oci8po), we use the superfast ADOdb extension code for movenext. |
---|
3332 | </p><p>Added schema support to mssql and odbc_mssql MetaPrimaryKeys(). |
---|
3333 | </p><p>Patched MSSQL driver to support PHP NULL and Boolean values |
---|
3334 | while binding the input array parameters in the _query() function. By Stephen Farmer. |
---|
3335 | </p><p>Added support for clob's for mssql, UpdateBlob(). Thx to gfran#directa.com.br |
---|
3336 | </p><p>Added normalize support for postgresql (true=lowercase table name, or false=case-sensitive table names) |
---|
3337 | to MetaColumns($table, $normalize=true). |
---|
3338 | </p><p>PHP5 variant dates in ADO not working. Fixed in adodb-ado.inc.php. |
---|
3339 | </p><p>Constant ADODB_FORCE_NULLS was not working properly for many releases (for GetUpdateSQL). Fixed. |
---|
3340 | Also GetUpdateSQL strips off ORDER BY now - thx Elieser Leão. |
---|
3341 | </p><p>Perf Monitor for oci8 now dynamically highlights optimizer_* params if too high/low. |
---|
3342 | </p><p>Added dsn support to NewADOConnection/ADONewConnection. |
---|
3343 | </p><p>Fixed out of page bounds bug in _adodb_pageexecute_all_rows() Thx to "Sergio Strampelli" sergio#rir.it |
---|
3344 | </p><p>Speedup of movenext for mysql and oci8 drivers. |
---|
3345 | </p><p>Moved debugging code _adodb_debug_execute() to adodb-lib.inc.php. |
---|
3346 | </p><p>Fixed postgresql bytea detection bug. See http://phplens.com/lens/lensforum/msgs.php?id=9849. |
---|
3347 | </p><p>Fixed ibase datetimestamp typo in PHP5. Thx stefan. |
---|
3348 | </p><p>Removed whitespace at end of odbtp drivers. |
---|
3349 | </p><p>Added db2 metaprimarykeys fix. |
---|
3350 | </p><p>Optimizations to MoveNext() for mysql and oci8. Misc speedups to Get* functions. |
---|
3351 | </p><p><a name="4.50"></a><b>4.50 6 July 2004</b> |
---|
3352 | </p><p>Bumped it to 4.50 to avoid confusion with PHP 4.3.x series. |
---|
3353 | </p><p>Added db2 metatables and metacolumns extensions. |
---|
3354 | </p><p>Added alpha PDO driver. Very buggy, only works with odbc. |
---|
3355 | </p><p>Tested mysqli. Set poorAffectedRows = true. Cleaned up movenext() and _fetch(). |
---|
3356 | </p><p>PageExecute does not work properly with php5 (return val not a variable). Reported Dmytro Sychevsky sych#php.com.ua. Fixed. |
---|
3357 | </p><p>MetaTables() for mysql, $showschema parameter was not backward compatible with older versions of adodb. Fixed. |
---|
3358 | </p><p>Changed mysql GetOne() to work with mysql 3.23 when using with non-select stmts (e.g. SHOW TABLES). |
---|
3359 | </p><p>Changed TRIG_ prefix to a variable in datadict-oci8.inc.php. Thx to Luca.Gioppo#csi.it. |
---|
3360 | </p><p>New to adodb-time code. We allow you to define your own daylights savings function, |
---|
3361 | adodb_daylight_sv for pre-1970 dates. If the function is defined |
---|
3362 | (somewhere in an include), then you can correct |
---|
3363 | for daylights savings. See http://phplens.com/phpeverywhere/node/view/16#daylightsavings |
---|
3364 | for more info. |
---|
3365 | </p><p>New sqlitepo driver. This is because assoc mode does not work like other drivers in sqlite. |
---|
3366 | Namely, when selecting (joining) multiple tables, in assoc mode the table |
---|
3367 | names are included in the assoc keys in the "sqlite" driver. |
---|
3368 | In "sqlitepo" driver, the table names are stripped from the returned column names. |
---|
3369 | When this results in a conflict, the first field get preference. |
---|
3370 | Contributed by Herman Kuiper herman#ozuzo.net |
---|
3371 | </p><p>Added $forcenull parameter to GetInsertSQL/GetUpdateSQL. Idea by Marco Aurelio Silva. |
---|
3372 | </p><p>More XHTML changes for GetMenu. By Jeremy Evans. |
---|
3373 | </p><p>Fixes some ibase date issues. Thx to stefan bogdan. |
---|
3374 | </p><p>Improvements to mysqli driver to support $ADODB_COUNTRECS. |
---|
3375 | </p><p>Fixed adodb-csvlib.inc.php problem when reading stream from socket. We need to poll stream continiously. |
---|
3376 | </p><p><a name="4.23"></a><b>4.23 16 June 2004</b> |
---|
3377 | </p><p> |
---|
3378 | New interbase/firebird fixes thx to Lester Caine. |
---|
3379 | Driver fixes a problem with getting field names in the result array, and |
---|
3380 | corrects a couple of data conversions. Also we default to dialect3 for firebird. |
---|
3381 | Also ibase sysDate property was wrong. Changed to cast as timestamp. |
---|
3382 | </p><p> |
---|
3383 | The datadict driver is set up to give quoted tables and fields as this |
---|
3384 | was the only way round reserved words being used as field names in |
---|
3385 | TikiWiki. TikiPro is tidying that up, and I hope to be able to produce a |
---|
3386 | build of THAT which uses what I consider proper UPPERCASE field and |
---|
3387 | table names. The conversion of TikiWiki to ADOdb helped in that, but |
---|
3388 | until the database is completely tidied up in TikiPro ... |
---|
3389 | </p><p>Modified _gencachename() to include fetchmode in name hash. |
---|
3390 | This means you should clear your cache directory after installing this release as the |
---|
3391 | cache name algorithm has changed. |
---|
3392 | </p><p>Now Cache* functions work in safe |
---|
3393 | mode, because we do not create sub-directories in the $ADODB_CACHE_DIR |
---|
3394 | in safe mode. In non-safe mode we still create sub-directories. Done by |
---|
3395 | modifying _gencachename(). |
---|
3396 | </p><p>Added $gmt parameter (true/false) |
---|
3397 | to UserDate and UserTimeStamp in connection class, to force conversion |
---|
3398 | of input (in local time) to be converted to UTC/GMT. |
---|
3399 | </p><p>Mssql datadict did not support INT types properly (no size param allowed). |
---|
3400 | Added _GetSize() to datadict-mssql.inc.php. |
---|
3401 | </p><p>For borland_ibase, BeginTrans(), changed:<br> |
---|
3402 | </p><pre> $this->_transactionID = $this->_connectionID;</pre> |
---|
3403 | to<br> |
---|
3404 | <pre> $this->_transactionID = ibase_trans($this->ibasetrans, $this->_connectionID);</pre> |
---|
3405 | |
---|
3406 | <p>Fixed typo in mysqi_field_seek(). Thx to Sh4dow (sh4dow#php.pl). |
---|
3407 | </p><p>LogSQL did not work with Firebird/Interbase. Fixed. |
---|
3408 | </p><p>Postgres: made errorno() handling more consistent. Thx to Michael Jahn, Michael.Jahn#mailbox.tu-dresden.de. |
---|
3409 | </p><p>Added informix patch to better support metatables, metacolumns by "Cecilio Albero" c-albero#eos-i.com |
---|
3410 | </p><p>Cyril Malevanov contributed patch to oci8 to support passing of LOB parameters: |
---|
3411 | </p><pre> $text = 'test test test';<br> $sql = "declare rs clob; begin :rs := lobinout(:sa0); end;";<br> $stmt = $conn -> PrepareSP($sql);<br> $conn -> InParameter($stmt,$text,'sa0', -1, OCI_B_CLOB);<br> $rs = '';<br> $conn -> OutParameter($stmt,$rs,'rs', -1, OCI_B_CLOB);<br> $conn -> Execute($stmt);<br> echo "return = ".$rs."<br>";<br></pre> |
---|
3412 | As he says, the LOBs limitations are: |
---|
3413 | <pre> - use OCINewDescriptor before binding<br> - if Param is IN, uses save() before each execute. This is done automatically for you.<br> - if Param is OUT, uses load() after each execute. This is done automatically for you.<br> - when we bind $var as LOB, we create new descriptor and return it as a<br> Bind Result, so if we want to use OUT parameters, we have to store<br> somewhere &$var to load() data from LOB to it.<br> - IN OUT params are not working now (should not be a big problem to fix it)<br> - now mass binding not working too (I've wrote about it before)<br></pre> |
---|
3414 | <p>Simplified Connect() and PConnect() error handling. |
---|
3415 | </p><p>When extension not loaded, Connect() and PConnect() will return null. On connect error, the fns will return false. |
---|
3416 | </p><p>CacheGetArray() added to code. |
---|
3417 | </p><p>Added Init() to adorecordset_empty(). |
---|
3418 | </p><p>Changed postgres64 driver, MetaColumns() to not strip off quotes in default value if :: detected (type-casting of default). |
---|
3419 | </p><p>Added test: if (!defined('ADODB_DIR')) die(). Useful to prevent hackers from detecting file paths. |
---|
3420 | </p><p>Changed metaTablesSQL to ignore Postgres 7.4 information schemas (sql_*). |
---|
3421 | </p><p>New polish language file by Grzegorz Pacan |
---|
3422 | </p><p>Added support for UNION in _adodb_getcount(). |
---|
3423 | </p><p>Added security check for ADODB_DIR to limit path disclosure issues. Requested by postnuke team. |
---|
3424 | </p><p>Added better error message support to oracle driver. Thx to Gaetano Giunta. |
---|
3425 | </p><p>Added showSchema support to mysql. |
---|
3426 | </p><p>Bind in oci8 did not handle $name=false properly. Fixed. |
---|
3427 | </p><p>If extension not loaded, Connect(), PConnect(), NConnect() will return null. |
---|
3428 | </p><p><b>4.22 15 Apr 2004</b> |
---|
3429 | </p><p>Moved docs to own adodb/docs folder. |
---|
3430 | </p><p>Fixed session bug when quoting compressed/encrypted data in Replace(). |
---|
3431 | </p><p>Netezza Driver and LDAP drivers contributed by Josh Eldridge. |
---|
3432 | </p><p>GetMenu now uses rtrim() on values instead of trim(). |
---|
3433 | </p><p>Changed MetaColumnNames to return an associative array, keys being the field names in uppercase. |
---|
3434 | </p><p>Suggested fix to adodb-ado.inc.php affected_rows to support PHP5 variants. Thx to Alexios Fakos. |
---|
3435 | </p><p>Contributed bulgarian language file by Valentin Sheiretsky valio#valio.eu.org. |
---|
3436 | </p><p>Contributed romanian language file by stefan bogdan. |
---|
3437 | </p><p>GetInsertSQL now checks for table name (string) in $rs, and will create a recordset for that |
---|
3438 | table automatically. Contributed by Walt Boring. Also added OCI_B_BLOB in bind on Walt's request - hope |
---|
3439 | it doesn't break anything :-) |
---|
3440 | </p><p>Some minor postgres speedups in _initrs(). |
---|
3441 | </p><p> ChangeTableSQL checks now if MetaColumns returns empty. Thx Jason Judge. |
---|
3442 | </p><p>Added ADOConnection::Time(), returns current database time in unix timestamp format, or false. |
---|
3443 | </p><p><b>4.21 20 Mar 2004</b> |
---|
3444 | </p><p>We no longer in SelectLimit for VFP driver add SELECT TOP X unless an ORDER BY exists. |
---|
3445 | </p><p>Pim Koeman contributed dutch language file adodb-nl.inc.php. |
---|
3446 | </p><p>Rick Hickerson added CLOB support to db2 datadict. |
---|
3447 | </p><p>Added odbtp driver. Thx to "stefan bogdan" sbogdan#rsb.ro. |
---|
3448 | </p><p>Changed PrepareSP() 2nd parameter, $cursor, to default to true (formerly false). Fixes oci8 backward |
---|
3449 | compat problems with OUT params. |
---|
3450 | </p><p>Fixed month calculation error in adodb-time.inc.php. 2102-June-01 appeared as 2102-May-32. |
---|
3451 | </p><p>Updated PHP5 RC1 iterator support. API changed, hasMore() renamed to valid(). |
---|
3452 | </p><p>Changed internal format of serialized cache recordsets. As we store a version number, this should be |
---|
3453 | backward compatible. |
---|
3454 | </p><p>Error handling when driver file not found was flawed in ADOLoadCode(). Fixed. |
---|
3455 | </p><p><b>4.20 27 Feb 2004</b> |
---|
3456 | </p><p>Updated to AXMLS 1.01. |
---|
3457 | </p><p>MetaForeignKeys for postgres7 modified by Edward Jaramilla, works on pg 7.4. |
---|
3458 | </p><p>Now numbers accepts function calls or sequences for GetInsertSQL/GetUpdateSQL numeric fields. |
---|
3459 | </p><p>Changed quotes of 'delete from $perf_table' to "". Thx Kehui (webmaster#kehui.net) |
---|
3460 | </p><p>Added ServerInfo() for ifx, and putenv trim fix. Thx Fernando Ortiz. |
---|
3461 | </p><p>Added addq(), which is analogous to addslashes(). |
---|
3462 | </p><p>Tested with php5b4. Fix some php5 compat problems with exceptions and sybase. |
---|
3463 | </p><p>Carl-Christian Salvesen added patch to mssql _query to support binds greater than 4000 chars. |
---|
3464 | </p><p>Mike suggested patch to PHP5 exception handler. $errno must be numeric. |
---|
3465 | </p><p>Added double quotes (") to ADODB_TABLE_REGEX. |
---|
3466 | </p><p>For oci8, Prepare(...,$cursor), |
---|
3467 | $cursor's meaning was accidentally inverted in 4.11. This causes |
---|
3468 | problems with ExecuteCursor() too, which calls Prepare() internally. |
---|
3469 | Thx to William Lovaton. |
---|
3470 | </p><p>Now dateHasTime property in connection object renamed to datetime for consistency. This could break bc. |
---|
3471 | </p><p>Csongor Halmai reports that db2 SelectLimit with input array is not working. Fixed.. |
---|
3472 | </p><p><b>4.11 27 Jan 2004</b> |
---|
3473 | </p><p>Csongor Halmai reports db2 binding not working. Reverted back to emulated binding. |
---|
3474 | </p><p>Dan Cech modifies datadict code. Adds support for DropIndex. Minor cleanups. |
---|
3475 | </p><p>Table misspelt in perf-oci8.inc.php. Changed v$conn_cache_advice to v$db_cache_advice. Reported by Steve W. |
---|
3476 | </p><p>UserTimeStamp and DBTimeStamp did not handle YYYYMMDDHHMMSS format properly. Reported by Mike Muir. Fixed. |
---|
3477 | </p><p>Changed oci8 Prepare(). Does not auto-allocate OCINewCursor automatically, unless 2nd param is set to true. |
---|
3478 | This will break backward compat, if Prepare/Execute is used instead of ExecuteCursor. Reported by Chris Jones. |
---|
3479 | </p><p>Added InParameter() and OutParameter(). Wrapper functions to Parameter(), but nicer because they |
---|
3480 | are self-documenting. |
---|
3481 | </p><p>Added 'R' handling in ActualType() to datadict-mysql.inc.php |
---|
3482 | </p><p>Added ADOConnection::SerializableRS($rs). Returns a recordset that can be serialized in a session. |
---|
3483 | </p><p>Added "Run SQL" to performance UI(). |
---|
3484 | </p><p>Misc spelling corrections in adodb-mysqli.inc.php, adodb-oci8.inc.php and datadict-oci8.inc.php, from Heinz Hombergs. |
---|
3485 | </p><p>MetaIndexes() for ibase contributed by Heinz Hombergs. |
---|
3486 | </p><p><b>4.10 12 Jan 2004</b> |
---|
3487 | </p><p>Dan Cech contributed extensive changes to data dictionary to support name quoting (with `), and drop table/index. |
---|
3488 | </p><p>Informix added cursorType property. Default remains IFX_SCROLL, but you can change to 0 (non-scrollable cursor) for performance. |
---|
3489 | </p><p>Added ADODB_View_PrimaryKeys() for returning view primary keys to MetaPrimaryKeys(). |
---|
3490 | </p><p>Simplified chinese file, adodb-cn.inc.php from cysoft. |
---|
3491 | </p><p>Added check for ctype_alnum in adodb-datadict.inc.php. Thx to Jason Judge. |
---|
3492 | </p><p>Added connection parameter to ibase Prepare(). Fix by Daniel Hassan. |
---|
3493 | </p><p>Added nameQuote for quoting identifiers and names to connection obj. Requested by Jason Judge. Also the |
---|
3494 | data dictionary parser now detects `field name` and generates column names with spaces correctly. |
---|
3495 | </p><p>BOOL type not recognised correctly as L. Fixed. |
---|
3496 | </p><p>Fixed paths in ADODB_DIR for session files, and back-ported it to 4.05 (15 Dec 2003) |
---|
3497 | </p><p>Added Schema to postgresql MetaTables. Thx to col#gear.hu |
---|
3498 | </p><p>Empty postgresql recordsets that had blob fields did not set EOF properly. Fixed. |
---|
3499 | </p><p>CacheSelectLimit internal parameters to SelectLimit were wrong. Thx to Nio. |
---|
3500 | </p><p>Modified adodb_pr() and adodb_backtrace() to support command-line usage (eg. no html). |
---|
3501 | </p><p>Fixed some fr and it lang errors. Thx to Gaetano G. |
---|
3502 | </p><p>Added contrib directory, with adodb rs to xmlrpc convertor by Gaetano G. |
---|
3503 | </p><p>Fixed array recordset bugs when _skiprow1 is true. Thx to Gaetano G. |
---|
3504 | </p><p>Fixed pivot table code when count is false. |
---|
3505 | </p><p> |
---|
3506 | |
---|
3507 | </p><p><b>4.05 13 Dec 2003 </b> |
---|
3508 | </p><p>Added MetaIndexes to data-dict code - thx to Dan Cech. |
---|
3509 | </p><p>Rewritten session code by Ross Smith. Moved code to adodb/session directory. |
---|
3510 | </p><p>Added function exists check on connecting to most drivers, so we don't crash with the unknown function error. |
---|
3511 | </p><p>Smart Transactions failed with GenID() when it no seq table has been created because the sql |
---|
3512 | statement fails. Fix by Mark Newnham. |
---|
3513 | </p><p>Added $db->length, which holds name of function that returns strlen. |
---|
3514 | </p><p>Fixed error handling for bad driver in ADONewConnection - passed too few params to error-handler. |
---|
3515 | </p><p>Datadict did not handle types like 16.0 properly in _GetSize. Fixed. |
---|
3516 | </p><p>Oci8 driver SelectLimit() bug &= instead of =& used. Thx to Swen Thümmler. |
---|
3517 | </p><p>Jesse Mullan suggested not flushing outp when output buffering enabled. Due to Apache 2.0 bug. Added. |
---|
3518 | </p><p>MetaTables/MetaColumns return ref bug with PHP5 fixed in adodb-datadict.inc.php. |
---|
3519 | </p><p>New mysqli driver contributed by Arjen de Rijke. Based on adodb 3.40 driver. |
---|
3520 | Then jlim added BeginTrans, CommitTrans, RollbackTrans, IfNull, SQLDate. Also fixed return ref bug. |
---|
3521 | </p><p>$ADODB_FLUSH added, if true then force flush in debugging outp. Default is false. In earlier |
---|
3522 | versions, outp defaulted to flush, which is not compat with apache 2.0. |
---|
3523 | </p><p>Mysql driver's GenID() function did not work when when sql logging is on. Fixed. |
---|
3524 | </p><p>$ADODB_SESSION_TBL not declared as global var. Not available if adodb-session.inc.php included in function. Fixed. |
---|
3525 | </p><p>The input array not passed to Execute() in _adodb_getcount(). Fixed. |
---|
3526 | </p><p><b>4.04 13 Nov 2003 </b> |
---|
3527 | </p><p>Switched back to foreach - faster than list-each. |
---|
3528 | </p><p>Fixed bug in ado driver - wiping out $this->fields with date fields. |
---|
3529 | </p><p>Performance Monitor, View SQL, Explain Plan did not work if strlen($SQL)>max($_GET length). Fixed. |
---|
3530 | </p><p>Performance monitor, oci8 driver added memory sort ratio. |
---|
3531 | </p><p>Added random property, returns SQL to generate a floating point number between 0 and 1; |
---|
3532 | </p><p><b>4.03 6 Nov 2003 </b> |
---|
3533 | </p><p>The path to adodb-php4.inc.php and adodb-iterators.inc.php was not setup properly. |
---|
3534 | </p><p>Patched SQLDate in interbase to support hours/mins/secs. Thx to ari kuorikoski. |
---|
3535 | </p><p>Force autorollback for pgsql persistent connections - |
---|
3536 | apparently pgsql did not autorollback properly before 4.3.4. See http://bugs.php.net/bug.php?id=25404 |
---|
3537 | </p><p><b>4.02 5 Nov 2003 </b> |
---|
3538 | </p><p>Some errors in adodb_error_pg() fixed. Thx to Styve. |
---|
3539 | </p><p>Spurious Insert_ID() error was generated by LogSQL(). Fixed. |
---|
3540 | </p><p>Insert_ID was interfering with Affected_Rows() and Replace() when LogSQL() enabled. Fixed. |
---|
3541 | </p><p>More foreach loops optimized with list/each. |
---|
3542 | </p><p>Null dates not handled properly in ADO driver (it becomes 31 Dec 1969!). |
---|
3543 | </p><p>Heinz Hombergs contributed patches for mysql MetaColumns - adding scale, made |
---|
3544 | interbase MetaColumns work with firebird/interbase, and added lang/adodb-de.inc.php. |
---|
3545 | </p><p>Added INFORMIXSERVER environment variable. |
---|
3546 | </p><p>Added $ADODB_ANSI_PADDING_OFF for interbase/firebird. |
---|
3547 | </p><p>PHP 5 beta 2 compat check. Foreach (Iterator) support. Exceptions support. |
---|
3548 | </p><p><b>4.01 23 Oct 2003 </b> |
---|
3549 | </p><p>Fixed bug in rs2html(), tohtml.inc.php, that generated blank table cells. |
---|
3550 | </p><p>Fixed insert_id() incorrectly generated when logsql() enabled. |
---|
3551 | </p><p>Modified PostgreSQL _fixblobs to use list/each instead of foreach. |
---|
3552 | </p><p>Informix ErrorNo() implemented correctly. |
---|
3553 | </p><p>Modified several places to use list/each, including GetRowAssoc(). |
---|
3554 | </p><p>Added UserTimeStamp() to connection class. |
---|
3555 | </p><p>Added $ADODB_ANSI_PADDING_OFF for oci8po. |
---|
3556 | </p><p><b>4.00 20 Oct 2003 </b> |
---|
3557 | </p><p>Upgraded adodb-xmlschema to 1 Oct 2003 snapshot. |
---|
3558 | </p><p>Fix to rs2html warning message. Thx to Filo. |
---|
3559 | </p><p>Fix for odbc_mssql/mssql SQLDate(), hours was wrong. |
---|
3560 | </p><p>Added MetaColumns and MetaPrimaryKeys for sybase. Thx to Chris Phillipson. |
---|
3561 | </p><p>Added autoquoting to datadict for MySQL and PostgreSQL. Suggestion by Karsten Dambekalns |
---|
3562 | </p><p><b>3.94 11 Oct 2003 </b> |
---|
3563 | </p><p>Create trigger in datadict-oci8.inc.php did not work, because all cr/lf's must be removed. |
---|
3564 | </p><p>ErrorMsg()/ErrorNo() did not work for many databases when logging enabled. Fixed. |
---|
3565 | </p><p>Removed global variable $ADODB_LOGSQL as it does not work properly with multiple connections. |
---|
3566 | </p><p>Added SQLDate support for sybase. Thx to Chris Phillipson |
---|
3567 | </p><p>Postgresql checking of pgsql resultset resource was incorrect. Fix by Bharat Mediratta bharat#menalto.com. |
---|
3568 | Same patch applied to _insertid and _affectedrows for adodb-postgres64.inc.php. |
---|
3569 | </p><p>Added support for NConnect for postgresql. |
---|
3570 | </p><p>Added Sybase data dict support. Thx to Chris Phillipson |
---|
3571 | </p><p>Extensive improvements in $perf->UI(), eg. Explain now opens in new window, we show scripts |
---|
3572 | which call sql, etc. |
---|
3573 | </p><p>Perf Monitor UI works with magic quotes enabled. |
---|
3574 | </p><p>rsPrefix was declared twice. Removed. |
---|
3575 | </p><p>Oci8 stored procedure support, eg. "begin func(); end;" was incorrect in _query. Fixed. |
---|
3576 | </p><p>Tiraboschi Massimiliano contributed italian language file. |
---|
3577 | </p><p>Fernando Ortiz, fortiz#lacorona.com.mx, contributed informix performance monitor. |
---|
3578 | </p><p>Added _varchar (varchar arrays) support for postgresql. Reported by PREVOT Stéphane.<hr /> |
---|
3579 | <p><strong>0.10 Sept 9 2000</strong> First release |
---|
3580 | </p><h3><strong>Old change log history moved to <a href="old-changelog.htm">old-changelog.htm</a>. |
---|
3581 | </strong></h3> |
---|
3582 | <p> </p> |
---|
3583 | <p> |
---|
3584 | </p></body></html> |
---|