Docs For Class db

Class db_oci8

Description

OCI8 Database Class.

Located in /inc/oci8_class.php (line 101)

Variable Summary

string $AdminEmail

integer $AffectedRows

string $appname

integer $connectRetries

string $database

integer $debug

string $errvars

string $host

integer $no_exit

array $output_hash

string $password

integer $querycounter

float $querytime

string $SAPI_type

integer $showError

mixed $sock

array $sqlcache

integer $sqlcount

string $sqlerr

string $sqlerrmsg

mixed $stmt

boolean $usePConnect

string $user

Method Summary

db_oci8 db_oci8 ([string $extconfig = ''])

integer AffectedRows ()

void checkSock ()

void clearOutputHash ()

integer Commit ()

mixed Connect ([string $user = NULL], [string $pass = NULL], [string $host = NULL], [integer $exit_on_error = 1])

array DescTable (string $tablename)

void Disconnect ([mixed $other_sock = -1])

mixed Execute (mixed $stmt)

mixed ExecuteHash (mixed $stmt, array &$bindvarhash)

array FetchResult ([integer $resflag = OCI_ASSOC], [mixed $extstmt = -1])

mixed FreeResult ([mixed $extstmt = -1])

array GetBindVars (string $query)

string GetClassVersion ()

mixed GetConnectionHandle ()

integer getConnectRetries ()

string GetErrorText ([string $exterr = ""])

float getmicrotime ()

array getOutputHash ()

integer GetQueryCount ()

float GetQueryTime ()

array getSQLError ()

mixed Prepare (string $querystring, [integer $no_exit = 0])

void PrintDebug (string $msg)

void Print_Error ([string $ustr = ''], [mixed $var2dump = NULL], [integer $exit_on_error = 1])

array Query (string $querystring, [integer $resflag = OCI_ASSOC], [integer $no_exit = 0])

array QueryHash (string $querystring, [integer $resflag = OCI_ASSOC], [integer $no_exit = 0], array &$bindvarhash)

mixed QueryResult (string $querystring)

mixed QueryResultHash (string $query, array &$inhash)

void RemoveFromQueryCache (integer $nr)

integer Rollback ()

integer SaveBLOB (string $file_to_save, string $blob_table, string $blob_field, string $where_clause)

integer SearchQueryCache (mixed $stmt)

void SendMailOnError (array $errarray)

void SetConnectionHandle (mixed $extsock)

integer setConnectRetries (integer $retcnt)

void SetDebug (integer $state)

void setErrorHandling (integer $val)

void setOutputHash (array &$outputhash)

boolean setPConnect (boolean $conntype)

boolean setPrefetch (integer $rows, [mixed $extstmt = -1])

void SQLDebug (boolean $state)

string Version ()

Variables

string $AdminEmail (line 140)

var: Email Address for the administrator of this project

integer $AffectedRows (line 136)

var: How many Rows where affected by previous DML operation

string $appname (line 120)

var: Name of application that uses this class.

integer $connectRetries (line 151)

var: How many connection retries we should try. Defaults to 1
since: 0.75

string $database (line 112)

var: Currently not in use.

integer $debug (line 122)

var: Debugstate, default is OFF.

string $errvars (line 130)

var: All passed variables except QUERY and Flags.

string $host (line 106)

var: The TNS name of the target database.

integer $no_exit (line 132)

var: Set to 1 to not auto-exit on error (Default is 0)

array $output_hash (line 144)

var: A hash array with all output parameters (used in QueryHash())

string $password (line 110)

var: The password used to connect to database.

integer $querycounter (line 114)

var: Counts amount of queries executed.

float $querytime (line 116)

var: Contains the total SQL execution time in microseconds.

string $SAPI_type (line 142)

var: The SAPI type of php (used to detect CLI sapi)

integer $showError (line 138)

var: Flag indates level of error information shown

mixed $sock (line 104)

var: Internal connection handle.

array $sqlcache (line 128)

var: Internal Cache for Prepare()/Execute() calls.

integer $sqlcount (line 134)

var: How many SQL queries have been executed

string $sqlerr (line 124)

var: Contains possible SQL query that failed.

string $sqlerrmsg (line 126)

var: Contains ocierror['message'] info in case of an error.

