ADOdb

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<WRAP right box>
[[v5:reference:Index]]\\
</WRAP>
====== Reference Manual ====== 

See the [[v5:database:feature_comparison|Feature Comparison Matrix]]
===== Variables =====
| [[v5:reference:adodb_countrecs|$ADODB_COUNTRECS]]                | In database drivers that do not support native recordset counting, controls whether to emulate the functionality                                     |
| [[v5:reference:adodb_ansi_padding_off|$ADODB_ANSI_PADDING_OFF]]  | Determines whether to right trim CHAR fields                                                                                                         |
| [[v5:reference:adodb_cache_dir|$ADODB_CACHE_DIR]]                | If using recordset caching, determines the directory holding the cached data                                                                         |
| [[v5:reference:adodb_cache_class|$ADODB_CACHE_CLASS]]            | If using recordset caching, specifies a class for cached recordset handling                                                                          |
| [[v5:datetime:adodb_date_locale|$ADODB_DATE_LOCALE]]             | Sets a default date and time format for the ADOdb date/time library                                                                                  |
| [[v5:reference:adodb_force_type|$ADODB_FORCE_TYPE]]              | Changes the behavior of empty and null field handling when updating or creating records                                                              |
| [[v5:reference:adodb_fetch_mode|$ADODB_FETCH_MODE]]              | Sets the global array type (numeric or associative) for returned recordsets                                                                          |
| [[v5:reference:adodb_getone_eof|$ADODB_GETONE_EOF]]              | Sets the returned value if a valid SQL statement does not match any record when the method [[v5:reference:connection:getone|getOne()]] is executed.  |
| [[v5:reference:adodb_lang|$ADODB_LANG]]                          | Sets the language for error messages                                                                                                                 |
| [[v5:reference:adodb_quote_fieldnames|$ADODB_QUOTE_FIELDNAMES]]  | Quotes, and optionally controls the casing of field name in constructed SQL statements                                                               |
| [[v5:reference:adodb_compat_fetch|$ADODB_COMPAT_FETCH]]          | Determines the behavior of a record buffer if the pointer is advanced beyond EOF                                                                     |
| [[v5:reference:connection:version#adodb_vers|$ADODB_vers]]       | ADOdb version and release date                                                                                                                       |

===== Constants =====

|[[v5:reference:ADODB_ASSOC_CASE]]|Controls the case-specifity of recordset keys returned as associative arrays|
|[[v5:reference:ADODB_DEFAULT_METATYPE]]|Controls the default value returned if an unknown data type is tested|
===== The Database Connection Object =====

==== Establishing Connections ====
| [[v5:reference:connection:adonewconnection|adoNewConnection() ]]  | Create a new connection object                                                      |
| [[v5:reference:connection:connect|connect()]]                     | Establishes a non-persistent connection with a database                             |
| [[v5:reference:connection:isconnected|isConnected()]]             | Indicates if a connection has been established                                      |
| [[v5:reference:connection:adonewconnection|newAdoConnection()]]   | Is a pseudonym for [[v5:reference:connection:adonewconnection|adoNewConnection()]]  |
| [[v5:reference:connection:nconnect|nConnect()]]                   | Forces the establishment of  a new connection with a database                       |
| [[v5:reference:connection:pconnect|pConnect()]]                   | Establishes a persistent connection with a database                                 |
| [[v5:reference:connection:selectdb|selectDb()]]                   | Select which database to connect to                                                 |
| [[v5:reference:connection:setconnectionparameter()]]              | Sets an optional connection parameter                                               |
| [[v5:reference:connection:close|close()]]                         | Closes a database connection                                                        |


**See Also** [[v5:reference:connection:properties|Public Properties Of The Connection]]

==== Working With Cached Recordsets ====
ADOdb supports the ability to work with cached query results, either through storing the results on local disks, or via the use of a [[http://memcached.org|Memcached Server]]. The functions below work the same as their non-caching equivalents, but also check for the availabiltiy of cached results first. This can help reduce database load.
| [[v5:userguide:local_cache|Local Caching Setup]]                 | Configuring local parameters for caching                                                                                                    |
| [[v5:userguide:memcached|Memcached Setup]]                       | Configuring a memcached server connection                                                                                                   |
| [[v5:reference:connection:cacheexecute|cacheExecute()]]          | Executes a provided SQL statement and returns a handle to the result, or a cached handle if available                                       |
| [[v5:reference:connection:cachegetall|cacheGetAll()]]            | Executes a provided SQL statement and returns the entire recordset into an array                                                            |
| [[v5:reference:connection:cachegetassoc|cacheGetAssoc()]]        | Executes a provided SQL statement and returns the entire recordset into an associatitive array with the value of the first column as a key  |
| [[v5:reference:connection:cachegetcol|cacheGetCol()]]            | Executes a provided SQL statement and returns the first column of each row in the  recordset into an array                                  |
| [[v5:reference:connection:cachegetone|cacheGetOne()]]            | Retrieves the first column of the first matching row of an executed SQL statement                                                           |
| [[v5:reference:connection:cachegetrow|cacheGetRow()]]            | Retrieves the first matching row of an executed SQL statement                                                                               |
| [[v5:reference:connection:cacheselectlimit|cacheSelectLimit()]]  | Executes a provided SQL statement and returns a handle to the result, with the ability to supply a starting offset and record count         |
| [[v5:reference:connection:cacheflush|cacheFlush()]]              | Flushes a cached result set                                                                                                                 |

==== Executing SQL ====
| [[v5:reference:connection:autoexecute|autoExecute()]]  | Automatically prepares and executes Insert and Update statements based on supplied parameters                                               |
| [[v5:reference:connection:execute|execute()]]          | Executes a provided SQL statement and returns a handle to the result                                                                        |
| [[v5:reference:connection:getall|getAll()]]            | Executes a provided SQL statement and returns the entire recordset into an array                                                            |
| [[v5:reference:connection:getassoc|getAssoc()]]        | Executes a provided SQL statement and returns the entire recordset into an associatitive array with the value of the first column as a key  |
| [[v5:reference:connection:getcol|getCol()]]            | Executes a provided SQL statement and returns the first column of each row of he entire recordset into an array                             |
| [[v5:reference:connection:getmedian|getMedian()]]      | Returns the median value of a column in a table                                                                                             |
| [[v5:reference:connection:getone|getOne()]]            | Retrieves the first column of the first matching row of an executed SQL statement                                                           |
| [[v5:reference:connection:getrow|getRow()]]            | Retrieves the first matching row of an executed SQL statement                                                                               |
| [[v5:reference:connection:replace|replace()]]          | Provides a simple single record replacement function                                                                                        |
| [[v5:reference:connection:selectlimit()]]              | Executes a provided SQL statement and returns a handle to the result, with the ability to supply a starting offset and record count         |
| [[v5:reference:connection:setcharset|setCharSet()]]    | Sets the character set for database connections (limited databases)                                                                         |

==== Prepared Statements ====

| [[v5:reference:connection:inparameter|inParameter()]]            | Sets an input parameter to a stored procedure                    |
| [[v5:reference:connection:outparameter|outParameter()]]          | Receives an output parameter from a stored procedure             |
| [[v5:reference:connection:param|param()]]                        | Returns a database specific parameter placeholder                |
| [[v5:reference:connection:prepare|prepare()]]                    | Prepares an SQL statement and returns a handle to use            |
| [[v5:reference:connection:preparesp|prepareSp()]]                | Access a stored procedure and returns a handle to the procedure  |
| [[v5:reference:connection:releasestatement|releaseStatement()]]  | Releases a previously prepared statement                         |


==== Generating Database Independent SQL strings ====

| [[v5:reference:connection:addq|addQ()]]                  | Quotes a string, without prefixing nor appending quotes                         |
| [[v5:reference:connection:charmax|charMax()]]            | Returns the largest length of data that can be inserted into a character field  |
| [[v5:reference:connection:concat|concat()]]              | Returns a database-specific concatenation of strings                            |
| [[v5:reference:connection:getupdatesql|getUpdateSQL()]]  | Creates a database-specific SQL UPDATE statement based on supplied parameters   |
| [[v5:reference:connection:getinsertsql|getInsertSQL()]]  | Creates a database-specific SQL INSERT statement based on supplied parameters   |
| [[v5:reference:connection:ifnull|ifNull()]]              | Replaces a null value with a specified replacement                              |
| [[v5:reference:connection:qstr|quote()]]                 | Is a pseudonym for the function [[v5:reference:connection:qstr]]                |
| [[v5:reference:connection:qstr|qStr()]]                  | Appropriately quotes strings with ' characters for insertion into the database  |
| [[v5:reference:connection:textmax|textMax()]]            | Returns the largest length of data that can be inserted into a text field       |

==== Handling Blobs ====
| [[v5:reference:connection:blobdecode|blobDecode()]]             || Decodes an encoded blob                                                                          |
| [[v5:reference:connection:blobencode|blobEncode()]]             || Encodes a blob field in preparation for database insertion                                       |
| [[v5:reference:connection:updateblob|updateBlob()]]             || Updates a blob field in a table using a syntax similar to autoexecute                            |
| [[v5:reference:connection:updateblobfile|updateBlobFile()]]     || Updates a blob field in a table directly from a disk file using a syntax similar to autoexecute  |
| [[v5:reference:connection:updateclob|updateClob()]]             || Updates a clob field in a table using a syntax similar to autoexecute                            |
==== Paging/Scrolling ====
| [[v5:reference:recordset:absolutepage|absolutePage()]] | gets or sets the current page number in a paged recordset               |
| [[v5:reference:recordset:atfirstpage|atFirstPage()]]  | gets or sets whether at the first page in a paged recordset             |
| [[v5:reference:recordset:atlastpage|atLastPage()]]  | gets or sets whether at the last page in a paged recordset              |
| [[v5:reference:connection:cachepageexecute|cachePageExecute()]]| Return a requested page from a (possibly) cached recordset              |
| [[v5:reference:connection:lastpageno|lastPageNo()]]  | Returns the page number of the last page in a paged recordset           |
| [[v5:reference:recordset:maxrecordcount|maxRecordCount()]]  | Returns the maximum number of records that can be returned when paging  |
| [[v5:reference:connection:pageexecute|pageExecute()]]  | Returns a requested page from a recordset     |
==== Transaction Scoping ====
See the [[v5:userguide:transactions|Transaction Management Guide]]

| [[v5:reference:connection:begintrans|beginTrans()]]                     || Begins a granular transaction                 |
| [[v5:reference:connection:committrans|commitTrans()]]                   || Commits a granular transaction                |
| [[v5:reference:connection:completetrans|completeTrans()]]               || Completes a smart transaction                 |
| [[v5:reference:connection:failtrans|failTrans()]]                       || Forces a smart transaction to fail            |
| [[v5:reference:connection:hasfailedtrans|hasFailedTrans()]]             || Reports if a granular transaction has failed  |
| [[v5:reference:connection:rollbacktrans|rollbackTrans()]]               || Rollback a smart transaction                  |
| [[v5:reference:connection:settransactionmode|setTransactionMode()]]     || Sets the isolation level of a transaction.    |
| [[v5:reference:connection:starttrans|startTrans()]]                     || Starts a smart transaction                    |
| [[v5:reference:connection:transcnt|transCnt]]|| Returns the nesting level of smart transactions| 
| [[v5:reference:connection:transcnt|transOff]]||Temporarily disables transactions| 
==== Fetching Data ====
|[[v5:reference:connection:getfetchmode|getFetchMode()]]|Get the array type for return data|
|[[v5:reference:connection:setfetchmode|setFetchMode()]]|Set the array type for return data|


==== Manipulating Dates & Times ====
| [[v5:reference:connection:binddate|bindDate()]]               | Creates a portable date field, for use in bind statements        |
| [[v5:reference:connection:bindtimestamp|bindTimeStamp()]]     | Creates a portable timestamp field, for use in bind statements   |
| [[v5:reference:connection:dbdate|dbDate()]]                   | Creates a portable date field, for use in SQL statements         |
| [[v5:reference:connection:dbtimestamp|dbTimeStamp()]]         | Creates a portable timestamp field, for use in SQL statements    |
| [[v5:reference:connection:offsetdate|offsetDate()]]           | Creates a portable date offset field, for use in SQL statements  |
| [[v5:reference:connection:setdatelocale|setDateLocale()]]                   | Changes the SQL connection to a specified Locale                 |
| [[v5:reference:connection:sqldate|sqlDate()]]            | Returns a portably-formatted date string from a timestamp database column       |
| [[v5:reference:connection:unixdate|unixDate()]]               | Uses the database connection to create date strings              |
| [[v5:reference:connection:unixtimestamp|unixTimeStamp()]]     | Uses the database connection to create date/time strings         |
==== Row Management ====
|[[v5:reference:connection:affected_rows|affected_rows()]]|Returns the number of rows affected by the last operation|
|[[v5:reference:connection:createsequence|createSequence()]]|Creates a sequence in the database|
|[[v5:reference:connection:dropsequence|dropSequence()]]|Drops a sequence in the database| 
|[[v5:reference:connection:genid|genId()]]|A portable method of creating sequence numbers|
|[[v5:reference:connection:insert_id|insert_id()]]|Returns the last auto-increment number for an SQL statement|
|[[v5:reference:connection:rowlock|rowLock()]]|Lock a table row for a duration of a transaction|


==== Error Handling ==== 
|[[v5:reference:connection:errormsg|errorMsg()]]|Returns a database specific error message|
|[[v5:reference:connection:ignoreerrors|ignoreErrors()]]|Overrides the built-in transaction and error handling status|
|[[v5:reference:connection:metaerror|metaError()]]|Returns a portable error number based on a database specific error|
|[[v5:reference:connection:metaerrormsg|metaErrorMsg()]]|Returns a portable error message based on a portable error number. The language of the message may be controlled by [[v5:reference:adodb_lang|$ADODB_LANG]]|

 

====Query Rewriting ====
| [[v5:reference:connection:fnexecute|fnExecute and fnCacheExecute]]     || A reference to a function that overrides the execute function  |
 
==== Information ====

| [[v5:reference:connection:version|version()]] | ADOdb version number |
| [[v5:reference:connection:serverinfo|serverInfo()]] | Database server version and information |


===== The Recordset Object =====
==== Returns one field ====
|[[v5:reference:recordset:fields|fields()]]|Returns a single field in a single row of the current recordset|

==== PEAR Compatibility ====
This series of  functions is designed to duplicate the commands and emulate the functionality provided by the now deprecated [[https://pear.php.net/manual/en/package.database.db.php|PEAR DB]] module. ADOdb also provides an unsupported PEAR Auth connection plugin in the ''/adodb/pear/auth'' directory.
 
| [[v5:reference:connection:fetchinto|fetchInto()]]        | Fetches  a recordset into an array                                                    |
| [[v5:reference:recordset:fetchnextobj|fetchNextObj()]]   | Returns the current row as an object for convenience and advances the record pointer  |
| [[v5:reference:recordset:fetchnextobj|fetchNextObject]]  | This is a pseudonym for fetchNextObj                                                  |
| [[v5:reference:recordset:fetchobj|fetchObj()]]           | Returns the current row as an object for convenience                                  |
| [[v5:reference:recordset:fetchobj|fetchObject()]]        | This is a pseudonym for fetchObj                                                      |
| [[v5:reference:recordset:fetchrow|fetchRow()]]           | Reads  a row of a result set and advances the recordset pointer                       |
| [[v5:reference:connection:close|free()]]                 | Is a pseudonym for **close()**                                                        |
| [[v5:reference:connection:getrowassoc|getRowAssoc()]]    | Reads a row in associative mode if the recordset fetch mode is numeric                |
| [[v5:reference:recordset:numcols|numCols()]]             | Returns the number of columns in a row of a returned recordset                        |
| [[v5:reference:recordset:numrows|numRows()]]             | Returns the number of rows in a returned recordset                                    |

==== Returns all rows ==== 
|[[v5:reference:connection:getarray|getArray()]]|Returns a complete recordset as an array|
|[[v5:reference:connection:getassoc|getAssoc()]]|Returns an associate key/value array, with other options|
|[[v5:reference:connection:getarray|getRows()]]|This function is a pseudonym for [[v5:reference:connection:getarray|getArray()]]|
|[[v5:reference:connection:getrandrow|getRandRow()]]|Returns a random record from a recordset|
==== Scrolling ====
| [[v5:reference:recordset:move|move()]]                       || Move to the n<sup>th</sup> record of a recordset                                |
| [[v5:reference:recordset:movenext|moveNext()]]               || Moves the cursor to the next record of the recordset from the current position  |
| [[v5:reference:recordset:movefirst|moveFirst()]]             || Moves the cursor to the first record of the recordset                           |
| [[v5:reference:recordset:movelast|moveLast()]]               || Moves to the last record of a recordset                                         |
| [[v5:reference:connection:currentrow|AbsolutePosition()]]     || absolutePosition() is a pseudonym for currentRow()                              |
| [[v5:reference:connection:currentrow|currentRow()]]           || Returns the current row number of a recordset                                   |

 
==== Menu generation ====
| [[v5:reference:recordset:getmenu|getMenu()]]    | Creates a string containing a single or multi select HTML select box                                              |
| [[v5:reference:recordset:getmenu2|getMenu2()]]  | (deprecated) Creates a string containing a basic HTML select box with alternate comparison criteria to getMenu()  |
| [[v5:reference:recordset:getmenu3|getMenu3()]]  | Creates a string containing a grouped (optgroup)  HTML single or muilti-select box                                |

==== Dates ====
| [[v5:reference:connection:unixdate|unixDate()]]               || Uses the DBMS to return a timestamp from a date string              |
| [[v5:reference:connection:unixtimestamp|unixTimeStamp()]]     || Uses the DBMS to return a timestamp from a date/time string         |
| [[v5:reference:connection:userdate|userDate()]]               || Returns a formatted date string for a user supplied timestamp       |
| [[v5:reference:connection:usertimestamp|userTimeStamp()]]     || Returns a formatted date/time string for a user supplied timestamp  |


==== Recordset Info ====
| [[v5:reference:recordset:nextrecordset|nextRecordSet()]]   | In databases that allow accessing of recordsets, retrieves the next set  |
| [[v5:reference:connection:po_recordcount|po_recordCount()]]| A Portable record count supported by all databases|
| [[v5:reference:connection:recordcount|recordCount()]]| Interface to the native driver recordCount function |
| [[v5:reference:connection:recordcount|rowCount()]]|Is a synonym for [[v5:reference:connection:recordcount|recordCount()]] |



==== Field Info ====
| [[v5:reference:recordset:fetchfield|fetchField()]]       | Returns raw, database specific information about a field                                   |
| [[v5:reference:recordset:fieldcount|fieldCount()]]       | Returns the the number of fields in a row of a recordset                                   |
| [[v5:reference:recordset:fieldtypesarray|fieldTypesArray()]]  | Returns an array of all the [[v5:dictionary:adofieldobject|ADOFieldObjects]] columns in a row  |
==== Recordset Cleanup ====
|[[v5:reference:connection:close|close()]]|Closes both the recordset and database connection|