[[v5:reference:Index]]\\ ====== 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^th 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|