mixed $stmt (line 118)

var: Stores active statement handle.

boolean $usePConnect (line 146)

var: TRUE = Connect() uses Persistant connection, else new one (Default)

string $user (line 108)

var: The username used to connect to database.

Methods

Constructor db_oci8 (line 164)

Class Constructor.

Whenever you instantiate this class the file dbdefs.inc.php will be included automatically. This file contains the default login data and other configuration options, see description inside this file for further informations. Since V0.72 you may optionally give an alternate file as configuration file. If no file is given inside the constructor the class still uses the file "dbdefs.inc.php" as default configuration file.

see: dbdefs.inc.php

db_oci8 db_oci8 ([string $extconfig = ''])

string $extconfig: Full path to dbdefs.inc.php, if empty class searches in current dir for dbdefs.inc.php

AffectedRows (line 1303)

Returns count of affected rows.

Info is set in Query() and QueryResult() / FreeResult() and should return the amount of rows affected by previous DML command

return: Number of affected rows of previous DML command

integer AffectedRows ()

checkSock (line 1136)

Checks if we are already connected to our database.

If not terminates by calling Print_Error().

see: db_oci8::Print_Error()
since: 0.40

void checkSock ()

clearOutputHash (line 1475)

Clears the internal output hash array.

You are responsible to manage this yourself, the class only uses the variable!

see: db_oci8::getOutputHash()
see: db_oci8::setOutputHash()

void clearOutputHash ()

Commit (line 796)

Commits current transaction.

return: The value of OCICommit() is returned.
see: oci_commit

integer Commit ()

Connect (line 242)

Performs the connection to Oracle.

If anything goes wrong calls Print_Error(). Also an Oracle procedure is called to register the Application name as defined in dbdefs.inc.php, This helps DBAs to better fine tune their databases according to application needs.

return: Either the DB connection handle or an error array/exit, depending how $exit_on_error is set
see: oci_plogon
see: oci_logon
see: db_oci8::Print_Error()
see: dbdefs.inc.php

mixed Connect ([string $user = NULL], [string $pass = NULL], [string $host = NULL], [integer $exit_on_error = 1])

string $user: Username used to connect to DB
string $pass: Password to use for given username
string $host: Hostname of database to connect to
integer $exit_on_error: If set to 1 Class will automatically exit with error code, else return error array

DescTable (line 951)

Describes a table by returning an array with all table info.

return: A 2-dimensional array with table informations.

array DescTable (string $tablename)

string $tablename: Name of table you want to describe.

Disconnect (line 331)

Disconnects from Oracle.

You may optionally pass an external link identifier

see: OCI_Logoff

void Disconnect ([mixed $other_sock = -1])

mixed $other_sock: Optionally your own connection handle to close, else internal socket will be used.

Execute (line 1033)

Executes a prepare()d statement and returns the result.

You may then Fetch rows with FetchResult() or call FreeResult() to free your allocated result. V0.38: Execute() searches first our QueryCache before executing, this way we can use almost unlimited Queries at once in the Prepare/Execute pair

return: Returns result set read for FetchResult() usage or an error state depending on class setting in case of an error.
see: db_oci8::Prepare()

mixed Execute (mixed $stmt)

mixed $stmt: The statement handle to be executed.

ExecuteHash (line 1591)

Executes a prepare()d statement and returns the result.

You may then fetch rows with FetchResult() or call FreeResult() to free your allocated result. This method is almost identical to "Execute()", however the bind variables used are passed as an associative array instead of "guessing" them from query and given parameter. This is now the prefered way to use bind variables!

return: Returns result set read for FetchResult() usage or an error state depending on class setting in case of an error.
see: db_oci8::Prepare()
since: 0.77

mixed ExecuteHash (mixed $stmt, array &$bindvarhash)

mixed $stmt: The statement handle to be executed.
array &$bindvarhash: The bind variables as associative array (key = bindvar name, value = bindvar value).

FetchResult (line 686)

Fetches next datarow.

Returns either numeric (OCI_NUM) or associative (OCI_ASSOC) array for one data row as pointed to by either internal or passed result var.

return: The fetched datarow or NULL if no more data exist.
see: db_oci8::FreeResult()
see: db_oci8::QueryResult()

