[htoolkit-cvs] HSQL/MySQL HSQL.hsc,1.1,1.2

[<kr_...@us...>]

Update of /cvsroot/htoolkit/HSQL/MySQL
In directory sc8-pr-cvs1:/tmp/cvs-serv8597/MySQL

Modified Files:
	HSQL.hsc 
Log Message:
comments


Index: HSQL.hsc
===================================================================
RCS file: /cvsroot/htoolkit/HSQL/MySQL/HSQL.hsc,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** HSQL.hsc	7 Sep 2003 19:16:11 -0000	1.1
--- HSQL.hsc	7 Sep 2003 22:57:25 -0000	1.2
***************
*** 133,137 ****
  -----------------------------------------------------------------------------------------
  
! connect :: String -> String -> String -> String -> IO Connection
  connect server database user authentication = do
  	pMYSQL <- mysql_init nullPtr
--- 133,142 ----
  -----------------------------------------------------------------------------------------
  
! -- | Makes a new connection to the database server.
! connect :: String   -- ^ Server name
!         -> String   -- ^ Database name
!         -> String   -- ^ User identifier
!         -> String   -- ^ Authentication string (password)
!         -> IO Connection
  connect server database user authentication = do
  	pMYSQL <- mysql_init nullPtr
***************
*** 147,151 ****
  	when (res == nullPtr) (handleSqlError pMYSQL)
  	return (Connection pMYSQL)
! 	
  disconnect :: Connection -> IO ()
  disconnect (Connection pMYSQL) = mysql_close pMYSQL
--- 152,157 ----
  	when (res == nullPtr) (handleSqlError pMYSQL)
  	return (Connection pMYSQL)
! 
! -- | Closes the connection.	
  disconnect :: Connection -> IO ()
  disconnect (Connection pMYSQL) = mysql_close pMYSQL
***************
*** 155,163 ****
  -----------------------------------------------------------------------------------------
  
  execute :: Connection -> String -> IO ()
  execute conn@(Connection pMYSQL) query = do
  	res <- withCString query (mysql_query pMYSQL)
  	when (res /= 0) (handleSqlError pMYSQL)
! 		
  query :: Connection -> String -> IO Statement
  query conn@(Connection pMYSQL) query = do
--- 161,171 ----
  -----------------------------------------------------------------------------------------
  
+ -- | Execute statement
  execute :: Connection -> String -> IO ()
  execute conn@(Connection pMYSQL) query = do
  	res <- withCString query (mysql_query pMYSQL)
  	when (res /= 0) (handleSqlError pMYSQL)
! 
! -- | Executes the statement and returns a 'Statement' value which represents the result set
  query :: Connection -> String -> IO Statement
  query conn@(Connection pMYSQL) query = do
