SF.net SVN: frontierkernel: [1719] ODBs/trunk/docServerRoot/docServerData/ formats/outline/mySql

[<cre...@us...>]

Revision: 1719
          http://frontierkernel.svn.sourceforge.net/frontierkernel/?rev=1719&view=rev
Author:   creecode
Date:     2007-07-20 13:07:49 -0700 (Fri, 20 Jul 2007)

Log Message:
-----------
documenting some mySql verbs

Added Paths:
-----------
    ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/clearQuery.fvc
    ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/close.fvc
    ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/compileQuery.fvc

Added: ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/clearQuery.fvc
===================================================================
--- ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/clearQuery.fvc	                        (rev 0)
+++ ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/clearQuery.fvc	2007-07-20 20:07:49 UTC (rev 1719)
@@ -0,0 +1,85 @@
+FrontierVcsFile:3:optx:docServerData.formats.outline.mySql.clearQuery
+
+Syntax
+	mySql.clearQuery ( queryId )
+Params
+	queryId is a number, a query id.
+Action
+	Clear a MySQL query.
+Returns
+	0 ( zero )
+Examples
+	on querySample ( ) {
+		local ( databaseId, databaseName = "States", host = "127.0.0.1", password = "", port = 3306, query = "SELECT * FROM States", queryId, result, user = "root" );
+		
+		result = mySql.init ( );
+		
+		databaseId = mySql.connect ( host, user, password, databaseName, port );
+		
+		queryId = mySql.compileQuery ( databaseId, query );
+		
+		dialog.alert ( "Selected row count: " + mySql.getSelectedRowCount ( queryId ) );
+		dialog.alert ( "Column count: " + mySql.getColumnCount ( databaseId ) );
+		dialog.alert ( "Query warnings: " + mySql.getQueryWarningCount ( databaseId ) );
+		dialog.alert ( "Query info: " + mySql.getQueryInfo ( databaseId ) );
+		
+		loop {
+			result = mySql.getRow ( queryId );
+			
+			if result == 0 {
+				break};
+			
+			dialog.alert ( result )};
+		
+		mySql.clearQuery ( queryId );
+		
+		result = mySql.close ( databaseId );
+		
+		result = mySql.end ( );
+		
+		msg ( result )}
+	
+	on easyQuery ( databaseId, query, maxRows = 0 ) {
+		local ( queryId, dataSet = { }, row, rowCount = 0 );
+		
+		bundle { // is maxRow a number?
+			try {
+				number ( maxRows )}
+			else {
+				scriptError ( "mySql.easyQuery requires a numeric value for maxRows." )}};
+		
+		queryId = mySql.compileQuery ( databaseId, query ); // this will scriptError on its own if it fails
+		
+		if queryId > 0 {
+			loop {
+				result = mySql.getRow ( queryId );
+				
+				if result == 0 { // MySQL's code for no more rows
+					break};
+				
+				++rowCount;
+				
+				if ( maxRows > 0 ) and ( rowCount > maxRows ) {
+					break};
+				
+				dataSet [ rowCount ] = result};
+			
+			mySql.clearQuery ( queryId )};
+		
+		return ( dataSet )}
+Notes
+	MySQL returns nothing from the mysql_free_result call, which is what Frontier\xD5s mySql.clearQuery calls. So there\xD5s no real point in doing any error checking here, although you might want to test the general MySQL error functions.
+See Also
+	mySql.compileQuery
+	mySql.easyQuery
+	mySql.getAffectedRowCount
+	mySql.getQueryInfo
+	mySql.getQueryWarningCount
+	mySql.getRow
+	mySql.getSelectedRowCount
+	mySql.seekRow
+See Also MySQL APIs
+	mysql_free_result < http://dev.mysql.com/doc/refman/5.0/en/mysql-free-result.html >
+
+
+


Property changes on: ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/clearQuery.fvc
___________________________________________________________________
Name: svn:eol-style
   + native

Added: ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/close.fvc
===================================================================
--- ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/close.fvc	                        (rev 0)
+++ ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/close.fvc	2007-07-20 20:07:49 UTC (rev 1719)
@@ -0,0 +1,42 @@
+FrontierVcsFile:3:optx:docServerData.formats.outline.mySql.close
+
+Syntax
+	mySql.close ( databaseId )
+Params
+	databaseId is a number, the database connection ID.
+Action
+	Close a MySQL database connection ID.
+Returns
+	Nothing
+Examples
+	bundle {
+		on connect ( ) {
+			local ( databaseId, databaseName = "States", host = "127.0.0.1", password = "", port = 3306, result, user = "root" );
+			
+			try {
+				databaseId = mySql.connect ( host, user, password, databaseName, port )}
+			else {
+				dialog.alert ( mySql.getErrorMessage ( databaseId ) );
+				dialog.alert ( mySql.getErrorNumber ( databaseId ) )};
+			
+			result = mySql.close ( databaseId );
+			
+			return ( result )};
+		
+		local ( i );
+		
+		mySql.init ( );
+		
+		for i = 1 to 1000000 {
+			msg ( i + ": " + connect ( ) + " (" + sys.memAvail ( ) + ")" )};
+		
+		mySql.end ( )}
+Notes
+	The MySQL close API function doesn\xD5t appear to return any value for success or failure.
+See Also
+	mySql.connect
+See Also MySQL APIs
+	mysql_close  < http://dev.mysql.com/doc/refman/5.0/en/mysql-close.html >
+
+
+