array FetchResult ([integer $resflag = OCI_ASSOC], [mixed $extstmt = -1])

integer $resflag: OCI_ASSOC => Return associative array or OCI_NUM => Return numeric array
mixed $extstmt: If != -1 then we try to fetch from that passed handle, else the class uses internal saved handle. Useful if you want to perform a lot of different queries.

FreeResult (line 715)

Frees result obtained by QueryResult().

You may optionally pass external Result handle, if you omit this parameter the internal handle is freed. This function also checks the built-in statement cache for the handle and removes it from cache, too.

return: The result of OCIFreeStatement() is returned.
see: OCI_Free_Statement
see: db_oci8::RemoveFromQueryCache()
see: db_oci8::SearchQueryCache()
see: db_oci8::FetchResult()
see: db_oci8::QueryResult()

mixed FreeResult ([mixed $extstmt = -1])

mixed $extstmt: Optional your external saved handle to be freed.

GetBindVars (line 836)

Function extracts all bind vars out of given query.

To avoid wrong determined bind vars this function first kills out all TO_*() functions together with their (possible) format strings which results in a query containing only valid bind vars, format tags or other similar constructed tags are removed.

return: Returns an array with all found bind vars in the order they are defined inside the query.

array GetBindVars (string $query)

string $query: The query to check for bind vars.

GetClassVersion (line 941)

Returns version of this class.

return: The version string in format "major.minor"

string GetClassVersion ()

GetConnectionHandle (line 1196)

Returns current connection handle.

Returns either the internal connection socket or -1 if no active handle exists. Useful if you want to work with OCI* functions in parallel to this class.

return: Internal socket value
since: 0.42

mixed GetConnectionHandle ()

getConnectRetries (line 1641)

Returns the number of retries in case of connection problems.

This value can be set globally inside the dbdefs.inc.php file via the OCIDB_CONNECT_RETRIES define but may be changed run-time also via the "setConnectRetries()" method.

return: The retry counter value currently set.
since: V0.78

integer getConnectRetries ()

GetErrorText (line 1271)

This function tries to get the description for a given error message.

Simply pass the $err['message'] field to this function, it tries to extract the required informations and call $ORACLE_HOME/bin/oerr to get the error description. If either the exterr or the internal sqlerrmsg variables are empty this function returns: "No error found."

return: The extracted error text.

string GetErrorText ([string $exterr = ""])

string $exterr: The error string from oracle. Maybe empty, in this case uses internal sqlerrmsg field.

getmicrotime (line 1555)

Returns microtime in format s.mmmmm.

Used to measure SQL execution time.

return: the current time in microseconds.

float getmicrotime ()

getOutputHash (line 1464)

Returns the contents of the output_hash variable.

return: The contents of the internal output_hash variable.
see: db_oci8::setOutputHash()

array getOutputHash ()

GetQueryCount (line 772)

Returns amount of queries executed by this class.

return: How many queries are executed currently by this class.

integer GetQueryCount ()

GetQueryTime (line 786)

Returns amount of time spend on queries executed by this class.

return: Time in seconds.msecs spent in executing SQL statements.
since: 0.68

float GetQueryTime ()

getSQLError (line 1313)

Returns hash with error informations from last query.

return: Assoc. array with error informations.
since: 0.55

array getSQLError ()

Prepare (line 991)

Preparses a query but do not execute it (yet).

This allows to use a compiled query inside loops without having to parse it everytime Since 0.38 all prepared() queries will be put into our own QueryCache() so we can use the Prepare()/Execute()/ExecuteHash() pair for more than one query at once.

return: Either the statement handle on success or an error code / calling print_error().

mixed Prepare (string $querystring, [integer $no_exit = 0])

string $querystring: The Query you want to prepare (can contain bind variables).
integer $no_exit: 1 => Function returns errorcode instead of calling Print_Error() or 0 => Will always call Print_Error()

PrintDebug (line 865)

Handles debug output according to internal debug flag.

void PrintDebug (string $msg)

string $msg: The string to be send out to selected output.

Print_Error (line 368)

Prints out an Oracle error.

Tries to highlight the buggy SQL part of the query and dumps out as much informations as possible. This may lead however to security problems, in this case you can set DBOF_SHOW_NO_ERRORS and the Error informations are returned to the callee instead of being displayed on-screen. Since V0.64 the class is able to send an email error message, see dbdefs.inc.php

