File: readme_Oracle_wrapper.txt

Readme for Oracle.lib.php (Oracle database access wrapper class)

This class is meant to provide an API to wrap around Oracle database access functions. 
The API is compatible with the one provided by the Mysql.lib.php wrapper.

Also see 'Oracle.test.php' for example scripts.


1) Include the class file in your script:

	include('Oracle.lib.php');


2) Create an instance of Oracle (make an object):

	$dbc = new Oracle();


3) Connect to Oracle database, call method connect with connection parameters:
	
	$dbc->connect($Sid, $Username, $Password);
	
	You can also give connection parameters into class constructor and so skip step 3:
	
		$dbc = new Oracle($carr); // where $carr = array('sid', 'username', 'password');


4) Set query string:

	$sql = "SELECT * FROM USERS"; // this is an example!

		
5) Execute query:

	$dbc->query($sql); // returns FALSE on error, TRUE on success
	
	On Error you can get Oracle error message from string $dbc->get_error_string():
	The $dbc->Error is Array, so you have to format it yourself: 
		$dbc->Error = Array(
			'code' => 'the error code',
			'message' => 'error message',
			'offset' => 'error offset in query',
			'sqltext' => 'the query string'
			)

		if ( !$dbc->query($sql) )
			print "Error ocurred: " . $dbc->get_error_string();


6) Get query result rows:
	
	$result_arr = array();
	
	while ( $dbc->next_record() ) 
	{
		$result_arr[] = $dbc->Record; // the whole row
			OR
		$result_arr[] => $dbc->f('fieldname'); // one field value from current row
			OR 
		$result_arr[] => $dbc->Record['fieldname']; // same as above
	}
	
	You can use handy help function 'build_results()',
	that gets the whole result into array (skiping step 5):
	
		$result_arr = $dbc->build_results($sql);


7) Happy?



Public methods in the Oracle class:
-----------------------------------

//  Class constructor, sets connection parameters (in array $arrp), if given
	
	Oracle($arrp = null)


// connects to database with given parameters (session id, username, password)
// parameters are not needed when parameters are given in class contructor
	
	connect($Sid = '', $Username = '', $Password = '') // returns FALSE on error, TRUE on success


// Disconnects from database
	
	disconnect() // returns FALSE on error


// Executes query, returns FALSE on error, TRUE on success

	query($sql)


// For compability with Mysql.lib.php, not doing anything

	last_insert_id() // in this case returns 0 (zero)
	
	/*
		Here is how you can get last inserted id in Oracle:
		(you have to have sequence named USERS_SEQ for table USERS) 
	
			$sql = "INSERT INTO USERS(FIRSTNAME, LASTNAME, USERNAME[, ...]) VALUES ( 'blaa', 'blaa', 'blaa'[, ...])";
			if ( !$dbc->query($sql) )
				return 0; // query failed
	
			$sql = 'SELECT USERS_SEQ.CURRVAL AS NEW_ID FROM DUAL';
			if ( $dbc->query($sql) && $dbc->next_record() )
				return $dbc->f('NEW_ID'); // return squence's current value (last inserted id for table USERS)
	*/
	

// Executes query, inserts query result rows into array
	
	build_results($query); // returns created array


// Gets next record (row) from query result

	next_record()


// Seeks to (result) row nr $r

	seek($r)


// Returns given field's ($name) value

	f($name) 

// Returns the Error Array as string
	get_error_string()


---
Tarmo Protsin <tarmopr@hot.ee>