[Phpgamedev-cvs-commits] plugins db_readme.txt,NONE,1.1

[Nick <sph...@us...>]

Update of /cvsroot/phpgamedev/plugins
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv25233

Added Files:
	db_readme.txt 
Log Message:


--- NEW FILE: db_readme.txt ---
/**************************************************/
/*
/* Readme for PHPGameDev DB Abstraction Layer
/* $Id: db_readme.txt,v 1.1 2005/06/14 20:29:16 sphen001 Exp $
/**************************************************/

You can find an online version of this readme at:

http://phpgamedev.sourceforge.net/docs/db_readme.html

Feature List:

   Features of the PHPGameDev DB Abstraction Layer

	DB Layer Definition: All of the DB layers support a type definition.  You can use this definition to switch between code for different DBMS's.

	For example, if you had a query that would not run in Oracle, you could use a switch to switch what code you use.  

	<?php
	// We have a query that will run on every DBMS except Oracle

	switch ( DB )
	{
		case 'MySQL' :
		case 'MSSQL' :
			$sql = 'Regular SQL code here';
			break;
		case 'Oracle' :
			$sql = 'Oracle specific SQL code here';
			break;
	{
	?>

	Connection Type: Supports both normal and persistent connections.

Function Reference:

	Here we'll define all the functions and explain what they are used for.

Function: connect($db_host, $db_username, $db_password, $db, $persistent = FALSE)

	This function connects to a DB.  Only $persistent is not required.

	$db_host: The hostname of the DB server you are connecting to.
	$db_username: The DB username you will be using.
	$db_password: The DB password you will be using.
	$db: The specific DB you will be accessing.
	$persistent: Open a persistent connection or not.  Defaults to no.

	Returns TRUE on success, and FALSE on failure.

	Example:
		
		<?php
		$db->connect('localhost', 'root', '', 'some_db', FALSE);
		?>

Function: disconnect()

	This function disconnects from a DB.  You do not specify any arguments.

	Returns TRUE on success, and FALSE on failure.

	Example:

		<?php
		$db->disconnect();
		?>

Function: query($query)

	This function executes a query on the DB.  All arguments are required.  

	$query: The SQL query that is to be executed.

	Returns the result on success, and FALSE on failure.

	Example:

		<?php
		$sql = "SELECT *
			FROM some_db
				WHERE some_condition='some_condition'";
		$db->query($sql);
		?>

Function: fetch_row($result, $type = 'ASSOC')

	This function fetches a row from the DB.  Only $result is required.

	$result: The result of an executed SQL query.
	$type: The type of fetch_row you want to perform.  Defaults to ASSOC.
		
		Types:
			ASSOC: Fetches an associative array (mysql_fetch_assoc())
			ARRAY: Fetches an array (mysql_fetch_array())
			OBJECT: Fetches an object (mysql_fetch_object())
			ROW: Fetches a single row (mysql_fetch_row())

	Returns row on success, and FALSE on failure.

	Example:

		<?php
		while ( $row = $db->fetch_row($result, 'ASSOC') )
		{
			echo $row['field_name'];
		}

		while ( $row = $db->fetch_row($result, 'ARRAY') )
		{
			echo $row[0];
		}

		while ( $row = $db->fetch_row($result, 'OBJECT') )
		{
			echo $row->some_field;
		}

		while ( $row = $db->fetch_row($result, 'ROW') )
		{
			echo $row[0];
		{
		?>

Function: num_rows($result)

	This function fetches the number of rows affected by the executed SQL query.  All arguments are required.

	$result: The result of an executed SQL query.

	Returns number of rows on success, and FALSE on failure.

	Example:

		<?php
		echo $db->num_rows($result);
		?>

Function: free_result($result)

	This function frees up the memory associated with the executed SQL query.  All arguments are required.

	$result: The result of an executed SQL query.

	Returns TRUE always.

	Example:

		<?php
		$db->free_result($result);
		?>

Function: num_queries()

	This function returns the number of queries that were performed during the scripts execution.

	Returns the number of queries performed.  

	Example:

		<?php
		echo $db->num_queries();
		?>

Function: escape($sql)

	This function escapes a SQL query.  

	Returns the escaped query

	Example:

	<?php
	$sql = "SELECT *
		FROM some_table";
	$sql = $db->escape($sql);
	?>

Variable Reference:

   Here are explanations of the variables used in the DB layer.

	var $connect_id: Contains the connection details of the DB connection.
	var $query_result: Contains the result of the executed SQL query.
	var $query_rowset: Contains a row selected from the result of the executed SQL query.
	var $num_rows: Contains the number of affected rows.
	var $num_queries: Contains the number of queries performed in the scripts execution.

Example Script:

   An example script to demonstrate the features of this layer.

	<?php

	// Include the DB layer, and instantiate a new class	

	include './db_*.php';
	$db = new db;

	// Connect

	$db->connect('localhost', 'root', '', 'db', FALSE);

	// Perform a query

   switch ( DB )
   {
      case 'MySQL' :
      case 'MSSQL' :
         $sql = "SELECT *
            FROM some_table";
         break;
      case 'Oracle' :
         $sql = "Oracle specific code";
         break;
   }

	$sql = $db->escape($sql);
	$result = $db->query($sql);

	// Get the result set

	while ( $row = $db->fetch_row($result, 'ASSOC') )
	{
		echo $row['field_name'];
	}

	// Get then number of affected rows and number of queries

	echo $db->num_rows($result);
	echo $db->num_queries();

	// Disconnect

	$db->disconnect();
	?>