see: oci_error
see: print_r

void Print_Error ([string $ustr = ''], [mixed $var2dump = NULL], [integer $exit_on_error = 1])

string $ustr: Optional user-error string to be displayed
mixed $var2dump: Optional a variable to be dumped out via print_r()
integer $exit_on_error: If set to default of 1 this function terminates execution of the script by calling exit, else it simply returns.

Query (line 520)

Performs a single row query with Bindvar support.

Resflag can be OCI_NUM or OCI_ASSOC depending on what kind of array you want to be returned. Remember to pass all required variables for all defined bind vars after the $no_exit parameter, else you will recieve errors because of wrong parameter count!

return: The result of the query as either associative or numeric array. In case of an error can be also an assoc. array of error informations.

array Query (string $querystring, [integer $resflag = OCI_ASSOC], [integer $no_exit = 0])

string $querystring: The query to be executed against the RDBMS
integer $resflag: OCI_NUM for numeric array or OCI_ASSOC (default) for associative array result
integer $no_exit: 1 => Function returns errorcode instead of calling Print_Error() or 0 => Will always call Print_Error()

QueryHash (line 1372)

Performs a single row query with Bindvar support passed as associative hash.

Resflag can be OCI_NUM or OCI_ASSOC depending on what kind of array you want to be returned. Remember to pass all required variables for all defined bind vars after the $no_exit parameter as an assoc. array (Key = name of bindvar without ':', value = value to add).

return: The result of the query as either associative or numeric array. In case of an error can be also an assoc. array of error informations.
see: db_oci8::clearOutputHash()
see: db_oci8::getOutputHash()
see: db_oci8::setOutputHash()
since: 0.62

array QueryHash (string $querystring, [integer $resflag = OCI_ASSOC], [integer $no_exit = 0], array &$bindvarhash)

string $querystring: The query to be executed against the RDBMS
integer $resflag: OCI_NUM for numeric array or OCI_ASSOC (default) for associative array result
integer $no_exit: 1 => Function returns errorcode instead of calling Print_Error() or 0 => Will always call Print_Error()
array &$bindvarhash: The bind vars as associative array (keys = bindvar names, values = bindvar values)

QueryResult (line 606)

Performs a multirow-query and returns result handle.

Required if you want to fetch many data rows. Does not return in case of error, so no further checking is required. Supports also binding, see Query() for further details.

return: Returns the statement handle or an error array in case of an error.
see: db_oci8::FreeResult()
see: db_oci8::FetchResult()
see: db_oci8::Query()

mixed QueryResult (string $querystring)

string $querystring: SQL-Statement to be executed

QueryResultHash (line 1225)

Executes a query with parameters passed as hash values.

Also IN/OUT and RETURNING INTO <...> clauses are supported. You have to use FetchResult()/FreeResult() after using this function.

return: Either the statement handle or an error code / calling Print_Error().
see: db_oci8::FetchResult()
see: db_oci8::FreeResult()
since: 0.44

mixed QueryResultHash (string $query, array &$inhash)

string $query: The Query to be executed.
array &$inhash: The bind vars as associative array (keys = bindvar names, values = bindvar values)

RemoveFromQueryCache (line 1113)

Removes query from cache.

Tries to remove a query from cache that was found by a previous call to SearchQueryCache().

since: 0.38

void RemoveFromQueryCache (integer $nr)

integer $nr: Number of statement handle to be removed from cache.

Rollback (line 814)

Rollback current transaction.

return: The value of OCIRollback() is returned.
see: oci_rollback

integer Rollback ()

SaveBLOB (line 1154)

Allows to save a file to a binary object field (BLOB).

Does not commit!

return: If all is okay returns 0 else an oracle error code.
since: 0.41

integer SaveBLOB (string $file_to_save, string $blob_table, string $blob_field, string $where_clause)

string $file_to_save: Full path and filename of file to save
string $blob_table: Name of Table where the blobfield resides
string $blob_field: Name of BLOB field
string $where_clause: Criteria to get the right row (i.e. WHERE ROWID=ABCDEF12345)

SearchQueryCache (line 1093)

