*l#H}      !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|portable provisional$John Goerzen <jgoerzen@complete.org>4*The different types of intervals in SQL. Difference in minutes+seconds Difference in hours+seconds Difference in hours+minutes Difference in days+seconds Difference in days+minutes Difference in days+hours Difference in seconds Difference in minutes Difference in hours Difference in days Difference in years+months Difference in years Difference in months )The type identifier for a given column. HThis represents the type of data stored in the column in the underlying :SQL engine. It does not form the entire column type; see +* for that. 9These types correspond mainly to those defined by ODBC. OA type not represented here; implementation-specific information in the String Global unique identifier A time or date difference  UTC time UTC date/time Combined date and time A time A date AVariable-length binary data, max length implementation dependant Variable-length binary data Fixed-length binary data 64-bit integer values 8-bit integer values  A single bit 'Signed inexact double-precision values %Signed inexact floating-point values  32-bit integer values !16-bit integer values "Signed exact integer values #Signed exact values $DVariable-width Unicode strings, max length implementation dependant %Variable-width Unicode strings &Fixed-width Unicode strings 'FVariable-width character strings, max length implementation dependant (!Variable-width character strings )Fixed-width character strings *The description of a column. =Fields are Nothing if the database backend cannot supply the requested information. #The colSize field works like this: CFor character types, the maximum width of the column. For numeric Jtypes, the total number of digits allowed. See the ODBC manual for more. HThe colOctetLength field is defined for character and binary types, and Ggives the number of bytes the column requires, regardless of encoding. +,Type of data stored here -The size of a column .The maximum size in octets /"Digits to the right of the period 0Whether NULL is acceptable }~1  !"#$%&'()*+,-./01*+,-./0)('&%$#"!  1  )('&%$#"!  !"#$%&'()*+,-./0+,-./0)1>The main type for expressing Haskell values to SQL databases. FThis type is used to marshall Haskell data to and from database APIs. GHDBC driver interfaces will do their best to use the most accurate and Aefficient way to send a particular value to the database server. AValues read back from the server are put in the most appropriate 1 type. B5 can then be used to convert them into whatever type is needed locally in Haskell. Most people will use A and B instead of manipulating 1 s directly. KThe default representation of time values is an integer number of seconds. GDatabases such as PostgreSQL with builtin timestamp types can will see Hautomatic conversion between these Haskell types to local types. Other ,databases can just use an int or a string. LThis behavior also exists for other types. For instance, many databases don't have a Rational type, so they'll just use Haskell's show function and store a Rational as a string. NTwo SqlValues are considered to be equal if one of these hold (first one that 6is true holds; if none are true, they are not equal):  * Both are NULL F * Both represent the same type and the encapsulated values are equal ? * The values of each, when converted to a string, are equal. 2"NULL in SQL or Nothing in Haskell 3Representation of TimeDiff 4,Representation of ClockTime or CalendarTime 56789:;<=>?@Conversions to and from 1s and standard Haskell types. 5Conversions are powerful; for instance, you can call B on a SqlInt32 Cand get a String or a Double out of it. This class attempts to Do IThe Right Thing whenever possible, and will raise an error when asked to Ddo something incorrect. In particular, when converting to any type except a Maybe, 20 as the input will cause an error to be raised. &Here are some notes about conversion: 8 Fractions of a second are not preserved on time values  See also Q, R. ABCAThe main HDBC exception object. As much information as possible Lis passed from the database through to the application through this object. IErrors generated in the Haskell layer will have seNativeError set to -1. DEFGHIJ@Execute the prepared statement, passing in the given positional E parameters (that should take the place of the question marks  in the call to prepare). :For non-SELECT queries, the return value is the number of G rows modified, if known. If no rows were modified, you get 0. G If the value is unknown, you get -1. All current HDBC drivers : support this function and should never return -1. +For SELECT queries, you will always get 0. HThis function should automatically call finish() to finish the previous ! execution, if necessary. K#Execute the query with many rows. A The return value is the return value from the final row  as if you had called J on it. 8Due to optimizations that are possible due to different F databases and driver designs, this can often be significantly  faster than using J multiple times since queries ' need to be compiled only once. 0This is most useful for non-SELECT statements. L2Abort a query in progress -- usually not needed. M&Fetches one row from the DB. Returns  if there 3 are no more rows. Will automatically call L when  the last row is read. N2Returns a list of the column names in the result. < For maximum portability, you should not assume that 0 information is available until after an J function  has been run. 2Information is returned here directly as returned ? by the underlying database layer. Note that different < databases have different rules about capitalization ; of return values and about representation of names B of columns that are not simple columns. For this reason, < it is suggested that you treat this information for A display purposes only. Failing that, you should convert * to lower (or upper) case, and use AS clauses for , anything other than simple columns. 4A simple getColumnNames implementation could simply  apply map fst to the return value of P. OThe original query that this IH was prepared  with. P8Obtain information about the columns in the result set. ! Must be run only after J. The String in the result " set is the column name. 9You should expect this to be returned in the same manner  as a result from Database.HDBC.fetchAllRows'. 5All results should be converted to lowercase for you  before you see them. Please see caveats under N for information ) on the column name field here. Q Converts any Integral type to a 1 by using toInteger. RBConvenience function for using numeric literals in your program. <Read a value from a string, and give an informative message  if it fails. DConverts the given timeDiff to the number of seconds it represents. 6Uses the same algorithm as normalizeTimeDiff in GHC. "123456789:;<=>?@ABCDEFGHIJKLMNOPQR"HIJKLMNOPCDEFG@ABQR1?>=<;:98765432"1?>=<;:9876543223456789:;<=>?@ABABCDEFGDEFGHIJKLMNOPIJKLMNOPQRportable provisional$John Goerzen <jgoerzen@complete.org>S9Sometimes, it is annoying to use typeclasses with Haskell's type system. JIn those situations, you can use a ConnWrapper. You can create one with:   let wrapped = ConnWrapper iconn ?You can then use this directly, since a ConnWrapper is also an U9. However, you will not be able to use private database functions on it. Or, you can use d. TUMain database handle object. An U> object is created by specific functions in the module for an Eindividual database. That is, the connect function -- which creates ?this object -- is not standardized through the HDBC interface. $A connection is closed by a call to V.  A call to W: is required to make sure that your changes get committed +to the database. In other words, HDBC has no support for autocommit, which  we consider an outdated notion. V%Disconnect from the remote database. PYou do not need to explicitly close an IConnection object, but you may do so if you so desire. If you don'0t, the object will disconnect from the database Jin a sane way when it is garbage-collected. However, a disconnection may 9raise an error, so you are encouraged to explicitly call V . Also, Ogarbage collection may not run when the program terminates, and some databases $really like an explicit disconnect. So, bottom line is, you're best off calling V directly, but the  world won't end if you forget. HThis function discards any data not committed already. Database driver &implementators should explicitly call X if their databases don't %do this automatically on disconnect. =Bad Things (TM) could happen if you call this while you have IHs Pactive. In more precise language, the results in such situations are undefined and vary by database. So don' t do it. W)Commit any pending data to the database. +Required to make any changes take effect. X8Roll back to the state the database was in prior to the  last W or X. Y0Execute a single SQL query. Returns the number ) of rows modified (see J for details). 2 The second parameter is a list 3 of replacement values, if any. Z%Prepares a statement for execution. 4Question marks in the statement will be replaced by < positional parameters in a later call to J. ,Please note that, depending on the database D and the driver, errors in your SQL may be raised % either here or by J. Make sure you @ handle exceptions both places if necessary. [ Create a new  Connection object, pointed at the same L server as this object is. This will generally establish 3 a separate physical connection. <When you wish to establish multiple connections to a single H server, the correct way to do so is to establish the H first connection with the driver-specific connection O function, and then clone it for each additional connection. +This can be important when a database doesn' t provide J much thread support itself, and the HDBC driver module C must serialize access to a particular database. 7This can also be a handy utility function whenever you K need a separate connection to whatever database you are * connected to already. \8The name of the HDBC driver module for this connection. J Ideally would be the same as the database name portion = of the Cabal package name. For instance, "sqlite3"  or "odbc"(. This is the layer that is bound most % tightly to HDBC. ]2The version of the C (or whatever) client library I that the HDBC driver module is bound to. The meaning G of this is driver-specific. For an ODBC or similar F proxying driver, this should be the version of the E ODBC library, not the eventual DB client driver. ^2In the case of a system such as ODBC, the name of & the database client/server in use, if available.  For others,  identical to \. _5In the case of a system such as ODBC, the version of J the database client in use, if available. For others,  identical to ]. This is the next layer . out past the HDBC driver. `3The version of the database server, if available. a;Whether or not the current database supports transactions. " If False, then W and X should be expected $ to raise errors. 7MySQL is the only commonly-used database that is known E to not support transactions entirely. Please see M the MySQL notes in the ODBC driver for more information. b2The names of all tables accessible by the current N connection, excluding special meta-tables (system tables). 9You should expect this to be returned in the same manner $ as a result from Database.HDBC.fetchAllRows'. 5All results should be converted to lowercase for you ( before you see them. c3Obtain information about the columns in a specific 4 table. The String in the result + set is the column name. 9You should expect this to be returned in the same manner $ as a result from Database.HDBC.fetchAllRows'. 5All results should be converted to lowercase for you ( before you see them. d Unwrap a TS and pass the embedded U to a function. Example: =withWConn wrapped run $ "SELECT * from foo where bar = 1" [] 4123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcd4UVWXYZ[\]^_`abcHIJKLMNOPCDEFG@ABQR1?>=<;:98765432STdSTTUVWXYZ[\]^_`abcVWXYZ[\]^_`abcdportable provisional$John Goerzen <jgoerzen@complete.org>eExecute the given IO action. If it raises a DC3, then execute the supplied handler and return its .return value. Otherwise, proceed as normal. fLike e), with the order of arguments reversed. gKGiven an Exception, return Just SqlError if it was an SqlError, or Nothing 2otherwise. Useful with functions like catchJust. hCatches DC.s, and re-raises them as IO errors with fail. Useful if you don'3t care to catch SQL errors, but want to see a sane Herror message if one happens. One would often use this as a high-level wrapper around SQL calls. iLike Y., but take a list of Maybe Strings instead of 1s. jLike J., but take a list of Maybe Strings instead of  1s. kLike K., but take a list of Maybe Strings instead of  1s. lLike M0, but return a list of Maybe Strings instead of  1s. m:Execute some code. If any uncaught exception occurs, run X" and re-raise it. Otherwise, run W and return. OThis function, therefore, encapsulates the logical property that a transaction is all about: all or nothing. The U6 object passed in is passed directly to the specified function as a convenience. This function traps all6 uncaught exceptions, not just SqlErrors. Therefore, 6you will get a rollback for any exception that you don't handle. That's probably what you want anyway. KSince all operations in HDBC are done in a transaction, this function doesn't issue an explicit "begin") to the server. You should ideally have called Database.HDBC.commit or Database.HDBC.rollback before $calling this function. If you haven')t, this function will commit or rollback 8more than just the changes made in the included action. $If there was an error while running X, this error will not be Dreported since the original exception will be propogated back. (You' d probably Elike to know about the root cause for all of this anyway.) Feedback on this behavior is solicited. n'Lazily fetch all rows from an executed IH. HYou can think of this as hGetContents applied to a database result set. OThe result of this is a lazy list, and each new row will be read, lazily, from 'the database as the list is processed. &When you have exhausted the list, the IH will be Led. OPlease note that the careless use of this function can lead to some unpleasant Ibehavior. In particular, if you have not consumed the entire list, then  attempt to L: or re-execute the statement, and then attempt to consume Jmore elements from the list, the result will almost certainly not be what  you want. 3But then, similar caveats apply with hGetContents. CBottom line: this is a very convenient abstraction; use it wisely. Use o/ if you need something that is strict, without all these caveats. oStrict version of n". Does not have the side-effects of n2, but forces the entire result set to be buffered  in memory. pLike n&, but return Maybe Strings instead of 1s. qStrict version of p. rLike M9, but instead of returning a list, return an association  list from column name to value. IThe keys of the column names are lowercase versions of the data returned by N2. Please heed the warnings there. Additionally, Mresults are undefined if multiple columns are returned with identical names. Strict version of r s Similar to r3, but return a Map instead of an association list. Strict version of s tLike n+, but instead of returning a list for each Irow, return an association list for each row, from column name to value. See r for more details. uStrict version of t vLike t1, but return a list of Maps instead of a list of association lists. wStrict version of v xAA quick way to do a query. Similar to preparing, executing, and  then calling n on a statement. See also y yStrict version of x. efghijklmnopqrstuvwxyefghijklmnopqrstuvwxyportable provisional$John Goerzen <jgoerzen@complete.org>z{2Close all children. Intended to be called by the V function in  Connection. MThere may be a potential race condition wherein a call to newSth at the same Ntime as a call to this function may result in the new child not being closed. |GAdds a new child to the existing list. Also takes care of registering ?a finalizer for it, to remove it from the list when possible. #The general finalizer for a child. PIt is simply a filter that removes any finalized weak pointers from the parent. LIf the MVar is locked at the start, does nothing to avoid deadlock. Future &runs would probably catch it anyway. z{|z{|z{|portable provisional$John Goerzen <jgoerzen@complete.org>y  !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyO@ABQR1?>=<;:98765432UVWXYZ[\]^_`abcSTdiyxmHJKLMNOPJjKkMrslnotuvwpqNPLOCDEFGefgh      !"#$%&'()*+,-./01123456789:;<=>?@ABCDEFGHIIJKLMMNOPQRSTUVWWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ HDBC-1.1.5Database.HDBC.ColTypesDatabase.HDBC.StatementDatabase.HDBC.Types Database.HDBCDatabase.HDBC.DriverUtilsDatabase.HDBC.Utils SqlIntervalSqlIntervalMinuteToSecondTSqlIntervalHourToSecondTSqlIntervalHourToMinuteTSqlIntervalDayToSecondTSqlIntervalDayToMinuteTSqlIntervalDayToHourTSqlIntervalSecondTSqlIntervalMinuteTSqlIntervalHourTSqlIntervalDayTSqlIntervalYearToMonthTSqlIntervalYearTSqlIntervalMonthT SqlTypeId SqlUnknownTSqlGUIDT SqlIntervalT SqlUTCTimeTSqlUTCDateTimeT SqlTimestampTSqlTimeTSqlDateTSqlLongVarBinaryT SqlVarBinaryT SqlBinaryT SqlBigIntT SqlTinyIntTSqlBitT SqlDoubleT SqlFloatTSqlRealT SqlIntegerT SqlSmallIntT SqlNumericT SqlDecimalTSqlWLongVarCharT SqlWVarCharT SqlWCharTSqlLongVarCharT SqlVarCharTSqlCharT SqlColDesccolTypecolSizecolOctetLength colDecDigits colNullableSqlValueSqlNull SqlTimeDiff SqlEpochTime SqlRational SqlDoubleSqlBoolSqlChar SqlIntegerSqlInt64SqlInt32 SqlWord64 SqlWord32 SqlByteString SqlStringSqlTypetoSqlfromSqlSqlErrorseState seNativeError seErrorMsg Statementexecute executeManyfinishfetchRowgetColumnNames originalQuerydescribeResultnToSqliToSql ConnWrapper IConnection disconnectcommitrollbackrunprepareclonehdbcDriverName hdbcClientVerproxiedClientNameproxiedClientVer dbServerVerdbTransactionSupport getTables describeTable withWConncatchSql handleSql sqlExceptionshandleSqlErrorsRunsExecute sExecuteMany sFetchRowwithTransaction fetchAllRows fetchAllRows' sFetchAllRowssFetchAllRows' fetchRowAL fetchRowMapfetchAllRowsALfetchAllRowsAL'fetchAllRowsMapfetchAllRowsMap' quickQuery quickQuery' ChildListcloseAllChildrenaddChild sqlColDescTc sqlTypeIdTc sqlIntervalTcbase Data.MaybeNothing sqlErrorTcstring2ByteString numToBoolbyteString2Stringsecs2tdread'timeDiffToSecsevalAll fetchRowAL' fetchRowMap'childFinalizer