Property changes on: ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/close.fvc
___________________________________________________________________
Name: svn:eol-style
   + native

Added: ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/compileQuery.fvc
===================================================================
--- ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/compileQuery.fvc	                        (rev 0)
+++ ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/compileQuery.fvc	2007-07-20 20:07:49 UTC (rev 1719)
@@ -0,0 +1,92 @@
+FrontierVcsFile:3:optx:docServerData.formats.outline.mySql.compileQuery
+
+Syntax
+	mySql.compileQuery ( databaseId, query )
+Params
+	databaseId is a number, the database connection ID.
+	query is a string, an SQL statement.
+Action
+	Compile a MySQL query, preparing it for execution.
+Returns
+	A number, query id or 0 (zero) if no rows were returned.
+Examples
+	on querySample ( ) {
+		local ( databaseId, databaseName = "States", host = "127.0.0.1", password = "", query = "SELECT * FROM States", queryId, result, sql, user = "root", port = 3306 );
+		
+		result = mySql.init ( );
+		
+		databaseId = mySql.connect ( host, user, password, databaseName, port );
+		
+		queryId = mySql.compileQuery ( databaseId, query );
+		
+		dialog.alert ( "Selected row count: " + mySql.getSelectedRowCount ( queryId ) );
+		dialog.alert ( "Column count: " + mySql.getColumnCount ( databaseId ) );
+		dialog.alert ( "Query warnings: " + mySql.getQueryWarningCount ( databaseId ) );
+		dialog.alert ( "Query info: " + mySql.getQueryInfo ( databaseId ) );
+		
+		loop {
+			result = mySql.getRow ( queryId );
+			
+			if result == 0 {
+				break};
+			
+			dialog.alert ( result )};
+		
+		mySql.clearQuery ( queryId );
+		
+		result = mySql.close ( databaseId );
+		result = mySql.end ( );
+		
+		return ( result )}
+	
+	on easyQuery ( databaseId, query, maxRows = 0 ) {
+		local ( queryId, dataSet = { }, row, rowCount = 0 );
+		
+		bundle { // is maxRow a number?
+			try {
+				number ( maxRows )}
+			else {
+				scriptError ( "mySql.easyQuery requires a numeric value for maxRows." )}};
+		
+		queryId = mySql.compileQuery ( databaseId, query ); // this will scriptError on its own if it fails
+		
+		if queryId > 0 {
+			loop {
+				result = mySql.getRow ( queryId );
+				
+				if result == 0 { // MySQL's code for no more rows
+					break};
+				
+				++rowCount;
+				
+				if ( maxRows > 0 ) and ( rowCount > maxRows ) {
+					break};
+				
+				dataSet [ rowCount ] = result};
+			
+			mySql.clearQuery ( queryId )};
+		
+		return ( dataSet )}
+Notes
+	Don\xD5t forget to put the mySql.compileQuery call inside a try statement. If you query with a bad SQL statement, Frontier will return a scriptError. It\xD5s also probably a good idea to check the various query information functions mySql.getSelectedRowCount, mySql.getColumnCount, mySql.getQueryWarningCount, and mySql.getQueryInfo.
+	
+	It\xD5s important to test the results of mySql.compileQuery for a 0 (zero) value. There are a number of other functions that rely on a queryID and if the queryID is 0, they will not function correctly or may crash. In particular, if mySql.compileQuery returns a 0, you do not need to execute a mySql.clearQuery command.
+	
+	There\xD5s a lot going on inside mySql.compileQuery. Within Frontier, we\xD5re calling two key MySQL API calls: mysql_query and mysql_store_result. As you might imagine, MySQL has a lot of depth in how it manages queries. In particular, it has two query result approaches: return the entire results table at once or return one line of the results table at once. The first uses the mysql_store_result API call and is the mechanism used within Frontier. While there are advantages to both, we use the store result approach because it gives us some more flexibility in certain areas. Read the MySQL API for more details. A lot of good information is at the bottom of this page.
+	
+	It should also be noted that MySQL supports multiple SQL statements in SQL queries. The current Frontier implementation does not. For each query, Frontier\xD5s wrapper to SQL will simply query based on the first statement in the SQL provided.
+See Also
+	mySql.clearQuery
+	mySql.easyQuery
+	mySql.getAffectedRowCount
+	mySql.getQueryInfo
+	mySql.getQueryWarningCount
+	mySql.getRow
+	mySql.getSelectedRowCount
+	mySql.seekRow
+See Also MySQL APIs
+	mysql_query < http://dev.mysql.com/doc/refman/5.0/en/mysql-query.html >
+	mysql_store_result < http://dev.mysql.com/doc/refman/5.0/en/mysql-store-result.html >
+
+
+


Property changes on: ODBs/trunk/docServerRoot/docServerData/formats/outline/mySql/compileQuery.fvc
___________________________________________________________________
Name: svn:eol-style
   + native


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.