htoolkit-cvs

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

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

Modified Files:
	HSQL.hsc 
Log Message:
comments


Index: HSQL.hsc
===================================================================
RCS file: /cvsroot/htoolkit/HSQL/PostgreSQL/HSQL.hsc,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** HSQL.hsc	7 Sep 2003 19:28:01 -0000	1.4
--- HSQL.hsc	7 Sep 2003 22:57:25 -0000	1.5
***************
*** 161,165 ****
  -----------------------------------------------------------------------------------------
  
! connect :: String -> String -> String -> String -> IO Connection
  connect server database user authentication = do
  	pServer <- newCString server
--- 161,170 ----
  -----------------------------------------------------------------------------------------
  
! -- | 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
  	pServer <- newCString server
***************
*** 178,181 ****
--- 183,187 ----
  	return (Connection pConn)
  
+ -- | Closes the connection.
  disconnect :: Connection -> IO ()
  disconnect (Connection pConn) = pqFinish pConn
***************
*** 186,189 ****
--- 192,196 ----
  -----------------------------------------------------------------------------------------
  
+ -- | Execute statement
  execute :: Connection -> String -> IO ()
  execute conn@(Connection pConn) sqlExpr = do
***************
*** 198,201 ****
--- 205,209 ----
  	return ()
  
+ -- | Executes the statement and returns a 'Statement' value which represents the result set
  query :: Connection -> String -> IO Statement
  query conn@(Connection pConn) query = do
***************
*** 258,261 ****
--- 266,271 ----
  		mkSqlType (#const UNKNOWNOID)	size = 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 {countTuples=countTuples, tupleIndex=tupleIndex}) = do
***************
*** 266,269 ****
--- 276,282 ----
  		else writeIORef tupleIndex index' >> return True
  
+ -- | '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 _ = return ()
***************
*** 273,277 ****
  -----------------------------------------------------------------------------------------
  
! inTransaction :: Connection -> (Connection -> IO a) -> IO a
  inTransaction conn action = do
  	execute conn "begin"
--- 286,296 ----
  -----------------------------------------------------------------------------------------
  
! -- | 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)  -- ^ an action
!               -> IO a                  -- ^ the returned value is the result returned from action
  inTransaction conn action = do
  	execute conn "begin"
***************
*** 544,548 ****
  			showHex = showIntAtBase 16 intToDigit
  
! getFieldValueMB :: SqlBind a => Statement -> String -> IO (Maybe a)
  getFieldValueMB (Statement {pRes=pRes, connection=conn, fields=fieldDefs, countTuples=countTuples, tupleIndex=tupleIndex}) name = do
  	index <- readIORef tupleIndex
--- 563,571 ----
  			showHex = showIntAtBase 16 intToDigit
  
! -- | 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 {pRes=pRes, connection=conn, fields=fieldDefs, countTuples=countTuples, tupleIndex=tupleIndex}) name = do
  	index <- readIORef tupleIndex
***************
*** 558,562 ****
  				Nothing -> throwDyn (SqlBadTypeCast name sqlType)
  
! getFieldValue :: SqlBind a => Statement -> String -> IO a
  getFieldValue stmt name = do
  	mb_v <- getFieldValueMB stmt name
--- 581,589 ----
  				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
***************
*** 565,573 ****
  		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
  getFieldValueType stmt name = sqlType
--- 592,606 ----
  		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
  getFieldValueType stmt name = sqlType
***************
*** 575,578 ****
--- 608,612 ----
  		(sqlType,colNumber) = findFieldInfo name (fields stmt) 1
  
+ -- | Returns the list of fields with their types and @nullable@ flags
  getFieldsTypes :: Statement -> [(String, SqlType)]
  getFieldsTypes = fields
***************
*** 589,597 ****
  -----------------------------------------------------------------------------------------
  
! 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
--- 623,638 ----
  -----------------------------------------------------------------------------------------
  
! -- | 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
***************
*** 599,602 ****
--- 640,646 ----
  	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