***************
*** 210,213 ****
--- 218,223 ----
  		mkSqlType (#const FIELD_TYPE_NULL) _ _ = SqlUnknown
  
+ -- | 'fetch' fetches the next rowset of data from the result set.
+ -- The values from columns can be retrieved with 'getFieldValue' function.
  fetch :: Statement -> IO Bool
  fetch (Statement {pRes=pRes,currRow=currRow})
***************
*** 218,221 ****
--- 228,234 ----
  		return (pRow /= nullPtr)
  
+ -- | 'closeStatement' stops processing associated with a specific statement, closes any open cursors 
+ -- associated with the statement, discards pending results, and frees all resources associated with 
+ -- the statement.
  closeStatement :: Statement -> IO ()
  closeStatement (Statement {pRes=pRes})
***************
*** 227,230 ****
--- 240,247 ----
  -----------------------------------------------------------------------------------------
  
+ -- | The 'inTransaction' function executes the specified action in transaction mode.
+ -- If the action completes successfully then the transaction will be commited.
+ -- If the action completes with an exception then the transaction will be rolled back
+ -- and the exception will be throw again.
  inTransaction :: Connection -> (Connection -> IO a) -> IO a
  inTransaction conn action = do
***************
*** 364,368 ****
  
  
! getFieldValueMB :: SqlBind a => Statement -> String -> IO (Maybe a)
  getFieldValueMB (Statement {currRow=currRow, fields=fieldDefs}) name = do
  	row <- readIORef currRow
--- 381,389 ----
  
  
! -- | Retrieves the value of field with the specified name.
! -- The returned value is Nothing if the field value is @null@.
! getFieldValueMB :: SqlBind a => Statement 
!                              -> String         -- ^ Field name
!                              -> IO (Maybe a)   -- ^ Field value or Nothing
  getFieldValueMB (Statement {currRow=currRow, fields=fieldDefs}) name = do
  	row <- readIORef currRow
***************
*** 377,381 ****
  				Nothing -> throwDyn (SqlBadTypeCast name sqlType)
  
! getFieldValue :: SqlBind a => Statement -> String -> IO a
  getFieldValue stmt name = do
  	mb_v <- getFieldValueMB stmt name
--- 398,406 ----
  				Nothing -> throwDyn (SqlBadTypeCast name sqlType)
  
! -- | Retrieves the value of field with the specified name.
! -- If the field value is @null@ then the function will throw 'SqlFetchNull' exception.
! getFieldValue :: SqlBind a => Statement 
!                            -> String       -- ^ Field name
!                            -> IO a         -- ^ Field value
  getFieldValue stmt name = do
  	mb_v <- getFieldValueMB stmt name
***************
*** 384,392 ****
  		Just a -> return a
  
! getFieldValue' :: SqlBind a => Statement -> String -> a -> IO a
  getFieldValue' stmt name def = do
  	mb_v <- getFieldValueMB stmt name
  	return (case mb_v of { Nothing -> def; Just a -> a })
  
  getFieldValueType :: Statement -> String -> (SqlType, Bool)
  getFieldValueType stmt name = (sqlType, nullable)
--- 409,423 ----
  		Just a -> return a
  
! -- | Retrieves the value of field with the specified name.
! -- If the field value is @null@ then the function will return the default value.
! getFieldValue' :: SqlBind a => Statement 
!                             -> String     -- ^ Field name
!                             -> a          -- ^ Default field value
!                             -> IO a       -- ^ Field value
  getFieldValue' stmt name def = do
  	mb_v <- getFieldValueMB stmt name
  	return (case mb_v of { Nothing -> def; Just a -> a })
  
+ -- | Returns the type and the @nullable@ flag for field with specified name
  getFieldValueType :: Statement -> String -> (SqlType, Bool)
  getFieldValueType stmt name = (sqlType, nullable)
***************
*** 394,397 ****
--- 425,429 ----
  		(sqlType,nullable,colNumber) = findFieldInfo name (fields stmt) 1
  
+ -- | Returns the list of fields with their types and @nullable@ flags
  getFieldsTypes :: Statement -> [(String, SqlType, Bool)]
  getFieldsTypes = fields
***************
*** 407,415 ****
  -----------------------------------------------------------------------------------------
  
! forEachRow :: (Statement -> s -> IO s) -> Statement -> s -> IO s
  forEachRow f stmt s = do
  	success <- fetch stmt
  	if success then f stmt s >>= forEachRow f stmt else closeStatement stmt >> return s
  
  forEachRow' :: (Statement -> IO ()) -> Statement -> IO ()
  forEachRow' f stmt = do
--- 439,454 ----
  -----------------------------------------------------------------------------------------
  
! -- | The 'forEachRow' function iterates through the result set in 'Statement' and
! -- executes the given action for each row in the set. After processing the last row
! -- the statement is automatically closed.
! forEachRow :: (Statement -> s -> IO s) -- ^ an action
!            -> Statement                -- ^ the statement
!            -> s                        -- ^ initial state
!            -> IO s                     -- ^ final state
  forEachRow f stmt s = do
  	success <- fetch stmt
  	if success then f stmt s >>= forEachRow f stmt else closeStatement stmt >> return s
  
+ -- | The 'forEachRow\'' function is analogous to 'forEachRow' but doesn't provide state.
  forEachRow' :: (Statement -> IO ()) -> Statement -> IO ()
  forEachRow' f stmt = do
***************
*** 417,420 ****
--- 456,462 ----
  	if success then f stmt >> forEachRow' f stmt else closeStatement stmt
  
+ -- | The 'collectRows' function iterates through the result set in 'Statement' and
+ -- executes the given action for each row in the set. The values returned from action
+ -- are collected and returned as list.
  collectRows :: (Statement -> IO a) -> Statement -> IO [a]
  collectRows f stmt = loop