Searches internal query cache for given statement id.

Returns index of found statement id or -1 to indicate an error. This function is considered private and should NOT (!) be called from outside this class!

return: The index number of the found statement or -1 if no handle could be found.
since: 0.38

integer SearchQueryCache (mixed $stmt)

mixed $stmt: The statement handle to search for

SendMailOnError (line 1487)

Sends an error email.

If OCIDB_SENTMAILONERROR is defined and != 0 the class sent out an error report to the configured email address in case of an error.

see: db_oci8::getSQLError()

void SendMailOnError (array $errarray)

array $errarray: The error array from Oracle as returned by getSQLError()

SetConnectionHandle (line 1209)

Allows to set internal socket to external value.

Note that the internal socket descriptor is only overriden if the class has no active connection stored! If already a connection was performed the class does not override it's internal handle to avoid problems!

since: 0.49

void SetConnectionHandle (mixed $extsock)

mixed $extsock: The connection handle as returned from OCILogon().

setConnectRetries (line 1654)

Change the number of retries the class performs in case of connection problems.

This value is globally setable in the dbdefs.inc.php script (see define OCIDB_CONNECT_RETRIES) but can be set also run-time via this method.

return: The previous value
since: V0.78

integer setConnectRetries (integer $retcnt)

integer $retcnt: The new number of connect retries.

SetDebug (line 856)

Function allows debugging of SQL Queries.

$state can have these values:

DBOF_DEBUGOFF = Turn off debugging
DBOF_DEBUGSCREEN = Turn on debugging on screen (every Query will be dumped on screen)
DBOF_DEBUFILE = Turn on debugging on PHP errorlog

You can mix the debug levels by adding the according defines!

void SetDebug (integer $state)

integer $state: The DEBUG level to set

setErrorHandling (line 1329)

Allows to set the handling of errors.

DBOF_SHOW_NO_ERRORS => Show no security-relevant informations
DBOF_SHOW_ALL_ERRORS => Show all errors (useful for develop)
DBOF_RETURN_ALL_ERRORS => No error/autoexit, just return the mysql_error code.

since: 0.57

void setErrorHandling (integer $val)

integer $val: The Error Handling mode you wish to use.

setOutputHash (line 1454)

Use this function to pass output hash data to QueryHash() function.

This is only required if you are using RETURNING INTO clauses or OUT variables, if you only use the bind variables for input (IN) you do not need to set this. WARNING: You are responsible to clear the array by using clearOutputHash()!

see: db_oci8::getOutputHash()

void setOutputHash (array &$outputhash)

array &$outputhash: The assoc. array to use for bind var return variables

setPConnect (line 1569)

Sets connection behavour.

If FALSE class uses oci_logon to connect. If TRUE class uses oci_plogon to connect (Persistant connection)

return: The previous state
since: 0.73

boolean setPConnect (boolean $conntype)

boolean $conntype: TRUE => Enable persistant connections, FALSE => Disable persistant connections

setPrefetch (line 1342)

Allows to set the prefetch value when returning results.

Default is 1 which may lead to performance problems when data is transmitted via WAN.

return: Return value of OCISetPrefetch()
see: OCISetPrefetch()

boolean setPrefetch (integer $rows, [mixed $extstmt = -1])

integer $rows: Amount of rows to be used for prefetching.
mixed $extstmt: Optionally your own statement handle. If you omit this parameter the internal statement handle is used.

SQLDebug (line 921)

Allows to en- or disable the SQL_TRACE feature of Oracle.

Pass TRUE to enable or FALSE to disable. When enabled all Statements of your session are saved in a tracefile stored in $ORACLE_BASE/admin/<DBNAME>/udump/*.trc After your session disconnects use the tkprof tool to generate Human-readable output from the tracefile, i.e.: $> tkprof oracle_ora_7527.trc out.txt Now read 'out.txt' and see what happen in Oracle!

void SQLDebug (boolean $state)

boolean $state: TRUE to enable or FALSE to disable the SQL_TRACE feature.

Version (line 747)

Returns Oracle Server Version.

Opens an own connection if no active one exists.

return: The Oracle Release Version string

string Version ()

Documentation generated on Tue, 22 Sep 2009 22:17:38 +0200 by phpDocumentor 1.4.2